











               XXlliibb −− CC LLaanngguuaaggee XX IInntteerrffaaccee

                  XX WWiinnddooww SSyysstteemm SSttaannddaarrdd

                  XX VVeerrssiioonn 1111,, RReelleeaassee 77

                        lliibbXX1111 11..33..22






                        James Gettys
               Cambridge Research Laboratory
               Digital Equipment Corporation


                    Robert W. Scheifler
              Laboratory for Computer Science
           Massachusetts Institute of Technology



                  _w_i_t_h _c_o_n_t_r_i_b_u_t_i_o_n_s _f_r_o_m



                Chuck Adams, Tektronix, Inc.

          Vania Joloboff, Open Software Foundation

            Hideki Hiura, Sun Microsystems, Inc.

           Bill McMahon, Hewlett‐Packard Company

     Ron Newman, Massachusetts Institute of Technology

               Al Tabayoyon, Tektronix, Inc.

               Glenn Widener, Tektronix, Inc.

                Shigeru Yamada, Fujitsu OSSI



























The X Window System is a trademark of The Open Group.

TekHVC is a trademark of Tektronix, Inc.



Copyright © 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994,
1996, 2002 The Open Group

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documenta­
tion files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom
the Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall
be included in all copies or substantial portions of the
Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR­
POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR­
TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of The Open
Group shall not be used in advertising or otherwise to pro­
mote the sale, use or other dealings in this Software with­
out prior written authorization from The Open Group.




Copyright © 1985, 1986, 1987, 1988, 1989, 1990, 1991 by Dig­
ital Equipment Corporation

Portions Copyright © 1990, 1991 by Tektronix, Inc.













Permission to use, copy, modify and distribute this documen­
tation for any purpose and without fee is hereby granted,
provided that the above copyright notice appears in all
copies and that both that copyright notice and this permis­
sion notice appear in all copies, and that the names of Dig­
ital and Tektronix not be used in in advertising or public­
ity pertaining to this documentation without specific, writ­
ten prior permission.  Digital and Tektronix makes no repre­
sentations about the suitability of this documentation for
any purpose.  It is provided ‘‘as is’’ without express or
implied warranty.

























































                      AAcckknnoowwlleeddggmmeennttss



The design and implementation of the first 10 versions of X
were primarily the work of three individuals: Robert Schei­
fler of the MIT Laboratory for Computer Science and Jim Get­
tys of Digital Equipment Corporation and Ron Newman of MIT,
both at MIT Project Athena.  X version 11, however, is the
result of the efforts of dozens of individuals at almost as
many locations and organizations.  At the risk of offending
some of the players by exclusion, we would like to acknowl­
edge some of the people who deserve special credit and
recognition for their work on Xlib.  Our apologies to anyone
inadvertently overlooked.

RReelleeaassee 11

Our thanks does to Ron Newman (MIT Project Athena), who con­
tributed substantially to the design and implementation of
the Version 11 Xlib interface.

Our thanks also goes to Ralph Swick (Project Athena and Dig­
ital) who kept it all together for us during the early
releases.  He handled literally thousands of requests from
people everywhere and saved the sanity of at least one of
us.  His calm good cheer was a foundation on which we could
build.

Our thanks also goes to Todd Brunhoff (Tektronix) who was
‘‘loaned’’ to Project Athena at exactly the right moment to
provide very capable and much‐needed assistance during the
alpha and beta releases.  He was responsible for the suc­
cessful integration of sources from multiple sites; we would
not have had a release without him.

Our thanks also goes to Al Mento and Al Wojtas of Digital’s
ULTRIX Documentation Group.  With good humor and cheer, they
took a rough draft and made it an infinitely better and more
useful document.  The work they have done will help many
everywhere.  We also would like to thank Hal Murray (Digital
SRC) and Peter George (Digital VMS) who contributed much by
proofreading the early drafts of this document.

Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson,
Jackie Granfield, and Vince Orgovan (Digital VMS) who helped
with the library utilities implementation; to Hania Gajewska
(Digital UEG‐WSL) who, along with Ellis Cohen (CMU and
Siemens), was instrumental in the semantic design of the
window manager properties; and to Dave Rosenthal (Sun
Microsystems) who also contributed to the protocol and pro­
vided the sample generic color frame buffer device‐dependent












code.

The alpha and beta test participants deserve special recog­
nition and thanks as well.  It is significant that the bug
reports (and many fixes) during alpha and beta test came
almost exclusively from just a few of the alpha testers,
mostly hardware vendors working on product implementations
of X.  The continued public contribution of vendors and uni­
versities is certainly to the benefit of the entire X commu­
nity.

Our special thanks must go to Sam Fuller, Vice‐President of
Corporate Research at Digital, who has remained committed to
the widest public availability of X and who made it possible
to greatly supplement MIT’s resources with the Digital staff
in order to make version 11 a reality.  Many of the people
mentioned here are part of the Western Software Laboratory
(Digital UEG‐WSL) of the ULTRIX Engineering group and work
for Smokey Wallace, who has been vital to the project’s suc­
cess.  Others not mentioned here worked on the toolkit and
are acknowledged in the X Toolkit documentation.

Of course, we must particularly thank Paul Asente, formerly
of Stanford University and now of Digital UEG‐WSL, who wrote
W, the predecessor to X, and Brian Reid, formerly of Stan­
ford University and now of Digital WRL, who had much to do
with W’s design.

Finally, our thanks goes to MIT,  Digital Equipment Corpora­
tion, and IBM for providing the environment where it could
happen.

RReelleeaassee 44

Our thanks go to Jim Fulton (MIT X Consortium) for designing
and specifying the new Xlib functions for Inter‐Client Com­
munication Conventions (ICCCM) support.

We also thank Al Mento of Digital for his continued effort
in maintaining this document and Jim Fulton and Donna Con­
verse (MIT X Consortium) for their much‐appreciated efforts
in reviewing the changes.

RReelleeaassee 55

The principal authors of the Input Method facilities are
Vania Joloboff (Open Software Foundation) and Bill McMahon
(Hewlett‐Packard).  The principal author of the rest of the
internationalization facilities is Glenn Widener (Tek­
tronix).  Our thanks to them for keeping their sense of
humor through a long and sometimes difficult design process.
Although the words and much of the design are due to them,
many others have contributed substantially to the design and
implementation.  Tom McFarland (HP) and Frank Rojas (IBM)












deserve particular recognition for their contributions.
Other contributors were: Tim Anderson (Motorola), Alka Bad­
shah (OSF), Gabe Beged‐Dov (HP), Chih‐Chung Ko (III), Vera
Cheng (III), Michael Collins (Digital), Walt Daniels (IBM),
Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu), Hitoshoi
Fukumoto (Nihon Sun), Tim Greenwood (Digital), John Harvey
(IBM), Hideki Hiura (Sun), Fred Horman (AT&T), Norikazu
Kaiya (Fujitsu), Yuji Kamata (IBM), Yutaka Kataoka (Waseda
University), Ranee Khubchandani (Sun), Akira Kon (NEC),
Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji
Kuwari (OMRON), Sandra Martin (OSF), Narita Masahiko
(Fujitsu), Masato Morisaki (NTT), Nelson Ng (Sun), Takashi
Nishimura (NTT America), Makato Nishino (IBM), Akira Ohsone
(Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&T),
Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori Mehring
(Digital), Shoji Sugiyama (IBM), and Eiji Tosa (IBM).

We are deeply indebted to Tatsuya Kato (NTT), Hiroshi Kurib­
ayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki
(NTT), and Li Yuhong (OMRON) for producing one of the first
complete sample implementation of the internationalization
facilities, and Hiromu Inukai (Nihon Sun), Takashi Fujiwara
(Fujitsu), Hideki Hiura (Sun), Yasuhiro Kawai (Oki Tech­
nosystems Laboratory), Kazunori Nishihara (Fuji Xerox),
Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba), Makoto
Wakamatsu (Sony Corporation) for producing the another com­
plete sample implementation of the internationalization
facilities.

The principal authors (design and implementation) of the
Xcms color management facilities are Al Tabayoyon (Tek­
tronix) and Chuck Adams (Tektronix).  Joann Taylor (Tek­
tronix), Bob Toole (Tektronix), and Keith Packard (MIT X
Consortium) also contributed significantly to the design.
Others who contributed are: Harold Boll (Kodak), Ken Bron­
stein (HP), Nancy Cam (SGI), Donna Converse (MIT X Consor­
tium), Elias Israel (ISC), Deron Johnson (Sun), Jim King
(Adobe), Ricardo Motta (HP), Chuck Peek (IBM), Wil Plouffe
(IBM), Dave Sternlicht (MIT X Consortium), Kumar Talluri
(AT&T), and Richard Verberg (IBM).

We also once again thank Al Mento of Digital for his work in
formatting and reformatting text for this manual, and for
producing man pages.  Thanks also to Clive Feather (IXI) for
proof‐reading and finding a number of small errors.

RReelleeaassee 66

Stephen Gildea (X Consortium) authored the threads support.
Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substan­
tially by testing the facilities and reporting bugs in a
timely fashion.














The principal authors of the internationalization facili­
ties, including Input and Output Methods, are Hideki Hiura
(SunSoft) and Shigeru Yamada (Fujitsu OSSI).  Although the
words and much of the design are due to them, many others
have contributed substantially to the design and implementa­
tion.  They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi
(IBM), Makoto Inada (Digital), Hiromu Inukai (Nihon Sun­
Soft), Song JaeKyung (KAIST), Franky Ling (Digital), Tom
McFarland (HP), Hiroyuki Miyamoto (Digital), Masahiko Narita
(Fujitsu), Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki
Takeuchi (Sony), Makoto Wakamatsu (Sony), Masaki Wakao
(IBM), Katsuhisa Yano(Toshiba) and Jinsoo Yoon (KAIST).

The principal producers of the sample implementation of the
internationalization facilities are: Jeffrey Bloomfield
(Fujitsu OSSI), Takashi Fujiwara (Fujitsu), Hideki Hiura
(SunSoft), Yoshio Horiuchi (IBM), Makoto Inada (Digital),
Hiromu Inukai (Nihon SunSoft), Song JaeKyung (KAIST), Riki
Kawaguchi (Fujitsu), Franky Ling (Digital), Hiroyuki
Miyamoto (Digital), Hidetoshi Tajima (HP), Toshimitsu Tera­
zono (Fujitsu), Makoto Wakamatsu (Sony), Masaki Wakao (IBM),
Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba).

The coordinators of the integration, testing, and release of
this implementation of the internationalization facilities
are Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony).

Others who have contributed to the architectural design or
testing of the sample implementation of the international­
ization facilities are: Hector Chan (Digital), Michael Kung
(IBM), Joseph Kwok (Digital), Hiroyuki Machida (Sony), Nel­
son Ng (SunSoft), Frank Rojas (IBM), Yoshiyuki Segawa
(Fujitsu OSSI), Makiko Shimamura (Fujitsu), Shoji Sugiyama
(IBM), Lining Sun (SGI), Masaki Takeuchi (Sony), Jinsoo Yoon
(KAIST) and Akiyasu Zen (HP).




Jim Gettys
Cambridge Research Laboratory
Digital Equipment Corporation

Robert W. Scheifler
Laboratory for Computer Science
Massachusetts Institute of Technology






















                         CChhaapptteerr 11

                    IInnttrroodduuccttiioonn ttoo XXlliibb



The X Window System is a network‐transparent window system
that was designed at MIT.  X display servers run on comput­
ers with either monochrome or color bitmap display hardware.
The server distributes user input to and accepts output
requests from various client programs located either on the
same machine or elsewhere in the network.  Xlib is a C sub­
routine library that application programs (clients) use to
interface with the window system by means of a stream con­
nection.  Although a client usually runs on the same machine
as the X server it is talking to, this need not be the case.

_X_l_i_b _− _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e is a reference guide to the
low‐level C language interface to the X Window System proto­
col.  It is neither a tutorial nor a user’s guide to pro­
gramming the X Window System.  Rather, it provides a
detailed description of each function in the library as well
as a discussion of the related background information.  _X_l_i_b
_− _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e assumes a basic understanding of a
graphics window system and of the C programming language.
Other higher‐level abstractions (for example, those provided
by the toolkits for X) are built on top of the Xlib library.
For further information about these higher‐level libraries,
see the appropriate toolkit documentation.  The _X _W_i_n_d_o_w
_S_y_s_t_e_m _P_r_o_t_o_c_o_l provides the definitive word on the behavior
of X.  Although additional information appears here, the
protocol document is the ruling document.

To provide an introduction to X programming, this chapter
discusses:

⋅    Overview of the X Window System

⋅    Errors

⋅    Standard header files

⋅    Generic values and types

⋅    Naming and argument conventions within Xlib

⋅    Programming considerations

⋅    Character sets and encodings

⋅    Formatting conventions




                              11





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


11..11..  OOvveerrvviieeww ooff tthhee XX WWiinnddooww SSyysstteemm

Some of the terms used in this book are unique to X, and
other terms that are common to other window systems have
different meanings in X.  You may find it helpful to refer
to the glossary, which is located at the end of the book.

The X Window System supports one or more screens containing
overlapping windows or subwindows.  A screen is a physical
monitor and hardware that can be color, grayscale, or
monochrome.  There can be multiple screens for each display
or workstation.  A single X server can provide display ser­
vices for any number of screens.  A set of screens for a
single user with one keyboard and one pointer (usually a
mouse) is called a display.

All the windows in an X server are arranged in strict hier­
archies.  At the top of each hierarchy is a root window,
which covers each of the display screens.  Each root window
is partially or completely covered by child windows.  All
windows, except for root windows, have parents.  There is
usually at least one window for each application program.
Child windows may in turn have their own children.  In this
way, an application program can create an arbitrarily deep
tree on each screen.  X provides graphics, text, and raster
operations for windows.

A child window can be larger than its parent.  That is, part
or all of the child window can extend beyond the boundaries
of the parent, but all output to a window is clipped by its
parent.  If several children of a window have overlapping
locations, one of the children is considered to be on top of
or raised over the others, thus obscuring them.  Output to
areas covered by other windows is suppressed by the window
system unless the window has backing store.  If a window is
obscured by a second window, the second window obscures only
those ancestors of the second window that are also ancestors
of the first window.

A window has a border zero or more pixels in width, which
can be any pattern (pixmap) or solid color you like.  A win­
dow usually but not always has a background pattern, which
will be repainted by the window system when uncovered.
Child windows obscure their parents, and graphic operations
in the parent window usually are clipped by the children.

Each window and pixmap has its own coordinate system.  The
coordinate system has the X axis horizontal and the Y axis
vertical with the origin [0, 0] at the upper‐left corner.
Coordinates are integral, in terms of pixels, and coincide
with pixel centers.  For a window, the origin is inside the
border at the inside, upper‐left corner.





                              22





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


X does not guarantee to preserve the contents of windows.
When part or all of a window is hidden and then brought back
onto the screen, its contents may be lost.  The server then
sends the client program an _E_x_p_o_s_e event to notify it that
part or all of the window needs to be repainted.  Programs
must be prepared to regenerate the contents of windows on
demand.

X also provides off‐screen storage of graphics objects,
called pixmaps.  Single plane (depth 1) pixmaps are some­
times referred to as bitmaps.  Pixmaps can be used in most
graphics functions interchangeably with windows and are used
in various graphics operations to define patterns or tiles.
Windows and pixmaps together are referred to as drawables.

Most of the functions in Xlib just add requests to an output
buffer.  These requests later execute asynchronously on the
X server.  Functions that return values of information
stored in the server do not return (that is, they block)
until an explicit reply is received or an error occurs.  You
can provide an error handler, which will be called when the
error is reported.

If a client does not want a request to execute asyn­
chronously, it can follow the request with a call to _X_S_y_n_c,
which blocks until all previously buffered asynchronous
events have been sent and acted on.  As an important side
effect, the output buffer in Xlib is always flushed by a
call to any function that returns a value from the server or
waits for input.

Many Xlib functions will return an integer resource ID,
which allows you to refer to objects stored on the X server.
These can be of type _W_i_n_d_o_w, _F_o_n_t, _P_i_x_m_a_p, _C_o_l_o_r_m_a_p, _C_u_r_s_o_r,
and _G_C_o_n_t_e_x_t, as defined in the file <_X_1_1_/_X_._h>.  These
resources are created by requests and are destroyed (or
freed) by requests or when connections are closed.  Most of
these resources are potentially sharable between applica­
tions, and in fact, windows are manipulated explicitly by
window manager programs.  Fonts and cursors are shared auto­
matically across multiple screens.  Fonts are loaded and
unloaded as needed and are shared by multiple clients.
Fonts are often cached in the server.  Xlib provides no sup­
port for sharing graphics contexts between applications.

Client programs are informed of events.  Events may either
be side effects of a request (for example, restacking win­
dows generates _E_x_p_o_s_e events) or completely asynchronous
(for example, from the keyboard).  A client program asks to
be informed of events.  Because other applications can send
events to your application, programs must be prepared to
handle (or ignore) events of all types.





                              33





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Input events (for example, a key pressed or the pointer
moved) arrive asynchronously from the server and are queued
until they are requested by an explicit call (for example,
_X_N_e_x_t_E_v_e_n_t or _X_W_i_n_d_o_w_E_v_e_n_t).  In addition, some library
functions (for example, _X_R_a_i_s_e_W_i_n_d_o_w) generate _E_x_p_o_s_e and
_C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t events.  These events also arrive asyn­
chronously, but the client may wish to explicitly wait for
them by calling _X_S_y_n_c after calling a function that can
cause the server to generate events.

11..22..  EErrrroorrss

Some functions return _S_t_a_t_u_s, an integer error indication.
If the function fails, it returns a zero.  If the function
returns a status of zero, it has not updated the return
arguments.  Because C does not provide multiple return val­
ues, many functions must return their results by writing
into client‐passed storage.  By default, errors are handled
either by a standard library function or by one that you
provide.  Functions that return pointers to strings return
NULL pointers if the string does not exist.

The X server reports protocol errors at the time that it
detects them.  If more than one error could be generated for
a given request, the server can report any of them.

Because Xlib usually does not transmit requests to the
server immediately (that is, it buffers them), errors can be
reported much later than they actually occur.  For debugging
purposes, however, Xlib provides a mechanism for forcing
synchronous behavior (see section 11.8.1).  When synchro­
nization is enabled, errors are reported as they are gener­
ated.

When Xlib detects an error, it calls an error handler, which
your program can provide.  If you do not provide an error
handler, the error is printed, and your program terminates.

11..33..  SSttaannddaarrdd HHeeaaddeerr FFiilleess

The following include files are part of the Xlib standard:

⋅    <_X_1_1_/_X_l_i_b_._h>

     This is the main header file for Xlib.  The majority of
     all Xlib symbols are declared by including this file.
     This file also contains the preprocessor symbol _X_l_i_b_­
     _S_p_e_c_i_f_i_c_a_t_i_o_n_R_e_l_e_a_s_e.  This symbol is defined to have
     the 6 in this release of the standard.  (Release 5 of
     Xlib was the first release to have this symbol.)

⋅    <_X_1_1_/_X_._h>





                              44





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     This file declares types and constants for the X proto­
     col that are to be used by applications.  It is
     included automatically from <_X_1_1_/_X_l_i_b_._h>, so applica­
     tion code should never need to reference this file
     directly.

⋅    <_X_1_1_/_X_c_m_s_._h>

     This file contains symbols for much of the color man­
     agement facilities described in chapter 6.  All func­
     tions, types, and symbols with the prefix ‘‘Xcms’’,
     plus the Color Conversion Contexts macros, are declared
     in this file.  <_X_1_1_/_X_l_i_b_._h> must be included before
     including this file.

⋅    <_X_1_1_/_X_u_t_i_l_._h>

     This file declares various functions, types, and sym­
     bols used for inter‐client communication and applica­
     tion utility functions, which are described in chapters
     14 and 16.  <_X_1_1_/_X_l_i_b_._h> must be included before
     including this file.

⋅    <_X_1_1_/_X_r_e_s_o_u_r_c_e_._h>

     This file declares all functions, types, and symbols
     for the resource manager facilities, which are
     described in chapter 15.  <_X_1_1_/_X_l_i_b_._h> must be included
     before including this file.

⋅    <_X_1_1_/_X_a_t_o_m_._h>

     This file declares all predefined atoms, which are sym­
     bols with the prefix ‘‘XA_’’.

⋅    <_X_1_1_/_c_u_r_s_o_r_f_o_n_t_._h>

     This file declares the cursor symbols for the standard
     cursor font, which are listed in appendix B.  All cur­
     sor symbols have the prefix ‘‘XC_’’.

⋅    <_X_1_1_/_k_e_y_s_y_m_d_e_f_._h>

     This file declares all standard KeySym values, which
     are symbols with the prefix ‘‘XK_’’.  The KeySyms are
     arranged in groups, and a preprocessor symbol controls
     inclusion of each group.  The preprocessor symbol must
     be defined prior to inclusion of the file to obtain the
     associated values.  The preprocessor symbols are
     XK_MISCELLANY, XK_XKB_KEYS, XK_3270, XK_LATIN1,
     XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARA­
     BIC, XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL,
     XK_PUBLISHING, XK_APL, XK_HEBREW, XK_THAI, and
     XK_KOREAN.



                              55





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    <_X_1_1_/_k_e_y_s_y_m_._h>

     This file defines the preprocessor symbols XK_MISCEL­
     LANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3,
     XK_LATIN4, and XK_GREEK and then includes
     <_X_1_1_/_k_e_y_s_y_m_d_e_f_._h>.

⋅    <_X_1_1_/_X_l_i_b_i_n_t_._h>

     This file declares all the functions, types, and sym­
     bols used for extensions, which are described in
     appendix C.  This file automatically includes
     <_X_1_1_/_X_l_i_b_._h>.

⋅    <_X_1_1_/_X_p_r_o_t_o_._h>

     This file declares types and symbols for the basic X
     protocol, for use in implementing extensions.  It is
     included automatically from <_X_1_1_/_X_l_i_b_i_n_t_._h>, so appli­
     cation and extension code should never need to refer­
     ence this file directly.

⋅    <_X_1_1_/_X_p_r_o_t_o_s_t_r_._h>

     This file declares types and symbols for the basic X
     protocol, for use in implementing extensions.  It is
     included automatically from <_X_1_1_/_X_p_r_o_t_o_._h>, so applica­
     tion and extension code should never need to reference
     this file directly.

⋅    <_X_1_1_/_X_1_0_._h>

     This file declares all the functions, types, and sym­
     bols used for the X10 compatibility functions, which
     are described in appendix D.

11..44..  GGeenneerriicc VVaalluueess aanndd TTyyppeess

The following symbols are defined by Xlib and used through­
out the manual:

⋅    Xlib defines the type _B_o_o_l and the Boolean values _T_r_u_e
     and _F_a_l_s_e.

⋅    _N_o_n_e is the universal null resource ID or atom.

⋅    The type _X_I_D is used for generic resource IDs.

⋅    The type _X_P_o_i_n_t_e_r is defined to be char* and is used as
     a generic opaque pointer to data.







                              66





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


11..55..  NNaammiinngg aanndd AArrgguummeenntt CCoonnvveennttiioonnss wwiitthhiinn XXlliibb

Xlib follows a number of conventions for the naming and syn­
tax of the functions.  Given that you remember what informa­
tion the function requires, these conventions are intended
to make the syntax of the functions more predictable.

The major naming conventions are:

⋅    To differentiate the X symbols from the other symbols,
     the library uses mixed case for external symbols.  It
     leaves lowercase for variables and all uppercase for
     user macros, as per existing convention.

⋅    All Xlib functions begin with a capital X.

⋅    The beginnings of all function names and symbols are
     capitalized.

⋅    All user‐visible data structures begin with a capital
     X.  More generally, anything that a user might derefer­
     ence begins with a capital X.

⋅    Macros and other symbols do not begin with a capital X.
     To distinguish them from all user symbols, each word in
     the macro is capitalized.

⋅    All elements  of or variables in a data structure are
     in lowercase.  Compound words, where needed, are con­
     structed with underscores (_).

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

⋅    All resource objects, where used, occur at the begin­
     ning of the argument list immediately after the display
     argument.

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

⋅    Source arguments always precede the destination argu­
     ments in the argument list.

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

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





                              77





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


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

⋅    Where a mask is accompanied with a structure, the mask
     always precedes the pointer to the structure in the
     argument list.

11..66..  PPrrooggrraammmmiinngg CCoonnssiiddeerraattiioonnss

The major programming considerations are:

⋅    Coordinates and sizes in X are actually 16‐bit quanti­
     ties.  This decision was made to minimize the bandwidth
     required for a given level of performance.  Coordinates
     usually are declared as an _i_n_t in the interface.  Val­
     ues larger than 16 bits are truncated silently.  Sizes
     (width and height) are declared as unsigned quantities.

⋅    Keyboards are the greatest variable between different
     manufacturers’ workstations.  If you want your program
     to be portable, you should be particularly conservative
     here.

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

⋅    The user should have control of his screen real estate.
     Therefore, you should write your applications to react
     to window management rather than presume control of the
     entire screen.  What you do inside of your top‐level
     window, however, is up to your application.  For fur­
     ther information, see chapter 14 and the _I_n_t_e_r_‐_C_l_i_e_n_t
     _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l.

11..77..  CChhaarraacctteerr SSeettss aanndd EEnnccooddiinnggss

Some of the Xlib functions make reference to specific char­
acter sets and character encodings.  The following are the
most common:

⋅    X Portable Character Set

     A basic set of 97 characters, which are assumed to
     exist in all locales supported by Xlib.  This set con­
     tains the following characters:


a..z A..Z 0..9 !"#$%&’()*+,‐./:;<=>?@[\]^_‘{|}~ <space>,
<tab>, and <newline>






                              88





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     This set is the left/lower half of the graphic charac­
     ter set of ISO8859‐1 plus space, tab, and newline.  It
     is also the set of graphic characters in 7‐bit ASCII
     plus the same three control characters.  The actual
     encoding of these characters on the host is system
     dependent.

⋅    Host Portable Character Encoding

     The encoding of the X Portable Character Set on the
     host.  The encoding itself is not defined by this stan­
     dard, but the encoding must be the same in all locales
     supported by Xlib on the host.  If a string is said to
     be in the Host Portable Character Encoding, then it
     only contains characters from the X Portable Character
     Set, in the host encoding.

⋅    Latin‐1

     The coded character set defined by the ISO8859‐1 stan­
     dard.

⋅    Latin Portable Character Encoding

     The encoding of the X Portable Character Set using the
     Latin‐1 codepoints plus ASCII control characters.  If a
     string is said to be in the Latin Portable Character
     Encoding, then it only contains characters from the X
     Portable Character Set, not all of Latin‐1.

⋅    STRING Encoding

     Latin‐1, plus tab and newline.

⋅    POSIX Portable Filename Character Set

     The set of 65 characters, which can be used in naming
     files on a POSIX‐compliant host, that are correctly
     processed in all locales.  The set is:


     a..z A..Z 0..9 ._‐


11..88..  FFoorrmmaattttiinngg CCoonnvveennttiioonnss

_X_l_i_b _− _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e uses the following conven­
tions:

⋅    Global symbols are printed in _t_h_i_s _s_p_e_c_i_a_l _f_o_n_t.  These
     can be either function names, symbols defined in
     include files, or structure names.  When declared and
     defined, function arguments are printed in _i_t_a_l_i_c_s.  In
     the explanatory text that follows, they usually are



                              99





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     printed in regular type.

⋅    Each function is introduced by a general discussion
     that distinguishes it from other functions.  The func­
     tion declaration itself follows, and each argument is
     specifically explained.  Although ANSI C function pro­
     totype syntax is not used, Xlib header files normally
     declare functions using function prototypes in ANSI C
     environments.  General discussion of the function, if
     any is required, follows the arguments.  Where applica­
     ble, the last paragraph of the explanation lists the
     possible Xlib error codes that the function can gener­
     ate.  For a complete discussion of the Xlib error
     codes, see section 11.8.2.

⋅    To eliminate any ambiguity between those arguments that
     you pass and those that a function returns to you, the
     explanations for all arguments that you pass start with
     the word _s_p_e_c_i_f_i_e_s or, in the case of multiple argu­
     ments, the word _s_p_e_c_i_f_y.  The explanations for all
     arguments that are returned to you start with the word
     _r_e_t_u_r_n_s or, in the case of multiple arguments, the word
     _r_e_t_u_r_n.  The explanations for all arguments that you
     can pass and are returned start with the words _s_p_e_c_i_­
     _f_i_e_s _a_n_d _r_e_t_u_r_n_s.

⋅    Any pointer to a structure that is used to return a
     value is designated as such by the ___r_e_t_u_r_n suffix as
     part of its name.  All other pointers passed to these
     functions are used for reading only.  A few arguments
     use pointers to structures that are used for both input
     and output and are indicated by using the ___i_n___o_u_t suf­
     fix.
























                             1100





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                            CChhaapptteerr 22

                        DDiissppllaayy FFuunnccttiioonnss



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

⋅    Open (connect to) the display

⋅    Obtain information about the display, image formats, or
     screens

⋅    Generate a _N_o_O_p_e_r_a_t_i_o_n protocol request

⋅    Free client‐created data

⋅    Close (disconnect from) a display

⋅    Use X Server connection close operations

⋅    Use Xlib with threads

⋅    Use internal connections

22..11..  OOppeenniinngg tthhee DDiissppllaayy

To open a connection to the X server that controls a dis­
play, use _X_O_p_e_n_D_i_s_p_l_a_y.

__
││
Display *XOpenDisplay(_d_i_s_p_l_a_y___n_a_m_e)
      char *_d_i_s_p_l_a_y___n_a_m_e;


_d_i_s_p_l_a_y___n_a_m_e
          Specifies the hardware display name, which deter­
          mines the display and communications domain to be
          used.  On a POSIX‐conformant system, if the dis­
          play_name is NULL, it defaults to the value of the
          DISPLAY environment variable.
││__

The encoding and interpretation of the display name are
implementation‐dependent.  Strings in the Host Portable
Character Encoding are supported; support for other charac­
ters is implementation‐dependent.  On POSIX‐conformant



                             1111





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


systems, the display name or DISPLAY environment variable
can be a string in the format:

__
││
          _p_r_o_t_o_c_o_l/_h_o_s_t_n_a_m_e:_n_u_m_b_e_r._s_c_r_e_e_n___n_u_m_b_e_r


_p_r_o_t_o_c_o_l  Specifies a protocol family or an alias for a pro­
          tocol family.  Supported protocol families are
          implementation dependent.  The protocol entry is
          optional.  If protocol is not specified, the /
          separating protocol and hostname must also not be
          specified.

_h_o_s_t_n_a_m_e  Specifies the name of the host machine on which
          the display is physically attached.  You follow
          the hostname with either a single colon (:) or a
          double colon (::).

_n_u_m_b_e_r    Specifies the number of the display server on that
          host machine.  You may optionally follow this dis­
          play number with a period (.).  A single CPU can
          have more than one display.  Multiple displays are
          usually numbered starting with zero.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the screen to be used on that server.
          Multiple screens can be controlled by a single X
          server.  The screen_number sets an internal vari­
          able that can be accessed by using the _D_e_f_a_u_l_t_­
          _S_c_r_e_e_n macro or the _X_D_e_f_a_u_l_t_S_c_r_e_e_n function if you
          are using languages other than C (see section
          2.2.1).
││__

For example, the following would specify screen 1 of display
0 on the machine named ‘‘dual‐headed’’:


     dual‐headed:0.1


The _X_O_p_e_n_D_i_s_p_l_a_y function returns a _D_i_s_p_l_a_y structure that
serves as the connection to the X server and that contains
all the information about that X server.  _X_O_p_e_n_D_i_s_p_l_a_y con­
nects your application to the X server through TCP or DECnet
communications protocols, or through some local inter‐pro­
cess communication protocol.  If the protocol is specified
as "tcp", "inet", or "inet6", or if no protocol is specified
and the hostname is a host machine name and a single colon
(:) separates the hostname and display number, _X_O_p_e_n_D_i_s_p_l_a_y
connects using TCP streams.  (If the protocol is specified
as "inet", TCP over IPv4 is used.  If the protocol is



                             1122





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


specified as "inet6", TCP over IPv6 is used.  Otherwise, the
implementation determines which IP version is used.)  If the
hostname and protocol are both not specified, Xlib uses
whatever it believes is the fastest transport.  If the host­
name is a host machine name and a double colon (::) sepa­
rates the hostname and display number, _X_O_p_e_n_D_i_s_p_l_a_y connects
using DECnet.  A single X server can support any or all of
these transport mechanisms simultaneously.  A particular
Xlib implementation can support many more of these transport
mechanisms.

If successful, _X_O_p_e_n_D_i_s_p_l_a_y returns a pointer to a _D_i_s_p_l_a_y
structure, which is defined in <_X_1_1_/_X_l_i_b_._h>.  If _X_O_p_e_n_D_i_s_­
_p_l_a_y does not succeed, it returns NULL.  After a successful
call to _X_O_p_e_n_D_i_s_p_l_a_y, all of the screens in the display can
be used by the client.  The screen number specified in the
display_name argument is returned by the _D_e_f_a_u_l_t_S_c_r_e_e_n macro
(or the _X_D_e_f_a_u_l_t_S_c_r_e_e_n function).  You can access elements
of the _D_i_s_p_l_a_y and _S_c_r_e_e_n structures only by using the
information macros or functions.  For information about
using macros and functions to obtain information from the
_D_i_s_p_l_a_y structure, see section 2.2.1.

X servers may implement various types of access control
mechanisms (see section 9.8).

22..22..  OObbttaaiinniinngg IInnffoorrmmaattiioonn aabboouutt tthhee DDiissppllaayy,, IImmaaggee FFoorr­­
mmaattss,, oorr SSccrreeeennss

The Xlib library provides a number of useful macros and cor­
responding functions that return data from the _D_i_s_p_l_a_y
structure.  The macros are used for C programming, and their
corresponding function equivalents are for other language
bindings.  This section discusses the:

⋅    Display macros

⋅    Image format functions and macros

⋅    Screen information macros

All other members of the _D_i_s_p_l_a_y structure (that is, those
for which no macros are defined) are private to Xlib and
must not be used.  Applications must never directly modify
or inspect these private members of the _D_i_s_p_l_a_y structure.

                            Note

     The _X_D_i_s_p_l_a_y_W_i_d_t_h, _X_D_i_s_p_l_a_y_H_e_i_g_h_t, _X_D_i_s_p_l_a_y_C_e_l_l_s,
     _X_D_i_s_p_l_a_y_P_l_a_n_e_s, _X_D_i_s_p_l_a_y_W_i_d_t_h_M_M, and _X_D_i_s_p_l_a_y_­
     _H_e_i_g_h_t_M_M functions in the next sections are mis­
     named.  These functions really should be named
     Screen_w_h_a_t_e_v_e_r and XScreen_w_h_a_t_e_v_e_r, not Display­
     _w_h_a_t_e_v_e_r or XDisplay_w_h_a_t_e_v_e_r.  Our apologies for



                             1133





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     the resulting confusion.


22..22..11..  DDiissppllaayy MMaaccrrooss

Applications should not directly modify any part of the _D_i_s_­
_p_l_a_y and _S_c_r_e_e_n structures.  The members should be consid­
ered read‐only, although they may change as the result of
other operations on the display.

The following lists the C language macros, their correspond­
ing function equivalents that are for other language bind­
ings, and what data both can return.


__
││
AllPlanes

unsigned long XAllPlanes()

││__

Both return a value with all bits set to 1 suitable for use
in a plane argument to a procedure.


Both _B_l_a_c_k_P_i_x_e_l and _W_h_i_t_e_P_i_x_e_l can be used in implementing a
monochrome application.  These pixel values are for perma­
nently allocated entries in the default colormap.  The
actual RGB (red, green, and blue) values are settable on
some screens and, in any case, may not actually be black or
white.  The names are intended to convey the expected rela­
tive intensity of the colors.
__
││
BlackPixel(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

unsigned long XBlackPixel(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the black pixel value for the specified screen.






                             1144





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
WhitePixel(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

unsigned long XWhitePixel(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the white pixel value for the specified screen.


__
││
ConnectionNumber(_d_i_s_p_l_a_y)

int XConnectionNumber(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return a connection number for the specified display.
On a POSIX‐conformant system, this is the file descriptor of
the connection.


__
││
DefaultColormap(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

Colormap XDefaultColormap(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the default colormap ID for allocation on the
specified screen.  Most routine allocations of color should
be made out of this colormap.




                             1155





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
DefaultDepth(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

int XDefaultDepth(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the depth (number of planes) of the default root
window for the specified screen.  Other depths may also be
supported on this screen (see _X_M_a_t_c_h_V_i_s_u_a_l_I_n_f_o).


To determine the number of depths that are available on a
given screen, use _X_L_i_s_t_D_e_p_t_h_s.
__
││
int *XListDepths(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r, _c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;
      int *_c_o_u_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of depths.
││__

The _X_L_i_s_t_D_e_p_t_h_s function returns the array of depths that
are available on the specified screen.  If the specified
screen_number is valid and sufficient memory for the array
can be allocated, _X_L_i_s_t_D_e_p_t_h_s sets count_return to the num­
ber of available depths.  Otherwise, it does not set
count_return and returns NULL.  To release the memory allo­
cated for the array of depths, use _X_F_r_e_e.










                             1166





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
DefaultGC(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

GC XDefaultGC(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the default graphics context for the root window
of the specified screen.  This GC is created for the conve­
nience of simple applications and contains the default GC
components with the foreground and background pixel values
initialized to the black and white pixels for the screen,
respectively.  You can modify its contents freely because it
is not used in any Xlib function.  This GC should never be
freed.


__
││
DefaultRootWindow(_d_i_s_p_l_a_y)

Window XDefaultRootWindow(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return the root window for the default screen.


__
││
DefaultScreenOfDisplay(_d_i_s_p_l_a_y)

Screen *XDefaultScreenOfDisplay(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return a pointer to the default screen.






                             1177





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
ScreenOfDisplay(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

Screen *XScreenOfDisplay(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return a pointer to the indicated screen.


__
││
DefaultScreen(_d_i_s_p_l_a_y)

int XDefaultScreen(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return the default screen number referenced by the
_X_O_p_e_n_D_i_s_p_l_a_y function.  This macro or function should be
used to retrieve the screen number in applications that will
use only a single screen.


__
││
DefaultVisual(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

Visual *XDefaultVisual(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the default visual type for the specified
screen.  For further information about visual types, see
section 3.1.



                             1188





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
DisplayCells(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

int XDisplayCells(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the number of entries in the default colormap.


__
││
DisplayPlanes(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

int XDisplayPlanes(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the depth of the root window of the specified
screen.  For an explanation of depth, see the glossary.


__
││
DisplayString(_d_i_s_p_l_a_y)

char *XDisplayString(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return the string that was passed to _X_O_p_e_n_D_i_s_p_l_a_y when
the current display was opened.  On POSIX‐conformant sys­
tems, if the passed string was NULL, these return the value
of the DISPLAY environment variable when the current display
was opened.  These are useful to applications that invoke



                             1199





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the _f_o_r_k system call and want to open a new connection to
the same display from the child process as well as for
printing error messages.


__
││
long XExtendedMaxRequestSize(_d_i_s_p_l_a_y)
     Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_E_x_t_e_n_d_e_d_M_a_x_R_e_q_u_e_s_t_S_i_z_e function returns zero if the
specified display does not support an extended‐length proto­
col encoding; otherwise, it returns the maximum request size
(in 4‐byte units) supported by the server using the
extended‐length encoding.  The Xlib functions _X_D_r_a_w_L_i_n_e_s,
_X_D_r_a_w_A_r_c_s, _X_F_i_l_l_P_o_l_y_g_o_n, _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y, _X_S_e_t_C_l_i_p_R_e_c_t_a_n_­
_g_l_e_s, and _X_S_e_t_R_e_g_i_o_n will use the extended‐length encoding
as necessary, if supported by the server.  Use of the
extended‐length encoding in other Xlib functions (for exam­
ple, _X_D_r_a_w_P_o_i_n_t_s, _X_D_r_a_w_R_e_c_t_a_n_g_l_e_s, _X_D_r_a_w_S_e_g_m_e_n_t_s, _X_F_i_l_l_A_r_c_s,
_X_F_i_l_l_R_e_c_t_a_n_g_l_e_s, _X_P_u_t_I_m_a_g_e) is permitted but not required;
an Xlib implementation may choose to split the data across
multiple smaller requests instead.


__
││
long XMaxRequestSize(_d_i_s_p_l_a_y)
     Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_M_a_x_R_e_q_u_e_s_t_S_i_z_e function returns the maximum request
size (in 4‐byte units) supported by the server without using
an extended‐length protocol encoding.  Single protocol
requests to the server can be no larger than this size
unless an extended‐length protocol encoding is supported by
the server.  The protocol guarantees the size to be no
smaller than 4096 units (16384 bytes).  Xlib automatically
breaks data up into multiple protocol requests as necessary
for the following functions: _X_D_r_a_w_P_o_i_n_t_s, _X_D_r_a_w_R_e_c_t_a_n_g_l_e_s,
_X_D_r_a_w_S_e_g_m_e_n_t_s, _X_F_i_l_l_A_r_c_s, _X_F_i_l_l_R_e_c_t_a_n_g_l_e_s, and _X_P_u_t_I_m_a_g_e.









                             2200





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
LastKnownRequestProcessed(_d_i_s_p_l_a_y)

unsigned long XLastKnownRequestProcessed(_d_i_s_p_l_a_y)
     Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both extract the full serial number of the last request
known by Xlib to have been processed by the X server.  Xlib
automatically sets this number when replies, events, and
errors are received.


__
││
NextRequest(_d_i_s_p_l_a_y)

unsigned long XNextRequest(_d_i_s_p_l_a_y)
     Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both extract the full serial number that is to be used for
the next request.  Serial numbers are maintained separately
for each display connection.


__
││
ProtocolVersion(_d_i_s_p_l_a_y)

int XProtocolVersion(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return the major version number (11) of the X protocol
associated with the connected display.












                             2211





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
ProtocolRevision(_d_i_s_p_l_a_y)

int XProtocolRevision(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return the minor protocol revision number of the X
server.


__
││
QLength(_d_i_s_p_l_a_y)

int XQLength(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return the length of the event queue for the connected
display.  Note that there may be more events that have not
been read into the queue yet (see _X_E_v_e_n_t_s_Q_u_e_u_e_d).


__
││
RootWindow(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

Window XRootWindow(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the root window.  These are useful with func­
tions that need a drawable of a particular screen and for
creating top‐level windows.








                             2222





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
ScreenCount(_d_i_s_p_l_a_y)

int XScreenCount(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return the number of available screens.


__
││
ServerVendor(_d_i_s_p_l_a_y)

char *XServerVendor(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return a pointer to a null‐terminated string that pro­
vides some identification of the owner of the X server
implementation.  If the data returned by the server is in
the Latin Portable Character Encoding, then the string is in
the Host Portable Character Encoding.  Otherwise, the con­
tents of the string are implementation‐dependent.


__
││
VendorRelease(_d_i_s_p_l_a_y)

int XVendorRelease(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return a number related to a vendor’s release of the X
server.

22..22..22..  IImmaaggee FFoorrmmaatt FFuunnccttiioonnss aanndd MMaaccrrooss

Applications are required to present data to the X server in
a format that the server demands.  To help simplify applica­
tions, most of the work required to convert the data is pro­
vided by Xlib (see sections 8.7 and 16.8).





                             2233





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The _X_P_i_x_m_a_p_F_o_r_m_a_t_V_a_l_u_e_s structure provides an interface to
the pixmap format information that is returned at the time
of a connection setup.  It contains:

__
││
typedef struct {
     int depth;
     int bits_per_pixel;
     int scanline_pad;
} XPixmapFormatValues;

││__


To obtain the pixmap format information for a given display,
use _X_L_i_s_t_P_i_x_m_a_p_F_o_r_m_a_t_s.
__
││
XPixmapFormatValues *XListPixmapFormats(_d_i_s_p_l_a_y, _c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int *_c_o_u_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of pixmap formats that are sup­
          ported by the display.
││__

The _X_L_i_s_t_P_i_x_m_a_p_F_o_r_m_a_t_s function returns an array of _X_P_i_x_m_a_p_­
_F_o_r_m_a_t_V_a_l_u_e_s structures that describe the types of Z format
images supported by the specified display.  If insufficient
memory is available, _X_L_i_s_t_P_i_x_m_a_p_F_o_r_m_a_t_s returns NULL.  To
free the allocated storage for the _X_P_i_x_m_a_p_F_o_r_m_a_t_V_a_l_u_e_s
structures, use _X_F_r_e_e.

The following lists the C language macros, their correspond­
ing function equivalents that are for other language bind­
ings, and what data they both return for the specified
server and screen.  These are often used by toolkits as well
as by simple applications.














                             2244





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
ImageByteOrder(_d_i_s_p_l_a_y)

int XImageByteOrder(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both specify the required byte order for images for each
scanline unit in XY format (bitmap) or for each pixel value
in Z format.  The macro or function can return either _L_S_B_­
_F_i_r_s_t or _M_S_B_F_i_r_s_t.


__
││
BitmapUnit(_d_i_s_p_l_a_y)

int XBitmapUnit(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Both return the size of a bitmap’s scanline unit in bits.
The scanline is calculated in multiples of this value.


__
││
BitmapBitOrder(_d_i_s_p_l_a_y)

int XBitmapBitOrder(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Within each bitmap unit, the left‐most bit in the bitmap as
displayed on the screen is either the least significant or
most significant bit in the unit.  This macro or function
can return _L_S_B_F_i_r_s_t or _M_S_B_F_i_r_s_t.











                             2255





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
BitmapPad(_d_i_s_p_l_a_y)

int XBitmapPad(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

Each scanline must be padded to a multiple of bits returned
by this macro or function.


__
││
DisplayHeight(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

int XDisplayHeight(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return an integer that describes the height of the
screen in pixels.


__
││
DisplayHeightMM(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

int XDisplayHeightMM(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the height of the specified screen in millime­
ters.





                             2266





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
DisplayWidth(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

int XDisplayWidth(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the width of the screen in pixels.


__
││
DisplayWidthMM(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)

int XDisplayWidthMM(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

Both return the width of the specified screen in millime­
ters.

22..22..33..  SSccrreeeenn IInnffoorrmmaattiioonn MMaaccrrooss

The following lists the C language macros, their correspond­
ing function equivalents that are for other language bind­
ings, and what data they both can return.  These macros or
functions all take a pointer to the appropriate screen
structure.













                             2277





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
BlackPixelOfScreen(_s_c_r_e_e_n)

unsigned long XBlackPixelOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the black pixel value of the specified screen.


__
││
WhitePixelOfScreen(_s_c_r_e_e_n)

unsigned long XWhitePixelOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the white pixel value of the specified screen.


__
││
CellsOfScreen(_s_c_r_e_e_n)

int XCellsOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the number of colormap cells in the default col­
ormap of the specified screen.


__
││
DefaultColormapOfScreen(_s_c_r_e_e_n)

Colormap XDefaultColormapOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the default colormap of the specified screen.



                             2288





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
DefaultDepthOfScreen(_s_c_r_e_e_n)

int XDefaultDepthOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the depth of the root window.


__
││
DefaultGCOfScreen(_s_c_r_e_e_n)

GC XDefaultGCOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return a default graphics context (GC) of the specified
screen, which has the same depth as the root window of the
screen.  The GC must never be freed.


__
││
DefaultVisualOfScreen(_s_c_r_e_e_n)

Visual *XDefaultVisualOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the default visual of the specified screen.  For
information on visual types, see section 3.1.















                             2299





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
DoesBackingStore(_s_c_r_e_e_n)

int XDoesBackingStore(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return a value indicating whether the screen supports
backing stores.  The value returned can be one of _W_h_e_n_­
_M_a_p_p_e_d, _N_o_t_U_s_e_f_u_l, or _A_l_w_a_y_s (see section 3.2.4).


__
││
DoesSaveUnders(_s_c_r_e_e_n)

Bool XDoesSaveUnders(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return a Boolean value indicating whether the screen
supports save unders.  If _T_r_u_e, the screen supports save
unders.  If _F_a_l_s_e, the screen does not support save unders
(see section 3.2.5).


__
││
DisplayOfScreen(_s_c_r_e_e_n)

Display *XDisplayOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the display of the specified screen.













                             3300





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XScreenNumberOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

The _X_S_c_r_e_e_n_N_u_m_b_e_r_O_f_S_c_r_e_e_n function returns the screen index
number of the specified screen.


__
││
EventMaskOfScreen(_s_c_r_e_e_n)

long XEventMaskOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the event mask of the root window for the speci­
fied screen at connection setup time.


__
││
WidthOfScreen(_s_c_r_e_e_n)

int XWidthOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the width of the specified screen in pixels.


__
││
HeightOfScreen(_s_c_r_e_e_n)

int XHeightOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the height of the specified screen in pixels.




                             3311





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
WidthMMOfScreen(_s_c_r_e_e_n)

int XWidthMMOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the width of the specified screen in millime­
ters.


__
││
HeightMMOfScreen(_s_c_r_e_e_n)

int XHeightMMOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the height of the specified screen in millime­
ters.


__
││
MaxCmapsOfScreen(_s_c_r_e_e_n)

int XMaxCmapsOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the maximum number of installed colormaps sup­
ported by the specified screen (see section 9.3).















                             3322





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
MinCmapsOfScreen(_s_c_r_e_e_n)

int XMinCmapsOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the minimum number of installed colormaps sup­
ported by the specified screen (see section 9.3).


__
││
PlanesOfScreen(_s_c_r_e_e_n)

int XPlanesOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the depth of the root window.


__
││
RootWindowOfScreen(_s_c_r_e_e_n)

Window XRootWindowOfScreen(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the appropriate _S_c_r_e_e_n structure.
││__

Both return the root window of the specified screen.

22..33..  GGeenneerraattiinngg aa NNooOOppeerraattiioonn PPrroottooccooll RReeqquueesstt

To execute a _N_o_O_p_e_r_a_t_i_o_n protocol request, use _X_N_o_O_p.
__
││
XNoOp(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_N_o_O_p function sends a _N_o_O_p_e_r_a_t_i_o_n protocol request to



                             3333





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the X server, thereby exercising the connection.

22..44..  FFrreeeeiinngg CClliieenntt‐‐CCrreeaatteedd DDaattaa

To free in‐memory data that was created by an Xlib function,
use _X_F_r_e_e.
__
││
XFree(_d_a_t_a)
     void *_d_a_t_a;


_d_a_t_a      Specifies the data that is to be freed.
││__

The _X_F_r_e_e function is a general‐purpose Xlib routine that
frees the specified data.  You must use it to free any
objects that were allocated by Xlib, unless an alternate
function is explicitly specified for the object.  A NULL
pointer cannot be passed to this function.

22..55..  CClloossiinngg tthhee DDiissppllaayy

To close a display or disconnect from the X server, use
_X_C_l_o_s_e_D_i_s_p_l_a_y.

__
││
XCloseDisplay(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_C_l_o_s_e_D_i_s_p_l_a_y function closes the connection to the X
server for the display specified in the _D_i_s_p_l_a_y structure
and destroys all windows, resource IDs (_W_i_n_d_o_w, _F_o_n_t,
_P_i_x_m_a_p, _C_o_l_o_r_m_a_p, _C_u_r_s_o_r, and _G_C_o_n_t_e_x_t), or other resources
that the client has created on this display, unless the
close‐down mode of the resource has been changed (see _X_S_e_t_­
_C_l_o_s_e_D_o_w_n_M_o_d_e).  Therefore, these windows, resource IDs, and
other resources should never be referenced again or an error
will be generated.  Before exiting, you should call
_X_C_l_o_s_e_D_i_s_p_l_a_y explicitly so that any pending errors are
reported as _X_C_l_o_s_e_D_i_s_p_l_a_y performs a final _X_S_y_n_c operation.

_X_C_l_o_s_e_D_i_s_p_l_a_y can generate a _B_a_d_G_C error.


Xlib provides a function to permit the resources owned by a
client to survive after the client’s connection is closed.
To change a client’s close‐down mode, use _X_S_e_t_C_l_o_s_e_D_o_w_n_M_o_d_e.




                             3344





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetCloseDownMode(_d_i_s_p_l_a_y, _c_l_o_s_e___m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      int _c_l_o_s_e___m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_l_o_s_e___m_o_d_e
          Specifies the client close‐down mode.  You can
          pass _D_e_s_t_r_o_y_A_l_l, _R_e_t_a_i_n_P_e_r_m_a_n_e_n_t, or _R_e_t_a_i_n_T_e_m_p_o_­
          _r_a_r_y.
││__

The _X_S_e_t_C_l_o_s_e_D_o_w_n_M_o_d_e defines what will happen to the
client’s resources at connection close.  A connection starts
in _D_e_s_t_r_o_y_A_l_l mode.  For information on what happens to the
client’s resources when the close_mode argument is _R_e_t_a_i_n_­
_P_e_r_m_a_n_e_n_t or _R_e_t_a_i_n_T_e_m_p_o_r_a_r_y, see section 2.6.

_X_S_e_t_C_l_o_s_e_D_o_w_n_M_o_d_e can generate a _B_a_d_V_a_l_u_e error.

22..66..  UUssiinngg XX SSeerrvveerr CCoonnnneeccttiioonn CClloossee OOppeerraattiioonnss

When the X server’s connection to a client is closed either
by an explicit call to _X_C_l_o_s_e_D_i_s_p_l_a_y or by a process that
exits, the X server performs the following automatic opera­
tions:

⋅    It disowns all selections owned by the client (see
     _X_S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r).

⋅    It performs an _X_U_n_g_r_a_b_P_o_i_n_t_e_r and _X_U_n_g_r_a_b_K_e_y_b_o_a_r_d if
     the client has actively grabbed the pointer or the key­
     board.

⋅    It performs an _X_U_n_g_r_a_b_S_e_r_v_e_r if the client has grabbed
     the server.

⋅    It releases all passive grabs made by the client.

⋅    It marks all resources (including colormap entries)
     allocated by the client either as permanent or tempo­
     rary, depending on whether the close‐down mode is
     _R_e_t_a_i_n_P_e_r_m_a_n_e_n_t or _R_e_t_a_i_n_T_e_m_p_o_r_a_r_y.  However, this does
     not prevent other client applications from explicitly
     destroying the resources (see _X_S_e_t_C_l_o_s_e_D_o_w_n_M_o_d_e).

When the close‐down mode is _D_e_s_t_r_o_y_A_l_l, the X server
destroys all of a client’s resources as follows:

⋅    It examines each window in the client’s save‐set to
     determine if it is an inferior (subwindow) of a window
     created by the client.  (The save‐set is a list of



                             3355





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     other clients’ windows that are referred to as save‐set
     windows.)  If so, the X server reparents the save‐set
     window to the closest ancestor so that the save‐set
     window is not an inferior of a window created by the
     client.  The reparenting leaves unchanged the absolute
     coordinates (with respect to the root window) of the
     upper‐left outer corner of the save‐set window.

⋅    It performs a _M_a_p_W_i_n_d_o_w request on the save‐set window
     if the save‐set window is unmapped.  The X server does
     this even if the save‐set window was not an inferior of
     a window created by the client.

⋅    It destroys all windows created by the client.

⋅    It performs the appropriate free request on each non­
     window resource created by the client in the server
     (for example, _F_o_n_t, _P_i_x_m_a_p, _C_u_r_s_o_r, _C_o_l_o_r_m_a_p, and _G_C_o_n_­
     _t_e_x_t).

⋅    It frees all colors and colormap entries allocated by a
     client application.

Additional processing occurs when the last connection to the
X server closes.  An X server goes through a cycle of having
no connections and having some connections.  When the last
connection to the X server closes as a result of a connec­
tion closing with the close_mode of _D_e_s_t_r_o_y_A_l_l, the X server
does the following:

⋅    It resets its state as if it had just been started.
     The X server begins by destroying all lingering
     resources from clients that have terminated in _R_e_t_a_i_n_­
     _P_e_r_m_a_n_e_n_t or _R_e_t_a_i_n_T_e_m_p_o_r_a_r_y mode.

⋅    It deletes all but the predefined atom identifiers.

⋅    It deletes all properties on all root windows (see sec­
     tion 4.3).

⋅    It resets all device maps and attributes (for example,
     key click, bell volume, and acceleration) as well as
     the access control list.

⋅    It restores the standard root tiles and cursors.

⋅    It restores the default font path.

⋅    It restores the input focus to state _P_o_i_n_t_e_r_R_o_o_t.

However, the X server does not reset if you close a connec­
tion with a close‐down mode set to _R_e_t_a_i_n_P_e_r_m_a_n_e_n_t or
_R_e_t_a_i_n_T_e_m_p_o_r_a_r_y.




                             3366





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


22..77..  UUssiinngg XXlliibb wwiitthh TThhrreeaaddss

On systems that have threads, support may be provided to
permit multiple threads to use Xlib concurrently.


To initialize support for concurrent threads, use _X_I_n_i_t_­
_T_h_r_e_a_d_s.
__
││
Status XInitThreads();

││__

The _X_I_n_i_t_T_h_r_e_a_d_s function initializes Xlib support for con­
current threads.  This function must be the first Xlib func­
tion a multi‐threaded program calls, and it must complete
before any other Xlib call is made.  This function returns a
nonzero status if initialization was successful; otherwise,
it returns zero.  On systems that do not support threads,
this function always returns zero.

It is only necessary to call this function if multiple
threads might use Xlib concurrently.  If all calls to Xlib
functions are protected by some other access mechanism (for
example, a mutual exclusion lock in a toolkit or through
explicit client programming), Xlib thread initialization is
not required.  It is recommended that single‐threaded pro­
grams not call this function.



To lock a display across several Xlib calls, use _X_L_o_c_k_D_i_s_­
_p_l_a_y.
__
││
void XLockDisplay(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_L_o_c_k_D_i_s_p_l_a_y function locks out all other threads from
using the specified display.  Other threads attempting to
use the display will block until the display is unlocked by
this thread.  Nested calls to _X_L_o_c_k_D_i_s_p_l_a_y work correctly;
the display will not actually be unlocked until _X_U_n_l_o_c_k_D_i_s_­
_p_l_a_y has been called the same number of times as _X_L_o_c_k_D_i_s_­
_p_l_a_y.  This function has no effect unless Xlib was success­
fully initialized for threads using _X_I_n_i_t_T_h_r_e_a_d_s.


To unlock a display, use _X_U_n_l_o_c_k_D_i_s_p_l_a_y.



                             3377





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XUnlockDisplay(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_U_n_l_o_c_k_D_i_s_p_l_a_y function allows other threads to use the
specified display again.  Any threads that have blocked on
the display are allowed to continue.  Nested locking works
correctly; if _X_L_o_c_k_D_i_s_p_l_a_y has been called multiple times by
a thread, then _X_U_n_l_o_c_k_D_i_s_p_l_a_y must be called an equal number
of times before the display is actually unlocked.  This
function has no effect unless Xlib was successfully initial­
ized for threads using _X_I_n_i_t_T_h_r_e_a_d_s.

22..88..  UUssiinngg IInntteerrnnaall CCoonnnneeccttiioonnss

In addition to the connection to the X server, an Xlib
implementation may require connections to other kinds of
servers (for example, to input method servers as described
in chapter 13).  Toolkits and clients that use multiple dis­
plays, or that use displays in combination with other
inputs, need to obtain these additional connections to cor­
rectly block until input is available and need to process
that input when it is available.  Simple clients that use a
single display and block for input in an Xlib event function
do not need to use these facilities.

To track internal connections for a display, use _X_A_d_d_C_o_n_n_e_c_­
_t_i_o_n_W_a_t_c_h.

























                             3388





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef void (*XConnectionWatchProc)(_d_i_s_p_l_a_y, _c_l_i_e_n_t___d_a_t_a, _f_d, _o_p_e_n_i_n_g, _w_a_t_c_h___d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      int _f_d;
      Bool _o_p_e_n_i_n_g;
      XPointer *_w_a_t_c_h___d_a_t_a;

Status XAddConnectionWatch(_d_i_s_p_l_a_y, _p_r_o_c_e_d_u_r_e, _c_l_i_e_n_t___d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      XWatchProc _p_r_o_c_e_d_u_r_e;
      XPointer _c_l_i_e_n_t___d_a_t_a;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_r_o_c_e_d_u_r_e Specifies the procedure to be called.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.
││__

The _X_A_d_d_C_o_n_n_e_c_t_i_o_n_W_a_t_c_h function registers a procedure to be
called each time Xlib opens or closes an internal connection
for the specified display.  The procedure is passed the dis­
play, the specified client_data, the file descriptor for the
connection, a Boolean indicating whether the connection is
being opened or closed, and a pointer to a location for pri­
vate watch data.  If opening is _T_r_u_e, the procedure can
store a pointer to private data in the location pointed to
by watch_data; when the procedure is later called for this
same connection and opening is _F_a_l_s_e, the location pointed
to by watch_data will hold this same private data pointer.

This function can be called at any time after a display is
opened.  If internal connections already exist, the regis­
tered procedure will immediately be called for each of them,
before _X_A_d_d_C_o_n_n_e_c_t_i_o_n_W_a_t_c_h returns.  _X_A_d_d_C_o_n_n_e_c_t_i_o_n_W_a_t_c_h
returns a nonzero status if the procedure is successfully
registered; otherwise, it returns zero.

The registered procedure should not call any Xlib functions.
If the procedure directly or indirectly causes the state of
internal connections or watch procedures to change, the
result is not defined.  If Xlib has been initialized for
threads, the procedure is called with the display locked and
the result of a call by the procedure to any Xlib function
that locks the display is not defined unless the executing
thread has externally locked the display using _X_L_o_c_k_D_i_s_p_l_a_y.


To stop tracking internal connections for a display, use
_X_R_e_m_o_v_e_C_o_n_n_e_c_t_i_o_n_W_a_t_c_h.




                             3399





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XRemoveConnectionWatch(_d_i_s_p_l_a_y, _p_r_o_c_e_d_u_r_e, _c_l_i_e_n_t___d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      XWatchProc _p_r_o_c_e_d_u_r_e;
      XPointer _c_l_i_e_n_t___d_a_t_a;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_r_o_c_e_d_u_r_e Specifies the procedure to be called.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.
││__

The _X_R_e_m_o_v_e_C_o_n_n_e_c_t_i_o_n_W_a_t_c_h function removes a previously
registered connection watch procedure.  The client_data must
match the client_data used when the procedure was initially
registered.



To process input on an internal connection, use _X_P_r_o_c_e_s_s_I_n_­
_t_e_r_n_a_l_C_o_n_n_e_c_t_i_o_n.
__
││
void XProcessInternalConnection(_d_i_s_p_l_a_y, _f_d)
      Display *_d_i_s_p_l_a_y;
      int _f_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_d        Specifies the file descriptor.
││__

The _X_P_r_o_c_e_s_s_I_n_t_e_r_n_a_l_C_o_n_n_e_c_t_i_o_n function processes input
available on an internal connection.  This function should
be called for an internal connection only after an operating
system facility (for example, _s_e_l_e_c_t or _p_o_l_l) has indicated
that input is available; otherwise, the effect is not
defined.


To obtain all of the current internal connections for a dis­
play, use _X_I_n_t_e_r_n_a_l_C_o_n_n_e_c_t_i_o_n_N_u_m_b_e_r_s.











                             4400





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XInternalConnectionNumbers(_d_i_s_p_l_a_y, _f_d___r_e_t_u_r_n, _c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int **_f_d___r_e_t_u_r_n;
      int *_c_o_u_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_d___r_e_t_u_r_n Returns the file descriptors.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of file descriptors.
││__

The _X_I_n_t_e_r_n_a_l_C_o_n_n_e_c_t_i_o_n_N_u_m_b_e_r_s function returns a list of
the file descriptors for all internal connections currently
open for the specified display.  When the allocated list is
no longer needed, free it by using _X_F_r_e_e.  This functions
returns a nonzero status if the list is successfully allo­
cated; otherwise, it returns zero.




































                             4411





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 33

                      WWiinnddooww FFuunnccttiioonnss



In the X Window System, a window is a rectangular area on
the screen that lets you view graphic output.  Client appli­
cations can display overlapping and nested windows on one or
more screens that are driven by X servers on one or more
machines.  Clients who want to create windows must first
connect their program to the X server by calling _X_O_p_e_n_D_i_s_­
_p_l_a_y.  This chapter begins with a discussion of visual types
and window attributes.  The chapter continues with a discus­
sion of the Xlib functions you can use to:

⋅    Create windows

⋅    Destroy windows

⋅    Map windows

⋅    Unmap windows

⋅    Configure windows

⋅    Change window stacking order

⋅    Change window attributes

This chapter also identifies the window actions that may
generate events.

Note that it is vital that your application conform to the
established conventions for communicating with window man­
agers for it to work well with the various window managers
in use (see section 14.1).  Toolkits generally adhere to
these conventions for you, relieving you of the burden.
Toolkits also often supersede many functions in this chapter
with versions of their own.  For more information, refer to
the documentation for the toolkit that you are using.

33..11..  VViissuuaall TTyyppeess

On some display hardware, it may be possible to deal with
color resources in more than one way.  For example, you may
be able to deal with a screen of either 12‐bit depth with
arbitrary mapping of pixel to color (pseudo‐color) or 24‐bit
depth with 8 bits of the pixel dedicated to each of red,
green, and blue.  These different ways of dealing with the
visual aspects of the screen are called visuals.  For each
screen of the display, there may be a list of valid visual



                             4422





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


types supported at different depths of the screen.  Because
default windows and visual types are defined for each
screen, most simple applications need not deal with this
complexity.  Xlib provides macros and functions that return
the default root window, the default depth of the default
root window, and the default visual type (see sections 2.2.1
and 16.7).

Xlib uses an opaque _V_i_s_u_a_l structure that contains informa­
tion about the possible color mapping.  The visual utility
functions (see section 16.7) use an _X_V_i_s_u_a_l_I_n_f_o structure to
return this information to an application.  The members of
this structure pertinent to this discussion are class,
red_mask, green_mask, blue_mask, bits_per_rgb, and col­
ormap_size.  The class member specifies one of the possible
visual classes of the screen and can be _S_t_a_t_i_c_G_r_a_y, _S_t_a_t_i_c_­
_C_o_l_o_r, _T_r_u_e_C_o_l_o_r, _G_r_a_y_S_c_a_l_e, _P_s_e_u_d_o_C_o_l_o_r, or _D_i_r_e_c_t_C_o_l_o_r.

The following concepts may serve to make the explanation of
visual types clearer.  The screen can be color or grayscale,
can have a colormap that is writable or read‐only, and can
also have a colormap whose indices are decomposed into sepa­
rate RGB pieces, provided one is not on a grayscale screen.
This leads to the following diagram:



                             Color          Gray‐scale
                         R/O      R/W      R/O      R/W
        +-------------+--------+--------+--------+-------+
        |Undecomposed | Static | Pseudo | Static | Gray  |
        |  Colormap   | Color  | Color  |  Gray  | Scale |
        +-------------+--------+--------+--------+-------+
        | Decomposed  |  True  | Direct |
        |  Colormap   | Color  | Color  |
        +-------------+--------+--------+



Conceptually, as each pixel is read out of video memory for
display on the screen, it goes through a look‐up stage by
indexing into a colormap.  Colormaps can be manipulated
arbitrarily on some hardware, in limited ways on other hard­
ware, and not at all on other hardware.  The visual types
affect the colormap and the RGB values in the following
ways:


⋅    For _P_s_e_u_d_o_C_o_l_o_r, a pixel value indexes a colormap to
     produce independent RGB values, and the RGB values can
     be changed dynamically.

⋅    _G_r_a_y_S_c_a_l_e is treated the same way as _P_s_e_u_d_o_C_o_l_o_r except
     that the primary that drives the screen is undefined.



                             4433





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     Thus, the client should always store the same value for
     red, green, and blue in the colormaps.

⋅    For _D_i_r_e_c_t_C_o_l_o_r, a pixel value is decomposed into sepa­
     rate RGB subfields, and each subfield separately
     indexes the colormap for the corresponding value.  The
     RGB values can be changed dynamically.

⋅    _T_r_u_e_C_o_l_o_r is treated the same way as _D_i_r_e_c_t_C_o_l_o_r except
     that the colormap has predefined, read‐only RGB values.
     These RGB values are server dependent but provide lin­
     ear or near‐linear ramps in each primary.

⋅    _S_t_a_t_i_c_C_o_l_o_r is treated the same way as _P_s_e_u_d_o_C_o_l_o_r
     except that the colormap has predefined, read‐only,
     server‐dependent RGB values.

⋅    _S_t_a_t_i_c_G_r_a_y is treated the same way as _S_t_a_t_i_c_C_o_l_o_r
     except that the RGB values are equal for any single
     pixel value, thus resulting in shades of gray.  _S_t_a_t_­
     _i_c_G_r_a_y with a two‐entry colormap can be thought of as
     monochrome.

The red_mask, green_mask, and blue_mask members are only
defined for _D_i_r_e_c_t_C_o_l_o_r and _T_r_u_e_C_o_l_o_r.  Each has one con­
tiguous set of bits with no intersections.  The bits_per_rgb
member specifies the log base 2 of the number of distinct
color values (individually) of red, green, and blue.  Actual
RGB values are unsigned 16‐bit numbers.  The colormap_size
member defines the number of available colormap entries in a
newly created colormap.  For _D_i_r_e_c_t_C_o_l_o_r and _T_r_u_e_C_o_l_o_r, this
is the size of an individual pixel subfield.


To obtain the visual ID from a _V_i_s_u_a_l, use _X_V_i_s_u_a_l_I_D_F_r_o_m_V_i_­
_s_u_a_l.
__
││
VisualID XVisualIDFromVisual(_v_i_s_u_a_l)
       Visual *_v_i_s_u_a_l;


_v_i_s_u_a_l    Specifies the visual type.
││__

The _X_V_i_s_u_a_l_I_D_F_r_o_m_V_i_s_u_a_l function returns the visual ID for
the specified visual type.

33..22..  WWiinnddooww AAttttrriibbuutteess

All _I_n_p_u_t_O_u_t_p_u_t windows have a border width of zero or more
pixels, an optional background, an event suppression mask
(which suppresses propagation of events from children), and
a property list (see section 4.3).  The window border and



                             4444





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


background can be a solid color or a pattern, called a tile.
All windows except the root have a parent and are clipped by
their parent.  If a window is stacked on top of another win­
dow, it obscures that other window for the purpose of input.
If a window has a background (almost all do), it obscures
the other window for purposes of output.  Attempts to output
to the obscured area do nothing, and no input events (for
example, pointer motion) are generated for the obscured
area.

Windows also have associated property lists (see section
4.3).

Both _I_n_p_u_t_O_u_t_p_u_t and _I_n_p_u_t_O_n_l_y windows have the following
common attributes, which are the only attributes of an _I_n_p_u_­
_t_O_n_l_y window:

⋅    win‐gravity

⋅    event‐mask

⋅    do‐not‐propagate‐mask

⋅    override‐redirect

⋅    cursor

If you specify any other attributes for an _I_n_p_u_t_O_n_l_y window,
a _B_a_d_M_a_t_c_h error results.

_I_n_p_u_t_O_n_l_y windows are used for controlling input events in
situations where _I_n_p_u_t_O_u_t_p_u_t windows are unnecessary.  _I_n_p_u_­
_t_O_n_l_y windows are invisible; can only be used to control
such things as cursors, input event generation, and grab­
bing; and cannot be used in any graphics requests.  Note
that _I_n_p_u_t_O_n_l_y windows cannot have _I_n_p_u_t_O_u_t_p_u_t windows as
inferiors.

Windows have borders of a programmable width and pattern as
well as a background pattern or tile.  Pixel values can be
used for solid colors.  The background and border pixmaps
can be destroyed immediately after creating the window if no
further explicit references to them are to be made.  The
pattern can either be relative to the parent or absolute.
If _P_a_r_e_n_t_R_e_l_a_t_i_v_e, the parent’s background is used.

When windows are first created, they are not visible (not
mapped) on the screen.  Any output to a window that is not
visible on the screen and that does not have backing store
will be discarded.  An application may wish to create a win­
dow long before it is mapped to the screen.  When a window
is eventually mapped to the screen (using _X_M_a_p_W_i_n_d_o_w), the X
server generates an _E_x_p_o_s_e event for the window if backing
store has not been maintained.



                             4455





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


A window manager can override your choice of size, border
width, and position for a top‐level window.  Your program
must be prepared to use the actual size and position of the
top window.  It is not acceptable for a client application
to resize itself unless in direct response to a human com­
mand to do so.  Instead, either your program should use the
space given to it, or if the space is too small for any use­
ful work, your program might ask the user to resize the win­
dow.  The border of your top‐level window is considered fair
game for window managers.

To set an attribute of a window, set the appropriate member
of the _X_S_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s structure and OR in the corre­
sponding value bitmask in your subsequent calls to _X_C_r_e_­
_a_t_e_W_i_n_d_o_w and _X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s, or use one of the
other convenience functions that set the appropriate
attribute.  The symbols for the value mask bits and the
_X_S_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s structure are:







































                             4466





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
/* Window attribute value mask bits */

#define   _C_W_B_a_c_k_P_i_x_m_a_p                (1L<<0)
#define   _C_W_B_a_c_k_P_i_x_e_l                 (1L<<1)
#define   _C_W_B_o_r_d_e_r_P_i_x_m_a_p              (1L<<2)
#define   _C_W_B_o_r_d_e_r_P_i_x_e_l               (1L<<3)
#define   _C_W_B_i_t_G_r_a_v_i_t_y                (1L<<4)
#define   _C_W_W_i_n_G_r_a_v_i_t_y                (1L<<5)
#define   _C_W_B_a_c_k_i_n_g_S_t_o_r_e              (1L<<6)
#define   _C_W_B_a_c_k_i_n_g_P_l_a_n_e_s             (1L<<7)
#define   _C_W_B_a_c_k_i_n_g_P_i_x_e_l              (1L<<8)
#define   _C_W_O_v_e_r_r_i_d_e_R_e_d_i_r_e_c_t          (1L<<9)
#define   _C_W_S_a_v_e_U_n_d_e_r                 (1L<<10)
#define   _C_W_E_v_e_n_t_M_a_s_k                 (1L<<11)
#define   _C_W_D_o_n_t_P_r_o_p_a_g_a_t_e             (1L<<12)
#define   _C_W_C_o_l_o_r_m_a_p                  (1L<<13)
#define   _C_W_C_u_r_s_o_r                    (1L<<14)


/* Values */

typedef struct {
     Pixmap background_pixmap;/* background, None, or ParentRelative */
     unsigned long background_pixel;/* background pixel */
     Pixmap border_pixmap;    /* border of the window or CopyFromParent */
     unsigned long border_pixel;/* border pixel value */
     int bit_gravity;         /* one of bit gravity values */
     int win_gravity;         /* one of the window gravity values */
     int backing_store;       /* NotUseful, WhenMapped, Always */
     unsigned long backing_planes;/* planes to be preserved if possible */
     unsigned long backing_pixel;/* value to use in restoring planes */
     Bool save_under;         /* should bits under be saved? (popups) */
     long event_mask;         /* set of events that should be saved */
     long do_not_propagate_mask;/* set of events that should not propagate */
     Bool override_redirect;  /* boolean value for override_redirect */
     Colormap colormap;       /* color map to be associated with window */
     Cursor cursor;           /* cursor to be displayed (or None) */
} XSetWindowAttributes;

││__

The following lists the defaults for each window attribute
and indicates whether the attribute is applicable to
_I_n_p_u_t_O_u_t_p_u_t and _I_n_p_u_t_O_n_l_y windows:

-------------------------------------------------------------
AAttttrriibbuuttee               DDeeffaauulltt         _I_n_p_u_t_O_u_t_­   _I_n_p_u_­
                                        _p_u_t         _t_O_n_l_y
-------------------------------------------------------------
background‐pixmap       _N_o_n_e               Yes         No
background‐pixel        Undefined          Yes         No





                             4477





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------------
AAttttrriibbuuttee               DDeeffaauulltt         _I_n_p_u_t_O_u_t_­   _I_n_p_u_­
                                        _p_u_t         _t_O_n_l_y
-------------------------------------------------------------
border‐pixmap           _C_o_p_y_F_r_o_m_P_a_r_­       Yes         No
                        _e_n_t
border‐pixel            Undefined          Yes         No
bit‐gravity             _F_o_r_g_e_t_G_r_a_v_i_t_y      Yes         No
win‐gravity             _N_o_r_t_h_W_e_s_t_­         Yes        Yes
                        _G_r_a_v_i_t_y
backing‐store           _N_o_t_U_s_e_f_u_l          Yes         No
backing‐planes          All ones           Yes         No
backing‐pixel           zero               Yes         No
save‐under              _F_a_l_s_e              Yes         No
event‐mask              empty set          Yes        Yes
do‐not‐propagate‐mask   empty set          Yes        Yes
override‐redirect       _F_a_l_s_e              Yes        Yes
colormap                _C_o_p_y_F_r_o_m_P_a_r_­       Yes         No
                        _e_n_t
cursor                  _N_o_n_e               Yes        Yes
-------------------------------------------------------------


33..22..11..  BBaacckkggrroouunndd AAttttrriibbuuttee

Only _I_n_p_u_t_O_u_t_p_u_t windows can have a background.  You can set
the background of an _I_n_p_u_t_O_u_t_p_u_t window by using a pixel or
a pixmap.

The background‐pixmap attribute of a window specifies the
pixmap to be used for a window’s background.  This pixmap
can be of any size, although some sizes may be faster than
others.  The background‐pixel attribute of a window speci­
fies a pixel value used to paint a window’s background in a
single color.

You can set the background‐pixmap to a pixmap, _N_o_n_e
(default), or _P_a_r_e_n_t_R_e_l_a_t_i_v_e.  You can set the background‐
pixel of a window to any pixel value (no default).  If you
specify a background‐pixel, it overrides either the default
background‐pixmap or any value you may have set in the back­
ground‐pixmap.  A pixmap of an undefined size that is filled
with the background‐pixel is used for the background.  Range
checking is not performed on the background pixel; it simply
is truncated to the appropriate number of bits.

If you set the background‐pixmap, it overrides the default.
The background‐pixmap and the window must have the same
depth, or a _B_a_d_M_a_t_c_h error results.  If you set background‐
pixmap to _N_o_n_e, the window has no defined background.  If
you set the background‐pixmap to _P_a_r_e_n_t_R_e_l_a_t_i_v_e:

⋅    The parent window’s background‐pixmap is used.  The
     child window, however, must have the same depth as its



                             4488





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     parent, or a _B_a_d_M_a_t_c_h error results.

⋅    If the parent window has a background‐pixmap of _N_o_n_e,
     the window also has a background‐pixmap of _N_o_n_e.

⋅    A copy of the parent window’s background‐pixmap is not
     made.  The parent’s background‐pixmap is examined each
     time the child window’s background‐pixmap is required.

⋅    The background tile origin always aligns with the par­
     ent window’s background tile origin.  If the back­
     ground‐pixmap is not _P_a_r_e_n_t_R_e_l_a_t_i_v_e, the background
     tile origin is the child window’s origin.

Setting a new background, whether by setting background‐
pixmap or background‐pixel, overrides any previous back­
ground.  The background‐pixmap can be freed immediately if
no further explicit reference is made to it (the X server
will keep a copy to use when needed).  If you later draw
into the pixmap used for the background, what happens is
undefined because the X implementation is free to make a
copy of the pixmap or to use the same pixmap.

When no valid contents are available for regions of a window
and either the regions are visible or the server is main­
taining backing store, the server automatically tiles the
regions with the window’s background unless the window has a
background of _N_o_n_e.  If the background is _N_o_n_e, the previous
screen contents from other windows of the same depth as the
window are simply left in place as long as the contents come
from the parent of the window or an inferior of the parent.
Otherwise, the initial contents of the exposed regions are
undefined.  _E_x_p_o_s_e events are then generated for the
regions, even if the background‐pixmap is _N_o_n_e (see section
10.9).

33..22..22..  BBoorrddeerr AAttttrriibbuuttee

Only _I_n_p_u_t_O_u_t_p_u_t windows can have a border.  You can set the
border of an _I_n_p_u_t_O_u_t_p_u_t window by using a pixel or a
pixmap.

The border‐pixmap attribute of a window specifies the pixmap
to be used for a window’s border.  The border‐pixel
attribute of a window specifies a pixmap of undefined size
filled with that pixel be used for a window’s border.  Range
checking is not performed on the background pixel; it simply
is truncated to the appropriate number of bits.  The border
tile origin is always the same as the background tile ori­
gin.

You can also set the border‐pixmap to a pixmap of any size
(some may be faster than others) or to _C_o_p_y_F_r_o_m_P_a_r_e_n_t
(default).  You can set the border‐pixel to any pixel value



                             4499





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


(no default).

If you set a border‐pixmap, it overrides the default.  The
border‐pixmap and the window must have the same depth, or a
_B_a_d_M_a_t_c_h error results.  If you set the border‐pixmap to
_C_o_p_y_F_r_o_m_P_a_r_e_n_t, the parent window’s border‐pixmap is copied.
Subsequent changes to the parent window’s border attribute
do not affect the child window.  However, the child window
must have the same depth as the parent window, or a _B_a_d_M_a_t_c_h
error results.

The border‐pixmap can be freed immediately if no further
explicit reference is made to it.  If you later draw into
the pixmap used for the border, what happens is undefined
because the X implementation is free either to make a copy
of the pixmap or to use the same pixmap.  If you specify a
border‐pixel, it overrides either the default border‐pixmap
or any value you may have set in the border‐pixmap.  All
pixels in the window’s border will be set to the border‐
pixel.  Setting a new border, whether by setting border‐
pixel or by setting border‐pixmap, overrides any previous
border.

Output to a window is always clipped to the inside of the
window.  Therefore, graphics operations never affect the
window border.

33..22..33..  GGrraavviittyy AAttttrriibbuutteess

The bit gravity of a window defines which region of the win­
dow should be retained when an _I_n_p_u_t_O_u_t_p_u_t window is
resized.  The default value for the bit‐gravity attribute is
_F_o_r_g_e_t_G_r_a_v_i_t_y.  The window gravity of a window allows you to
define how the _I_n_p_u_t_O_u_t_p_u_t or _I_n_p_u_t_O_n_l_y window should be
repositioned if its parent is resized.  The default value
for the win‐gravity attribute is _N_o_r_t_h_W_e_s_t_G_r_a_v_i_t_y.

If the inside width or height of a window is not changed and
if the window is moved or its border is changed, then the
contents of the window are not lost but move with the win­
dow.  Changing the inside width or height of the window
causes its contents to be moved or lost (depending on the
bit‐gravity of the window) and causes children to be recon­
figured (depending on their win‐gravity).  For a change of
width and height, the (x, y) pairs are defined:


----------------------------------------
GGrraavviittyy DDiirreeccttiioonn   CCoooorrddiinnaatteess
----------------------------------------
_N_o_r_t_h_W_e_s_t_G_r_a_v_i_t_y    (0, 0)
_N_o_r_t_h_G_r_a_v_i_t_y        (Width/2, 0)
_N_o_r_t_h_E_a_s_t_G_r_a_v_i_t_y    (Width, 0)




                             5500





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_W_e_s_t_G_r_a_v_i_t_y         (0, Height/2)
_C_e_n_t_e_r_G_r_a_v_i_t_y       (Width/2, Height/2)
_E_a_s_t_G_r_a_v_i_t_y         (Width, Height/2)
_S_o_u_t_h_W_e_s_t_G_r_a_v_i_t_y    (0, Height)
_S_o_u_t_h_G_r_a_v_i_t_y        (Width/2, Height)
_S_o_u_t_h_E_a_s_t_G_r_a_v_i_t_y    (Width, Height)
----------------------------------------


When a window with one of these bit‐gravity values is
resized, the corresponding pair defines the change in posi­
tion of each pixel in the window.  When a window with one of
these win‐gravities has its parent window resized, the cor­
responding pair defines the change in position of the window
within the parent.  When a window is so repositioned, a
_G_r_a_v_i_t_y_N_o_t_i_f_y event is generated (see section 10.10.5).

A bit‐gravity of _S_t_a_t_i_c_G_r_a_v_i_t_y indicates that the contents
or origin should not move relative to the origin of the root
window.  If the change in size of the window is coupled with
a change in position (x, y), then for bit‐gravity the change
in position of each pixel is (−x, −y), and for win‐gravity
the change in position of a child when its parent is so
resized is (−x, −y).  Note that _S_t_a_t_i_c_G_r_a_v_i_t_y still only
takes effect when the width or height of the window is
changed, not when the window is moved.

A bit‐gravity of _F_o_r_g_e_t_G_r_a_v_i_t_y indicates that the window’s
contents are always discarded after a size change, even if a
backing store or save under has been requested.  The window
is tiled with its background and zero or more _E_x_p_o_s_e events
are generated.  If no background is defined, the existing
screen contents are not altered.  Some X servers may also
ignore the specified bit‐gravity and always generate _E_x_p_o_s_e
events.

The contents and borders of inferiors are not affected by
their parent’s bit‐gravity.  A server is permitted to ignore
the specified bit‐gravity and use _F_o_r_g_e_t instead.

A win‐gravity of _U_n_m_a_p_G_r_a_v_i_t_y is like _N_o_r_t_h_W_e_s_t_G_r_a_v_i_t_y (the
window is not moved), except the child is also unmapped when
the parent is resized, and an _U_n_m_a_p_N_o_t_i_f_y event is gener­
ated.

33..22..44..  BBaacckkiinngg SSttoorree AAttttrriibbuuttee

Some implementations of the X server may choose to maintain
the contents of _I_n_p_u_t_O_u_t_p_u_t windows.  If the X server main­
tains the contents of a window, the off‐screen saved pixels
are known as backing store.  The backing store advises the X
server on what to do with the contents of a window.  The
backing‐store attribute can be set to _N_o_t_U_s_e_f_u_l (default),
_W_h_e_n_M_a_p_p_e_d, or _A_l_w_a_y_s.



                             5511





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


A backing‐store attribute of _N_o_t_U_s_e_f_u_l advises the X server
that maintaining contents is unnecessary, although some X
implementations may still choose to maintain contents and,
therefore, not generate _E_x_p_o_s_e events.  A backing‐store
attribute of _W_h_e_n_M_a_p_p_e_d advises the X server that maintain­
ing contents of obscured regions when the window is mapped
would be beneficial.  In this case, the server may generate
an _E_x_p_o_s_e event when the window is created.  A backing‐store
attribute of _A_l_w_a_y_s advises the X server that maintaining
contents even when the window is unmapped would be benefi­
cial.  Even if the window is larger than its parent, this is
a request to the X server to maintain complete contents, not
just the region within the parent window boundaries.  While
the X server maintains the window’s contents, _E_x_p_o_s_e events
normally are not generated, but the X server may stop main­
taining contents at any time.

When the contents of obscured regions of a window are being
maintained, regions obscured by noninferior windows are
included in the destination of graphics requests (and
source, when the window is the source).  However, regions
obscured by inferior windows are not included.

33..22..55..  SSaavvee UUnnddeerr FFllaagg

Some server implementations may preserve contents of
_I_n_p_u_t_O_u_t_p_u_t windows under other _I_n_p_u_t_O_u_t_p_u_t windows.  This
is not the same as preserving the contents of a window for
you.  You may get better visual appeal if transient windows
(for example, pop‐up menus) request that the system preserve
the screen contents under them, so the temporarily obscured
applications do not have to repaint.

You can set the save‐under flag to _T_r_u_e or _F_a_l_s_e (default).
If save‐under is _T_r_u_e, the X server is advised that, when
this window is mapped, saving the contents of windows it
obscures would be beneficial.

33..22..66..  BBaacckkiinngg PPllaanneess aanndd BBaacckkiinngg PPiixxeell AAttttrriibbuutteess

You can set backing planes to indicate (with bits set to 1)
which bit planes of an _I_n_p_u_t_O_u_t_p_u_t window hold dynamic data
that must be preserved in backing store and during save
unders.  The default value for the backing‐planes attribute
is all bits set to 1.  You can set backing pixel to specify
what bits to use in planes not covered by backing planes.
The default value for the backing‐pixel attribute is all
bits set to 0.  The X server is free to save only the speci­
fied bit planes in the backing store or the save under and
is free to regenerate the remaining planes with the speci­
fied pixel value.  Any extraneous bits in these values (that
is, those bits beyond the specified depth of the window) may
be simply ignored.  If you request backing store or save
unders, you should use these members to minimize the amount



                             5522





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


of off‐screen memory required to store your window.

33..22..77..  EEvveenntt MMaasskk aanndd DDoo NNoott PPrrooppaaggaattee MMaasskk AAttttrriibbuutteess

The event mask defines which events the client is interested
in for this _I_n_p_u_t_O_u_t_p_u_t or _I_n_p_u_t_O_n_l_y window (or, for some
event types, inferiors of this window).  The event mask is
the bitwise inclusive OR of zero or more of the valid event
mask bits.  You can specify that no maskable events are
reported by setting _N_o_E_v_e_n_t_M_a_s_k (default).

The do‐not‐propagate‐mask attribute defines which events
should not be propagated to ancestor windows when no client
has the event type selected in this _I_n_p_u_t_O_u_t_p_u_t or _I_n_p_u_t_O_n_l_y
window.  The do‐not‐propagate‐mask is the bitwise inclusive
OR of zero or more of the following masks: _K_e_y_P_r_e_s_s, _K_e_y_R_e_­
_l_e_a_s_e, _B_u_t_t_o_n_P_r_e_s_s, _B_u_t_t_o_n_R_e_l_e_a_s_e, _P_o_i_n_t_e_r_M_o_t_i_o_n, _B_u_t_­
_t_o_n_1_M_o_t_i_o_n, _B_u_t_t_o_n_2_M_o_t_i_o_n, _B_u_t_t_o_n_3_M_o_t_i_o_n, _B_u_t_t_o_n_4_M_o_t_i_o_n,
_B_u_t_t_o_n_5_M_o_t_i_o_n, and _B_u_t_t_o_n_M_o_t_i_o_n.  You can specify that all
events are propagated by setting _N_o_E_v_e_n_t_M_a_s_k (default).

33..22..88..  OOvveerrrriiddee RReeddiirreecctt FFllaagg

To control window placement or to add decoration, a window
manager often needs to intercept (redirect) any map or con­
figure request.  Pop‐up windows, however, often need to be
mapped without a window manager getting in the way.  To con­
trol whether an _I_n_p_u_t_O_u_t_p_u_t or _I_n_p_u_t_O_n_l_y window is to ignore
these structure control facilities, use the override‐redi­
rect flag.

The override‐redirect flag specifies whether map and config­
ure requests on this window should override a _S_u_b_s_t_r_u_c_t_u_r_­
_e_R_e_d_i_r_e_c_t_M_a_s_k on the parent.  You can set the override‐redi­
rect flag to _T_r_u_e or _F_a_l_s_e (default).  Window managers use
this information to avoid tampering with pop‐up windows (see
also chapter 14).

33..22..99..  CCoolloorrmmaapp AAttttrriibbuuttee

The colormap attribute specifies which colormap best
reflects the true colors of the _I_n_p_u_t_O_u_t_p_u_t window.  The
colormap must have the same visual type as the window, or a
_B_a_d_M_a_t_c_h error results.  X servers capable of supporting
multiple hardware colormaps can use this information, and
window managers can use it for calls to _X_I_n_s_t_a_l_l_C_o_l_o_r_m_a_p.
You can set the colormap attribute to a colormap or to _C_o_p_y_­
_F_r_o_m_P_a_r_e_n_t (default).

If you set the colormap to _C_o_p_y_F_r_o_m_P_a_r_e_n_t, the parent win­
dow’s colormap is copied and used by its child.  However,
the child window must have the same visual type as the par­
ent, or a _B_a_d_M_a_t_c_h error results.  The parent window must
not have a colormap of _N_o_n_e, or a _B_a_d_M_a_t_c_h error results.



                             5533





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The colormap is copied by sharing the colormap object
between the child and parent, not by making a complete copy
of the colormap contents.  Subsequent changes to the parent
window’s colormap attribute do not affect the child window.

33..22..1100..  CCuurrssoorr AAttttrriibbuuttee

The cursor attribute specifies which cursor is to be used
when the pointer is in the _I_n_p_u_t_O_u_t_p_u_t or _I_n_p_u_t_O_n_l_y window.
You can set the cursor to a cursor or _N_o_n_e (default).

If you set the cursor to _N_o_n_e, the parent’s cursor is used
when the pointer is in the _I_n_p_u_t_O_u_t_p_u_t or _I_n_p_u_t_O_n_l_y window,
and any change in the parent’s cursor will cause an immedi­
ate change in the displayed cursor.  By calling _X_F_r_e_e_C_u_r_s_o_r,
the cursor can be freed immediately as long as no further
explicit reference to it is made.

33..33..  CCrreeaattiinngg WWiinnddoowwss

Xlib provides basic ways for creating windows, and toolkits
often supply higher‐level functions specifically for creat­
ing and placing top‐level windows, which are discussed in
the appropriate toolkit documentation.  If you do not use a
toolkit, however, you must provide some standard information
or hints for the window manager by using the Xlib inter‐
client communication functions (see chapter 14).

If you use Xlib to create your own top‐level windows (direct
children of the root window), you must observe the following
rules so that all applications interact reasonably across
the different styles of window management:

⋅    You must never fight with the window manager for the
     size or placement of your top‐level window.

⋅    You must be able to deal with whatever size window you
     get, even if this means that your application just
     prints a message like ‘‘Please make me bigger’’ in its
     window.

⋅    You should only attempt to resize or move top‐level
     windows in direct response to a user request.  If a
     request to change the size of a top‐level window fails,
     you must be prepared to live with what you get.  You
     are free to resize or move the children of top‐level
     windows as necessary.  (Toolkits often have facilities
     for automatic relayout.)

⋅    If you do not use a toolkit that automatically sets
     standard window properties, you should set these prop­
     erties for top‐level windows before mapping them.





                             5544





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


For further information, see chapter 14 and the _I_n_t_e_r_‐_C_l_i_e_n_t
_C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l.

_X_C_r_e_a_t_e_W_i_n_d_o_w is the more general function that allows you
to set specific window attributes when you create a window.
_X_C_r_e_a_t_e_S_i_m_p_l_e_W_i_n_d_o_w creates a window that inherits its
attributes from its parent window.

The X server acts as if _I_n_p_u_t_O_n_l_y windows do not exist for
the purposes of graphics requests, exposure processing, and
_V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y events.  An _I_n_p_u_t_O_n_l_y window cannot be used
as a drawable (that is, as a source or destination for
graphics requests).  _I_n_p_u_t_O_n_l_y and _I_n_p_u_t_O_u_t_p_u_t windows act
identically in other respects (properties, grabs, input con­
trol, and so on).  Extension packages can define other
classes of windows.

To create an unmapped window and set its window attributes,
use _X_C_r_e_a_t_e_W_i_n_d_o_w.






































                             5555





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Window XCreateWindow(_d_i_s_p_l_a_y, _p_a_r_e_n_t, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _b_o_r_d_e_r___w_i_d_t_h, _d_e_p_t_h,
                       _c_l_a_s_s, _v_i_s_u_a_l, _v_a_l_u_e_m_a_s_k, _a_t_t_r_i_b_u_t_e_s)
      Display *_d_i_s_p_l_a_y;
      Window _p_a_r_e_n_t;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      unsigned int _b_o_r_d_e_r___w_i_d_t_h;
      int _d_e_p_t_h;
      unsigned int _c_l_a_s_s;
      Visual *_v_i_s_u_a_l;
      unsigned long _v_a_l_u_e_m_a_s_k;
      XSetWindowAttributes *_a_t_t_r_i_b_u_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_a_r_e_n_t    Specifies the parent window.

_x
_y         Specify the x and y coordinates, which are the
          top‐left outside corner of the created window’s
          borders and are relative to the inside of the par­
          ent window’s borders.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the cre­
          ated window’s inside dimensions and do not include
          the created window’s borders.  The dimensions must
          be nonzero, or a _B_a_d_V_a_l_u_e error results.

_b_o_r_d_e_r___w_i_d_t_h
          Specifies the width of the created window’s border
          in pixels.

_d_e_p_t_h     Specifies the window’s depth.  A depth of _C_o_p_y_­
          _F_r_o_m_P_a_r_e_n_t means the depth is taken from the par­
          ent.

_c_l_a_s_s     Specifies the created window’s class.  You can
          pass _I_n_p_u_t_O_u_t_p_u_t, _I_n_p_u_t_O_n_l_y, or _C_o_p_y_F_r_o_m_P_a_r_e_n_t.  A
          class of _C_o_p_y_F_r_o_m_P_a_r_e_n_t means the class is taken
          from the parent.

_v_i_s_u_a_l    Specifies the visual type.  A visual of _C_o_p_y_­
          _F_r_o_m_P_a_r_e_n_t means the visual type is taken from the
          parent.

_v_a_l_u_e_m_a_s_k Specifies which window attributes are defined in
          the attributes argument.  This mask is the bitwise
          inclusive OR of the valid attribute mask bits.  If
          valuemask is zero, the attributes are ignored and
          are not referenced.




                             5566





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_a_t_t_r_i_b_u_t_e_s
          Specifies the structure from which the values (as
          specified by the value mask) are to be taken.  The
          value mask should have the appropriate bits set to
          indicate which attributes have been set in the
          structure.
││__

The _X_C_r_e_a_t_e_W_i_n_d_o_w function creates an unmapped subwindow for
a specified parent window, returns the window ID of the cre­
ated window, and causes the X server to generate a _C_r_e_a_t_e_N_o_­
_t_i_f_y event.  The created window is placed on top in the
stacking order with respect to siblings.

The coordinate system has the X axis horizontal and the Y
axis vertical with the origin [0, 0] at the upper‐left cor­
ner.  Coordinates are integral, in terms of pixels, and
coincide with pixel centers.  Each window and pixmap has its
own coordinate system.  For a window, the origin is inside
the border at the inside, upper‐left corner.

The border_width for an _I_n_p_u_t_O_n_l_y window must be zero, or a
_B_a_d_M_a_t_c_h error results.  For class _I_n_p_u_t_O_u_t_p_u_t, the visual
type and depth must be a combination supported for the
screen, or a _B_a_d_M_a_t_c_h error results.  The depth need not be
the same as the parent, but the parent must not be a window
of class _I_n_p_u_t_O_n_l_y, or a _B_a_d_M_a_t_c_h error results.  For an
_I_n_p_u_t_O_n_l_y window, the depth must be zero, and the visual
must be one supported by the screen.  If either condition is
not met, a _B_a_d_M_a_t_c_h error results.  The parent window, how­
ever, may have any depth and class.  If you specify any
invalid window attribute for a window, a _B_a_d_M_a_t_c_h error
results.

The created window is not yet displayed (mapped) on the
user’s display.  To display the window, call _X_M_a_p_W_i_n_d_o_w.
The new window initially uses the same cursor as its parent.
A new cursor can be defined for the new window by calling
_X_D_e_f_i_n_e_C_u_r_s_o_r.  The window will not be visible on the screen
unless it and all of its ancestors are mapped and it is not
obscured by any of its ancestors.

_X_C_r_e_a_t_e_W_i_n_d_o_w can generate _B_a_d_A_l_l_o_c, _B_a_d_C_o_l_o_r, _B_a_d_C_u_r_s_o_r,
_B_a_d_M_a_t_c_h, _B_a_d_P_i_x_m_a_p, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w errors.


To create an unmapped _I_n_p_u_t_O_u_t_p_u_t subwindow of a given par­
ent window, use _X_C_r_e_a_t_e_S_i_m_p_l_e_W_i_n_d_o_w.









                             5577





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Window XCreateSimpleWindow(_d_i_s_p_l_a_y, _p_a_r_e_n_t, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _b_o_r_d_e_r___w_i_d_t_h,
                             _b_o_r_d_e_r, _b_a_c_k_g_r_o_u_n_d)
      Display *_d_i_s_p_l_a_y;
      Window _p_a_r_e_n_t;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      unsigned int _b_o_r_d_e_r___w_i_d_t_h;
      unsigned long _b_o_r_d_e_r;
      unsigned long _b_a_c_k_g_r_o_u_n_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_a_r_e_n_t    Specifies the parent window.

_x
_y         Specify the x and y coordinates, which are the
          top‐left outside corner of the new window’s bor­
          ders and are relative to the inside of the parent
          window’s borders.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the cre­
          ated window’s inside dimensions and do not include
          the created window’s borders.  The dimensions must
          be nonzero, or a _B_a_d_V_a_l_u_e error results.

_b_o_r_d_e_r___w_i_d_t_h
          Specifies the width of the created window’s border
          in pixels.

_b_o_r_d_e_r    Specifies the border pixel value of the window.

_b_a_c_k_g_r_o_u_n_d
          Specifies the background pixel value of the win­
          dow.

││__

The _X_C_r_e_a_t_e_S_i_m_p_l_e_W_i_n_d_o_w function creates an unmapped
_I_n_p_u_t_O_u_t_p_u_t subwindow for a specified parent window, returns
the window ID of the created window, and causes the X server
to generate a _C_r_e_a_t_e_N_o_t_i_f_y event.  The created window is
placed on top in the stacking order with respect to sib­
lings.  Any part of the window that extends outside its par­
ent window is clipped.  The border_width for an _I_n_p_u_t_O_n_l_y
window must be zero, or a _B_a_d_M_a_t_c_h error results.  _X_C_r_e_a_t_e_S_­
_i_m_p_l_e_W_i_n_d_o_w inherits its depth, class, and visual from its
parent.  All other window attributes, except background and
border, have their default values.

_X_C_r_e_a_t_e_S_i_m_p_l_e_W_i_n_d_o_w can generate _B_a_d_A_l_l_o_c, _B_a_d_M_a_t_c_h, _B_a_d_­
_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w errors.



                             5588





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


33..44..  DDeessttrrooyyiinngg WWiinnddoowwss

Xlib provides functions that you can use to destroy a window
or destroy all subwindows of a window.


To destroy a window and all of its subwindows, use _X_D_e_s_t_r_o_y_­
_W_i_n_d_o_w.
__
││
XDestroyWindow(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_D_e_s_t_r_o_y_W_i_n_d_o_w function destroys the specified window as
well as all of its subwindows and causes the X server to
generate a _D_e_s_t_r_o_y_N_o_t_i_f_y event for each window.  The window
should never be referenced again.  If the window specified
by the w argument is mapped, it is unmapped automatically.
The ordering of the _D_e_s_t_r_o_y_N_o_t_i_f_y events is such that for
any given window being destroyed, _D_e_s_t_r_o_y_N_o_t_i_f_y is generated
on any inferiors of the window before being generated on the
window itself.  The ordering among siblings and across sub­
hierarchies is not otherwise constrained.  If the window you
specified is a root window, no windows are destroyed.
Destroying a mapped window will generate _E_x_p_o_s_e events on
other windows that were obscured by the window being
destroyed.

_X_D_e_s_t_r_o_y_W_i_n_d_o_w can generate a _B_a_d_W_i_n_d_o_w error.


To destroy all subwindows of a specified window, use _X_D_e_­
_s_t_r_o_y_S_u_b_w_i_n_d_o_w_s.
__
││
XDestroySubwindows(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_D_e_s_t_r_o_y_S_u_b_w_i_n_d_o_w_s function destroys all inferior win­
dows of the specified window, in bottom‐to‐top stacking



                             5599





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


order.  It causes the X server to generate a _D_e_s_t_r_o_y_N_o_t_i_f_y
event for each window.  If any mapped subwindows were actu­
ally destroyed, _X_D_e_s_t_r_o_y_S_u_b_w_i_n_d_o_w_s causes the X server to
generate _E_x_p_o_s_e events on the specified window.  This is
much more efficient than deleting many windows one at a time
because much of the work need be performed only once for all
of the windows, rather than for each window.  The subwindows
should never be referenced again.

_X_D_e_s_t_r_o_y_S_u_b_w_i_n_d_o_w_s can generate a _B_a_d_W_i_n_d_o_w error.

33..55..  MMaappppiinngg WWiinnddoowwss

A window is considered mapped if an _X_M_a_p_W_i_n_d_o_w call has been
made on it.  It may not be visible on the screen for one of
the following reasons:

⋅    It is obscured by another opaque window.

⋅    One of its ancestors is not mapped.

⋅    It is entirely clipped by an ancestor.

_E_x_p_o_s_e events are generated for the window when part or all
of it becomes visible on the screen.  A client receives the
_E_x_p_o_s_e events only if it has asked for them.  Windows retain
their position in the stacking order when they are unmapped.

A window manager may want to control the placement of sub­
windows.  If _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k has been selected by a
window manager on a parent window (usually a root window), a
map request initiated by other clients on a child window is
not performed, and the window manager is sent a _M_a_p_R_e_q_u_e_s_t
event.  However, if the override‐redirect flag on the child
had been set to _T_r_u_e (usually only on pop‐up menus), the map
request is performed.

A tiling window manager might decide to reposition and
resize other clients’ windows and then decide to map the
window to its final location.  A window manager that wants
to provide decoration might reparent the child into a frame
first.  For further information, see sections 3.2.8 and
10.10.  Only a single client at a time can select for _S_u_b_­
_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k.

Similarly, a single client can select for _R_e_s_i_z_e_R_e_d_i_r_e_c_t_M_a_s_k
on a parent window.  Then, any attempt to resize the window
by another client is suppressed, and the client receives a
_R_e_s_i_z_e_R_e_q_u_e_s_t event.


To map a given window, use _X_M_a_p_W_i_n_d_o_w.





                             6600





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XMapWindow(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_M_a_p_W_i_n_d_o_w function maps the window and all of its sub­
windows that have had map requests.  Mapping a window that
has an unmapped ancestor does not display the window but
marks it as eligible for display when the ancestor becomes
mapped.  Such a window is called unviewable.  When all its
ancestors are mapped, the window becomes viewable and will
be visible on the screen if it is not obscured by another
window.  This function has no effect if the window is
already mapped.

If the override‐redirect of the window is _F_a_l_s_e and if some
other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on the
parent window, then the X server generates a _M_a_p_R_e_q_u_e_s_t
event, and the _X_M_a_p_W_i_n_d_o_w function does not map the window.
Otherwise, the window is mapped, and the X server generates
a _M_a_p_N_o_t_i_f_y event.

If the window becomes viewable and no earlier contents for
it are remembered, the X server tiles the window with its
background.  If the window’s background is undefined, the
existing screen contents are not altered, and the X server
generates zero or more _E_x_p_o_s_e events.  If backing‐store was
maintained while the window was unmapped, no _E_x_p_o_s_e events
are generated.  If backing‐store will now be maintained, a
full‐window exposure is always generated.  Otherwise, only
visible regions may be reported.  Similar tiling and expo­
sure take place for any newly viewable inferiors.

If the window is an _I_n_p_u_t_O_u_t_p_u_t window, _X_M_a_p_W_i_n_d_o_w generates
_E_x_p_o_s_e events on each _I_n_p_u_t_O_u_t_p_u_t window that it causes to
be displayed.  If the client maps and paints the window and
if the client begins processing events, the window is
painted twice.  To avoid this, first ask for _E_x_p_o_s_e events
and then map the window, so the client processes input
events as usual.  The event list will include _E_x_p_o_s_e for
each window that has appeared on the screen.  The client’s
normal response to an _E_x_p_o_s_e event should be to repaint the
window.  This method usually leads to simpler programs and
to proper interaction with window managers.

_X_M_a_p_W_i_n_d_o_w can generate a _B_a_d_W_i_n_d_o_w error.





                             6611





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To map and raise a window, use _X_M_a_p_R_a_i_s_e_d.
__
││
XMapRaised(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_M_a_p_R_a_i_s_e_d function essentially is similar to _X_M_a_p_W_i_n_d_o_w
in that it maps the window and all of its subwindows that
have had map requests.  However, it also raises the speci­
fied window to the top of the stack.  For additional infor­
mation, see _X_M_a_p_W_i_n_d_o_w.

_X_M_a_p_R_a_i_s_e_d can generate multiple _B_a_d_W_i_n_d_o_w errors.


To map all subwindows for a specified window, use _X_M_a_p_S_u_b_­
_w_i_n_d_o_w_s.
__
││
XMapSubwindows(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_M_a_p_S_u_b_w_i_n_d_o_w_s function maps all subwindows for a speci­
fied window in top‐to‐bottom stacking order.  The X server
generates _E_x_p_o_s_e events on each newly displayed window.
This may be much more efficient than mapping many windows
one at a time because the server needs to perform much of
the work only once, for all of the windows, rather than for
each window.

_X_M_a_p_S_u_b_w_i_n_d_o_w_s can generate a _B_a_d_W_i_n_d_o_w error.

33..66..  UUnnmmaappppiinngg WWiinnddoowwss

Xlib provides functions that you can use to unmap a window
or all subwindows.


To unmap a window, use _X_U_n_m_a_p_W_i_n_d_o_w.




                             6622





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XUnmapWindow(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_U_n_m_a_p_W_i_n_d_o_w function unmaps the specified window and
causes the X server to generate an _U_n_m_a_p_N_o_t_i_f_y event.  If
the specified window is already unmapped, _X_U_n_m_a_p_W_i_n_d_o_w has
no effect.  Normal exposure processing on formerly obscured
windows is performed.  Any child window will no longer be
visible until another map call is made on the parent.  In
other words, the subwindows are still mapped but are not
visible until the parent is mapped.  Unmapping a window will
generate _E_x_p_o_s_e events on windows that were formerly
obscured by it.

_X_U_n_m_a_p_W_i_n_d_o_w can generate a _B_a_d_W_i_n_d_o_w error.


To unmap all subwindows for a specified window, use _X_U_n_m_a_p_­
_S_u_b_w_i_n_d_o_w_s.
__
││
XUnmapSubwindows(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_U_n_m_a_p_S_u_b_w_i_n_d_o_w_s function unmaps all subwindows for the
specified window in bottom‐to‐top stacking order.  It causes
the X server to generate an _U_n_m_a_p_N_o_t_i_f_y event on each sub­
window and _E_x_p_o_s_e events on formerly obscured windows.
Using this function is much more efficient than unmapping
multiple windows one at a time because the server needs to
perform much of the work only once, for all of the windows,
rather than for each window.

_X_U_n_m_a_p_S_u_b_w_i_n_d_o_w_s can generate a _B_a_d_W_i_n_d_o_w error.

33..77..  CCoonnffiigguurriinngg WWiinnddoowwss






                             6633





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Xlib provides functions that you can use to move a window,
resize a window, move and resize a window, or change a win­
dow’s border width.  To change one of these parameters, set
the appropriate member of the _X_W_i_n_d_o_w_C_h_a_n_g_e_s structure and
OR in the corresponding value mask in subsequent calls to
_X_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w.  The symbols for the value mask bits and
the _X_W_i_n_d_o_w_C_h_a_n_g_e_s structure are:
__
││
/* Configure window value mask bits */

#define   _C_W_X                         (1<<0)
#define   _C_W_Y                         (1<<1)
#define   _C_W_W_i_d_t_h                     (1<<2)
#define   _C_W_H_e_i_g_h_t                    (1<<3)
#define   _C_W_B_o_r_d_e_r_W_i_d_t_h               (1<<4)
#define   _C_W_S_i_b_l_i_n_g                   (1<<5)
#define   _C_W_S_t_a_c_k_M_o_d_e                 (1<<6)


/* Values */

typedef struct {
     int x, y;
     int width, height;
     int border_width;
     Window sibling;
     int stack_mode;
} XWindowChanges;

││__

The x and y members are used to set the window’s x and y
coordinates, which are relative to the parent’s origin and
indicate the position of the upper‐left outer corner of the
window.  The width and height members are used to set the
inside size of the window, not including the border, and
must be nonzero, or a _B_a_d_V_a_l_u_e error results.  Attempts to
configure a root window have no effect.

The border_width member is used to set the width of the bor­
der in pixels.  Note that setting just the border width
leaves the outer‐left corner of the window in a fixed posi­
tion but moves the absolute position of the window’s origin.
If you attempt to set the border‐width attribute of an _I_n_p_u_­
_t_O_n_l_y window nonzero, a _B_a_d_M_a_t_c_h error results.

The sibling member is used to set the sibling window for
stacking operations.  The stack_mode member is used to set
how the window is to be restacked and can be set to _A_b_o_v_e,
_B_e_l_o_w, _T_o_p_I_f, _B_o_t_t_o_m_I_f, or _O_p_p_o_s_i_t_e.

If the override‐redirect flag of the window is _F_a_l_s_e and if
some other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on



                             6644





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the parent, the X server generates a _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t event,
and no further processing is performed.  Otherwise, if some
other client has selected _R_e_s_i_z_e_R_e_d_i_r_e_c_t_M_a_s_k on the window
and the inside width or height of the window is being
changed, a _R_e_s_i_z_e_R_e_q_u_e_s_t event is generated, and the current
inside width and height are used instead.  Note that the
override‐redirect flag of the window has no effect on _R_e_s_i_z_­
_e_R_e_d_i_r_e_c_t_M_a_s_k and that _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on the par­
ent has precedence over _R_e_s_i_z_e_R_e_d_i_r_e_c_t_M_a_s_k on the window.

When the geometry of the window is changed as specified, the
window is restacked among siblings, and a _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y
event is generated if the state of the window actually
changes.  _G_r_a_v_i_t_y_N_o_t_i_f_y events are generated after _C_o_n_f_i_g_­
_u_r_e_N_o_t_i_f_y events.  If the inside width or height of the win­
dow has actually changed, children of the window are
affected as specified.

If a window’s size actually changes, the window’s subwindows
move according to their window gravity.  Depending on the
window’s bit gravity, the contents of the window also may be
moved (see section 3.2.3).

If regions of the window were obscured but now are not,
exposure processing is performed on these formerly obscured
windows, including the window itself and its inferiors.  As
a result of increasing the width or height, exposure pro­
cessing is also performed on any new regions of the window
and any regions where window contents are lost.

The restack check (specifically, the computation for _B_o_t_­
_t_o_m_I_f, _T_o_p_I_f, and _O_p_p_o_s_i_t_e) is performed with respect to the
window’s final size and position (as controlled by the other
arguments of the request), not its initial position.  If a
sibling is specified without a stack_mode, a _B_a_d_M_a_t_c_h error
results.

If a sibling and a stack_mode are specified, the window is
restacked as follows:

_A_b_o_v_e        The window is placed just above the sibling.
_B_e_l_o_w        The window is placed just below the sibling.
_T_o_p_I_f        If the sibling occludes the window, the window is
             placed at the top of the stack.
_B_o_t_t_o_m_I_f     If the window occludes the sibling, the window is
             placed at the bottom of the stack.
_O_p_p_o_s_i_t_e     If the sibling occludes the window, the window is
             placed at the top of the stack.  If the window
             occludes the sibling, the window is placed at the
             bottom of the stack.


If a stack_mode is specified but no sibling is specified,
the window is restacked as follows:



                             6655





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_A_b_o_v_e        The window is placed at the top of the stack.
_B_e_l_o_w        The window is placed at the bottom of the stack.
_T_o_p_I_f        If any sibling occludes the window, the window is
             placed at the top of the stack.
_B_o_t_t_o_m_I_f     If the window occludes any sibling, the window is
             placed at the bottom of the stack.
_O_p_p_o_s_i_t_e     If any sibling occludes the window, the window is
             placed at the top of the stack.  If the window
             occludes any sibling, the window is placed at the
             bottom of the stack.


Attempts to configure a root window have no effect.


To configure a window’s size, location, stacking, or border,
use _X_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w.
__
││
XConfigureWindow(_d_i_s_p_l_a_y, _w, _v_a_l_u_e___m_a_s_k, _v_a_l_u_e_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      unsigned int _v_a_l_u_e___m_a_s_k;
      XWindowChanges *_v_a_l_u_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window to be reconfigured.

_v_a_l_u_e___m_a_s_k
          Specifies which values are to be set using infor­
          mation in the values structure.  This mask is the
          bitwise inclusive OR of the valid configure window
          values bits.

_v_a_l_u_e_s    Specifies the _X_W_i_n_d_o_w_C_h_a_n_g_e_s structure.
││__

The _X_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w function uses the values specified in
the _X_W_i_n_d_o_w_C_h_a_n_g_e_s structure to reconfigure a window’s size,
position, border, and stacking order.  Values not specified
are taken from the existing geometry of the window.

If a sibling is specified without a stack_mode or if the
window is not actually a sibling, a _B_a_d_M_a_t_c_h error results.
Note that the computations for _B_o_t_t_o_m_I_f, _T_o_p_I_f, and _O_p_p_o_s_i_t_e
are performed with respect to the window’s final geometry
(as controlled by the other arguments passed to _X_C_o_n_f_i_g_­
_u_r_e_W_i_n_d_o_w), not its initial geometry.  Any backing store
contents of the window, its inferiors, and other newly visi­
ble windows are either discarded or changed to reflect the
current screen contents (depending on the implementation).




                             6666





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w can generate _B_a_d_M_a_t_c_h, _B_a_d_V_a_l_u_e, and _B_a_d_­
_W_i_n_d_o_w errors.


To move a window without changing its size, use _X_M_o_v_e_W_i_n_d_o_w.
__
││
XMoveWindow(_d_i_s_p_l_a_y, _w, _x, _y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _x, _y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window to be moved.

_x
_y         Specify the x and y coordinates, which define the
          new location of the top‐left pixel of the window’s
          border or the window itself if it has no border.
││__

The _X_M_o_v_e_W_i_n_d_o_w function moves the specified window to the
specified x and y coordinates, but it does not change the
window’s size, raise the window, or change the mapping state
of the window.  Moving a mapped window may or may not lose
the window’s contents depending on if the window is obscured
by nonchildren and if no backing store exists.  If the con­
tents of the window are lost, the X server generates _E_x_p_o_s_e
events.  Moving a mapped window generates _E_x_p_o_s_e events on
any formerly obscured windows.

If the override‐redirect flag of the window is _F_a_l_s_e and
some other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on
the parent, the X server generates a _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t event,
and no further processing is performed.  Otherwise, the win­
dow is moved.

_X_M_o_v_e_W_i_n_d_o_w can generate a _B_a_d_W_i_n_d_o_w error.


To change a window’s size without changing the upper‐left
coordinate, use _X_R_e_s_i_z_e_W_i_n_d_o_w.













                             6677





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XResizeWindow(_d_i_s_p_l_a_y, _w, _w_i_d_t_h, _h_e_i_g_h_t)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the inte­
          rior dimensions of the window after the call com­
          pletes.
││__

The _X_R_e_s_i_z_e_W_i_n_d_o_w function changes the inside dimensions of
the specified window, not including its borders.  This func­
tion does not change the window’s upper‐left coordinate or
the origin and does not restack the window.  Changing the
size of a mapped window may lose its contents and generate
_E_x_p_o_s_e events.  If a mapped window is made smaller, changing
its size generates _E_x_p_o_s_e events on windows that the mapped
window formerly obscured.

If the override‐redirect flag of the window is _F_a_l_s_e and
some other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on
the parent, the X server generates a _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t event,
and no further processing is performed.  If either width or
height is zero, a _B_a_d_V_a_l_u_e error results.

_X_R_e_s_i_z_e_W_i_n_d_o_w can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w errors.


To change the size and location of a window, use _X_M_o_v_e_R_e_­
_s_i_z_e_W_i_n_d_o_w.




















                             6688





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XMoveResizeWindow(_d_i_s_p_l_a_y, _w, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window to be reconfigured.

_x
_y         Specify the x and y coordinates, which define the
          new position of the window relative to its parent.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which define the
          interior size of the window.
││__

The _X_M_o_v_e_R_e_s_i_z_e_W_i_n_d_o_w function changes the size and location
of the specified window without raising it.  Moving and
resizing a mapped window may generate an _E_x_p_o_s_e event on the
window.  Depending on the new size and location parameters,
moving and resizing a window may generate _E_x_p_o_s_e events on
windows that the window formerly obscured.

If the override‐redirect flag of the window is _F_a_l_s_e and
some other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on
the parent, the X server generates a _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t event,
and no further processing is performed.  Otherwise, the win­
dow size and location are changed.

_X_M_o_v_e_R_e_s_i_z_e_W_i_n_d_o_w can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w
errors.


To change the border width of a given window, use _X_S_e_t_W_i_n_­
_d_o_w_B_o_r_d_e_r_W_i_d_t_h.

















                             6699





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetWindowBorderWidth(_d_i_s_p_l_a_y, _w, _w_i_d_t_h)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      unsigned int _w_i_d_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_w_i_d_t_h     Specifies the width of the window border.
││__

The _X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r_W_i_d_t_h function sets the specified win­
dow’s border width to the specified width.

_X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r_W_i_d_t_h can generate a _B_a_d_W_i_n_d_o_w error.

33..88..  CChhaannggiinngg WWiinnddooww SSttaacckkiinngg OOrrddeerr


Xlib provides functions that you can use to raise, lower,
circulate, or restack windows.


To raise a window so that no sibling window obscures it, use
_X_R_a_i_s_e_W_i_n_d_o_w.
__
││
XRaiseWindow(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_R_a_i_s_e_W_i_n_d_o_w function raises the specified window to the
top of the stack so that no sibling window obscures it.  If
the windows are regarded as overlapping sheets of paper
stacked on a desk, then raising a window is analogous to
moving the sheet to the top of the stack but leaving its x
and y location on the desk constant.  Raising a mapped win­
dow may generate _E_x_p_o_s_e events for the window and any mapped
subwindows that were formerly obscured.

If the override‐redirect attribute of the window is _F_a_l_s_e
and some other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k
on the parent, the X server generates a _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t
event, and no processing is performed.  Otherwise, the win­
dow is raised.



                             7700





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_R_a_i_s_e_W_i_n_d_o_w can generate a _B_a_d_W_i_n_d_o_w error.


To lower a window so that it does not obscure any sibling
windows, use _X_L_o_w_e_r_W_i_n_d_o_w.
__
││
XLowerWindow(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_L_o_w_e_r_W_i_n_d_o_w function lowers the specified window to the
bottom of the stack so that it does not obscure any sibling
windows.  If the windows are regarded as overlapping sheets
of paper stacked on a desk, then lowering a window is analo­
gous to moving the sheet to the bottom of the stack but
leaving its x and y location on the desk constant.  Lowering
a mapped window will generate _E_x_p_o_s_e events on any windows
it formerly obscured.

If the override‐redirect attribute of the window is _F_a_l_s_e
and some other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k
on the parent, the X server generates a _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t
event, and no processing is performed.  Otherwise, the win­
dow is lowered to the bottom of the stack.

_X_L_o_w_e_r_W_i_n_d_o_w can generate a _B_a_d_W_i_n_d_o_w error.


To circulate a subwindow up or down, use _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_­
_d_o_w_s.




















                             7711





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XCirculateSubwindows(_d_i_s_p_l_a_y, _w, _d_i_r_e_c_t_i_o_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _d_i_r_e_c_t_i_o_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_d_i_r_e_c_t_i_o_n Specifies the direction (up or down) that you want
          to circulate the window.  You can pass _R_a_i_s_e_L_o_w_e_s_t
          or _L_o_w_e_r_H_i_g_h_e_s_t.
││__

The _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s function circulates children of the
specified window in the specified direction.  If you specify
_R_a_i_s_e_L_o_w_e_s_t, _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s raises the lowest mapped
child (if any) that is occluded by another child to the top
of the stack.  If you specify _L_o_w_e_r_H_i_g_h_e_s_t, _X_C_i_r_c_u_l_a_t_e_S_u_b_­
_w_i_n_d_o_w_s lowers the highest mapped child (if any) that
occludes another child to the bottom of the stack.  Exposure
processing is then performed on formerly obscured windows.
If some other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k
on the window, the X server generates a _C_i_r_c_u_l_a_t_e_R_e_q_u_e_s_t
event, and no further processing is performed.  If a child
is actually restacked, the X server generates a _C_i_r_c_u_l_a_t_e_N_o_­
_t_i_f_y event.

_X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w
errors.


To raise the lowest mapped child of a window that is par­
tially or completely occluded by another child, use _X_C_i_r_c_u_­
_l_a_t_e_S_u_b_w_i_n_d_o_w_s_U_p.
__
││
XCirculateSubwindowsUp(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s_U_p function raises the lowest mapped
child of the specified window that is partially or com­
pletely occluded by another child.  Completely unobscured
children are not affected.  This is a convenience function
equivalent to _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s with _R_a_i_s_e_L_o_w_e_s_t



                             7722





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


specified.

_X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s_U_p can generate a _B_a_d_W_i_n_d_o_w error.


To lower the highest mapped child of a window that partially
or completely occludes another child, use _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_­
_d_o_w_s_D_o_w_n.
__
││
XCirculateSubwindowsDown(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s_D_o_w_n function lowers the highest
mapped child of the specified window that partially or com­
pletely occludes another child.  Completely unobscured chil­
dren are not affected.  This is a convenience function
equivalent to _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s with _L_o_w_e_r_H_i_g_h_e_s_t speci­
fied.

_X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s_D_o_w_n can generate a _B_a_d_W_i_n_d_o_w error.


To restack a set of windows from top to bottom, use
_X_R_e_s_t_a_c_k_W_i_n_d_o_w_s.
__
││
XRestackWindows(_d_i_s_p_l_a_y, _w_i_n_d_o_w_s, _n_w_i_n_d_o_w_s);
      Display *_d_i_s_p_l_a_y;
      Window _w_i_n_d_o_w_s[];
      int _n_w_i_n_d_o_w_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w_i_n_d_o_w_s   Specifies an array containing the windows to be
          restacked.

_n_w_i_n_d_o_w_s  Specifies the number of windows to be restacked.
││__

The _X_R_e_s_t_a_c_k_W_i_n_d_o_w_s function restacks the windows in the
order specified, from top to bottom.  The stacking order of
the first window in the windows array is unaffected, but the
other windows in the array are stacked underneath the first
window, in the order of the array.  The stacking order of
the other windows is not affected.  For each window in the



                             7733





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


window array that is not a child of the specified window, a
_B_a_d_M_a_t_c_h error results.

If the override‐redirect attribute of a window is _F_a_l_s_e and
some other client has selected _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on
the parent, the X server generates _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t events
for each window whose override‐redirect flag is not set, and
no further processing is performed.  Otherwise, the windows
will be restacked in top‐to‐bottom order.

_X_R_e_s_t_a_c_k_W_i_n_d_o_w_s can generate a _B_a_d_W_i_n_d_o_w error.

33..99..  CChhaannggiinngg WWiinnddooww AAttttrriibbuutteess


Xlib provides functions that you can use to set window
attributes.  _X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s is the more general
function that allows you to set one or more window
attributes provided by the _X_S_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s structure.
The other functions described in this section allow you to
set one specific window attribute, such as a window’s back­
ground.


To change one or more attributes for a given window, use
_X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s.































                             7744





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XChangeWindowAttributes(_d_i_s_p_l_a_y, _w, _v_a_l_u_e_m_a_s_k, _a_t_t_r_i_b_u_t_e_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      unsigned long _v_a_l_u_e_m_a_s_k;
      XSetWindowAttributes *_a_t_t_r_i_b_u_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_v_a_l_u_e_m_a_s_k Specifies which window attributes are defined in
          the attributes argument.  This mask is the bitwise
          inclusive OR of the valid attribute mask bits.  If
          valuemask is zero, the attributes are ignored and
          are not referenced.  The values and restrictions
          are the same as for _X_C_r_e_a_t_e_W_i_n_d_o_w.


_a_t_t_r_i_b_u_t_e_s
          Specifies the structure from which the values (as
          specified by the value mask) are to be taken.  The
          value mask should have the appropriate bits set to
          indicate which attributes have been set in the
          structure (see section 3.2).
││__

Depending on the valuemask, the _X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s
function uses the window attributes in the _X_S_e_t_W_i_n_d_o_w_A_t_­
_t_r_i_b_u_t_e_s structure to change the specified window
attributes.  Changing the background does not cause the win­
dow contents to be changed.  To repaint the window and its
background, use _X_C_l_e_a_r_W_i_n_d_o_w.  Setting the border or chang­
ing the background such that the border tile origin changes
causes the border to be repainted.  Changing the background
of a root window to _N_o_n_e or _P_a_r_e_n_t_R_e_l_a_t_i_v_e restores the
default background pixmap.  Changing the border of a root
window to _C_o_p_y_F_r_o_m_P_a_r_e_n_t restores the default border pixmap.
Changing the win‐gravity does not affect the current posi­
tion of the window.  Changing the backing‐store of an
obscured window to _W_h_e_n_M_a_p_p_e_d or _A_l_w_a_y_s, or changing the
backing‐planes, backing‐pixel, or save‐under of a mapped
window may have no immediate effect.  Changing the colormap
of a window (that is, defining a new map, not changing the
contents of the existing map) generates a _C_o_l_o_r_m_a_p_N_o_t_i_f_y
event.  Changing the colormap of a visible window may have
no immediate effect on the screen because the map may not be
installed (see _X_I_n_s_t_a_l_l_C_o_l_o_r_m_a_p).  Changing the cursor of a
root window to _N_o_n_e restores the default cursor.  Whenever
possible, you are encouraged to share colormaps.

Multiple clients can select input on the same window.  Their
event masks are maintained separately.  When an event is



                             7755





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


generated, it is reported to all interested clients.  How­
ever, only one client at a time can select for _S_u_b_s_t_r_u_c_t_u_r_­
_e_R_e_d_i_r_e_c_t_M_a_s_k, _R_e_s_i_z_e_R_e_d_i_r_e_c_t_M_a_s_k, and _B_u_t_t_o_n_P_r_e_s_s_M_a_s_k.  If
a client attempts to select any of these event masks and
some other client has already selected one, a _B_a_d_A_c_c_e_s_s
error results.  There is only one do‐not‐propagate‐mask for
a window, not one per client.

_X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r,
_B_a_d_C_u_r_s_o_r, _B_a_d_M_a_t_c_h, _B_a_d_P_i_x_m_a_p, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w
errors.


To set the background of a window to a given pixel, use
_X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d.
__
││
XSetWindowBackground(_d_i_s_p_l_a_y, _w, _b_a_c_k_g_r_o_u_n_d___p_i_x_e_l)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      unsigned long _b_a_c_k_g_r_o_u_n_d___p_i_x_e_l;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_b_a_c_k_g_r_o_u_n_d___p_i_x_e_l
          Specifies the pixel that is to be used for the
          background.
││__

The _X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d function sets the background of the
window to the specified pixel value.  Changing the back­
ground does not cause the window contents to be changed.
_X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d uses a pixmap of undefined size filled
with the pixel value you passed.  If you try to change the
background of an _I_n_p_u_t_O_n_l_y window, a _B_a_d_M_a_t_c_h error results.

_X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d can generate _B_a_d_M_a_t_c_h and _B_a_d_W_i_n_d_o_w
errors.



To set the background of a window to a given pixmap, use
_X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d_P_i_x_m_a_p.











                             7766





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetWindowBackgroundPixmap(_d_i_s_p_l_a_y, _w, _b_a_c_k_g_r_o_u_n_d___p_i_x_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Pixmap _b_a_c_k_g_r_o_u_n_d___p_i_x_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_b_a_c_k_g_r_o_u_n_d___p_i_x_m_a_p
          Specifies the background pixmap, _P_a_r_e_n_t_R_e_l_a_t_i_v_e,
          or _N_o_n_e.
││__

The _X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d_P_i_x_m_a_p function sets the background
pixmap of the window to the specified pixmap.  The back­
ground pixmap can immediately be freed if no further
explicit references to it are to be made.  If _P_a_r_e_n_t_R_e_l_a_t_i_v_e
is specified, the background pixmap of the window’s parent
is used, or on the root window, the default background is
restored.  If you try to change the background of an _I_n_p_u_­
_t_O_n_l_y window, a _B_a_d_M_a_t_c_h error results.  If the background
is set to _N_o_n_e, the window has no defined background.

_X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d_P_i_x_m_a_p can generate _B_a_d_M_a_t_c_h, _B_a_d_P_i_x_m_a_p,
and _B_a_d_W_i_n_d_o_w errors.

                            Note

     _X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d and _X_S_e_t_W_i_n_d_o_w_B_a_c_k_g_r_o_u_n_d_­
     _P_i_x_m_a_p do not change the current contents of the
     window.



To change and repaint a window’s border to a given pixel,
use _X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r.


















                             7777





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetWindowBorder(_d_i_s_p_l_a_y, _w, _b_o_r_d_e_r___p_i_x_e_l)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      unsigned long _b_o_r_d_e_r___p_i_x_e_l;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_b_o_r_d_e_r___p_i_x_e_l
          Specifies the entry in the colormap.
││__

The _X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r function sets the border of the window
to the pixel value you specify.  If you attempt to perform
this on an _I_n_p_u_t_O_n_l_y window, a _B_a_d_M_a_t_c_h error results.

_X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r can generate _B_a_d_M_a_t_c_h and _B_a_d_W_i_n_d_o_w errors.


To change and repaint the border tile of a given window, use
_X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r_P_i_x_m_a_p.
__
││
XSetWindowBorderPixmap(_d_i_s_p_l_a_y, _w, _b_o_r_d_e_r___p_i_x_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Pixmap _b_o_r_d_e_r___p_i_x_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_b_o_r_d_e_r___p_i_x_m_a_p
          Specifies the border pixmap or _C_o_p_y_F_r_o_m_P_a_r_e_n_t.
││__

The _X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r_P_i_x_m_a_p function sets the border pixmap
of the window to the pixmap you specify.  The border pixmap
can be freed immediately if no further explicit references
to it are to be made.  If you specify _C_o_p_y_F_r_o_m_P_a_r_e_n_t, a copy
of the parent window’s border pixmap is used.  If you
attempt to perform this on an _I_n_p_u_t_O_n_l_y window, a _B_a_d_M_a_t_c_h
error results.

_X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r_P_i_x_m_a_p can generate _B_a_d_M_a_t_c_h, _B_a_d_P_i_x_m_a_p, and
_B_a_d_W_i_n_d_o_w errors.


To set the colormap of a given window, use _X_S_e_t_W_i_n_d_o_w_C_o_l_­
_o_r_m_a_p.



                             7788





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetWindowColormap(_d_i_s_p_l_a_y, _w, _c_o_l_o_r_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Colormap _c_o_l_o_r_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_c_o_l_o_r_m_a_p  Specifies the colormap.
││__

The _X_S_e_t_W_i_n_d_o_w_C_o_l_o_r_m_a_p function sets the specified colormap
of the specified window.  The colormap must have the same
visual type as the window, or a _B_a_d_M_a_t_c_h error results.

_X_S_e_t_W_i_n_d_o_w_C_o_l_o_r_m_a_p can generate _B_a_d_C_o_l_o_r, _B_a_d_M_a_t_c_h, and _B_a_d_­
_W_i_n_d_o_w errors.


To define which cursor will be used in a window, use _X_D_e_­
_f_i_n_e_C_u_r_s_o_r.
__
││
XDefineCursor(_d_i_s_p_l_a_y, _w, _c_u_r_s_o_r)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Cursor _c_u_r_s_o_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_c_u_r_s_o_r    Specifies the cursor that is to be displayed or
          _N_o_n_e.
││__

If a cursor is set, it will be used when the pointer is in
the window.  If the cursor is _N_o_n_e, it is equivalent to _X_U_n_­
_d_e_f_i_n_e_C_u_r_s_o_r.

_X_D_e_f_i_n_e_C_u_r_s_o_r can generate _B_a_d_C_u_r_s_o_r and _B_a_d_W_i_n_d_o_w errors.


To undefine the cursor in a given window, use _X_U_n_d_e_f_i_n_e_C_u_r_­
_s_o_r.








                             7799





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XUndefineCursor(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_U_n_d_e_f_i_n_e_C_u_r_s_o_r function undoes the effect of a previous
_X_D_e_f_i_n_e_C_u_r_s_o_r for this window.  When the pointer is in the
window, the parent’s cursor will now be used.  On the root
window, the default cursor is restored.

_X_U_n_d_e_f_i_n_e_C_u_r_s_o_r can generate a _B_a_d_W_i_n_d_o_w error.








































                             8800





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 44

                WWiinnddooww IInnffoorrmmaattiioonn FFuunnccttiioonnss



After you connect the display to the X server and create a
window, you can use the Xlib window information functions
to:

⋅    Obtain information about a window

⋅    Translate screen coordinates

⋅    Manipulate property lists

⋅    Obtain and change window properties

⋅    Manipulate selections

44..11..  OObbttaaiinniinngg WWiinnddooww IInnffoorrmmaattiioonn

Xlib provides functions that you can use to obtain informa­
tion about the window tree, the window’s current attributes,
the window’s current geometry, or the current pointer coor­
dinates.  Because they are most frequently used by window
managers, these functions all return a status to indicate
whether the window still exists.


To obtain the parent, a list of children, and number of
children for a given window, use _X_Q_u_e_r_y_T_r_e_e.























                             8811





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XQueryTree(_d_i_s_p_l_a_y, _w, _r_o_o_t___r_e_t_u_r_n, _p_a_r_e_n_t___r_e_t_u_r_n, _c_h_i_l_d_r_e_n___r_e_t_u_r_n, _n_c_h_i_l_d_r_e_n___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Window *_r_o_o_t___r_e_t_u_r_n;
      Window *_p_a_r_e_n_t___r_e_t_u_r_n;
      Window **_c_h_i_l_d_r_e_n___r_e_t_u_r_n;
      unsigned int *_n_c_h_i_l_d_r_e_n___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose list of children, root,
          parent, and number of children you want to obtain.

_r_o_o_t___r_e_t_u_r_n
          Returns the root window.

_p_a_r_e_n_t___r_e_t_u_r_n
          Returns the parent window.

_c_h_i_l_d_r_e_n___r_e_t_u_r_n
          Returns the list of children.

_n_c_h_i_l_d_r_e_n___r_e_t_u_r_n
          Returns the number of children.
││__

The _X_Q_u_e_r_y_T_r_e_e function returns the root ID, the parent win­
dow ID, a pointer to the list of children windows (NULL when
there are no children), and the number of children in the
list for the specified window.  The children are listed in
current stacking order, from bottom‐most (first) to top‐most
(last).  _X_Q_u_e_r_y_T_r_e_e returns zero if it fails and nonzero if
it succeeds.  To free a non‐NULL children list when it is no
longer needed, use _X_F_r_e_e.

_X_Q_u_e_r_y_T_r_e_e can generate a _B_a_d_W_i_n_d_o_w error.


To obtain the current attributes of a given window, use
_X_G_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s.















                             8822





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetWindowAttributes(_d_i_s_p_l_a_y, _w, _w_i_n_d_o_w___a_t_t_r_i_b_u_t_e_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XWindowAttributes *_w_i_n_d_o_w___a_t_t_r_i_b_u_t_e_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose current attributes you
          want to obtain.

_w_i_n_d_o_w___a_t_t_r_i_b_u_t_e_s___r_e_t_u_r_n
          Returns the specified window’s attributes in the
          _X_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s structure.
││__

The _X_G_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s function returns the current
attributes for the specified window to an _X_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s
structure.

__
││
typedef struct {
     int x, y;                /* location of window */
     int width, height;       /* width and height of window */
     int border_width;        /* border width of window */
     int depth;               /* depth of window */
     Visual *visual;          /* the associated visual structure */
     Window root;             /* root of screen containing window */
     int class;               /* InputOutput, InputOnly*/
     int bit_gravity;         /* one of the bit gravity values */
     int win_gravity;         /* one of the window gravity values */
     int backing_store;       /* NotUseful, WhenMapped, Always */
     unsigned long backing_planes;/* planes to be preserved if possible */
     unsigned long backing_pixel;/* value to be used when restoring planes */
     Bool save_under;         /* boolean, should bits under be saved? */
     Colormap colormap;       /* color map to be associated with window */
     Bool map_installed;      /* boolean, is color map currently installed*/
     int map_state;           /* IsUnmapped, IsUnviewable, IsViewable */
     long all_event_masks;    /* set of events all people have interest in*/
     long your_event_mask;    /* my event mask */
     long do_not_propagate_mask;/* set of events that should not propagate */
     Bool override_redirect;  /* boolean value for override‐redirect */
     Screen *screen;          /* back pointer to correct screen */
} XWindowAttributes;

││__

The x and y members are set to the upper‐left outer corner
relative to the parent window’s origin.  The width and
height members are set to the inside size of the window, not
including the border.  The border_width member is set to the
window’s border width in pixels.  The depth member is set to



                             8833





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the depth of the window (that is, bits per pixel for the
object).  The visual member is a pointer to the screen’s
associated _V_i_s_u_a_l structure.  The root member is set to the
root window of the screen containing the window.  The class
member is set to the window’s class and can be either
_I_n_p_u_t_O_u_t_p_u_t or _I_n_p_u_t_O_n_l_y.

The bit_gravity member is set to the window’s bit gravity
and can be one of the following:


_F_o_r_g_e_t_G_r_a_v_i_t_y     _E_a_s_t_G_r_a_v_i_t_y
_N_o_r_t_h_W_e_s_t_G_r_a_v_­    _S_o_u_t_h_W_e_s_t_G_r_a_v_­
_i_t_y               _i_t_y
_N_o_r_t_h_G_r_a_v_i_t_y      _S_o_u_t_h_G_r_a_v_i_t_y
_N_o_r_t_h_E_a_s_t_G_r_a_v_­    _S_o_u_t_h_E_a_s_t_G_r_a_v_­
_i_t_y               _i_t_y
_W_e_s_t_G_r_a_v_i_t_y       _S_t_a_t_i_c_G_r_a_v_i_t_y
_C_e_n_t_e_r_G_r_a_v_i_t_y


The win_gravity member is set to the window’s window gravity
and can be one of the following:


_U_n_m_a_p_G_r_a_v_i_t_y      _E_a_s_t_G_r_a_v_i_t_y
_N_o_r_t_h_W_e_s_t_G_r_a_v_­    _S_o_u_t_h_W_e_s_t_G_r_a_v_­
_i_t_y               _i_t_y
_N_o_r_t_h_G_r_a_v_i_t_y      _S_o_u_t_h_G_r_a_v_i_t_y
_N_o_r_t_h_E_a_s_t_G_r_a_v_­    _S_o_u_t_h_E_a_s_t_G_r_a_v_­
_i_t_y               _i_t_y
_W_e_s_t_G_r_a_v_i_t_y       _S_t_a_t_i_c_G_r_a_v_i_t_y
_C_e_n_t_e_r_G_r_a_v_i_t_y


For additional information on gravity, see section 3.2.3.

The backing_store member is set to indicate how the X server
should maintain the contents of a window and can be _W_h_e_n_­
_M_a_p_p_e_d, _A_l_w_a_y_s, or _N_o_t_U_s_e_f_u_l.  The backing_planes member is
set to indicate (with bits set to 1) which bit planes of the
window hold dynamic data that must be preserved in back­
ing_stores and during save_unders.  The backing_pixel member
is set to indicate what values to use for planes not set in
backing_planes.

The save_under member is set to _T_r_u_e or _F_a_l_s_e.  The colormap
member is set to the colormap for the specified window and
can be a colormap ID or _N_o_n_e.  The map_installed member is
set to indicate whether the colormap is currently installed
and can be _T_r_u_e or _F_a_l_s_e.  The map_state member is set to
indicate the state of the window and can be _I_s_U_n_m_a_p_p_e_d,
_I_s_U_n_v_i_e_w_a_b_l_e, or _I_s_V_i_e_w_a_b_l_e.  _I_s_U_n_v_i_e_w_a_b_l_e is used if the
window is mapped but some ancestor is unmapped.



                             8844





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The all_event_masks member is set to the bitwise inclusive
OR of all event masks selected on the window by all clients.
The your_event_mask member is set to the bitwise inclusive
OR of all event masks selected by the querying client.  The
do_not_propagate_mask member is set to the bitwise inclusive
OR of the set of events that should not propagate.

The override_redirect member is set to indicate whether this
window overrides structure control facilities and can be
_T_r_u_e or _F_a_l_s_e.  Window manager clients should ignore the
window if this member is _T_r_u_e.

The screen member is set to a screen pointer that gives you
a back pointer to the correct screen.  This makes it easier
to obtain the screen information without having to loop over
the root window fields to see which field matches.

_X_G_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s can generate _B_a_d_D_r_a_w_a_b_l_e and _B_a_d_W_i_n_d_o_w
errors.


To obtain the current geometry of a given drawable, use
_X_G_e_t_G_e_o_m_e_t_r_y.


































                             8855





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetGeometry(_d_i_s_p_l_a_y, _d, _r_o_o_t___r_e_t_u_r_n, _x___r_e_t_u_r_n, _y___r_e_t_u_r_n, _w_i_d_t_h___r_e_t_u_r_n,
                      _h_e_i_g_h_t___r_e_t_u_r_n, _b_o_r_d_e_r___w_i_d_t_h___r_e_t_u_r_n, _d_e_p_t_h___r_e_t_u_r_n)
        Display *_d_i_s_p_l_a_y;
        Drawable _d;
        Window *_r_o_o_t___r_e_t_u_r_n;
        int *_x___r_e_t_u_r_n, *_y___r_e_t_u_r_n;
        unsigned int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;
        unsigned int *_b_o_r_d_e_r___w_i_d_t_h___r_e_t_u_r_n;
        unsigned int *_d_e_p_t_h___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable, which can be a window or a
          pixmap.

_r_o_o_t___r_e_t_u_r_n
          Returns the root window.

_x___r_e_t_u_r_n
_y___r_e_t_u_r_n  Return the x and y coordinates that define the
          location of the drawable.  For a window, these
          coordinates specify the upper‐left outer corner
          relative to its parent’s origin.  For pixmaps,
          these coordinates are always zero.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the drawable’s dimensions (width and
          height).  For a window, these dimensions specify
          the inside size, not including the border.

_b_o_r_d_e_r___w_i_d_t_h___r_e_t_u_r_n
          Returns the border width in pixels.  If the draw­
          able is a pixmap, it returns zero.

_d_e_p_t_h___r_e_t_u_r_n
          Returns the depth of the drawable (bits per pixel
          for the object).
││__

The _X_G_e_t_G_e_o_m_e_t_r_y function returns the root window and the
current geometry of the drawable.  The geometry of the draw­
able includes the x and y coordinates, width and height,
border width, and depth.  These are described in the argu­
ment list.  It is legal to pass to this function a window
whose class is _I_n_p_u_t_O_n_l_y.

_X_G_e_t_G_e_o_m_e_t_r_y can generate a _B_a_d_D_r_a_w_a_b_l_e error.







                             8866





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


44..22..  TTrraannssllaattiinngg SSccrreeeenn CCoooorrddiinnaatteess

Applications sometimes need to perform a coordinate trans­
formation from the coordinate space of one window to another
window or need to determine which window the pointing device
is in.  _X_T_r_a_n_s_l_a_t_e_C_o_o_r_d_i_n_a_t_e_s and _X_Q_u_e_r_y_P_o_i_n_t_e_r fulfill
these needs (and avoid any race conditions) by asking the X
server to perform these operations.


To translate a coordinate in one window to the coordinate
space of another window, use _X_T_r_a_n_s_l_a_t_e_C_o_o_r_d_i_n_a_t_e_s.
__
││
Bool XTranslateCoordinates(_d_i_s_p_l_a_y, _s_r_c___w, _d_e_s_t___w, _s_r_c___x, _s_r_c___y, _d_e_s_t___x___r_e_t_u_r_n,
                            _d_e_s_t___y___r_e_t_u_r_n, _c_h_i_l_d___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _s_r_c___w, _d_e_s_t___w;
      int _s_r_c___x, _s_r_c___y;
      int *_d_e_s_t___x___r_e_t_u_r_n, *_d_e_s_t___y___r_e_t_u_r_n;
      Window *_c_h_i_l_d___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_r_c___w     Specifies the source window.

_d_e_s_t___w    Specifies the destination window.

_s_r_c___x
_s_r_c___y     Specify the x and y coordinates within the source
          window.

_d_e_s_t___x___r_e_t_u_r_n
_d_e_s_t___y___r_e_t_u_r_n
          Return the x and y coordinates within the destina­
          tion window.

_c_h_i_l_d___r_e_t_u_r_n
          Returns the child if the coordinates are contained
          in a mapped child of the destination window.
││__

If _X_T_r_a_n_s_l_a_t_e_C_o_o_r_d_i_n_a_t_e_s returns _T_r_u_e, it takes the src_x
and src_y coordinates relative to the source window’s origin
and returns these coordinates to dest_x_return and
dest_y_return relative to the destination window’s origin.
If _X_T_r_a_n_s_l_a_t_e_C_o_o_r_d_i_n_a_t_e_s returns _F_a_l_s_e, src_w and dest_w are
on different screens, and dest_x_return and dest_y_return
are zero.  If the coordinates are contained in a mapped
child of dest_w, that child is returned to child_return.
Otherwise, child_return is set to _N_o_n_e.





                             8877





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_T_r_a_n_s_l_a_t_e_C_o_o_r_d_i_n_a_t_e_s can generate a _B_a_d_W_i_n_d_o_w error.


To obtain the screen coordinates of the pointer or to deter­
mine the pointer coordinates relative to a specified window,
use _X_Q_u_e_r_y_P_o_i_n_t_e_r.
__
││
Bool XQueryPointer(_d_i_s_p_l_a_y, _w, _r_o_o_t___r_e_t_u_r_n, _c_h_i_l_d___r_e_t_u_r_n, _r_o_o_t___x___r_e_t_u_r_n, _r_o_o_t___y___r_e_t_u_r_n,
                     _w_i_n___x___r_e_t_u_r_n, _w_i_n___y___r_e_t_u_r_n, _m_a_s_k___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Window *_r_o_o_t___r_e_t_u_r_n, *_c_h_i_l_d___r_e_t_u_r_n;
      int *_r_o_o_t___x___r_e_t_u_r_n, *_r_o_o_t___y___r_e_t_u_r_n;
      int *_w_i_n___x___r_e_t_u_r_n, *_w_i_n___y___r_e_t_u_r_n;
      unsigned int *_m_a_s_k___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_r_o_o_t___r_e_t_u_r_n
          Returns the root window that the pointer is in.

_c_h_i_l_d___r_e_t_u_r_n
          Returns the child window that the pointer is
          located in, if any.

_r_o_o_t___x___r_e_t_u_r_n
_r_o_o_t___y___r_e_t_u_r_n
          Return the pointer coordinates relative to the
          root window’s origin.

_w_i_n___x___r_e_t_u_r_n
_w_i_n___y___r_e_t_u_r_n
          Return the pointer coordinates relative to the
          specified window.

_m_a_s_k___r_e_t_u_r_n
          Returns the current state of the modifier keys and
          pointer buttons.
││__

The _X_Q_u_e_r_y_P_o_i_n_t_e_r function returns the root window the
pointer is logically on and the pointer coordinates relative
to the root window’s origin.  If _X_Q_u_e_r_y_P_o_i_n_t_e_r returns
_F_a_l_s_e, the pointer is not on the same screen as the speci­
fied window, and _X_Q_u_e_r_y_P_o_i_n_t_e_r returns _N_o_n_e to child_return
and zero to win_x_return and win_y_return.  If _X_Q_u_e_r_y_P_o_i_n_t_e_r
returns _T_r_u_e, the pointer coordinates returned to
win_x_return and win_y_return are relative to the origin of
the specified window.  In this case, _X_Q_u_e_r_y_P_o_i_n_t_e_r returns
the child that contains the pointer, if any, or else _N_o_n_e to



                             8888





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


child_return.

_X_Q_u_e_r_y_P_o_i_n_t_e_r returns the current logical state of the key­
board buttons and the modifier keys in mask_return.  It sets
mask_return to the bitwise inclusive OR of one or more of
the button or modifier key bitmasks to match the current
state of the mouse buttons and the modifier keys.

Note that the logical state of a device (as seen through
Xlib) may lag the physical state if device event processing
is frozen (see section 12.1).

_X_Q_u_e_r_y_P_o_i_n_t_e_r can generate a _B_a_d_W_i_n_d_o_w error.

44..33..  PPrrooppeerrttiieess aanndd AAttoommss

A property is a collection of named, typed data.  The window
system has a set of predefined properties (for example, the
name of a window, size hints, and so on), and users can
define any other arbitrary information and associate it with
windows.  Each property has a name, which is an ISO Latin‐1
string.  For each named property, a unique identifier (atom)
is associated with it.  A property also has a type, for
example, string or integer.  These types are also indicated
using atoms, so arbitrary new types can be defined.  Data of
only one type may be associated with a single property name.
Clients can store and retrieve properties associated with
windows.  For efficiency reasons, an atom is used rather
than a character string.  _X_I_n_t_e_r_n_A_t_o_m can be used to obtain
the atom for property names.

A property is also stored in one of several possible for­
mats.  The X server can store the information as 8‐bit quan­
tities, 16‐bit quantities, or 32‐bit quantities.  This per­
mits the X server to present the data in the byte order that
the client expects.

                            Note

     If you define further properties of complex type,
     you must encode and decode them yourself.  These
     functions must be carefully written if they are to
     be portable.  For further information about how to
     write a library extension, see appendix C.

The type of a property is defined by an atom, which allows
for arbitrary extension in this type scheme.

Certain property names are predefined in the server for com­
monly used functions.  The atoms for these properties are
defined in <_X_1_1_/_X_a_t_o_m_._h>.  To avoid name clashes with user
symbols, the _#_d_e_f_i_n_e name for each atom has the XA_ prefix.
For an explanation of the functions that let you get and set
much of the information stored in these predefined



                             8899





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


properties, see chapter 14.

The core protocol imposes no semantics on these property
names, but semantics are specified in other X Consortium
standards, such as the _I_n_t_e_r_‐_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_­
_t_i_o_n_s _M_a_n_u_a_l and the _X _L_o_g_i_c_a_l _F_o_n_t _D_e_s_c_r_i_p_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s.

You can use properties to communicate other information
between applications.  The functions described in this sec­
tion let you define new properties and get the unique atom
IDs in your applications.

Although any particular atom can have some client interpre­
tation within each of the name spaces, atoms occur in five
distinct name spaces within the protocol:

⋅    Selections

⋅    Property names

⋅    Property types

⋅    Font properties

⋅    Type of a _C_l_i_e_n_t_M_e_s_s_a_g_e event (none are built into the
     X server)


The built‐in selection property names are:


PRIMARY
SECONDARY


The built‐in property names are:

CUT_BUFFER0            RESOURCE_MANAGER
CUT_BUFFER1            WM_CLASS
CUT_BUFFER2            WM_CLIENT_MACHINE
CUT_BUFFER3            WM_COLORMAP_WINDOWS
CUT_BUFFER4            WM_COMMAND
CUT_BUFFER5            WM_HINTS
CUT_BUFFER6            WM_ICON_NAME
CUT_BUFFER7            WM_ICON_SIZE
RGB_BEST_MAP           WM_NAME
RGB_BLUE_MAP           WM_NORMAL_HINTS
RGB_DEFAULT_MAP        WM_PROTOCOLS
RGB_GRAY_MAP           WM_STATE
RGB_GREEN_MAP          WM_TRANSIENT_FOR
RGB_RED_MAP            WM_ZOOM_HINTS






                             9900





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The built‐in property types are:


ARC                    POINT
ATOM                   RGB_COLOR_MAP
BITMAP                 RECTANGLE
CARDINAL               STRING
COLORMAP               VISUALID
CURSOR                 WINDOW
DRAWABLE               WM_HINTS
FONT                   WM_SIZE_HINTS
INTEGER
PIXMAP


The built‐in font property names are:

MIN_SPACE              STRIKEOUT_DESCENT
NORM_SPACE             STRIKEOUT_ASCENT
MAX_SPACE              ITALIC_ANGLE
END_SPACE              X_HEIGHT
SUPERSCRIPT_X          QUAD_WIDTH
SUPERSCRIPT_Y          WEIGHT
SUBSCRIPT_X            POINT_SIZE
SUBSCRIPT_Y            RESOLUTION
UNDERLINE_POSITION     COPYRIGHT
UNDERLINE_THICKNESS    NOTICE
FONT_NAME              FAMILY_NAME
FULL_NAME              CAP_HEIGHT


For further information about font properties, see section
8.5.


To return an atom for a given name, use _X_I_n_t_e_r_n_A_t_o_m.





















                             9911





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Atom XInternAtom(_d_i_s_p_l_a_y, _a_t_o_m___n_a_m_e, _o_n_l_y___i_f___e_x_i_s_t_s)
      Display *_d_i_s_p_l_a_y;
      char *_a_t_o_m___n_a_m_e;
      Bool _o_n_l_y___i_f___e_x_i_s_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_a_t_o_m___n_a_m_e Specifies the name associated with the atom you
          want returned.

_o_n_l_y___i_f___e_x_i_s_t_s
          Specifies a Boolean value that indicates whether
          the atom must be created.
││__

The _X_I_n_t_e_r_n_A_t_o_m function returns the atom identifier associ­
ated with the specified atom_name string.  If only_if_exists
is _F_a_l_s_e, the atom is created if it does not exist.  There­
fore, _X_I_n_t_e_r_n_A_t_o_m can return _N_o_n_e.  If the atom name is not
in the Host Portable Character Encoding, the result is
implementation‐dependent.  Uppercase and lowercase matter;
the strings ‘‘thing’’, ‘‘Thing’’, and ‘‘thinG’’ all desig­
nate different atoms.  The atom will remain defined even
after the client’s connection closes.  It will become unde­
fined only when the last connection to the X server closes.

_X_I_n_t_e_r_n_A_t_o_m can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e errors.


To return atoms for an array of names, use _X_I_n_t_e_r_n_A_t_o_m_s.

























                             9922





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XInternAtoms(_d_i_s_p_l_a_y, _n_a_m_e_s, _c_o_u_n_t, _o_n_l_y___i_f___e_x_i_s_t_s, _a_t_o_m_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      char **_n_a_m_e_s;
      int _c_o_u_n_t;
      Bool _o_n_l_y___i_f___e_x_i_s_t_s;
      Atom *_a_t_o_m_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_a_m_e_s     Specifies the array of atom names.

_c_o_u_n_t     Specifies the number of atom names in the array.

_o_n_l_y___i_f___e_x_i_s_t_s
          Specifies a Boolean value that indicates whether
          the atom must be created.

_a_t_o_m_s___r_e_t_u_r_n
          Returns the atoms.
││__

The _X_I_n_t_e_r_n_A_t_o_m_s function returns the atom identifiers asso­
ciated with the specified names.  The atoms are stored in
the atoms_return array supplied by the caller.  Calling this
function is equivalent to calling _X_I_n_t_e_r_n_A_t_o_m for each of
the names in turn with the specified value of
only_if_exists, but this function minimizes the number of
round‐trip protocol exchanges between the client and the X
server.

This function returns a nonzero status if atoms are returned
for all of the names; otherwise, it returns zero.

_X_I_n_t_e_r_n_A_t_o_m_s can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e errors.


To return a name for a given atom identifier, use _X_G_e_t_A_t_o_m_­
_N_a_m_e.
__
││
char *XGetAtomName(_d_i_s_p_l_a_y, _a_t_o_m)
      Display *_d_i_s_p_l_a_y;
      Atom _a_t_o_m;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_a_t_o_m      Specifies the atom for the property name you want
          returned.
││__

The _X_G_e_t_A_t_o_m_N_a_m_e function returns the name associated with



                             9933





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the specified atom.  If the data returned by the server is
in the Latin Portable Character Encoding, then the returned
string is in the Host Portable Character Encoding.  Other­
wise, the result is implementation‐dependent.  To free the
resulting string, call _X_F_r_e_e.

_X_G_e_t_A_t_o_m_N_a_m_e can generate a _B_a_d_A_t_o_m error.


To return the names for an array of atom identifiers, use
_X_G_e_t_A_t_o_m_N_a_m_e_s.
__
││
Status XGetAtomNames(_d_i_s_p_l_a_y, _a_t_o_m_s, _c_o_u_n_t, _n_a_m_e_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Atom *_a_t_o_m_s;
      int _c_o_u_n_t;
      char **_n_a_m_e_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_a_t_o_m_s     Specifies the array of atoms.

_c_o_u_n_t     Specifies the number of atoms in the array.

_n_a_m_e_s___r_e_t_u_r_n
          Returns the atom names.
││__

The _X_G_e_t_A_t_o_m_N_a_m_e_s function returns the names associated with
the specified atoms.  The names are stored in the
names_return array supplied by the caller.  Calling this
function is equivalent to calling _X_G_e_t_A_t_o_m_N_a_m_e for each of
the atoms in turn, but this function minimizes the number of
round‐trip protocol exchanges between the client and the X
server.

This function returns a nonzero status if names are returned
for all of the atoms; otherwise, it returns zero.

_X_G_e_t_A_t_o_m_N_a_m_e_s can generate a _B_a_d_A_t_o_m error.

44..44..  OObbttaaiinniinngg aanndd CChhaannggiinngg WWiinnddooww PPrrooppeerrttiieess

You can attach a property list to every window.  Each prop­
erty has a name, a type, and a value (see section 4.3).  The
value is an array of 8‐bit, 16‐bit, or 32‐bit quantities,
whose interpretation is left to the clients.  The type _c_h_a_r
is used to represent 8‐bit quantities, the type _s_h_o_r_t is
used to represent 16‐bit quantities, and the type _l_o_n_g is
used to represent 32‐bit quantities.





                             9944





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Xlib provides functions that you can use to obtain, change,
update, or interchange window properties.  In addition, Xlib
provides other utility functions for inter‐client communica­
tion (see chapter 14).


To obtain the type, format, and value of a property of a
given window, use _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y.

















































                             9955





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XGetWindowProperty(_d_i_s_p_l_a_y, _w, _p_r_o_p_e_r_t_y, _l_o_n_g___o_f_f_s_e_t, _l_o_n_g___l_e_n_g_t_h, _d_e_l_e_t_e, _r_e_q___t_y_p_e,
                        _a_c_t_u_a_l___t_y_p_e___r_e_t_u_r_n, _a_c_t_u_a_l___f_o_r_m_a_t___r_e_t_u_r_n, _n_i_t_e_m_s___r_e_t_u_r_n, _b_y_t_e_s___a_f_t_e_r___r_e_t_u_r_n,
                        _p_r_o_p___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Atom _p_r_o_p_e_r_t_y;
      long _l_o_n_g___o_f_f_s_e_t, _l_o_n_g___l_e_n_g_t_h;
      Bool _d_e_l_e_t_e;
      Atom _r_e_q___t_y_p_e;
      Atom *_a_c_t_u_a_l___t_y_p_e___r_e_t_u_r_n;
      int *_a_c_t_u_a_l___f_o_r_m_a_t___r_e_t_u_r_n;
      unsigned long *_n_i_t_e_m_s___r_e_t_u_r_n;
      unsigned long *_b_y_t_e_s___a_f_t_e_r___r_e_t_u_r_n;
      unsigned char **_p_r_o_p___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose property you want to
          obtain.

_p_r_o_p_e_r_t_y  Specifies the property name.

_l_o_n_g___o_f_f_s_e_t
          Specifies the offset in the specified property (in
          32‐bit quantities) where the data is to be
          retrieved.

_l_o_n_g___l_e_n_g_t_h
          Specifies the length in 32‐bit multiples of the
          data to be retrieved.

_d_e_l_e_t_e    Specifies a Boolean value that determines whether
          the property is deleted.

_r_e_q___t_y_p_e  Specifies the atom identifier associated with the
          property type or _A_n_y_P_r_o_p_e_r_t_y_T_y_p_e.

_a_c_t_u_a_l___t_y_p_e___r_e_t_u_r_n
          Returns the atom identifier  that defines the
          actual type of the property.

_a_c_t_u_a_l___f_o_r_m_a_t___r_e_t_u_r_n
          Returns the actual format of the property.

_n_i_t_e_m_s___r_e_t_u_r_n
          Returns the actual number of 8‐bit, 16‐bit, or
          32‐bit items stored in the prop_return data.

_b_y_t_e_s___a_f_t_e_r___r_e_t_u_r_n
          Returns the number of bytes remaining to be read
          in the property if a partial read was performed.




                             9966





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_p_r_o_p___r_e_t_u_r_n
          Returns the data in the specified format.
││__

The _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y function returns the actual type of
the property; the actual format of the property; the number
of 8‐bit, 16‐bit, or 32‐bit items transferred; the number of
bytes remaining to be read in the property; and a pointer to
the data actually returned.  _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y sets the
return arguments as follows:

⋅    If the specified property does not exist for the speci­
     fied window, _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y returns _N_o_n_e to
     actual_type_return and the value zero to actual_for­
     mat_return and bytes_after_return.  The nitems_return
     argument is empty.  In this case, the delete argument
     is ignored.

⋅    If the specified property exists but its type does not
     match the specified type, _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y returns
     the actual property type to actual_type_return, the
     actual property format (never zero) to actual_for­
     mat_return, and the property length in bytes (even if
     the actual_format_return is 16 or 32) to
     bytes_after_return.  It also ignores the delete argu­
     ment.  The nitems_return argument is empty.

⋅    If the specified property exists and either you assign
     _A_n_y_P_r_o_p_e_r_t_y_T_y_p_e to the req_type argument or the speci­
     fied type matches the actual property type, _X_G_e_t_W_i_n_d_o_w_­
     _P_r_o_p_e_r_t_y returns the actual property type to
     actual_type_return and the actual property format
     (never zero) to actual_format_return.  It also returns
     a value to bytes_after_return and nitems_return, by
     defining the following values:

          N = actual length of the stored property in bytes
               (even if the format is 16 or 32)
          I = 4 * long_offset
          T = N ‐ I
          L = MINIMUM(T, 4 * long_length)
          A = N ‐ (I + L)

     The returned value starts at byte index I in the prop­
     erty (indexing from zero), and its length in bytes is
     L.  If the value for long_offset causes L to be nega­
     tive, a _B_a_d_V_a_l_u_e error results.  The value of
     bytes_after_return is A, giving the number of trailing
     unread bytes in the stored property.

If the returned format is 8, the returned data is repre­
sented as a _c_h_a_r array.  If the returned format is 16, the
returned data is represented as a _s_h_o_r_t array and should be
cast to that type to obtain the elements.  If the returned



                             9977





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


format is 32, the returned data is represented as a _l_o_n_g
array and should be cast to that type to obtain the ele­
ments.

_X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y always allocates one extra byte in
prop_return (even if the property is zero length) and sets
it to zero so that simple properties consisting of charac­
ters do not have to be copied into yet another string before
use.

If delete is _T_r_u_e and bytes_after_return is zero, _X_G_e_t_W_i_n_­
_d_o_w_P_r_o_p_e_r_t_y deletes the property from the window and gener­
ates a _P_r_o_p_e_r_t_y_N_o_t_i_f_y event on the window.

The function returns _S_u_c_c_e_s_s if it executes successfully.
To free the resulting data, use _X_F_r_e_e.

_X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y can generate _B_a_d_A_t_o_m, _B_a_d_V_a_l_u_e, and _B_a_d_­
_W_i_n_d_o_w errors.


To obtain a given window’s property list, use _X_L_i_s_t_P_r_o_p_e_r_­
_t_i_e_s.
__
││
Atom *XListProperties(_d_i_s_p_l_a_y, _w, _n_u_m___p_r_o_p___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int *_n_u_m___p_r_o_p___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose property list you want
          to obtain.

_n_u_m___p_r_o_p___r_e_t_u_r_n
          Returns the length of the properties array.
││__

The _X_L_i_s_t_P_r_o_p_e_r_t_i_e_s function returns a pointer to an array
of atom properties that are defined for the specified window
or returns NULL if no properties were found.  To free the
memory allocated by this function, use _X_F_r_e_e.

_X_L_i_s_t_P_r_o_p_e_r_t_i_e_s can generate a _B_a_d_W_i_n_d_o_w error.


To change a property of a given window, use _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y.








                             9988





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XChangeProperty(_d_i_s_p_l_a_y, _w, _p_r_o_p_e_r_t_y, _t_y_p_e, _f_o_r_m_a_t, _m_o_d_e, _d_a_t_a, _n_e_l_e_m_e_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Atom _p_r_o_p_e_r_t_y, _t_y_p_e;
      int _f_o_r_m_a_t;
      int _m_o_d_e;
      unsigned char *_d_a_t_a;
      int _n_e_l_e_m_e_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose property you want to
          change.

_p_r_o_p_e_r_t_y  Specifies the property name.

_t_y_p_e      Specifies the type of the property.  The X server
          does not interpret the type but simply passes it
          back to an application that later calls _X_G_e_t_W_i_n_­
          _d_o_w_P_r_o_p_e_r_t_y.

_f_o_r_m_a_t    Specifies whether the data should be viewed as a
          list of 8‐bit, 16‐bit, or 32‐bit quantities.  Pos­
          sible values are 8, 16, and 32.  This information
          allows the X server to correctly perform byte‐swap
          operations as necessary.  If the format is 16‐bit
          or 32‐bit, you must explicitly cast your data
          pointer to an (unsigned char *) in the call to
          _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y.

_m_o_d_e      Specifies the mode of the operation.  You can pass
          _P_r_o_p_M_o_d_e_R_e_p_l_a_c_e, _P_r_o_p_M_o_d_e_P_r_e_p_e_n_d, or _P_r_o_p_M_o_d_e_A_p_­
          _p_e_n_d.

_d_a_t_a      Specifies the property data.

_n_e_l_e_m_e_n_t_s Specifies the number of elements of the specified
          data format.
││__

The _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y function alters the property for the
specified window and causes the X server to generate a _P_r_o_p_­
_e_r_t_y_N_o_t_i_f_y event on that window.  _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y performs
the following:

⋅    If mode is _P_r_o_p_M_o_d_e_R_e_p_l_a_c_e, _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y discards
     the previous property value and stores the new data.

⋅    If mode is _P_r_o_p_M_o_d_e_P_r_e_p_e_n_d or _P_r_o_p_M_o_d_e_A_p_p_e_n_d, _X_C_h_a_n_g_e_­
     _P_r_o_p_e_r_t_y inserts the specified data before the begin­
     ning of the existing data or onto the end of the exist­
     ing data, respectively.  The type and format must match



                             9999





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     the existing property value, or a _B_a_d_M_a_t_c_h error
     results.  If the property is undefined, it is treated
     as defined with the correct type and format with zero‐
     length data.

If the specified format is 8, the property data must be a
_c_h_a_r array.  If the specified format is 16, the property
data must be a _s_h_o_r_t array.  If the specified format is 32,
the property data must be a _l_o_n_g array.

The lifetime of a property is not tied to the storing
client.  Properties remain until explicitly deleted, until
the window is destroyed, or until the server resets.  For a
discussion of what happens when the connection to the X
server is closed, see section 2.6.  The maximum size of a
property is server dependent and can vary dynamically
depending on the amount of memory the server has available.
(If there is insufficient space, a _B_a_d_A_l_l_o_c error results.)

_X_C_h_a_n_g_e_P_r_o_p_e_r_t_y can generate _B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, _B_a_d_M_a_t_c_h,
_B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w errors.


To rotate a window’s property list, use _X_R_o_t_a_t_e_W_i_n_d_o_w_P_r_o_p_e_r_­
_t_i_e_s.

__
││
XRotateWindowProperties(_d_i_s_p_l_a_y, _w, _p_r_o_p_e_r_t_i_e_s, _n_u_m___p_r_o_p, _n_p_o_s_i_t_i_o_n_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Atom _p_r_o_p_e_r_t_i_e_s[];
      int _n_u_m___p_r_o_p;
      int _n_p_o_s_i_t_i_o_n_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_p_r_o_p_e_r_t_i_e_s
          Specifies the array of properties that are to be
          rotated.

_n_u_m___p_r_o_p  Specifies the length of the properties array.

_n_p_o_s_i_t_i_o_n_s
          Specifies the rotation amount.
││__

The _X_R_o_t_a_t_e_W_i_n_d_o_w_P_r_o_p_e_r_t_i_e_s function allows you to rotate
properties on a window and causes the X server to generate
_P_r_o_p_e_r_t_y_N_o_t_i_f_y events.  If the property names in the proper­
ties array are viewed as being numbered starting from zero



                             110000





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


and if there are num_prop property names in the list, then
the value associated with property name I becomes the value
associated with property name (I + npositions) mod N for all
I from zero to N − 1.  The effect is to rotate the states by
npositions places around the virtual ring of property names
(right for positive npositions, left for negative nposi­
tions).  If npositions mod N is nonzero, the X server gener­
ates a _P_r_o_p_e_r_t_y_N_o_t_i_f_y event for each property in the order
that they are listed in the array.  If an atom occurs more
than once in the list or no property with that name is
defined for the window, a _B_a_d_M_a_t_c_h error results.  If a
_B_a_d_A_t_o_m or _B_a_d_M_a_t_c_h error results, no properties are
changed.

_X_R_o_t_a_t_e_W_i_n_d_o_w_P_r_o_p_e_r_t_i_e_s can generate _B_a_d_A_t_o_m, _B_a_d_M_a_t_c_h, and
_B_a_d_W_i_n_d_o_w errors.


To delete a property on a given window, use _X_D_e_l_e_t_e_P_r_o_p_e_r_t_y.
__
││
XDeleteProperty(_d_i_s_p_l_a_y, _w, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose property you want to
          delete.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_D_e_l_e_t_e_P_r_o_p_e_r_t_y function deletes the specified property
only if the property was defined on the specified window and
causes the X server to generate a _P_r_o_p_e_r_t_y_N_o_t_i_f_y event on
the window unless the property does not exist.

_X_D_e_l_e_t_e_P_r_o_p_e_r_t_y can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w errors.

44..55..  SSeelleeccttiioonnss

Selections are one method used by applications to exchange
data.  By using the property mechanism, applications can
exchange data of arbitrary types and can negotiate the type
of the data.  A selection can be thought of as an indirect
property with a dynamic type.  That is, rather than having
the property stored in the X server, the property is main­
tained by some client (the owner).  A selection is global in
nature (considered to belong to the user but be maintained
by clients) rather than being private to a particular window
subhierarchy or a particular set of clients.



                             110011





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Xlib provides functions that you can use to set, get, or
request conversion of selections.  This allows applications
to implement the notion of current selection, which requires
that notification be sent to applications when they no
longer own the selection.  Applications that support selec­
tion often highlight the current selection and so must be
informed when another application has acquired the selection
so that they can unhighlight the selection.

When a client asks for the contents of a selection, it spec­
ifies a selection target type.  This target type can be used
to control the transmitted representation of the contents.
For example, if the selection is ‘‘the last thing the user
clicked on’’ and that is currently an image, then the target
type might specify whether the contents of the image should
be sent in XY format or Z format.

The target type can also be used to control the class of
contents transmitted, for example, asking for the ‘‘looks’’
(fonts, line spacing, indentation, and so forth) of a para­
graph selection, not the text of the paragraph.  The target
type can also be used for other purposes.  The protocol does
not constrain the semantics.


To set the selection owner, use _X_S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r.
__
││
XSetSelectionOwner(_d_i_s_p_l_a_y, _s_e_l_e_c_t_i_o_n, _o_w_n_e_r, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      Atom _s_e_l_e_c_t_i_o_n;
      Window _o_w_n_e_r;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_e_l_e_c_t_i_o_n Specifies the selection atom.

_o_w_n_e_r     Specifies the owner of the specified selection
          atom.  You can pass a window or _N_o_n_e.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

The _X_S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r function changes the owner and last‐
change time for the specified selection and has no effect if
the specified time is earlier than the current last‐change
time of the specified selection or is later than the current
X server time.  Otherwise, the last‐change time is set to
the specified time, with _C_u_r_r_e_n_t_T_i_m_e replaced by the current
server time.  If the owner window is specified as _N_o_n_e, then
the owner of the selection becomes _N_o_n_e (that is, no owner).



                             110022





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Otherwise, the owner of the selection becomes the client
executing the request.

If the new owner (whether a client or _N_o_n_e) is not the same
as the current owner of the selection and the current owner
is not _N_o_n_e, the current owner is sent a _S_e_l_e_c_t_i_o_n_C_l_e_a_r
event.  If the client that is the owner of a selection is
later terminated (that is, its connection is closed) or if
the owner window it has specified in the request is later
destroyed, the owner of the selection automatically reverts
to _N_o_n_e, but the last‐change time is not affected.  The
selection atom is uninterpreted by the X server.  _X_G_e_t_S_e_l_e_c_­
_t_i_o_n_O_w_n_e_r returns the owner window, which is reported in
_S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t and _S_e_l_e_c_t_i_o_n_C_l_e_a_r events.  Selections are
global to the X server.

_X_S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w
errors.


To return the selection owner, use _X_G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r.
__
││
Window XGetSelectionOwner(_d_i_s_p_l_a_y, _s_e_l_e_c_t_i_o_n)
      Display *_d_i_s_p_l_a_y;
      Atom _s_e_l_e_c_t_i_o_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_e_l_e_c_t_i_o_n Specifies the selection atom whose owner you want
          returned.
││__

The _X_G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r function returns the window ID asso­
ciated with the window that currently owns the specified
selection.  If no selection was specified, the function
returns the constant _N_o_n_e.  If _N_o_n_e is returned, there is no
owner for the selection.

_X_G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r can generate a _B_a_d_A_t_o_m error.


To request conversion of a selection, use _X_C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n.













                             110033





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XConvertSelection(_d_i_s_p_l_a_y, _s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t, _p_r_o_p_e_r_t_y, _r_e_q_u_e_s_t_o_r, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      Atom _s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t;
      Atom _p_r_o_p_e_r_t_y;
      Window _r_e_q_u_e_s_t_o_r;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_e_l_e_c_t_i_o_n Specifies the selection atom.

_t_a_r_g_e_t    Specifies the target atom.

_p_r_o_p_e_r_t_y  Specifies the property name.  You also can pass
          _N_o_n_e.

_r_e_q_u_e_s_t_o_r Specifies the requestor.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

_X_C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n requests that the specified selection be
converted to the specified target type:

⋅    If the specified selection has an owner, the X server
     sends a _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t event to that owner.

⋅    If no owner for the specified selection exists, the X
     server generates a _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event to the
     requestor with property _N_o_n_e.

The arguments are passed on unchanged in either of the
events.  There are two predefined selection atoms: PRIMARY
and SECONDARY.

_X_C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w errors.


















                             110044





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 55

                PPiixxmmaapp aanndd CCuurrssoorr FFuunnccttiioonnss



Once you have connected to an X server, you can use the Xlib
functions to:

⋅    Create and free pixmaps

⋅    Create, recolor, and free cursors

55..11..  CCrreeaattiinngg aanndd FFrreeeeiinngg PPiixxmmaappss

Pixmaps can only be used on the screen on which they were
created.  Pixmaps are off‐screen resources that are used for
various operations, such as defining cursors as tiling pat­
terns or as the source for certain raster operations.  Most
graphics requests can operate either on a window or on a
pixmap.  A bitmap is a single bit‐plane pixmap.


To create a pixmap of a given size, use _X_C_r_e_a_t_e_P_i_x_m_a_p.
__
││
Pixmap XCreatePixmap(_d_i_s_p_l_a_y, _d, _w_i_d_t_h, _h_e_i_g_h_t, _d_e_p_t_h)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      unsigned int _d_e_p_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies which screen the pixmap is created on.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which define the
          dimensions of the pixmap.

_d_e_p_t_h     Specifies the depth of the pixmap.
││__

The _X_C_r_e_a_t_e_P_i_x_m_a_p function creates a pixmap of the width,
height, and depth you specified and returns a pixmap ID that
identifies it.  It is valid to pass an _I_n_p_u_t_O_n_l_y window to
the drawable argument.  The width and height arguments must
be nonzero, or a _B_a_d_V_a_l_u_e error results.  The depth argument
must be one of the depths supported by the screen of the
specified drawable, or a _B_a_d_V_a_l_u_e error results.




                             110055





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The server uses the specified drawable to determine on which
screen to create the pixmap.  The pixmap can be used only on
this screen and only with other drawables of the same depth
(see _X_C_o_p_y_P_l_a_n_e for an exception to this rule).  The initial
contents of the pixmap are undefined.

_X_C_r_e_a_t_e_P_i_x_m_a_p can generate _B_a_d_A_l_l_o_c, _B_a_d_D_r_a_w_a_b_l_e, and _B_a_d_­
_V_a_l_u_e errors.


To free all storage associated with a specified pixmap, use
_X_F_r_e_e_P_i_x_m_a_p.
__
││
XFreePixmap(_d_i_s_p_l_a_y, _p_i_x_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Pixmap _p_i_x_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_i_x_m_a_p    Specifies the pixmap.
││__

The _X_F_r_e_e_P_i_x_m_a_p function first deletes the association
between the pixmap ID and the pixmap.  Then, the X server
frees the pixmap storage when there are no references to it.
The pixmap should never be referenced again.

_X_F_r_e_e_P_i_x_m_a_p can generate a _B_a_d_P_i_x_m_a_p error.

55..22..  CCrreeaattiinngg,, RReeccoolloorriinngg,, aanndd FFrreeeeiinngg CCuurrssoorrss

Each window can have a different cursor defined for it.
Whenever the pointer is in a visible window, it is set to
the cursor defined for that window.  If no cursor was
defined for that window, the cursor is the one defined for
the parent window.

From X’s perspective, a cursor consists of a cursor source,
mask, colors, and a hotspot.  The mask pixmap determines the
shape of the cursor and must be a depth of one.  The source
pixmap must have a depth of one, and the colors determine
the colors of the source.  The hotspot defines the point on
the cursor that is reported when a pointer event occurs.
There may be limitations imposed by the hardware on cursors
as to size and whether a mask is implemented.
_X_Q_u_e_r_y_B_e_s_t_C_u_r_s_o_r can be used to find out what sizes are pos­
sible.  There is a standard font for creating cursors, but
Xlib provides functions that you can use to create cursors
from an arbitrary font or from bitmaps.


To create a cursor from the standard cursor font, use



                             110066





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_C_r_e_a_t_e_F_o_n_t_C_u_r_s_o_r.
__
││
#include <X11/cursorfont.h>
Cursor XCreateFontCursor(_d_i_s_p_l_a_y, _s_h_a_p_e)
      Display *_d_i_s_p_l_a_y;
      unsigned int _s_h_a_p_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_h_a_p_e     Specifies the shape of the cursor.
││__

X provides a set of standard cursor shapes in a special font
named cursor.  Applications are encouraged to use this
interface for their cursors because the font can be cus­
tomized for the individual display type.  The shape argument
specifies which glyph of the standard fonts to use.

The hotspot comes from the information stored in the cursor
font.  The initial colors of a cursor are a black foreground
and a white background (see _X_R_e_c_o_l_o_r_C_u_r_s_o_r).  For further
information about cursor shapes, see appendix B.

_X_C_r_e_a_t_e_F_o_n_t_C_u_r_s_o_r can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e errors.


To create a cursor from font glyphs, use _X_C_r_e_a_t_e_G_l_y_p_h_C_u_r_s_o_r.




























                             110077





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Cursor XCreateGlyphCursor(_d_i_s_p_l_a_y, _s_o_u_r_c_e___f_o_n_t, _m_a_s_k___f_o_n_t, _s_o_u_r_c_e___c_h_a_r, _m_a_s_k___c_h_a_r,
                           _f_o_r_e_g_r_o_u_n_d___c_o_l_o_r, _b_a_c_k_g_r_o_u_n_d___c_o_l_o_r)
      Display *_d_i_s_p_l_a_y;
      Font _s_o_u_r_c_e___f_o_n_t, _m_a_s_k___f_o_n_t;
      unsigned int _s_o_u_r_c_e___c_h_a_r, _m_a_s_k___c_h_a_r;
      XColor *_f_o_r_e_g_r_o_u_n_d___c_o_l_o_r;
      XColor *_b_a_c_k_g_r_o_u_n_d___c_o_l_o_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_o_u_r_c_e___f_o_n_t
          Specifies the font for the source glyph.

_m_a_s_k___f_o_n_t Specifies the font for the mask glyph or _N_o_n_e.

_s_o_u_r_c_e___c_h_a_r
          Specifies the character glyph for the source.

_m_a_s_k___c_h_a_r Specifies the glyph character for the mask.

_f_o_r_e_g_r_o_u_n_d___c_o_l_o_r
          Specifies the RGB values for the foreground of the
          source.

_b_a_c_k_g_r_o_u_n_d___c_o_l_o_r
          Specifies the RGB values for the background of the
          source.
││__

The _X_C_r_e_a_t_e_G_l_y_p_h_C_u_r_s_o_r function is similar to _X_C_r_e_­
_a_t_e_P_i_x_m_a_p_C_u_r_s_o_r except that the source and mask bitmaps are
obtained from the specified font glyphs.  The source_char
must be a defined glyph in source_font, or a _B_a_d_V_a_l_u_e error
results.  If mask_font is given, mask_char must be a defined
glyph in mask_font, or a _B_a_d_V_a_l_u_e error results.  The
mask_font and character are optional.  The origins of the
source_char and mask_char (if defined) glyphs are positioned
coincidently and define the hotspot.  The source_char and
mask_char need not have the same bounding box metrics, and
there is no restriction on the placement of the hotspot rel­
ative to the bounding boxes.  If no mask_char is given, all
pixels of the source are displayed.  You can free the fonts
immediately by calling _X_F_r_e_e_F_o_n_t if no further explicit ref­
erences to them are to be made.

For 2‐byte matrix fonts, the 16‐bit value should be formed
with the byte1 member in the most significant byte and the
byte2 member in the least significant byte.

_X_C_r_e_a_t_e_G_l_y_p_h_C_u_r_s_o_r can generate _B_a_d_A_l_l_o_c, _B_a_d_F_o_n_t, and _B_a_d_­
_V_a_l_u_e errors.




                             110088





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To create a cursor from two bitmaps, use _X_C_r_e_a_t_e_P_i_x_m_a_p_C_u_r_­
_s_o_r.
__
││
Cursor XCreatePixmapCursor(_d_i_s_p_l_a_y, _s_o_u_r_c_e, _m_a_s_k, _f_o_r_e_g_r_o_u_n_d___c_o_l_o_r, _b_a_c_k_g_r_o_u_n_d___c_o_l_o_r, _x, _y)
      Display *_d_i_s_p_l_a_y;
      Pixmap _s_o_u_r_c_e;
      Pixmap _m_a_s_k;
      XColor *_f_o_r_e_g_r_o_u_n_d___c_o_l_o_r;
      XColor *_b_a_c_k_g_r_o_u_n_d___c_o_l_o_r;
      unsigned int _x, _y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_o_u_r_c_e    Specifies the shape of the source cursor.

_m_a_s_k      Specifies the cursor’s source bits to be displayed
          or _N_o_n_e.

_f_o_r_e_g_r_o_u_n_d___c_o_l_o_r
          Specifies the RGB values for the foreground of the
          source.

_b_a_c_k_g_r_o_u_n_d___c_o_l_o_r
          Specifies the RGB values for the background of the
          source.

_x
_y         Specify the x and y coordinates, which indicate
          the hotspot relative to the source’s origin.
││__

The _X_C_r_e_a_t_e_P_i_x_m_a_p_C_u_r_s_o_r function creates a cursor and
returns the cursor ID associated with it.  The foreground
and background RGB values must be specified using fore­
ground_color and background_color, even if the X server only
has a _S_t_a_t_i_c_G_r_a_y or _G_r_a_y_S_c_a_l_e screen.  The foreground color
is used for the pixels set to 1 in the source, and the back­
ground color is used for the pixels set to 0.  Both source
and mask, if specified, must have depth one (or a _B_a_d_M_a_t_c_h
error results) but can have any root.  The mask argument
defines the shape of the cursor.  The pixels set to 1 in the
mask define which source pixels are displayed, and the pix­
els set to 0 define which pixels are ignored.  If no mask is
given, all pixels of the source are displayed.  The mask, if
present, must be the same size as the pixmap defined by the
source argument, or a _B_a_d_M_a_t_c_h error results.  The hotspot
must be a point within the source, or a _B_a_d_M_a_t_c_h error
results.

The components of the cursor can be transformed arbitrarily
to meet display limitations.  The pixmaps can be freed imme­
diately if no further explicit references to them are to be



                             110099





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


made.  Subsequent drawing in the source or mask pixmap has
an undefined effect on the cursor.  The X server might or
might not make a copy of the pixmap.

_X_C_r_e_a_t_e_P_i_x_m_a_p_C_u_r_s_o_r can generate _B_a_d_A_l_l_o_c and _B_a_d_P_i_x_m_a_p
errors.


To determine useful cursor sizes, use _X_Q_u_e_r_y_B_e_s_t_C_u_r_s_o_r.
__
││
Status XQueryBestCursor(_d_i_s_p_l_a_y, _d, _w_i_d_t_h, _h_e_i_g_h_t, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      unsigned int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable, which indicates the
          screen.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height of the cursor that
          you want the size information for.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the best width and height that is closest
          to the specified width and height.
││__

Some displays allow larger cursors than other displays.  The
_X_Q_u_e_r_y_B_e_s_t_C_u_r_s_o_r function provides a way to find out what
size cursors are actually possible on the display.  It
returns the largest size that can be displayed.  Applica­
tions should be prepared to use smaller cursors on displays
that cannot support large ones.

_X_Q_u_e_r_y_B_e_s_t_C_u_r_s_o_r can generate a _B_a_d_D_r_a_w_a_b_l_e error.


To change the color of a given cursor, use _X_R_e_c_o_l_o_r_C_u_r_s_o_r.













                             111100





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XRecolorCursor(_d_i_s_p_l_a_y, _c_u_r_s_o_r, _f_o_r_e_g_r_o_u_n_d___c_o_l_o_r, _b_a_c_k_g_r_o_u_n_d___c_o_l_o_r)
      Display *_d_i_s_p_l_a_y;
      Cursor _c_u_r_s_o_r;
      XColor *_f_o_r_e_g_r_o_u_n_d___c_o_l_o_r, *_b_a_c_k_g_r_o_u_n_d___c_o_l_o_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_u_r_s_o_r    Specifies the cursor.

_f_o_r_e_g_r_o_u_n_d___c_o_l_o_r
          Specifies the RGB values for the foreground of the
          source.

_b_a_c_k_g_r_o_u_n_d___c_o_l_o_r
          Specifies the RGB values for the background of the
          source.
││__

The _X_R_e_c_o_l_o_r_C_u_r_s_o_r function changes the color of the speci­
fied cursor, and if the cursor is being displayed on a
screen, the change is visible immediately.  The pixel mem­
bers of the _X_C_o_l_o_r structures are ignored; only the RGB val­
ues are used.

_X_R_e_c_o_l_o_r_C_u_r_s_o_r can generate a _B_a_d_C_u_r_s_o_r error.


To free (destroy) a given cursor, use _X_F_r_e_e_C_u_r_s_o_r.
__
││
XFreeCursor(_d_i_s_p_l_a_y, _c_u_r_s_o_r)
      Display *_d_i_s_p_l_a_y;
      Cursor _c_u_r_s_o_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_u_r_s_o_r    Specifies the cursor.
││__

The _X_F_r_e_e_C_u_r_s_o_r function deletes the association between the
cursor resource ID and the specified cursor.  The cursor
storage is freed when no other resource references it.  The
specified cursor ID should not be referred to again.

_X_F_r_e_e_C_u_r_s_o_r can generate a _B_a_d_C_u_r_s_o_r error.









                             111111





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 66

                 CCoolloorr MMaannaaggeemmeenntt FFuunnccttiioonnss



Each X window always has an associated colormap that pro­
vides a level of indirection between pixel values and colors
displayed on the screen.  Xlib provides functions that you
can use to manipulate a colormap.  The X protocol defines
colors using values in the RGB color space.  The RGB color
space is device dependent; rendering an RGB value on differ­
ing output devices typically results in different colors.
Xlib also provides a means for clients to specify color
using device‐independent color spaces for consistent results
across devices.  Xlib supports device‐independent color
spaces derivable from the CIE XYZ color space.  This
includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces
as well as the TekHVC color space.

This chapter discusses how to:

⋅    Create, copy, and destroy a colormap

⋅    Specify colors by name or value

⋅    Allocate, modify, and free color cells

⋅    Read entries in a colormap

⋅    Convert between color spaces

⋅    Control aspects of color conversion

⋅    Query the color gamut of a screen

⋅    Add new color spaces

All functions, types, and symbols in this chapter with the
prefix ‘‘Xcms’’ are defined in <_X_1_1_/_X_c_m_s_._h>.  The remaining
functions and types are defined in <_X_1_1_/_X_l_i_b_._h>.

Functions in this chapter manipulate the representation of
color on the screen.  For each possible value that a pixel
can take in a window, there is a color cell in the colormap.
For example, if a window is 4 bits deep, pixel values 0
through 15 are defined.  A colormap is a collection of color
cells.  A color cell consists of a triple of red, green, and
blue (RGB) values.  The hardware imposes limits on the num­
ber of significant bits in these values.  As each pixel is
read out of display memory, the pixel is looked up in a col­
ormap.  The RGB value of the cell determines what color is



                             111122





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


displayed on the screen.  On a grayscale display with a
black‐and‐white monitor, the values are combined to deter­
mine the brightness on the screen.

Typically, an application allocates color cells or sets of
color cells to obtain the desired colors.  The client can
allocate read‐only cells.  In which case, the pixel values
for these colors can be shared among multiple applications,
and the RGB value of the cell cannot be changed.  If the
client allocates read/write cells, they are exclusively
owned by the client, and the color associated with the pixel
value can be changed at will.  Cells must be allocated (and,
if read/write, initialized with an RGB value) by a client to
obtain desired colors.  The use of pixel value for an unal­
located cell results in an undefined color.

Because colormaps are associated with windows, X supports
displays with multiple colormaps and, indeed, different
types of colormaps.  If there are insufficient colormap
resources in the display, some windows will display in their
true colors, and others will display with incorrect colors.
A window manager usually controls which windows are dis­
played in their true colors if more than one colormap is
required for the color resources the applications are using.
At any time, there is a set of installed colormaps for a
screen.  Windows using one of the installed colormaps dis­
play with true colors, and windows using other colormaps
generally display with incorrect colors.  You can control
the set of installed colormaps by using _X_I_n_s_t_a_l_l_C_o_l_o_r_m_a_p and
_X_U_n_i_n_s_t_a_l_l_C_o_l_o_r_m_a_p.

Colormaps are local to a particular screen.  Screens always
have a default colormap, and programs typically allocate
cells out of this colormap.  Generally, you should not write
applications that monopolize color resources.  Although some
hardware supports multiple colormaps installed at one time,
many of the hardware displays built today support only a
single installed colormap, so the primitives are written to
encourage sharing of colormap entries between applications.

The _D_e_f_a_u_l_t_C_o_l_o_r_m_a_p macro returns the default colormap.  The
_D_e_f_a_u_l_t_V_i_s_u_a_l macro returns the default visual type for the
specified screen.  Possible visual types are _S_t_a_t_i_c_G_r_a_y,
_G_r_a_y_S_c_a_l_e, _S_t_a_t_i_c_C_o_l_o_r, _P_s_e_u_d_o_C_o_l_o_r, _T_r_u_e_C_o_l_o_r, or _D_i_r_e_c_t_­
_C_o_l_o_r (see section 3.1).

66..11..  CCoolloorr SSttrruuccttuurreess

Functions that operate only on RGB color space values use an
_X_C_o_l_o_r structure, which contains:







                             111133





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     unsigned long pixel;/* pixel value */
     unsigned short red, green, blue;/* rgb values */
     char flags;         /* DoRed, DoGreen, DoBlue */
     char pad;
} XColor;

││__

The red, green, and blue values are always in the range 0 to
65535 inclusive, independent of the number of bits actually
used in the display hardware.  The server scales these val­
ues down to the range used by the hardware.  Black is repre­
sented by (0,0,0), and white is represented by
(65535,65535,65535).  In some functions, the flags member
controls which of the red, green, and blue members is used
and can be the inclusive OR of zero or more of _D_o_R_e_d,
_D_o_G_r_e_e_n, and _D_o_B_l_u_e.


Functions that operate on all color space values use an _X_c_m_­
_s_C_o_l_o_r structure.  This structure contains a union of sub­
structures, each supporting color specification encoding for
a particular color space.  Like the _X_C_o_l_o_r structure, the
_X_c_m_s_C_o_l_o_r structure contains pixel and color specification
information (the spec member in the _X_c_m_s_C_o_l_o_r structure).
__
││

typedef unsigned long XcmsColorFormat;/* Color Specification Format */

typedef struct {
     union {
          XcmsRGB RGB;
          XcmsRGBi RGBi;
          XcmsCIEXYZ CIEXYZ;
          XcmsCIEuvY CIEuvY;
          XcmsCIExyY CIExyY;
          XcmsCIELab CIELab;
          XcmsCIELuv CIELuv;
          XcmsTekHVC TekHVC;
          XcmsPad Pad;
     } spec;
     unsigned long pixel;
     XcmsColorFormat format;
} XcmsColor;             /* Xcms Color Structure */

││__

Because the color specification can be encoded for the vari­
ous color spaces, encoding for the spec member is identified
by the format member, which is of type _X_c_m_s_C_o_l_o_r_F_o_r_m_a_t.  The
following macros define standard formats.



                             111144





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
#define   _X_c_m_s_U_n_d_e_f_i_n_e_d_­     0x00000000
          _F_o_r_m_a_t
#define   _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t   0x00000001       /* CIE XYZ */
#define   _X_c_m_s_C_I_E_u_v_Y_F_o_r_m_a_t   0x00000002       /* CIE u’v’Y */
#define   _X_c_m_s_C_I_E_x_y_Y_F_o_r_m_a_t   0x00000003       /* CIE xyY */
#define   _X_c_m_s_C_I_E_L_a_b_F_o_r_m_a_t   0x00000004       /* CIE L*a*b*
                                              */
#define   _X_c_m_s_C_I_E_L_u_v_F_o_r_m_a_t   0x00000005       /* CIE L*u*v*
                                              */
#define   _X_c_m_s_T_e_k_H_V_C_F_o_r_m_a_t   0x00000006       /* TekHVC */
#define   _X_c_m_s_R_G_B_F_o_r_m_a_t      0x80000000       /* RGB Device
                                              */
#define   _X_c_m_s_R_G_B_i_F_o_r_m_a_t     0x80000001       /* RGB Inten­
                                              sity */

││__

Formats for device‐independent color spaces are distinguish­
able from those for device‐dependent spaces by the 32nd bit.
If this bit is set, it indicates that the color specifica­
tion is in a device‐dependent form; otherwise, it is in a
device‐independent form.  If the 31st bit is set, this indi­
cates that the color space has been added to Xlib at run
time (see section 6.12.4).  The format value for a color
space added at run time may be different each time the pro­
gram is executed.  If references to such a color space must
be made outside the client (for example, storing a color
specification in a file), then reference should be made by
color space string prefix (see _X_c_m_s_F_o_r_m_a_t_O_f_P_r_e_f_i_x and _X_c_m_­
_s_P_r_e_f_i_x_O_f_F_o_r_m_a_t).

Data types that describe the color specification encoding
for the various color spaces are defined as follows:























                             111155





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││

typedef double XcmsFloat;

typedef struct {
     unsigned short red; /* 0x0000 to 0xffff */
     unsigned short green;/* 0x0000 to 0xffff */
     unsigned short blue;/* 0x0000 to 0xffff */
} XcmsRGB;               /* RGB Device */



typedef struct {
     XcmsFloat red;      /* 0.0 to 1.0 */
     XcmsFloat green;    /* 0.0 to 1.0 */
     XcmsFloat blue;     /* 0.0 to 1.0 */
} XcmsRGBi;              /* RGB Intensity */



typedef struct {
     XcmsFloat X;
     XcmsFloat Y;        /* 0.0 to 1.0 */
     XcmsFloat Z;
} XcmsCIEXYZ;            /* CIE XYZ */



typedef struct {
     XcmsFloat u_prime;  /* 0.0 to ~0.6 */
     XcmsFloat v_prime;  /* 0.0 to ~0.6 */
     XcmsFloat Y;        /* 0.0 to 1.0 */
} XcmsCIEuvY;            /* CIE u’v’Y */



typedef struct {
     XcmsFloat x;        /* 0.0 to ~.75 */
     XcmsFloat y;        /* 0.0 to ~.85 */
     XcmsFloat Y;        /* 0.0 to 1.0 */
} XcmsCIExyY;            /* CIE xyY */



typedef struct {
     XcmsFloat L_star;   /* 0.0 to 100.0 */
     XcmsFloat a_star;
     XcmsFloat b_star;
} XcmsCIELab;            /* CIE L*a*b* */



typedef struct {
     XcmsFloat L_star;   /* 0.0 to 100.0 */



                             111166





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     XcmsFloat u_star;
     XcmsFloat v_star;
} XcmsCIELuv;            /* CIE L*u*v* */



typedef struct {
     XcmsFloat H;        /* 0.0 to 360.0 */
     XcmsFloat V;        /* 0.0 to 100.0 */
     XcmsFloat C;        /* 0.0 to 100.0 */
} XcmsTekHVC;            /* TekHVC */



typedef struct {
     XcmsFloat pad0;
     XcmsFloat pad1;
     XcmsFloat pad2;
     XcmsFloat pad3;
} XcmsPad;               /* four doubles */

││__

The device‐dependent formats provided allow color specifica­
tion in:

⋅    RGB Intensity (_X_c_m_s_R_G_B_i)

     Red, green, and blue linear intensity values, floating‐
     point values from 0.0 to 1.0, where 1.0 indicates full
     intensity, 0.5 half intensity, and so on.

⋅    RGB Device (_X_c_m_s_R_G_B)

     Red, green, and blue values appropriate for the speci­
     fied output device.  _X_c_m_s_R_G_B values are of type
     unsigned short, scaled from 0 to 65535 inclusive, and
     are interchangeable with the red, green, and blue val­
     ues in an _X_C_o_l_o_r structure.

It is important to note that RGB Intensity values are not
gamma corrected values.  In contrast, RGB Device values gen­
erated as a result of converting color specifications are
always gamma corrected, and RGB Device values acquired as a
result of querying a colormap or passed in by the client are
assumed by Xlib to be gamma corrected.  The term _R_G_B _v_a_l_u_e
in this manual always refers to an RGB Device value.

66..22..  CCoolloorr SSttrriinnggss

Xlib provides a mechanism for using string names for colors.
A color string may either contain an abstract color name or
a numerical color specification.  Color strings are case‐
insensitive.



                             111177





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Color strings are used in the following functions:

⋅    _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r

⋅    _X_c_m_s_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r

⋅    _X_L_o_o_k_u_p_C_o_l_o_r

⋅    _X_c_m_s_L_o_o_k_u_p_C_o_l_o_r

⋅    _X_P_a_r_s_e_C_o_l_o_r

⋅    _X_S_t_o_r_e_N_a_m_e_d_C_o_l_o_r

Xlib supports the use of abstract color names, for example,
red or blue.  A value for this abstract name is obtained by
searching one or more color name databases.  Xlib first
searches zero or more client‐side databases; the number,
location, and content of these databases is implementation‐
dependent and might depend on the current locale.  If the
name is not found, Xlib then looks for the color in the X
server’s database.  If the color name is not in the Host
Portable Character Encoding, the result is implementation‐
dependent.

A numerical color specification consists of a color space
name and a set of values in the following syntax:

__
││
_<_c_o_l_o_r___s_p_a_c_e___n_a_m_e_>:_<_v_a_l_u_e_>_/_._._._/_<_v_a_l_u_e_>

││__

The following are examples of valid color strings.


"CIEXYZ:0.3227/0.28133/0.2493"
"RGBi:1.0/0.0/0.0"
"rgb:00/ff/00"
"CIELuv:50.0/0.0/0.0"

The syntax and semantics of numerical specifications are
given for each standard color space in the following sec­
tions.

66..22..11..  RRGGBB DDeevviiccee SSttrriinngg SSppeecciiffiiccaattiioonn

An RGB Device specification is identified by the prefix
‘‘rgb:’’ and conforms to the following syntax:


rgb:_<_r_e_d_>_/_<_g_r_e_e_n_>_/_<_b_l_u_e_>




                             111188





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


    _<_r_e_d_>, _<_g_r_e_e_n_>, _<_b_l_u_e_> := _h | _h_h | _h_h_h | _h_h_h_h
    _h := single hexadecimal digits (case insignificant)


Note that _h indicates the value scaled in 4 bits, _h_h the
value scaled in 8 bits, _h_h_h the value scaled in 12 bits, and
_h_h_h_h the value scaled in 16 bits, respectively.

Typical examples are the strings ‘‘rgb:ea/75/52’’ and
‘‘rgb:ccc/320/320’’, but mixed numbers of hexadecimal digit
strings (‘‘rgb:ff/a5/0’’ and ‘‘rgb:ccc/32/0’’) are also
allowed.

For backward compatibility, an older syntax for RGB Device
is supported, but its continued use is not encouraged.  The
syntax is an initial sharp sign character followed by a
numeric specification, in one of the following formats:


#RGB                (4 bits each)
#RRGGBB             (8 bits each)
#RRRGGGBBB          (12 bits each)
#RRRRGGGGBBBB       (16 bits each)


The R, G, and B represent single hexadecimal digits.  When
fewer than 16 bits each are specified, they represent the
most significant bits of the value (unlike the ‘‘rgb:’’ syn­
tax, in which values are scaled).  For example, the string
‘‘#3a7’’ is the same as ‘‘#3000a0007000’’.

66..22..22..  RRGGBB IInntteennssiittyy SSttrriinngg SSppeecciiffiiccaattiioonn

An RGB intensity specification is identified by the prefix
‘‘rgbi:’’ and conforms to the following syntax:


rgbi:_<_r_e_d_>_/_<_g_r_e_e_n_>_/_<_b_l_u_e_>


Note that red, green, and blue are floating‐point values
between 0.0 and 1.0, inclusive.  The input format for these
values is an optional sign, a string of numbers possibly
containing a decimal point, and an optional exponent field
containing an E or e followed by a possibly signed integer
string.

66..22..33..  DDeevviiccee‐‐IInnddeeppeennddeenntt SSttrriinngg SSppeecciiffiiccaattiioonnss

The standard device‐independent string specifications have
the following syntax:


CIEXYZ:_<_X_>_/_<_Y_>_/_<_Z_>



                             111199





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


CIEuvY:_<_u_>_/_<_v_>_/_<_Y_>
CIExyY:_<_x_>_/_<_y_>_/_<_Y_>
CIELab:_<_L_>_/_<_a_>_/_<_b_>
CIELuv:_<_L_>_/_<_u_>_/_<_v_>
TekHVC:_<_H_>_/_<_V_>_/_<_C_>


All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
floating‐point values.  The syntax for these values is an
optional plus or minus sign, a string of digits possibly
containing a decimal point, and an optional exponent field
consisting of an ‘‘E’’ or ‘‘e’’ followed by an optional plus
or minus followed by a string of digits.

66..33..  CCoolloorr CCoonnvveerrssiioonn CCoonntteexxttss aanndd GGaammuutt MMaappppiinngg

When Xlib converts device‐independent color specifications
into device‐dependent specifications and vice versa, it uses
knowledge about the color limitations of the screen hard­
ware.  This information, typically called the device pro­
file, is available in a Color Conversion Context (CCC).

Because a specified color may be outside the color gamut of
the target screen and the white point associated with the
color specification may differ from the white point inherent
to the screen, Xlib applies gamut mapping when it encounters
certain conditions:

⋅    Gamut compression occurs when conversion of device‐
     independent color specifications to device‐dependent
     color specifications results in a color out of the tar­
     get screen’s gamut.

⋅    White adjustment occurs when the inherent white point
     of the screen differs from the white point assumed by
     the client.

Gamut handling methods are stored as callbacks in the CCC,
which in turn are used by the color space conversion rou­
tines.  Client data is also stored in the CCC for each call­
back.  The CCC also contains the white point the client
assumes to be associated with color specifications (that is,
the Client White Point).  The client can specify the gamut
handling callbacks and client data as well as the Client
White Point.  Xlib does not preclude the X client from per­
forming other forms of gamut handling (for example, gamut
expansion); however, Xlib does not provide direct support
for gamut handling other than white adjustment and gamut
compression.

Associated with each colormap is an initial CCC transpar­
ently generated by Xlib.  Therefore, when you specify a col­
ormap as an argument to an Xlib function, you are indirectly
specifying a CCC.  There is a default CCC associated with



                             112200





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


each screen.  Newly created CCCs inherit attributes from the
default CCC, so the default CCC attributes can be modified
to affect new CCCs.

Xcms functions in which gamut mapping can occur return _S_t_a_­
_t_u_s and have specific status values defined for them, as
follows:

⋅    _X_c_m_s_F_a_i_l_u_r_e indicates that the function failed.

⋅    _X_c_m_s_S_u_c_c_e_s_s indicates that the function succeeded.  In
     addition, if the function performed any color conver­
     sion, the colors did not need to be compressed.

⋅    _X_c_m_s_S_u_c_c_e_s_s_W_i_t_h_C_o_m_p_r_e_s_s_i_o_n indicates the function per­
     formed color conversion and at least one of the colors
     needed to be compressed.  The gamut compression method
     is determined by the gamut compression procedure in the
     CCC that is specified directly as a function argument
     or in the CCC indirectly specified by means of the col­
     ormap argument.

66..44..  CCrreeaattiinngg,, CCooppyyiinngg,, aanndd DDeessttrrooyyiinngg CCoolloorrmmaappss

To create a colormap for a screen, use _X_C_r_e_a_t_e_C_o_l_o_r_m_a_p.
__
││
Colormap XCreateColormap(_d_i_s_p_l_a_y, _w, _v_i_s_u_a_l, _a_l_l_o_c)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Visual *_v_i_s_u_a_l;
      int _a_l_l_o_c;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window on whose screen you want to
          create a colormap.

_v_i_s_u_a_l    Specifies a visual type supported on the screen.
          If the visual type is not one supported by the
          screen, a _B_a_d_M_a_t_c_h error results.

_a_l_l_o_c     Specifies the colormap entries to be allocated.
          You can pass _A_l_l_o_c_N_o_n_e or _A_l_l_o_c_A_l_l.
││__

The _X_C_r_e_a_t_e_C_o_l_o_r_m_a_p function creates a colormap of the spec­
ified visual type for the screen on which the specified win­
dow resides and returns the colormap ID associated with it.
Note that the specified window is only used to determine the
screen.





                             112211





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The initial values of the colormap entries are undefined for
the visual classes _G_r_a_y_S_c_a_l_e, _P_s_e_u_d_o_C_o_l_o_r, and _D_i_r_e_c_t_C_o_l_o_r.
For _S_t_a_t_i_c_G_r_a_y, _S_t_a_t_i_c_C_o_l_o_r, and _T_r_u_e_C_o_l_o_r, the entries have
defined values, but those values are specific to the visual
and are not defined by X.  For _S_t_a_t_i_c_G_r_a_y, _S_t_a_t_i_c_C_o_l_o_r, and
_T_r_u_e_C_o_l_o_r, alloc must be _A_l_l_o_c_N_o_n_e, or a _B_a_d_M_a_t_c_h error
results.  For the other visual classes, if alloc is _A_l_l_o_c_­
_N_o_n_e, the colormap initially has no allocated entries, and
clients can allocate them.  For information about the visual
types, see section 3.1.

If alloc is _A_l_l_o_c_A_l_l, the entire colormap is allocated
writable.  The initial values of all allocated entries are
undefined.  For _G_r_a_y_S_c_a_l_e and _P_s_e_u_d_o_C_o_l_o_r, the effect is as
if an _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s call returned all pixel values from
zero to N − 1, where N is the colormap entries value in the
specified visual.  For _D_i_r_e_c_t_C_o_l_o_r, the effect is as if an
_X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s call returned a pixel value of zero and
red_mask, green_mask, and blue_mask values containing the
same bits as the corresponding masks in the specified
visual.  However, in all cases, none of these entries can be
freed by using _X_F_r_e_e_C_o_l_o_r_s.

_X_C_r_e_a_t_e_C_o_l_o_r_m_a_p can generate _B_a_d_A_l_l_o_c, _B_a_d_M_a_t_c_h, _B_a_d_V_a_l_u_e,
and _B_a_d_W_i_n_d_o_w errors.


To create a new colormap when the allocation out of a previ­
ously shared colormap has failed because of resource exhaus­
tion, use _X_C_o_p_y_C_o_l_o_r_m_a_p_A_n_d_F_r_e_e.
__
││
Colormap XCopyColormapAndFree(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.
││__

The _X_C_o_p_y_C_o_l_o_r_m_a_p_A_n_d_F_r_e_e function creates a colormap of the
same visual type and for the same screen as the specified
colormap and returns the new colormap ID.  It also moves all
of the client’s existing allocation from the specified col­
ormap to the new colormap with their color values intact and
their read‐only or writable characteristics intact and frees
those entries in the specified colormap.  Color values in
other entries in the new colormap are undefined.  If the
specified colormap was created by the client with alloc set
to _A_l_l_o_c_A_l_l, the new colormap is also created with _A_l_l_o_c_A_l_l,
all color values for all entries are copied from the speci­
fied colormap, and then all entries in the specified



                             112222





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


colormap are freed.  If the specified colormap was not cre­
ated by the client with _A_l_l_o_c_A_l_l, the allocations to be
moved are all those pixels and planes that have been allo­
cated by the client using _X_A_l_l_o_c_C_o_l_o_r, _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r,
_X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s, or _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s and that have not
been freed since they were allocated.

_X_C_o_p_y_C_o_l_o_r_m_a_p_A_n_d_F_r_e_e can generate _B_a_d_A_l_l_o_c and _B_a_d_C_o_l_o_r
errors.


To destroy a colormap, use _X_F_r_e_e_C_o_l_o_r_m_a_p.
__
││
XFreeColormap(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap that you want to destroy.
││__

The _X_F_r_e_e_C_o_l_o_r_m_a_p function deletes the association between
the colormap resource ID and the colormap and frees the col­
ormap storage.  However, this function has no effect on the
default colormap for a screen.  If the specified colormap is
an installed map for a screen, it is uninstalled (see _X_U_n_i_n_­
_s_t_a_l_l_C_o_l_o_r_m_a_p).  If the specified colormap is defined as the
colormap for a window (by _X_C_r_e_a_t_e_W_i_n_d_o_w, _X_S_e_t_W_i_n_d_o_w_C_o_l_o_r_m_a_p,
or _X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s), _X_F_r_e_e_C_o_l_o_r_m_a_p changes the col­
ormap associated with the window to _N_o_n_e and generates a
_C_o_l_o_r_m_a_p_N_o_t_i_f_y event.  X does not define the colors dis­
played for a window with a colormap of _N_o_n_e.

_X_F_r_e_e_C_o_l_o_r_m_a_p can generate a _B_a_d_C_o_l_o_r error.

66..55..  MMaappppiinngg CCoolloorr NNaammeess ttoo VVaalluueess


To map a color name to an RGB value, use _X_L_o_o_k_u_p_C_o_l_o_r.















                             112233





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XLookupColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r___n_a_m_e, _e_x_a_c_t___d_e_f___r_e_t_u_r_n, _s_c_r_e_e_n___d_e_f___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      char *_c_o_l_o_r___n_a_m_e;
      XColor *_e_x_a_c_t___d_e_f___r_e_t_u_r_n, *_s_c_r_e_e_n___d_e_f___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r___n_a_m_e
          Specifies the color name string (for example, red)
          whose color definition structure you want
          returned.

_e_x_a_c_t___d_e_f___r_e_t_u_r_n
          Returns the exact RGB values.

_s_c_r_e_e_n___d_e_f___r_e_t_u_r_n
          Returns the closest RGB values provided by the
          hardware.
││__

The _X_L_o_o_k_u_p_C_o_l_o_r function looks up the string name of a
color with respect to the screen associated with the speci­
fied colormap.  It returns both the exact color values and
the closest values provided by the screen with respect to
the visual type of the specified colormap.  If the color
name is not in the Host Portable Character Encoding, the
result is implementation‐dependent.  Use of uppercase or
lowercase does not matter.  _X_L_o_o_k_u_p_C_o_l_o_r returns nonzero if
the name is resolved; otherwise, it returns zero.

_X_L_o_o_k_u_p_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.


To map a color name to the exact RGB value, use _X_P_a_r_s_e_C_o_l_o_r.


















                             112244





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XParseColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _s_p_e_c, _e_x_a_c_t___d_e_f___r_e_t_u_r_n)
        Display *_d_i_s_p_l_a_y;
        Colormap _c_o_l_o_r_m_a_p;
        char *_s_p_e_c;
        XColor *_e_x_a_c_t___d_e_f___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_s_p_e_c      Specifies the color name string; case is ignored.

_e_x_a_c_t___d_e_f___r_e_t_u_r_n
          Returns the exact color value for later use and
          sets the _D_o_R_e_d, _D_o_G_r_e_e_n, and _D_o_B_l_u_e flags.
││__

The _X_P_a_r_s_e_C_o_l_o_r function looks up the string name of a color
with respect to the screen associated with the specified
colormap.  It returns the exact color value.  If the color
name is not in the Host Portable Character Encoding, the
result is implementation‐dependent.  Use of uppercase or
lowercase does not matter.  _X_P_a_r_s_e_C_o_l_o_r returns nonzero if
the name is resolved; otherwise, it returns zero.

_X_P_a_r_s_e_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.


To map a color name to a value in an arbitrary color space,
use _X_c_m_s_L_o_o_k_u_p_C_o_l_o_r.

























                             112255





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsLookupColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r___s_t_r_i_n_g, _c_o_l_o_r___e_x_a_c_t___r_e_t_u_r_n, _c_o_l_o_r___s_c_r_e_e_n___r_e_t_u_r_n,
                               _r_e_s_u_l_t___f_o_r_m_a_t)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      char *_c_o_l_o_r___s_t_r_i_n_g;
      XcmsColor *_c_o_l_o_r___e_x_a_c_t___r_e_t_u_r_n, *_c_o_l_o_r___s_c_r_e_e_n___r_e_t_u_r_n;
      XcmsColorFormat _r_e_s_u_l_t___f_o_r_m_a_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r___s_t_r_i_n_g
          Specifies the color string.

_c_o_l_o_r___e_x_a_c_t___r_e_t_u_r_n
          Returns the color specification parsed from the
          color string or parsed from the corresponding
          string found in a color‐name database.

_c_o_l_o_r___s_c_r_e_e_n___r_e_t_u_r_n
          Returns the color that can be reproduced on the
          screen.

_r_e_s_u_l_t___f_o_r_m_a_t
          Specifies the color format for the returned color
          specifications (color_screen_return and
          color_exact_return arguments).  If the format is
          _X_c_m_s_U_n_d_e_f_i_n_e_d_F_o_r_m_a_t and the color string contains
          a numerical color specification, the specification
          is returned in the format used in that numerical
          color specification.  If the format is _X_c_m_s_U_n_d_e_­
          _f_i_n_e_d_F_o_r_m_a_t and the color string contains a color
          name, the specification is returned in the format
          used to store the color in the database.
││__

The _X_c_m_s_L_o_o_k_u_p_C_o_l_o_r function looks up the string name of a
color with respect to the screen associated with the speci­
fied colormap.  It returns both the exact color values and
the closest values provided by the screen with respect to
the visual type of the specified colormap.  The values are
returned in the format specified by result_format.  If the
color name is not in the Host Portable Character Encoding,
the result is implementation‐dependent.  Use of uppercase or
lowercase does not matter.  _X_c_m_s_L_o_o_k_u_p_C_o_l_o_r returns _X_c_m_s_S_u_c_­
_c_e_s_s or _X_c_m_s_S_u_c_c_e_s_s_W_i_t_h_C_o_m_p_r_e_s_s_i_o_n if the name is resolved;
otherwise, it returns _X_c_m_s_F_a_i_l_u_r_e.  If _X_c_m_s_S_u_c_c_e_s_s_W_i_t_h_C_o_m_­
_p_r_e_s_s_i_o_n is returned, the color specification returned in
color_screen_return is the result of gamut compression.





                             112266





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


66..66..  AAllllooccaattiinngg aanndd FFrreeeeiinngg CCoolloorr CCeellllss

There are two ways of allocating color cells: explicitly as
read‐only entries, one pixel value at a time, or read/write,
where you can allocate a number of color cells and planes
simultaneously.  A read‐only cell has its RGB value set by
the server.  Read/write cells do not have defined colors
initially; functions described in the next section must be
used to store values into them.  Although it is possible for
any client to store values into a read/write cell allocated
by another client, read/write cells normally should be con­
sidered private to the client that allocated them.

Read‐only colormap cells are shared among clients.  The
server counts each allocation and freeing of the cell by
clients.  When the last client frees a shared cell, the cell
is finally deallocated.  If a single client allocates the
same read‐only cell multiple times, the server counts each
such allocation, not just the first one.


To allocate a read‐only color cell with an RGB value, use
_X_A_l_l_o_c_C_o_l_o_r.
__
││
Status XAllocColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _s_c_r_e_e_n___i_n___o_u_t)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XColor *_s_c_r_e_e_n___i_n___o_u_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_s_c_r_e_e_n___i_n___o_u_t
          Specifies and returns the values actually used in
          the colormap.
││__

The _X_A_l_l_o_c_C_o_l_o_r function allocates a read‐only colormap
entry corresponding to the closest RGB value supported by
the hardware.  _X_A_l_l_o_c_C_o_l_o_r returns the pixel value of the
color closest to the specified RGB elements supported by the
hardware and returns the RGB value actually used.  The cor­
responding colormap cell is read‐only.  In addition, _X_A_l_l_o_c_­
_C_o_l_o_r returns nonzero if it succeeded or zero if it failed.
Multiple clients that request the same effective RGB value
can be assigned the same read‐only entry, thus allowing
entries to be shared.  When the last client deallocates a
shared cell, it is deallocated.  _X_A_l_l_o_c_C_o_l_o_r does not use or
affect the flags in the _X_C_o_l_o_r structure.





                             112277





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_A_l_l_o_c_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.


To allocate a read‐only color cell with a color in arbitrary
format, use _X_c_m_s_A_l_l_o_c_C_o_l_o_r.
__
││
Status XcmsAllocColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r___i_n___o_u_t, _r_e_s_u_l_t___f_o_r_m_a_t)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XcmsColor *_c_o_l_o_r___i_n___o_u_t;
      XcmsColorFormat _r_e_s_u_l_t___f_o_r_m_a_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r___i_n___o_u_t
          Specifies the color to allocate and returns the
          pixel and color that is actually used in the col­
          ormap.

_r_e_s_u_l_t___f_o_r_m_a_t
          Specifies the color format for the returned color
          specification.
││__

The _X_c_m_s_A_l_l_o_c_C_o_l_o_r function is similar to _X_A_l_l_o_c_C_o_l_o_r except
the color can be specified in any format.  The _X_c_m_s_A_l_l_o_c_­
_C_o_l_o_r function ultimately calls _X_A_l_l_o_c_C_o_l_o_r to allocate a
read‐only color cell (colormap entry) with the specified
color.  _X_c_m_s_A_l_l_o_c_C_o_l_o_r first converts the color specified to
an RGB value and then passes this to _X_A_l_l_o_c_C_o_l_o_r.  _X_c_m_s_A_l_­
_l_o_c_C_o_l_o_r returns the pixel value of the color cell and the
color specification actually allocated.  This returned color
specification is the result of converting the RGB value
returned by _X_A_l_l_o_c_C_o_l_o_r into the format specified with the
result_format argument.  If there is no interest in a
returned color specification, unnecessary computation can be
bypassed if result_format is set to _X_c_m_s_R_G_B_F_o_r_m_a_t.  The cor­
responding colormap cell is read‐only.  If this routine
returns _X_c_m_s_F_a_i_l_u_r_e, the color_in_out color specification is
left unchanged.

_X_c_m_s_A_l_l_o_c_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.


To allocate a read‐only color cell using a color name and
return the closest color supported by the hardware in RGB
format, use _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r.






                             112288





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XAllocNamedColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r___n_a_m_e, _s_c_r_e_e_n___d_e_f___r_e_t_u_r_n, _e_x_a_c_t___d_e_f___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      char *_c_o_l_o_r___n_a_m_e;
      XColor *_s_c_r_e_e_n___d_e_f___r_e_t_u_r_n, *_e_x_a_c_t___d_e_f___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r___n_a_m_e
          Specifies the color name string (for example, red)
          whose color definition structure you want
          returned.

_s_c_r_e_e_n___d_e_f___r_e_t_u_r_n
          Returns the closest RGB values provided by the
          hardware.

_e_x_a_c_t___d_e_f___r_e_t_u_r_n
          Returns the exact RGB values.
││__

The _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r function looks up the named color with
respect to the screen that is associated with the specified
colormap.  It returns both the exact database definition and
the closest color supported by the screen.  The allocated
color cell is read‐only.  The pixel value is returned in
screen_def_return.  If the color name is not in the Host
Portable Character Encoding, the result is implementation‐
dependent.  Use of uppercase or lowercase does not matter.
If screen_def_return and exact_def_return point to the same
structure, the pixel field will be set correctly, but the
color values are undefined.  _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r returns
nonzero if a cell is allocated; otherwise, it returns zero.

_X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.


To allocate a read‐only color cell using a color name and
return the closest color supported by the hardware in an
arbitrary format, use _X_c_m_s_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r.













                             112299





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsAllocNamedColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r___s_t_r_i_n_g, _c_o_l_o_r___s_c_r_e_e_n___r_e_t_u_r_n, _c_o_l_o_r___e_x_a_c_t___r_e_t_u_r_n,
                            _r_e_s_u_l_t___f_o_r_m_a_t)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      char *_c_o_l_o_r___s_t_r_i_n_g;
      XcmsColor *_c_o_l_o_r___s_c_r_e_e_n___r_e_t_u_r_n;
      XcmsColor *_c_o_l_o_r___e_x_a_c_t___r_e_t_u_r_n;
      XcmsColorFormat _r_e_s_u_l_t___f_o_r_m_a_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r___s_t_r_i_n_g
          Specifies the color string whose color definition
          structure is to be returned.

_c_o_l_o_r___s_c_r_e_e_n___r_e_t_u_r_n
          Returns the pixel value of the color cell and
          color specification that actually is stored for
          that cell.

_c_o_l_o_r___e_x_a_c_t___r_e_t_u_r_n
          Returns the color specification parsed from the
          color string or parsed from the corresponding
          string found in a color‐name database.

_r_e_s_u_l_t___f_o_r_m_a_t
          Specifies the color format for the returned color
          specifications (color_screen_return and
          color_exact_return arguments).  If the format is
          _X_c_m_s_U_n_d_e_f_i_n_e_d_F_o_r_m_a_t and the color string contains
          a numerical color specification, the specification
          is returned in the format used in that numerical
          color specification.  If the format is _X_c_m_s_U_n_d_e_­
          _f_i_n_e_d_F_o_r_m_a_t and the color string contains a color
          name, the specification is returned in the format
          used to store the color in the database.
││__

The _X_c_m_s_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r function is similar to _X_A_l_l_o_c_N_a_m_e_d_­
_C_o_l_o_r except that the color returned can be in any format
specified.  This function ultimately calls _X_A_l_l_o_c_C_o_l_o_r to
allocate a read‐only color cell with the color specified by
a color string.  The color string is parsed into an _X_c_m_s_­
_C_o_l_o_r structure (see _X_c_m_s_L_o_o_k_u_p_C_o_l_o_r), converted to an RGB
value, and finally passed to _X_A_l_l_o_c_C_o_l_o_r.  If the color name
is not in the Host Portable Character Encoding, the result
is implementation‐dependent.  Use of uppercase or lowercase
does not matter.





                             113300





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


This function returns both the color specification as a
result of parsing (exact specification) and the actual color
specification stored (screen specification).  This screen
specification is the result of converting the RGB value
returned by _X_A_l_l_o_c_C_o_l_o_r into the format specified in
result_format.  If there is no interest in a returned color
specification, unnecessary computation can be bypassed if
result_format is set to _X_c_m_s_R_G_B_F_o_r_m_a_t.  If
color_screen_return and color_exact_return point to the same
structure, the pixel field will be set correctly, but the
color values are undefined.

_X_c_m_s_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.


To allocate read/write color cell and color plane combina­
tions for a _P_s_e_u_d_o_C_o_l_o_r model, use _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s.
__
││
Status XAllocColorCells(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_n_t_i_g, _p_l_a_n_e___m_a_s_k_s___r_e_t_u_r_n, _n_p_l_a_n_e_s,
                          _p_i_x_e_l_s___r_e_t_u_r_n, _n_p_i_x_e_l_s)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      Bool _c_o_n_t_i_g;
      unsigned long _p_l_a_n_e___m_a_s_k_s___r_e_t_u_r_n[];
      unsigned int _n_p_l_a_n_e_s;
      unsigned long _p_i_x_e_l_s___r_e_t_u_r_n[];
      unsigned int _n_p_i_x_e_l_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_n_t_i_g    Specifies a Boolean value that indicates whether
          the planes must be contiguous.

_p_l_a_n_e___m_a_s_k___r_e_t_u_r_n
          Returns an array of plane masks.

_n_p_l_a_n_e_s   Specifies the number of plane masks that are to be
          returned in the plane masks array.

_p_i_x_e_l_s___r_e_t_u_r_n
          Returns an array of pixel values.

_n_p_i_x_e_l_s   Specifies the number of pixel values that are to
          be returned in the pixels_return array.
││__

The _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s function allocates read/write color
cells.  The number of colors must be positive and the number
of planes nonnegative, or a _B_a_d_V_a_l_u_e error results.  If
ncolors and nplanes are requested, then ncolors pixels and



                             113311





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


nplane plane masks are returned.  No mask will have any bits
set to 1 in common with any other mask or with any of the
pixels.  By ORing together each pixel with zero or more
masks, ncolors * 2_n_p_l_a_n_e_s distinct pixels can be produced.
All of these are allocated writable by the request.  For
_G_r_a_y_S_c_a_l_e or _P_s_e_u_d_o_C_o_l_o_r, each mask has exactly one bit set
to 1.  For _D_i_r_e_c_t_C_o_l_o_r, each has exactly three bits set to
1.  If contig is _T_r_u_e and if all masks are ORed together, a
single contiguous set of bits set to 1 will be formed for
_G_r_a_y_S_c_a_l_e or _P_s_e_u_d_o_C_o_l_o_r and three contiguous sets of bits
set to 1 (one within each pixel subfield) for _D_i_r_e_c_t_C_o_l_o_r.
The RGB values of the allocated entries are undefined.  _X_A_l_­
_l_o_c_C_o_l_o_r_C_e_l_l_s returns nonzero if it succeeded or zero if it
failed.

_X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s can generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e errors.


To allocate read/write color resources for a _D_i_r_e_c_t_C_o_l_o_r
model, use _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s.





































                             113322





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XAllocColorPlanes(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_n_t_i_g, _p_i_x_e_l_s___r_e_t_u_r_n, _n_c_o_l_o_r_s, _n_r_e_d_s, _n_g_r_e_e_n_s,
                           _n_b_l_u_e_s, _r_m_a_s_k___r_e_t_u_r_n, _g_m_a_s_k___r_e_t_u_r_n, _b_m_a_s_k___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      Bool _c_o_n_t_i_g;
      unsigned long _p_i_x_e_l_s___r_e_t_u_r_n[];
      int _n_c_o_l_o_r_s;
      int _n_r_e_d_s, _n_g_r_e_e_n_s, _n_b_l_u_e_s;
      unsigned long *_r_m_a_s_k___r_e_t_u_r_n, *_g_m_a_s_k___r_e_t_u_r_n, *_b_m_a_s_k___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_n_t_i_g    Specifies a Boolean value that indicates whether
          the planes must be contiguous.

_p_i_x_e_l_s___r_e_t_u_r_n
          Returns an array of pixel values.  _X_A_l_l_o_c_C_o_l_o_r_­
          _P_l_a_n_e_s returns the pixel values in this array.

_n_c_o_l_o_r_s   Specifies the number of pixel values that are to
          be returned in the pixels_return array.

_n_r_e_d_s
_n_g_r_e_e_n_s
_n_b_l_u_e_s
          Specify the number of red, green, and blue planes.
          The value you pass must be nonnegative.

_r_m_a_s_k___r_e_t_u_r_n
_g_m_a_s_k___r_e_t_u_r_n
_b_m_a_s_k___r_e_t_u_r_n
          Return bit masks for the red, green, and blue
          planes.
││__

The specified ncolors must be positive; and nreds, ngreens,
and nblues must be nonnegative, or a _B_a_d_V_a_l_u_e error results.
If ncolors colors, nreds reds, ngreens greens, and nblues
blues are requested, ncolors pixels are returned; and the
masks have nreds, ngreens, and nblues bits set to 1, respec­
tively.  If contig is _T_r_u_e, each mask will have a contiguous
set of bits set to 1.  No mask will have any bits set to 1
in common with any other mask or with any of the pixels.
For _D_i_r_e_c_t_C_o_l_o_r, each mask will lie within the corresponding
pixel subfield.  By ORing together subsets of masks with
each pixel value, ncolors * 2(_n_r_e_d_s+_n_g_r_e_e_n_s+_n_b_l_u_e_s) distinct
pixel values can be produced.  All of these are allocated by
the request.  However, in the colormap, there are only ncol­
ors * 2_n_r_e_d_s independent red entries, ncolors * 2_n_g_r_e_e_n_s
independent green entries, and ncolors * 2_n_b_l_u_e_s independent



                             113333





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


blue entries.  This is true even for _P_s_e_u_d_o_C_o_l_o_r.  When the
colormap entry of a pixel value is changed (using _X_S_t_o_r_e_C_o_l_­
_o_r_s, _X_S_t_o_r_e_C_o_l_o_r, or _X_S_t_o_r_e_N_a_m_e_d_C_o_l_o_r), the pixel is decom­
posed according to the masks, and the corresponding indepen­
dent entries are updated.  _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s returns nonzero
if it succeeded or zero if it failed.

_X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s can generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e errors.


To free colormap cells, use _X_F_r_e_e_C_o_l_o_r_s.
__
││
XFreeColors(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _p_i_x_e_l_s, _n_p_i_x_e_l_s, _p_l_a_n_e_s)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      unsigned long _p_i_x_e_l_s[];
      int _n_p_i_x_e_l_s;
      unsigned long _p_l_a_n_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_p_i_x_e_l_s    Specifies an array of pixel values that map to the
          cells in the specified colormap.

_n_p_i_x_e_l_s   Specifies the number of pixels.

_p_l_a_n_e_s    Specifies the planes you want to free.
││__

The _X_F_r_e_e_C_o_l_o_r_s function frees the cells represented by pix­
els whose values are in the pixels array.  The planes argu­
ment should not have any bits set to 1 in common with any of
the pixels.  The set of all pixels is produced by ORing
together subsets of the planes argument with the pixels.
The request frees all of these pixels that were allocated by
the client (using _X_A_l_l_o_c_C_o_l_o_r, _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r, _X_A_l_l_o_c_C_o_l_­
_o_r_C_e_l_l_s, and _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s).  Note that freeing an indi­
vidual pixel obtained from _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s may not actu­
ally allow it to be reused until all of its related pixels
are also freed.  Similarly, a read‐only entry is not actu­
ally freed until it has been freed by all clients, and if a
client allocates the same read‐only entry multiple times, it
must free the entry that many times before the entry is
actually freed.

All specified pixels that are allocated by the client in the
colormap are freed, even if one or more pixels produce an
error.  If a specified pixel is not a valid index into the
colormap, a _B_a_d_V_a_l_u_e error results.  If a specified pixel is
not allocated by the client (that is, is unallocated or is



                             113344





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


only allocated by another client) or if the colormap was
created with all entries writable (by passing _A_l_l_o_c_A_l_l to
_X_C_r_e_a_t_e_C_o_l_o_r_m_a_p), a _B_a_d_A_c_c_e_s_s error results.  If more than
one pixel is in error, the one that gets reported is arbi­
trary.

_X_F_r_e_e_C_o_l_o_r_s can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r, and _B_a_d_V_a_l_u_e
errors.

66..77..  MMooddiiffyyiinngg aanndd QQuueerryyiinngg CCoolloorrmmaapp CCeellllss


To store an RGB value in a single colormap cell, use _X_S_t_o_r_e_­
_C_o_l_o_r.
__
││
XStoreColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XColor *_c_o_l_o_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r     Specifies the pixel and RGB values.
││__

The _X_S_t_o_r_e_C_o_l_o_r function changes the colormap entry of the
pixel value specified in the pixel member of the _X_C_o_l_o_r
structure.  You specified this value in the pixel member of
the _X_C_o_l_o_r structure.  This pixel value must be a read/write
cell and a valid index into the colormap.  If a specified
pixel is not a valid index into the colormap, a _B_a_d_V_a_l_u_e
error results.  _X_S_t_o_r_e_C_o_l_o_r also changes the red, green,
and/or blue color components.  You specify which color com­
ponents are to be changed by setting _D_o_R_e_d, _D_o_G_r_e_e_n, and/or
_D_o_B_l_u_e in the flags member of the _X_C_o_l_o_r structure.  If the
colormap is an installed map for its screen, the changes are
visible immediately.

_X_S_t_o_r_e_C_o_l_o_r can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r, and _B_a_d_V_a_l_u_e
errors.


To store multiple RGB values in multiple colormap cells, use
_X_S_t_o_r_e_C_o_l_o_r_s.









                             113355





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XStoreColors(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r, _n_c_o_l_o_r_s)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XColor _c_o_l_o_r[];
      int _n_c_o_l_o_r_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r     Specifies an array of color definition structures
          to be stored.

_n_c_o_l_o_r_s   Specifies the number of _X_C_o_l_o_r structures in the
          color definition array.
││__

The _X_S_t_o_r_e_C_o_l_o_r_s function changes the colormap entries of
the pixel values specified in the pixel members of the
_X_C_o_l_o_r structures.  You specify which color components are
to be changed by setting _D_o_R_e_d, _D_o_G_r_e_e_n, and/or _D_o_B_l_u_e in
the flags member of the _X_C_o_l_o_r structures.  If the colormap
is an installed map for its screen, the changes are visible
immediately.  _X_S_t_o_r_e_C_o_l_o_r_s changes the specified pixels if
they are allocated writable in the colormap by any client,
even if one or more pixels generates an error.  If a speci­
fied pixel is not a valid index into the colormap, a _B_a_d_­
_V_a_l_u_e error results.  If a specified pixel either is unallo­
cated or is allocated read‐only, a _B_a_d_A_c_c_e_s_s error results.
If more than one pixel is in error, the one that gets
reported is arbitrary.

_X_S_t_o_r_e_C_o_l_o_r_s can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r, and _B_a_d_V_a_l_u_e
errors.


To store a color of arbitrary format in a single colormap
cell, use _X_c_m_s_S_t_o_r_e_C_o_l_o_r.

















                             113366





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsStoreColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XcmsColor *_c_o_l_o_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r     Specifies the color cell and the color to store.
          Values specified in this _X_c_m_s_C_o_l_o_r structure
          remain unchanged on return.
││__

The _X_c_m_s_S_t_o_r_e_C_o_l_o_r function converts the color specified in
the _X_c_m_s_C_o_l_o_r structure into RGB values.  It then uses this
RGB specification in an _X_C_o_l_o_r structure, whose three flags
(_D_o_R_e_d, _D_o_G_r_e_e_n, and _D_o_B_l_u_e) are set, in a call to _X_S_t_o_r_e_­
_C_o_l_o_r to change the color cell specified by the pixel member
of the _X_c_m_s_C_o_l_o_r structure.  This pixel value must be a
valid index for the specified colormap, and the color cell
specified by the pixel value must be a read/write cell.  If
the pixel value is not a valid index, a _B_a_d_V_a_l_u_e error
results.  If the color cell is unallocated or is allocated
read‐only, a _B_a_d_A_c_c_e_s_s error results.  If the colormap is an
installed map for its screen, the changes are visible imme­
diately.

Note that _X_S_t_o_r_e_C_o_l_o_r has no return value; therefore, an
_X_c_m_s_S_u_c_c_e_s_s return value from this function indicates that
the conversion to RGB succeeded and the call to _X_S_t_o_r_e_C_o_l_o_r
was made.  To obtain the actual color stored, use _X_c_m_s_Q_u_e_r_y_­
_C_o_l_o_r.  Because of the screen’s hardware limitations or
gamut compression, the color stored in the colormap may not
be identical to the color specified.

_X_c_m_s_S_t_o_r_e_C_o_l_o_r can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r, and _B_a_d_­
_V_a_l_u_e errors.


To store multiple colors of arbitrary format in multiple
colormap cells, use _X_c_m_s_S_t_o_r_e_C_o_l_o_r_s.













                             113377





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsStoreColors(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r_s, _n_c_o_l_o_r_s, _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XcmsColor _c_o_l_o_r_s[];
      int _n_c_o_l_o_r_s;
      Bool _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n[];


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r_s    Specifies the color specification array of _X_c_m_s_­
          _C_o_l_o_r structures, each specifying a color cell and
          the color to store in that cell.  Values specified
          in the array remain unchanged upon return.

_n_c_o_l_o_r_s   Specifies the number of _X_c_m_s_C_o_l_o_r structures in
          the color‐specification array.

_c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n
          Returns an array of Boolean values indicating com­
          pression status.  If a non‐NULL pointer is sup­
          plied, each element of the array is set to _T_r_u_e if
          the corresponding color was compressed and _F_a_l_s_e
          otherwise.  Pass NULL if the compression status is
          not useful.
││__

The _X_c_m_s_S_t_o_r_e_C_o_l_o_r_s function converts the colors specified
in the array of _X_c_m_s_C_o_l_o_r structures into RGB values and
then uses these RGB specifications in _X_C_o_l_o_r structures,
whose three flags (_D_o_R_e_d, _D_o_G_r_e_e_n, and _D_o_B_l_u_e) are set, in a
call to _X_S_t_o_r_e_C_o_l_o_r_s to change the color cells specified by
the pixel member of the corresponding _X_c_m_s_C_o_l_o_r structure.
Each pixel value must be a valid index for the specified
colormap, and the color cell specified by each pixel value
must be a read/write cell.  If a pixel value is not a valid
index, a _B_a_d_V_a_l_u_e error results.  If a color cell is unallo­
cated or is allocated read‐only, a _B_a_d_A_c_c_e_s_s error results.
If more than one pixel is in error, the one that gets
reported is arbitrary.  If the colormap is an installed map
for its screen, the changes are visible immediately.

Note that _X_S_t_o_r_e_C_o_l_o_r_s has no return value; therefore, an
_X_c_m_s_S_u_c_c_e_s_s return value from this function indicates that
conversions to RGB succeeded and the call to _X_S_t_o_r_e_C_o_l_o_r_s
was made.  To obtain the actual colors stored, use _X_c_m_s_­
_Q_u_e_r_y_C_o_l_o_r_s.  Because of the screen’s hardware limitations
or gamut compression, the colors stored in the colormap may
not be identical to the colors specified.





                             113388





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_c_m_s_S_t_o_r_e_C_o_l_o_r_s can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r, and _B_a_d_­
_V_a_l_u_e errors.


To store a color specified by name in a single colormap
cell, use _X_S_t_o_r_e_N_a_m_e_d_C_o_l_o_r.
__
││
XStoreNamedColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r, _p_i_x_e_l, _f_l_a_g_s)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      char *_c_o_l_o_r;
      unsigned long _p_i_x_e_l;
      int _f_l_a_g_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r     Specifies the color name string (for example,
          red).

_p_i_x_e_l     Specifies the entry in the colormap.

_f_l_a_g_s     Specifies which red, green, and blue components
          are set.
││__

The _X_S_t_o_r_e_N_a_m_e_d_C_o_l_o_r function looks up the named color with
respect to the screen associated with the colormap and
stores the result in the specified colormap.  The pixel
argument determines the entry in the colormap.  The flags
argument determines which of the red, green, and blue compo­
nents are set.  You can set this member to the bitwise
inclusive OR of the bits _D_o_R_e_d, _D_o_G_r_e_e_n, and _D_o_B_l_u_e.  If the
color name is not in the Host Portable Character Encoding,
the result is implementation‐dependent.  Use of uppercase or
lowercase does not matter.  If the specified pixel is not a
valid index into the colormap, a _B_a_d_V_a_l_u_e error results.  If
the specified pixel either is unallocated or is allocated
read‐only, a _B_a_d_A_c_c_e_s_s error results.

_X_S_t_o_r_e_N_a_m_e_d_C_o_l_o_r can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r, _B_a_d_N_a_m_e,
and _B_a_d_V_a_l_u_e errors.

The _X_Q_u_e_r_y_C_o_l_o_r and _X_Q_u_e_r_y_C_o_l_o_r_s functions take pixel values
in the pixel member of _X_C_o_l_o_r structures and store in the
structures the RGB values for those pixels from the speci­
fied colormap.  The values returned for an unallocated entry
are undefined.  These functions also set the flags member in
the _X_C_o_l_o_r structure to all three colors.  If a pixel is not
a valid index into the specified colormap, a _B_a_d_V_a_l_u_e error
results.  If more than one pixel is in error, the one that



                             113399





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


gets reported is arbitrary.


To query the RGB value of a single colormap cell, use
_X_Q_u_e_r_y_C_o_l_o_r.
__
││
XQueryColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _d_e_f___i_n___o_u_t)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XColor *_d_e_f___i_n___o_u_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_d_e_f___i_n___o_u_t
          Specifies and returns the RGB values for the pixel
          specified in the structure.
││__

The _X_Q_u_e_r_y_C_o_l_o_r function returns the current RGB value for
the pixel in the _X_C_o_l_o_r structure and sets the _D_o_R_e_d,
_D_o_G_r_e_e_n, and _D_o_B_l_u_e flags.

_X_Q_u_e_r_y_C_o_l_o_r can generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e errors.


To query the RGB values of multiple colormap cells, use
_X_Q_u_e_r_y_C_o_l_o_r_s.
__
││
XQueryColors(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _d_e_f_s___i_n___o_u_t, _n_c_o_l_o_r_s)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XColor _d_e_f_s___i_n___o_u_t[];
      int _n_c_o_l_o_r_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_d_e_f_s___i_n___o_u_t
          Specifies and returns an array of color definition
          structures for the pixel specified in the struc­
          ture.

_n_c_o_l_o_r_s   Specifies the number of _X_C_o_l_o_r structures in the
          color definition array.
││__

The _X_Q_u_e_r_y_C_o_l_o_r_s function returns the RGB value for each



                             114400





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


pixel in each _X_C_o_l_o_r structure and sets the _D_o_R_e_d, _D_o_G_r_e_e_n,
and _D_o_B_l_u_e flags in each structure.


_X_Q_u_e_r_y_C_o_l_o_r_s can generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e errors.


To query the color of a single colormap cell in an arbitrary
format, use _X_c_m_s_Q_u_e_r_y_C_o_l_o_r.
__
││
Status XcmsQueryColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r___i_n___o_u_t, _r_e_s_u_l_t___f_o_r_m_a_t)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XcmsColor *_c_o_l_o_r___i_n___o_u_t;
      XcmsColorFormat _r_e_s_u_l_t___f_o_r_m_a_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r___i_n___o_u_t
          Specifies the pixel member that indicates the
          color cell to query.  The color specification
          stored for the color cell is returned in this _X_c_m_­
          _s_C_o_l_o_r structure.

_r_e_s_u_l_t___f_o_r_m_a_t
          Specifies the color format for the returned color
          specification.
││__

The _X_c_m_s_Q_u_e_r_y_C_o_l_o_r function obtains the RGB value for the
pixel value in the pixel member of the specified _X_c_m_s_C_o_l_o_r
structure and then converts the value to the target format
as specified by the result_format argument.  If the pixel is
not a valid index in the specified colormap, a _B_a_d_V_a_l_u_e
error results.

_X_c_m_s_Q_u_e_r_y_C_o_l_o_r can generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e errors.


To query the color of multiple colormap cells in an arbi­
trary format, use _X_c_m_s_Q_u_e_r_y_C_o_l_o_r_s.












                             114411





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsQueryColors(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r_s___i_n___o_u_t, _n_c_o_l_o_r_s, _r_e_s_u_l_t___f_o_r_m_a_t)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XcmsColor _c_o_l_o_r_s___i_n___o_u_t[];
      unsigned int _n_c_o_l_o_r_s;
      XcmsColorFormat _r_e_s_u_l_t___f_o_r_m_a_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_o_l_o_r_s___i_n___o_u_t
          Specifies an array of _X_c_m_s_C_o_l_o_r structures, each
          pixel member indicating the color cell to query.
          The color specifications for the color cells are
          returned in these structures.

_n_c_o_l_o_r_s   Specifies the number of _X_c_m_s_C_o_l_o_r structures in
          the color‐specification array.

_r_e_s_u_l_t___f_o_r_m_a_t
          Specifies the color format for the returned color
          specification.
││__

The _X_c_m_s_Q_u_e_r_y_C_o_l_o_r_s function obtains the RGB values for
pixel values in the pixel members of _X_c_m_s_C_o_l_o_r structures
and then converts the values to the target format as speci­
fied by the result_format argument.  If a pixel is not a
valid index into the specified colormap, a _B_a_d_V_a_l_u_e error
results.  If more than one pixel is in error, the one that
gets reported is arbitrary.

_X_c_m_s_Q_u_e_r_y_C_o_l_o_r_s can generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e errors.

66..88..  CCoolloorr CCoonnvveerrssiioonn CCoonntteexxtt FFuunnccttiioonnss

This section describes functions to create, modify, and
query Color Conversion Contexts (CCCs).

Associated with each colormap is an initial CCC transpar­
ently generated by Xlib.  Therefore, when you specify a col­
ormap as an argument to a function, you are indirectly spec­
ifying a CCC.  The CCC attributes that can be modified by
the X client are:

⋅    Client White Point

⋅    Gamut compression procedure and client data

⋅    White point adjustment procedure and client data




                             114422





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The initial values for these attributes are implementation
specific.  The CCC attributes for subsequently created CCCs
can be defined by changing the CCC attributes of the default
CCC.  There is a default CCC associated with each screen.

66..88..11..  GGeettttiinngg aanndd SSeettttiinngg tthhee CCoolloorr CCoonnvveerrssiioonn CCoonntteexxtt ooff
aa CCoolloorrmmaapp


To obtain the CCC associated with a colormap, use _X_c_m_s_C_C_C_O_f_­
_C_o_l_o_r_m_a_p.
__
││
XcmsCCC XcmsCCCOfColormap(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.
││__

The _X_c_m_s_C_C_C_O_f_C_o_l_o_r_m_a_p function returns the CCC associated
with the specified colormap.  Once obtained, the CCC
attributes can be queried or modified.  Unless the CCC asso­
ciated with the specified colormap is changed with _X_c_m_s_S_e_t_C_­
_C_C_O_f_C_o_l_o_r_m_a_p, this CCC is used when the specified colormap
is used as an argument to color functions.


To change the CCC associated with a colormap, use _X_c_m_s_S_e_t_C_C_­
_C_O_f_C_o_l_o_r_m_a_p.
__
││
XcmsCCC XcmsSetCCCOfColormap(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_c_c)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;
      XcmsCCC _c_c_c;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_c_c_c       Specifies the CCC.
││__

The _X_c_m_s_S_e_t_C_C_C_O_f_C_o_l_o_r_m_a_p function changes the CCC associated
with the specified colormap.  It returns the CCC previously
associated with the colormap.  If they are not used again in
the application, CCCs should be freed by calling _X_c_m_s_­
_F_r_e_e_C_C_C.  Several colormaps may share the same CCC without
restriction; this includes the CCCs generated by Xlib with



                             114433





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


each colormap.  Xlib, however, creates a new CCC with each
new colormap.

66..88..22..  OObbttaaiinniinngg tthhee DDeeffaauulltt CCoolloorr CCoonnvveerrssiioonn CCoonntteexxtt

You can change the default CCC attributes for subsequently
created CCCs by changing the CCC attributes of the default
CCC.  A default CCC is associated with each screen.


To obtain the default CCC for a screen, use _X_c_m_s_D_e_f_a_u_l_t_C_C_C.
__
││
XcmsCCC XcmsDefaultCCC(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

The _X_c_m_s_D_e_f_a_u_l_t_C_C_C function returns the default CCC for the
specified screen.  Its visual is the default visual of the
screen.  Its initial gamut compression and white point
adjustment procedures as well as the associated client data
are implementation specific.

66..88..33..  CCoolloorr CCoonnvveerrssiioonn CCoonntteexxtt MMaaccrrooss

Applications should not directly modify any part of the _X_c_m_­
_s_C_C_C.  The following lists the C language macros, their cor­
responding function equivalents for other language bindings,
and what data they both can return.


__
││
DisplayOfCCC(_c_c_c)
     XcmsCCC _c_c_c;

Display *XcmsDisplayOfCCC(_c_c_c)
     XcmsCCC _c_c_c;


_c_c_c       Specifies the CCC.
││__

Both return the display associated with the specified CCC.





                             114444





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
VisualOfCCC(_c_c_c)
     XcmsCCC _c_c_c;

Visual *XcmsVisualOfCCC(_c_c_c)
     XcmsCCC _c_c_c;


_c_c_c       Specifies the CCC.
││__

Both return the visual associated with the specified CCC.


__
││
ScreenNumberOfCCC(_c_c_c)
     XcmsCCC _c_c_c;

int XcmsScreenNumberOfCCC(_c_c_c)
     XcmsCCC _c_c_c;


_c_c_c       Specifies the CCC.
││__

Both return the number of the screen associated with the
specified CCC.


__
││
ScreenWhitePointOfCCC(_c_c_c)
     XcmsCCC _c_c_c;

XcmsColor *XcmsScreenWhitePointOfCCC(_c_c_c)
     XcmsCCC _c_c_c;


_c_c_c       Specifies the CCC.
││__

Both return the white point of the screen associated with
the specified CCC.













                             114455





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
ClientWhitePointOfCCC(_c_c_c)
     XcmsCCC _c_c_c;

XcmsColor *XcmsClientWhitePointOfCCC(_c_c_c)
     XcmsCCC _c_c_c;


_c_c_c       Specifies the CCC.
││__

Both return the Client White Point of the specified CCC.

66..88..44..  MMooddiiffyyiinngg AAttttrriibbuutteess ooff aa CCoolloorr CCoonnvveerrssiioonn CCoonntteexxtt

To set the Client White Point in the CCC, use _X_c_m_s_S_e_t_W_h_i_t_e_­
_P_o_i_n_t.
__
││
Status XcmsSetWhitePoint(_c_c_c, _c_o_l_o_r)
      XcmsCCC _c_c_c;
      XcmsColor *_c_o_l_o_r;


_c_c_c       Specifies the CCC.

_c_o_l_o_r     Specifies the new Client White Point.
││__

The _X_c_m_s_S_e_t_W_h_i_t_e_P_o_i_n_t function changes the Client White
Point in the specified CCC.  Note that the pixel member is
ignored and that the color specification is left unchanged
upon return.  The format for the new white point must be
_X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t, _X_c_m_s_C_I_E_u_v_Y_F_o_r_m_a_t, _X_c_m_s_C_I_E_x_y_Y_F_o_r_m_a_t, or
_X_c_m_s_U_n_d_e_f_i_n_e_d_F_o_r_m_a_t.  If the color argument is NULL, this
function sets the format component of the Client White Point
specification to _X_c_m_s_U_n_d_e_f_i_n_e_d_F_o_r_m_a_t, indicating that the
Client White Point is assumed to be the same as the Screen
White Point.

This function returns nonzero status if the format for the
new white point is valid; otherwise, it returns zero.



To set the gamut compression procedure and corresponding
client data in a specified CCC, use _X_c_m_s_S_e_t_C_o_m_p_r_e_s_s_i_o_n_P_r_o_c.










                             114466





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XcmsCompressionProc XcmsSetCompressionProc(_c_c_c, _c_o_m_p_r_e_s_s_i_o_n___p_r_o_c, _c_l_i_e_n_t___d_a_t_a)
      XcmsCCC _c_c_c;
      XcmsCompressionProc _c_o_m_p_r_e_s_s_i_o_n___p_r_o_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;


_c_c_c       Specifies the CCC.

_c_o_m_p_r_e_s_s_i_o_n___p_r_o_c
          Specifies the gamut compression procedure that is
          to be applied when a color lies outside the
          screen’s color gamut.  If NULL is specified and a
          function using this CCC must convert a color spec­
          ification to a device‐dependent format and encoun­
          ters a color that lies outside the screen’s color
          gamut, that function will return _X_c_m_s_F_a_i_l_u_r_e.

_c_l_i_e_n_t___d_a_t_a
          Specifies client data for the gamut compression
          procedure or NULL.
││__

The _X_c_m_s_S_e_t_C_o_m_p_r_e_s_s_i_o_n_P_r_o_c function first sets the gamut
compression procedure and client data in the specified CCC
with the newly specified procedure and client data and then
returns the old procedure.


To set the white point adjustment procedure and correspond­
ing client data in a specified CCC, use _X_c_m_s_S_e_t_W_h_i_t_e_A_d_j_u_s_t_­
_P_r_o_c.

__
││    XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc(_c_c_c, _w_h_i_t_e___a_d_j_u_s_t___p_r_o_c, _c_l_i_e_n_t___d_a_t_a)
      XcmsCCC _c_c_c;
      XcmsWhiteAdjustProc _w_h_i_t_e___a_d_j_u_s_t___p_r_o_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;


_c_c_c       Specifies the CCC.

_w_h_i_t_e___a_d_j_u_s_t___p_r_o_c
          Specifies the white point adjustment procedure.

_c_l_i_e_n_t___d_a_t_a
          Specifies client data for the white point adjust­
          ment procedure or NULL.
││__

The _X_c_m_s_S_e_t_W_h_i_t_e_A_d_j_u_s_t_P_r_o_c function first sets the white
point adjustment procedure and client data in the specified
CCC with the newly specified procedure and client data and
then returns the old procedure.



                             114477





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


66..88..55..  CCrreeaattiinngg aanndd FFrreeeeiinngg aa CCoolloorr CCoonnvveerrssiioonn CCoonntteexxtt

You can explicitly create a CCC within your application by
calling _X_c_m_s_C_r_e_a_t_e_C_C_C.  These created CCCs can then be used
by those functions that explicitly call for a CCC argument.
Old CCCs that will not be used by the application should be
freed using _X_c_m_s_F_r_e_e_C_C_C.


To create a CCC, use _X_c_m_s_C_r_e_a_t_e_C_C_C.















































                             114488





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XcmsCCC XcmsCreateCCC(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r, _v_i_s_u_a_l, _c_l_i_e_n_t___w_h_i_t_e___p_o_i_n_t, _c_o_m_p_r_e_s_s_i_o_n___p_r_o_c,
                    _c_o_m_p_r_e_s_s_i_o_n___c_l_i_e_n_t___d_a_t_a, _w_h_i_t_e___a_d_j_u_s_t___p_r_o_c, _w_h_i_t_e___a_d_j_u_s_t___c_l_i_e_n_t___d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;
      Visual *_v_i_s_u_a_l;
      XcmsColor *_c_l_i_e_n_t___w_h_i_t_e___p_o_i_n_t;
      XcmsCompressionProc _c_o_m_p_r_e_s_s_i_o_n___p_r_o_c;
      XPointer _c_o_m_p_r_e_s_s_i_o_n___c_l_i_e_n_t___d_a_t_a;
      XcmsWhiteAdjustProc _w_h_i_t_e___a_d_j_u_s_t___p_r_o_c;
      XPointer _w_h_i_t_e___a_d_j_u_s_t___c_l_i_e_n_t___d_a_t_a;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.

_v_i_s_u_a_l    Specifies the visual type.

_c_l_i_e_n_t___w_h_i_t_e___p_o_i_n_t
          Specifies the Client White Point.  If NULL is
          specified, the Client White Point is to be assumed
          to be the same as the Screen White Point.  Note
          that the pixel member is ignored.

_c_o_m_p_r_e_s_s_i_o_n___p_r_o_c
          Specifies the gamut compression procedure that is
          to be applied when a color lies outside the
          screen’s color gamut.  If NULL is specified and a
          function using this CCC must convert a color spec­
          ification to a device‐dependent format and encoun­
          ters a color that lies outside the screen’s color
          gamut, that function will return _X_c_m_s_F_a_i_l_u_r_e.

_c_o_m_p_r_e_s_s_i_o_n___c_l_i_e_n_t___d_a_t_a
          Specifies client data for use by the gamut com­
          pression procedure or NULL.

_w_h_i_t_e___a_d_j_u_s_t___p_r_o_c
          Specifies the white adjustment procedure that is
          to be applied when the Client White Point differs
          from the Screen White Point.  NULL indicates that
          no white point adjustment is desired.

_w_h_i_t_e___a_d_j_u_s_t___c_l_i_e_n_t___d_a_t_a
          Specifies client data for use with the white point
          adjustment procedure or NULL.
││__

The _X_c_m_s_C_r_e_a_t_e_C_C_C function creates a CCC for the specified
display, screen, and visual.




                             114499





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To free a CCC, use _X_c_m_s_F_r_e_e_C_C_C.
__
││
void XcmsFreeCCC(_c_c_c)
      XcmsCCC _c_c_c;


_c_c_c       Specifies the CCC.
││__

The _X_c_m_s_F_r_e_e_C_C_C function frees the memory used for the spec­
ified CCC.  Note that default CCCs and those currently asso­
ciated with colormaps are ignored.

66..99..  CCoonnvveerrttiinngg bbeettwweeeenn CCoolloorr SSppaacceess


To convert an array of color specifications in arbitrary
color formats to a single destination format, use _X_c_m_s_C_o_n_­
_v_e_r_t_C_o_l_o_r_s.





































                             115500





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsConvertColors(_c_c_c, _c_o_l_o_r_s___i_n___o_u_t, _n_c_o_l_o_r_s, _t_a_r_g_e_t___f_o_r_m_a_t, _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsColor _c_o_l_o_r_s___i_n___o_u_t[];
      unsigned int _n_c_o_l_o_r_s;
      XcmsColorFormat _t_a_r_g_e_t___f_o_r_m_a_t;
      Bool _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n[];


_c_c_c       Specifies the CCC.  If conversion is between
          device‐independent color spaces only (for example,
          TekHVC to CIELuv), the CCC is necessary only to
          specify the Client White Point.

_c_o_l_o_r_s___i_n___o_u_t
          Specifies an array of color specifications.  Pixel
          members are ignored and remain unchanged upon
          return.

_n_c_o_l_o_r_s   Specifies the number of _X_c_m_s_C_o_l_o_r structures in
          the color‐specification array.

_t_a_r_g_e_t___f_o_r_m_a_t
          Specifies the target color specification format.

_c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n
          Returns an array of Boolean values indicating com­
          pression status.  If a non‐NULL pointer is sup­
          plied, each element of the array is set to _T_r_u_e if
          the corresponding color was compressed and _F_a_l_s_e
          otherwise.  Pass NULL if the compression status is
          not useful.
││__

The _X_c_m_s_C_o_n_v_e_r_t_C_o_l_o_r_s function converts the color specifica­
tions in the specified array of _X_c_m_s_C_o_l_o_r structures from
their current format to a single target format, using the
specified CCC.  When the return value is _X_c_m_s_F_a_i_l_u_r_e, the
contents of the color specification array are left
unchanged.

The array may contain a mixture of color specification for­
mats (for example, 3 CIE XYZ, 2 CIE Luv, and so on).  When
the array contains both device‐independent and device‐depen­
dent color specifications and the target_format argument
specifies a device‐dependent format (for example, _X_c_m_s_R_G_B_i_­
_F_o_r_m_a_t, _X_c_m_s_R_G_B_F_o_r_m_a_t), all specifications are converted to
CIE XYZ format and then to the target device‐dependent for­
mat.

66..1100..  CCaallllbbaacckk FFuunnccttiioonnss

This section describes the gamut compression and white point
adjustment callbacks.



                             115511





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The gamut compression procedure specified in the CCC is
called when an attempt to convert a color specification from
_X_c_m_s_C_I_E_X_Y_Z to a device‐dependent format (typically _X_c_m_s_R_G_B_i)
results in a color that lies outside the screen’s color
gamut.  If the gamut compression procedure requires client
data, this data is passed via the gamut compression client
data in the CCC.

During color specification conversion between device‐inde­
pendent and device‐dependent color spaces, if a white point
adjustment procedure is specified in the CCC, it is trig­
gered when the Client White Point and Screen White Point
differ.  If required, the client data is obtained from the
CCC.

66..1100..11..  PPrroottoottyyppee GGaammuutt CCoommpprreessssiioonn PPrroocceedduurree

The gamut compression callback interface must adhere to the
following:






































                             115522





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef Status (*XcmsCompressionProc)(_c_c_c, _c_o_l_o_r_s___i_n___o_u_t, _n_c_o_l_o_r_s, _i_n_d_e_x, _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsColor _c_o_l_o_r_s___i_n___o_u_t_[_];
      unsigned int _n_c_o_l_o_r_s;
      unsigned int _i_n_d_e_x;
      Bool _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n_[_];


_c_c_c       Specifies the CCC.

_c_o_l_o_r_s___i_n___o_u_t
          Specifies an array of color specifications.  Pixel
          members should be ignored and must remain
          unchanged upon return.

_n_c_o_l_o_r_s   Specifies the number of _X_c_m_s_C_o_l_o_r structures in
          the color‐specification array.

_i_n_d_e_x     Specifies the index into the array of _X_c_m_s_C_o_l_o_r
          structures for the encountered color specification
          that lies outside the screen’s color gamut.  Valid
          values are 0 (for the first element) to ncolors −
          1.

_c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n
          Returns an array of Boolean values for indicating
          compression status.  If a non‐NULL pointer is sup­
          plied and a color at a given index is compressed,
          then _T_r_u_e should be stored at the corresponding
          index in this array; otherwise, the array should
          not be modified.
││__

When implementing a gamut compression procedure, consider
the following rules and assumptions:

⋅    The gamut compression procedure can attempt to compress
     one or multiple specifications at a time.

⋅    When called, elements 0 to index − 1 in the color spec­
     ification array can be assumed to fall within the
     screen’s color gamut.  In addition, these color speci­
     fications are already in some device‐dependent format
     (typically _X_c_m_s_R_G_B_i).  If any modifications are made to
     these color specifications, they must be in their ini­
     tial device‐dependent format upon return.

⋅    When called, the element in the color specification
     array specified by the index argument contains the
     color specification outside the screen’s color gamut
     encountered by the calling routine.  In addition, this
     color specification can be assumed to be in _X_c_m_s_C_I_E_X_Y_Z.
     Upon return, this color specification must be in



                             115533





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     _X_c_m_s_C_I_E_X_Y_Z.

⋅    When called, elements from index to ncolors − 1 in the
     color specification array may or may not fall within
     the screen’s color gamut.  In addition, these color
     specifications can be assumed to be in _X_c_m_s_C_I_E_X_Y_Z.  If
     any modifications are made to these color specifica­
     tions, they must be in _X_c_m_s_C_I_E_X_Y_Z upon return.

⋅    The color specifications passed to the gamut compres­
     sion procedure have already been adjusted to the Screen
     White Point.  This means that at this point the color
     specification’s white point is the Screen White Point.

⋅    If the gamut compression procedure uses a device‐inde­
     pendent color space not initially accessible for use in
     the color management system, use _X_c_m_s_A_d_d_C_o_l_o_r_S_p_a_c_e to
     ensure that it is added.

66..1100..22..  SSuupppplliieedd GGaammuutt CCoommpprreessssiioonn PPrroocceedduurreess

The following equations are useful in describing gamut com­
pression functions:


_C_I_E_L_a_b_P_s_y_c_h_o_m_e_t_r_i_c_C_h_r_o_m_a=_s_q_r_t(_a__s_t_a_r2+_b__s_t_a_r2)

_C_I_E_L_a_b_P_s_y_c_h_o_m_e_t_r_i_c_H_u_e=tan−1[_b_a_______s_s___t_t___a_a___r_r__]

_C_I_E_L_u_v_P_s_y_c_h_o_m_e_t_r_i_c_C_h_r_o_m_a=_s_q_r_t(_u__s_t_a_r2+_v__s_t_a_r2)

_C_I_E_L_u_v_P_s_y_c_h_o_m_e_t_r_i_c_H_u_e=tan−1[_v_u_______s_s___t_t___a_a___r_r__]


The gamut compression callback procedures provided by Xlib
are as follows:

⋅    _X_c_m_s_C_I_E_L_a_b_C_l_i_p_L

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by reducing or
     increasing CIE metric lightness (L*) in the CIE L*a*b*
     color space until the color is within the gamut.  If
     the Psychometric Chroma of the color specification is
     beyond maximum for the Psychometric Hue Angle, then
     while maintaining the same Psychometric Hue Angle, the
     color will be clipped to the CIE L*a*b* coordinates of
     maximum Psychometric Chroma.  See _X_c_m_s_C_I_E_L_a_b_Q_u_e_r_y_M_a_x_C.
     No client data is necessary.

⋅    _X_c_m_s_C_I_E_L_a_b_C_l_i_p_a_b

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by reducing



                             115544





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     Psychometric Chroma, while maintaining Psychometric Hue
     Angle, until the color is within the gamut.  No client
     data is necessary.

⋅    _X_c_m_s_C_I_E_L_a_b_C_l_i_p_L_a_b

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by replacing it
     with CIE L*a*b* coordinates that fall within the color
     gamut while maintaining the original Psychometric Hue
     Angle and whose vector to the original coordinates is
     the shortest attainable.  No client data is necessary.

⋅    _X_c_m_s_C_I_E_L_u_v_C_l_i_p_L

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by reducing or
     increasing CIE metric lightness (L*) in the CIE L*u*v*
     color space until the color is within the gamut.  If
     the Psychometric Chroma of the color specification is
     beyond maximum for the Psychometric Hue Angle, then,
     while maintaining the same Psychometric Hue Angle, the
     color will be clipped to the CIE L*u*v* coordinates of
     maximum Psychometric Chroma.  See _X_c_m_s_C_I_E_L_u_v_Q_u_e_r_y_M_a_x_C.
     No client data is necessary.

⋅    _X_c_m_s_C_I_E_L_u_v_C_l_i_p_u_v

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by reducing Psy­
     chometric Chroma, while maintaining Psychometric Hue
     Angle, until the color is within the gamut.  No client
     data is necessary.

⋅    _X_c_m_s_C_I_E_L_u_v_C_l_i_p_L_u_v

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by replacing it
     with CIE L*u*v* coordinates that fall within the color
     gamut while maintaining the original Psychometric Hue
     Angle and whose vector to the original coordinates is
     the shortest attainable.  No client data is necessary.

⋅    _X_c_m_s_T_e_k_H_V_C_C_l_i_p_V

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by reducing or
     increasing the Value dimension in the TekHVC color
     space until the color is within the gamut.  If Chroma
     of the color specification is beyond maximum for the
     particular Hue, then, while maintaining the same Hue,
     the color will be clipped to the Value and Chroma coor­
     dinates that represent maximum Chroma for that particu­
     lar Hue.  No client data is necessary.



                             115555





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    _X_c_m_s_T_e_k_H_V_C_C_l_i_p_C

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by reducing the
     Chroma dimension in the TekHVC color space until the
     color is within the gamut.  No client data is neces­
     sary.

⋅    _X_c_m_s_T_e_k_H_V_C_C_l_i_p_V_C

     This brings the encountered out‐of‐gamut color specifi­
     cation into the screen’s color gamut by replacing it
     with TekHVC coordinates that fall within the color
     gamut while maintaining the original Hue and whose vec­
     tor to the original coordinates is the shortest attain­
     able.  No client data is necessary.

66..1100..33..  PPrroottoottyyppee WWhhiittee PPooiinntt AAddjjuussttmmeenntt PPrroocceedduurree

The white point adjustment procedure interface must adhere
to the following:




































                             115566





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef Status (*XcmsWhiteAdjustProc)(_c_c_c, _i_n_i_t_i_a_l___w_h_i_t_e___p_o_i_n_t, _t_a_r_g_e_t___w_h_i_t_e___p_o_i_n_t, _t_a_r_g_e_t___f_o_r_m_a_t,
                _c_o_l_o_r_s___i_n___o_u_t, _n_c_o_l_o_r_s, _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n)
       XcmsCCC _c_c_c;
       XcmsColor *_i_n_i_t_i_a_l___w_h_i_t_e___p_o_i_n_t;
       XcmsColor *_t_a_r_g_e_t___w_h_i_t_e___p_o_i_n_t;
       XcmsColorFormat _t_a_r_g_e_t___f_o_r_m_a_t;
       XcmsColor _c_o_l_o_r_s___i_n___o_u_t_[_];
       unsigned int _n_c_o_l_o_r_s;
       Bool _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n_[_];


_c_c_c       Specifies the CCC.

_i_n_i_t_i_a_l___w_h_i_t_e___p_o_i_n_t
          Specifies the initial white point.

_t_a_r_g_e_t___w_h_i_t_e___p_o_i_n_t
          Specifies the target white point.

_t_a_r_g_e_t___f_o_r_m_a_t
          Specifies the target color specification format.

_c_o_l_o_r_s___i_n___o_u_t
          Specifies an array of color specifications.  Pixel
          members should be ignored and must remain
          unchanged upon return.

_n_c_o_l_o_r_s   Specifies the number of _X_c_m_s_C_o_l_o_r structures in
          the color‐specification array.

_c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n
          Returns an array of Boolean values for indicating
          compression status.  If a non‐NULL pointer is sup­
          plied and a color at a given index is compressed,
          then _T_r_u_e should be stored at the corresponding
          index in this array; otherwise, the array should
          not be modified.
││__


66..1100..44..  SSuupppplliieedd WWhhiittee PPooiinntt AAddjjuussttmmeenntt PPrroocceedduurreess

White point adjustment procedures provided by Xlib are as
follows:

⋅    _X_c_m_s_C_I_E_L_a_b_W_h_i_t_e_S_h_i_f_t_C_o_l_o_r_s

     This uses the CIE L*a*b* color space for adjusting the
     chromatic character of colors to compensate for the
     chromatic differences between the source and destina­
     tion white points.  This procedure simply converts the
     color specifications to _X_c_m_s_C_I_E_L_a_b using the source
     white point and then converts to the target



                             115577





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     specification format using the destination’s white
     point.  No client data is necessary.

⋅    _X_c_m_s_C_I_E_L_u_v_W_h_i_t_e_S_h_i_f_t_C_o_l_o_r_s

     This uses the CIE L*u*v* color space for adjusting the
     chromatic character of colors to compensate for the
     chromatic differences between the source and destina­
     tion white points.  This procedure simply converts the
     color specifications to _X_c_m_s_C_I_E_L_u_v using the source
     white point and then converts to the target specifica­
     tion format using the destination’s white point.  No
     client data is necessary.

⋅    _X_c_m_s_T_e_k_H_V_C_W_h_i_t_e_S_h_i_f_t_C_o_l_o_r_s

     This uses the TekHVC color space for adjusting the
     chromatic character of colors to compensate for the
     chromatic differences between the source and destina­
     tion white points.  This procedure simply converts the
     color specifications to _X_c_m_s_T_e_k_H_V_C using the source
     white point and then converts to the target specifica­
     tion format using the destination’s white point.  An
     advantage of this procedure over those previously
     described is an attempt to minimize hue shift.  No
     client data is necessary.

From an implementation point of view, these white point
adjustment procedures convert the color specifications to a
device‐independent but white‐point‐dependent color space
(for example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one
white point and then converting those specifications to the
target color space using another white point.  In other
words, the specification goes in the color space with one
white point but comes out with another white point, result­
ing in a chromatic shift based on the chromatic displacement
between the initial white point and target white point.  The
CIE color spaces that are assumed to be white‐point‐indepen­
dent are CIE u’v’Y, CIE XYZ, and CIE xyY.  When developing a
custom white point adjustment procedure that uses a device‐
independent color space not initially accessible for use in
the color management system, use _X_c_m_s_A_d_d_C_o_l_o_r_S_p_a_c_e to ensure
that it is added.

As an example, if the CCC specifies a white point adjustment
procedure and if the Client White Point and Screen White
Point differ, the _X_c_m_s_A_l_l_o_c_C_o_l_o_r function will use the white
point adjustment procedure twice:

⋅    Once to convert to _X_c_m_s_R_G_B

⋅    A second time to convert from _X_c_m_s_R_G_B





                             115588





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


For example, assume the specification is in _X_c_m_s_C_I_E_u_v_Y and
the adjustment procedure is _X_c_m_s_C_I_E_L_u_v_W_h_i_t_e_S_h_i_f_t_C_o_l_o_r_s.
During conversion to _X_c_m_s_R_G_B, the call to _X_c_m_s_A_l_l_o_c_C_o_l_o_r
results in the following series of color specification con­
versions:

⋅    From _X_c_m_s_C_I_E_u_v_Y to _X_c_m_s_C_I_E_L_u_v using the Client White
     Point

⋅    From _X_c_m_s_C_I_E_L_u_v to _X_c_m_s_C_I_E_u_v_Y using the Screen White
     Point

⋅    From _X_c_m_s_C_I_E_u_v_Y to _X_c_m_s_C_I_E_X_Y_Z (CIE u’v’Y and XYZ are
     white‐point‐independent color spaces)

⋅    From _X_c_m_s_C_I_E_X_Y_Z to _X_c_m_s_R_G_B_i

⋅    From _X_c_m_s_R_G_B_i to _X_c_m_s_R_G_B

The resulting RGB specification is passed to _X_A_l_l_o_c_C_o_l_o_r,
and the RGB specification returned by _X_A_l_l_o_c_C_o_l_o_r is con­
verted back to _X_c_m_s_C_I_E_u_v_Y by reversing the color conversion
sequence.

66..1111..  GGaammuutt QQuueerryyiinngg FFuunnccttiioonnss

This section describes the gamut querying functions that
Xlib provides.  These functions allow the client to query
the boundary of the screen’s color gamut in terms of the CIE
L*a*b*, CIE L*u*v*, and TekHVC color spaces.  Functions are
also provided that allow you to query the color specifica­
tion of:

⋅    White (full‐intensity red, green, and blue)

⋅    Red (full‐intensity red while green and blue are zero)

⋅    Green (full‐intensity green while red and blue are
     zero)

⋅    Blue (full‐intensity blue while red and green are zero)

⋅    Black (zero‐intensity red, green, and blue)

The white point associated with color specifications passed
to and returned from these gamut querying functions is
assumed to be the Screen White Point.  This is a reasonable
assumption, because the client is trying to query the
screen’s color gamut.

The following naming convention is used for the Max and Min
functions:





                             115599





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Xcms_<_c_o_l_o_r___s_p_a_c_e_>QueryMax_<_d_i_m_e_n_s_i_o_n_s_>

Xcms_<_c_o_l_o_r___s_p_a_c_e_>QueryMin_<_d_i_m_e_n_s_i_o_n_s_>


The <dimensions> consists of a letter or letters that iden­
tify the dimensions of the color space that are not fixed.
For example, _X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_C is given a fixed Hue and
Value for which maximum Chroma is found.

66..1111..11..  RReedd,, GGrreeeenn,, aanndd BBlluuee QQuueerriieess

To obtain the color specification for black (zero‐intensity
red, green, and blue), use _X_c_m_s_Q_u_e_r_y_B_l_a_c_k.
__
││
Status XcmsQueryBlack(_c_c_c, _t_a_r_g_e_t___f_o_r_m_a_t, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsColorFormat _t_a_r_g_e_t___f_o_r_m_a_t;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_t_a_r_g_e_t___f_o_r_m_a_t
          Specifies the target color specification format.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the color specification in the specified
          target format for zero‐intensity red, green, and
          blue.  The white point associated with the
          returned color specification is the Screen White
          Point.  The value returned in the pixel member is
          undefined.
││__

The _X_c_m_s_Q_u_e_r_y_B_l_a_c_k function returns the color specification
in the specified target format for zero‐intensity red,
green, and blue.


To obtain the color specification for blue (full‐intensity
blue while red and green are zero), use _X_c_m_s_Q_u_e_r_y_B_l_u_e.













                             116600





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsQueryBlue(_c_c_c, _t_a_r_g_e_t___f_o_r_m_a_t, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsColorFormat _t_a_r_g_e_t___f_o_r_m_a_t;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_t_a_r_g_e_t___f_o_r_m_a_t
          Specifies the target color specification format.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the color specification in the specified
          target format for full‐intensity blue while red
          and green are zero.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_Q_u_e_r_y_B_l_u_e function returns the color specification
in the specified target format for full‐intensity blue while
red and green are zero.


To obtain the color specification for green (full‐intensity
green while red and blue are zero), use _X_c_m_s_Q_u_e_r_y_G_r_e_e_n.
__
││
Status XcmsQueryGreen(_c_c_c, _t_a_r_g_e_t___f_o_r_m_a_t, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsColorFormat _t_a_r_g_e_t___f_o_r_m_a_t;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_t_a_r_g_e_t___f_o_r_m_a_t
          Specifies the target color specification format.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the color specification in the specified
          target format for full‐intensity green while red
          and blue are zero.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_Q_u_e_r_y_G_r_e_e_n function returns the color specification
in the specified target format for full‐intensity green



                             116611





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


while red and blue are zero.


To obtain the color specification for red (full‐intensity
red while green and blue are zero), use _X_c_m_s_Q_u_e_r_y_R_e_d.
__
││
Status XcmsQueryRed(_c_c_c, _t_a_r_g_e_t___f_o_r_m_a_t, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsColorFormat _t_a_r_g_e_t___f_o_r_m_a_t;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_t_a_r_g_e_t___f_o_r_m_a_t
          Specifies the target color specification format.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the color specification in the specified
          target format for full‐intensity red while green
          and blue are zero.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_Q_u_e_r_y_R_e_d function returns the color specification in
the specified target format for full‐intensity red while
green and blue are zero.


To obtain the color specification for white (full‐intensity
red, green, and blue), use _X_c_m_s_Q_u_e_r_y_W_h_i_t_e.






















                             116622





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsQueryWhite(_c_c_c, _t_a_r_g_e_t___f_o_r_m_a_t, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsColorFormat _t_a_r_g_e_t___f_o_r_m_a_t;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_t_a_r_g_e_t___f_o_r_m_a_t
          Specifies the target color specification format.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the color specification in the specified
          target format for full‐intensity red, green, and
          blue.  The white point associated with the
          returned color specification is the Screen White
          Point.  The value returned in the pixel member is
          undefined.
││__

The _X_c_m_s_Q_u_e_r_y_W_h_i_t_e function returns the color specification
in the specified target format for full‐intensity red,
green, and blue.

66..1111..22..  CCIIEELLaabb QQuueerriieess

The following equations are useful in describing the CIELab
query functions:


_C_I_E_L_a_b_P_s_y_c_h_o_m_e_t_r_i_c_C_h_r_o_m_a=_s_q_r_t(_a__s_t_a_r2+_b__s_t_a_r2)

_C_I_E_L_a_b_P_s_y_c_h_o_m_e_t_r_i_c_H_u_e=tan−1[_b_a_______s_s___t_t___a_a___r_r__]


To obtain the CIE L*a*b* coordinates of maximum Psychometric
Chroma for a given Psychometric Hue Angle and CIE metric
lightness (L*), use _X_c_m_s_C_I_E_L_a_b_Q_u_e_r_y_M_a_x_C.

















                             116633





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsCIELabQueryMaxC(_c_c_c, _h_u_e___a_n_g_l_e, _L___s_t_a_r, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e___a_n_g_l_e;
      XcmsFloat _L___s_t_a_r;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e___a_n_g_l_e Specifies the hue angle (in degrees) at which to
          find maximum chroma.

_L___s_t_a_r    Specifies the lightness (L*) at which to find max­
          imum chroma.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the CIE L*a*b* coordinates of maximum
          chroma displayable by the screen for the given hue
          angle and lightness.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_C_I_E_L_a_b_Q_u_e_r_y_M_a_x_C function, given a hue angle and
lightness, finds the point of maximum chroma displayable by
the screen.  It returns this point in CIE L*a*b* coordi­
nates.


To obtain the CIE L*a*b* coordinates of maximum CIE metric
lightness (L*) for a given Psychometric Hue Angle and Psy­
chometric Chroma, use _X_c_m_s_C_I_E_L_a_b_Q_u_e_r_y_M_a_x_L.






















                             116644





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsCIELabQueryMaxL(_c_c_c, _h_u_e___a_n_g_l_e, _c_h_r_o_m_a, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e___a_n_g_l_e;
      XcmsFloat _c_h_r_o_m_a;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e___a_n_g_l_e Specifies the hue angle (in degrees) at which to
          find maximum lightness.

_c_h_r_o_m_a    Specifies the chroma at which to find maximum
          lightness.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the CIE L*a*b* coordinates of maximum
          lightness displayable by the screen for the given
          hue angle and chroma.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_C_I_E_L_a_b_Q_u_e_r_y_M_a_x_L function, given a hue angle and
chroma, finds the point in CIE L*a*b* color space of maximum
lightness (L*) displayable by the screen.  It returns this
point in CIE L*a*b* coordinates.  An _X_c_m_s_F_a_i_l_u_r_e return
value usually indicates that the given chroma is beyond max­
imum for the given hue angle.


To obtain the CIE L*a*b* coordinates of maximum Psychometric
Chroma for a given Psychometric Hue Angle, use _X_c_m_s_C_I_E_L_a_b_­
_Q_u_e_r_y_M_a_x_L_C.




















                             116655





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsCIELabQueryMaxLC(_c_c_c, _h_u_e___a_n_g_l_e, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e___a_n_g_l_e;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e___a_n_g_l_e Specifies the hue angle (in degrees) at which to
          find maximum chroma.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the CIE L*a*b* coordinates of maximum
          chroma displayable by the screen for the given hue
          angle.  The white point associated with the
          returned color specification is the Screen White
          Point.  The value returned in the pixel member is
          undefined.
││__

The _X_c_m_s_C_I_E_L_a_b_Q_u_e_r_y_M_a_x_L_C function, given a hue angle, finds
the point of maximum chroma displayable by the screen.  It
returns this point in CIE L*a*b* coordinates.


To obtain the CIE L*a*b* coordinates of minimum CIE metric
lightness (L*) for a given Psychometric Hue Angle and Psy­
chometric Chroma, use _X_c_m_s_C_I_E_L_a_b_Q_u_e_r_y_M_i_n_L.



























                             116666





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsCIELabQueryMinL(_c_c_c, _h_u_e___a_n_g_l_e, _c_h_r_o_m_a, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e___a_n_g_l_e;
      XcmsFloat _c_h_r_o_m_a;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e___a_n_g_l_e Specifies the hue angle (in degrees) at which to
          find minimum lightness.

_c_h_r_o_m_a    Specifies the chroma at which to find minimum
          lightness.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the CIE L*a*b* coordinates of minimum
          lightness displayable by the screen for the given
          hue angle and chroma.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_C_I_E_L_a_b_Q_u_e_r_y_M_i_n_L function, given a hue angle and
chroma, finds the point of minimum lightness (L*) dis­
playable by the screen.  It returns this point in CIE L*a*b*
coordinates.  An _X_c_m_s_F_a_i_l_u_r_e return value usually indicates
that the given chroma is beyond maximum for the given hue
angle.

66..1111..33..  CCIIEELLuuvv QQuueerriieess

The following equations are useful in describing the CIELuv
query functions:


_C_I_E_L_u_v_P_s_y_c_h_o_m_e_t_r_i_c_C_h_r_o_m_a=_s_q_r_t(_u__s_t_a_r2+_v__s_t_a_r2)

_C_I_E_L_u_v_P_s_y_c_h_o_m_e_t_r_i_c_H_u_e=tan−1[_v_u_______s_s___t_t___a_a___r_r__]



To obtain the CIE L*u*v* coordinates of maximum Psychometric
Chroma for a given Psychometric Hue Angle and CIE metric
lightness (L*), use _X_c_m_s_C_I_E_L_u_v_Q_u_e_r_y_M_a_x_C.









                             116677





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsCIELuvQueryMaxC(_c_c_c, _h_u_e___a_n_g_l_e, _L___s_t_a_r, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e___a_n_g_l_e;
      XcmsFloat _L___s_t_a_r;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e___a_n_g_l_e Specifies the hue angle (in degrees) at which to
          find maximum chroma.

_L___s_t_a_r    Specifies the lightness (L*) at which to find max­
          imum chroma.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the CIE L*u*v* coordinates of maximum
          chroma displayable by the screen for the given hue
          angle and lightness.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_C_I_E_L_u_v_Q_u_e_r_y_M_a_x_C function, given a hue angle and
lightness, finds the point of maximum chroma displayable by
the screen.  It returns this point in CIE L*u*v* coordi­
nates.


To obtain the CIE L*u*v* coordinates of maximum CIE metric
lightness (L*) for a given Psychometric Hue Angle and Psy­
chometric Chroma, use _X_c_m_s_C_I_E_L_u_v_Q_u_e_r_y_M_a_x_L.






















                             116688





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsCIELuvQueryMaxL(_c_c_c, _h_u_e___a_n_g_l_e, _c_h_r_o_m_a, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e___a_n_g_l_e;
      XcmsFloat _c_h_r_o_m_a;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e___a_n_g_l_e Specifies the hue angle (in degrees) at which to
          find maximum lightness.

_L___s_t_a_r    Specifies the lightness (L*) at which to find max­
          imum lightness.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the CIE L*u*v* coordinates of maximum
          lightness displayable by the screen for the given
          hue angle and chroma.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_C_I_E_L_u_v_Q_u_e_r_y_M_a_x_L function, given a hue angle and
chroma, finds the point in CIE L*u*v* color space of maximum
lightness (L*) displayable by the screen.  It returns this
point in CIE L*u*v* coordinates.  An _X_c_m_s_F_a_i_l_u_r_e return
value usually indicates that the given chroma is beyond max­
imum for the given hue angle.


To obtain the CIE L*u*v* coordinates of maximum Psychometric
Chroma for a given Psychometric Hue Angle, use _X_c_m_s_C_I_E_L_u_v_­
_Q_u_e_r_y_M_a_x_L_C.




















                             116699





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsCIELuvQueryMaxLC(_c_c_c, _h_u_e___a_n_g_l_e, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e___a_n_g_l_e;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e___a_n_g_l_e Specifies the hue angle (in degrees) at which to
          find maximum chroma.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the CIE L*u*v* coordinates of maximum
          chroma displayable by the screen for the given hue
          angle.  The white point associated with the
          returned color specification is the Screen White
          Point.  The value returned in the pixel member is
          undefined.
││__

The _X_c_m_s_C_I_E_L_u_v_Q_u_e_r_y_M_a_x_L_C function, given a hue angle, finds
the point of maximum chroma displayable by the screen.  It
returns this point in CIE L*u*v* coordinates.


To obtain the CIE L*u*v* coordinates of minimum CIE metric
lightness (L*) for a given Psychometric Hue Angle and Psy­
chometric Chroma, use _X_c_m_s_C_I_E_L_u_v_Q_u_e_r_y_M_i_n_L.



























                             117700





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsCIELuvQueryMinL(_c_c_c, _h_u_e___a_n_g_l_e, _c_h_r_o_m_a, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e___a_n_g_l_e;
      XcmsFloat _c_h_r_o_m_a;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e___a_n_g_l_e Specifies the hue angle (in degrees) at which to
          find minimum lightness.

_c_h_r_o_m_a    Specifies the chroma at which to find minimum
          lightness.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the CIE L*u*v* coordinates of minimum
          lightness displayable by the screen for the given
          hue angle and chroma.  The white point associated
          with the returned color specification is the
          Screen White Point.  The value returned in the
          pixel member is undefined.
││__

The _X_c_m_s_C_I_E_L_u_v_Q_u_e_r_y_M_i_n_L function, given a hue angle and
chroma, finds the point of minimum lightness (L*) dis­
playable by the screen.  It returns this point in CIE L*u*v*
coordinates.  An _X_c_m_s_F_a_i_l_u_r_e return value usually indicates
that the given chroma is beyond maximum for the given hue
angle.

66..1111..44..  TTeekkHHVVCC QQuueerriieess

To obtain the maximum Chroma for a given Hue and Value, use
_X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_C.




















                             117711





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsTekHVCQueryMaxC(_c_c_c, _h_u_e, _v_a_l_u_e, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e;
      XcmsFloat _v_a_l_u_e;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e       Specifies the Hue in which to find the maximum
          Chroma.

_v_a_l_u_e     Specifies the Value in which to find the maximum
          Chroma.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the maximum Chroma along with the actual
          Hue and Value  at which the maximum Chroma was
          found.  The white point associated with the
          returned color specification is the Screen White
          Point.  The value returned in the pixel member is
          undefined.
││__

The _X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_C function, given a Hue and Value,
determines the maximum Chroma in TekHVC color space dis­
playable by the screen.  It returns the maximum Chroma along
with the actual Hue and Value at which the maximum Chroma
was found.


To obtain the maximum Value for a given Hue and Chroma, use
_X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_V.






















                             117722





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsTekHVCQueryMaxV(_c_c_c, _h_u_e, _c_h_r_o_m_a, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e;
      XcmsFloat _c_h_r_o_m_a;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e       Specifies the Hue in which to find the maximum
          Value.

_c_h_r_o_m_a    Specifies the chroma at which to find maximum
          Value.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the maximum Value along with the Hue and
          Chroma at which the maximum Value was found.  The
          white point associated with the returned color
          specification is the Screen White Point.  The
          value returned in the pixel member is undefined.
││__

The _X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_V function, given a Hue and Chroma,
determines the maximum Value in TekHVC color space dis­
playable by the screen.  It returns the maximum Value and
the actual Hue and Chroma at which the maximum Value was
found.


To obtain the maximum Chroma and Value at which it is
reached for a specified Hue, use _X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_V_C.























                             117733





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsTekHVCQueryMaxVC(_c_c_c, _h_u_e, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e       Specifies the Hue in which to find the maximum
          Chroma.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the color specification in XcmsTekHVC for
          the maximum Chroma, the Value at which that maxi­
          mum Chroma is reached, and the actual Hue at which
          the maximum Chroma was found.  The white point
          associated with the returned color specification
          is the Screen White Point.  The value returned in
          the pixel member is undefined.
││__

The _X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_V_C function, given a Hue, determines
the maximum Chroma in TekHVC color space displayable by the
screen and the Value at which that maximum Chroma is
reached.  It returns the maximum Chroma, the Value at which
that maximum Chroma is reached, and the actual Hue for which
the maximum Chroma was found.


To obtain a specified number of TekHVC specifications such
that they contain maximum Values for a specified Hue and the
Chroma at which the maximum Values are reached, use _X_c_m_­
_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_V_S_a_m_p_l_e_s.






















                             117744





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsTekHVCQueryMaxVSamples(_c_c_c, _h_u_e, _c_o_l_o_r_s___r_e_t_u_r_n, _n_s_a_m_p_l_e_s)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e;
      XcmsColor _c_o_l_o_r_s___r_e_t_u_r_n_[_];
      unsigned int _n_s_a_m_p_l_e_s;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e       Specifies the Hue for maximum Chroma/Value sam­
          ples.

_n_s_a_m_p_l_e_s  Specifies the number of samples.

_c_o_l_o_r_s___r_e_t_u_r_n
          Returns nsamples of color specifications in Xcm­
          sTekHVC such that the Chroma is the maximum
          attainable for the Value and Hue.  The white point
          associated with the returned color specification
          is the Screen White Point.  The value returned in
          the pixel member is undefined.
││__

The _X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_a_x_V_S_a_m_p_l_e_s returns nsamples of maximum
Value, the Chroma at which that maximum Value is reached,
and the actual Hue for which the maximum Chroma was found.
These sample points may then be used to plot the maximum
Value/Chroma boundary of the screen’s color gamut for the
specified Hue in TekHVC color space.


To obtain the minimum Value for a given Hue and Chroma, use
_X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_i_n_V.






















                             117755





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XcmsTekHVCQueryMinV(_c_c_c, _h_u_e, _c_h_r_o_m_a, _c_o_l_o_r___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsFloat _h_u_e;
      XcmsFloat _c_h_r_o_m_a;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_c_c       Specifies the CCC.  The CCC’s Client White Point
          and white point adjustment procedures are ignored.

_h_u_e       Specifies the Hue in which to find the minimum
          Value.

_v_a_l_u_e     Specifies the Value in which to find the minimum
          Value.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the minimum Value and the actual Hue and
          Chroma at which the minimum Value was found.  The
          white point associated with the returned color
          specification is the Screen White Point.  The
          value returned in the pixel member is undefined.
││__

The _X_c_m_s_T_e_k_H_V_C_Q_u_e_r_y_M_i_n_V function, given a Hue and Chroma,
determines the minimum Value in TekHVC color space dis­
playable by the screen.  It returns the minimum Value and
the actual Hue and Chroma at which the minimum Value was
found.

66..1122..  CCoolloorr MMaannaaggeemmeenntt EExxtteennssiioonnss

The Xlib color management facilities can be extended in two
ways:

⋅    Device‐Independent Color Spaces

     Device‐independent color spaces that are derivable to
     CIE XYZ space can be added using the _X_c_m_s_A_d_d_C_o_l_o_r_S_p_a_c_e
     function.

⋅    Color Characterization Function Set

     A Color Characterization Function Set consists of
     device‐dependent color spaces and their functions that
     convert between these color spaces and the CIE XYZ
     color space, bundled together for a specific class of
     output devices.  A function set can be added using the
     _X_c_m_s_A_d_d_F_u_n_c_t_i_o_n_S_e_t function.







                             117766





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


66..1122..11..  CCoolloorr SSppaacceess

The CIE XYZ color space serves as the hub for all conver­
sions between device‐independent and device‐dependent color
spaces.  Therefore, the knowledge to convert an _X_c_m_s_C_o_l_o_r
structure to and from CIE XYZ format is associated with each
color space.  For example, conversion from CIE L*u*v* to RGB
requires the knowledge to convert from CIE L*u*v* to CIE XYZ
and from CIE XYZ to RGB.  This knowledge is stored as an
array of functions that, when applied in series, will con­
vert the _X_c_m_s_C_o_l_o_r structure to or from CIE XYZ format.
This color specification conversion mechanism facilitates
the addition of color spaces.

Of course, when converting between only device‐independent
color spaces or only device‐dependent color spaces, short­
cuts are taken whenever possible.  For example, conversion
from TekHVC to CIE L*u*v* is performed by intermediate con­
version to CIE u*v*Y and then to CIE L*u*v*, thus bypassing
conversion between CIE u*v*Y and CIE XYZ.

66..1122..22..  AAddddiinngg DDeevviiccee‐‐IInnddeeppeennddeenntt CCoolloorr SSppaacceess

To add a device‐independent color space, use _X_c_m_s_A_d_d_C_o_l_­
_o_r_S_p_a_c_e.
__
││
Status XcmsAddColorSpace(_c_o_l_o_r___s_p_a_c_e)
      XcmsColorSpace *_c_o_l_o_r___s_p_a_c_e;


_c_o_l_o_r___s_p_a_c_e
          Specifies the device‐independent color space to
          add.
││__

The _X_c_m_s_A_d_d_C_o_l_o_r_S_p_a_c_e function makes a device‐independent
color space (actually an _X_c_m_s_C_o_l_o_r_S_p_a_c_e structure) accessi­
ble by the color management system.  Because format values
for unregistered color spaces are assigned at run time, they
should be treated as private to the client.  If references
to an unregistered color space must be made outside the
client (for example, storing color specifications in a file
using the unregistered color space), then reference should
be made by color space prefix (see _X_c_m_s_F_o_r_m_a_t_O_f_P_r_e_f_i_x and
_X_c_m_s_P_r_e_f_i_x_O_f_F_o_r_m_a_t).

If the _X_c_m_s_C_o_l_o_r_S_p_a_c_e structure is already accessible in the
color management system, _X_c_m_s_A_d_d_C_o_l_o_r_S_p_a_c_e returns _X_c_m_s_S_u_c_­
_c_e_s_s.

Note that added _X_c_m_s_C_o_l_o_r_S_p_a_c_e_s must be retained for refer­
ence by Xlib.




                             117777





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


66..1122..33..  QQuueerryyiinngg CCoolloorr SSppaaccee FFoorrmmaatt aanndd PPrreeffiixx

To obtain the format associated with the color space associ­
ated with a specified color string prefix, use _X_c_m_s_F_o_r_m_a_t_O_f_­
_P_r_e_f_i_x.
__
││
XcmsColorFormat XcmsFormatOfPrefix(_p_r_e_f_i_x)
      char *_p_r_e_f_i_x;


_p_r_e_f_i_x    Specifies the string that contains the color space
          prefix.
││__

The _X_c_m_s_F_o_r_m_a_t_O_f_P_r_e_f_i_x function returns the format for the
specified color space prefix (for example, the string
‘‘CIEXYZ’’).  The prefix is case‐insensitive.  If the color
space is not accessible in the color management system,
_X_c_m_s_F_o_r_m_a_t_O_f_P_r_e_f_i_x returns _X_c_m_s_U_n_d_e_f_i_n_e_d_F_o_r_m_a_t.


To obtain the color string prefix associated with the color
space specified by a color format, use _X_c_m_s_P_r_e_f_i_x_O_f_F_o_r_m_a_t.
__
││
char *XcmsPrefixOfFormat(_f_o_r_m_a_t)
      XcmsColorFormat _f_o_r_m_a_t;


_f_o_r_m_a_t    Specifies the color specification format.
││__

The _X_c_m_s_P_r_e_f_i_x_O_f_F_o_r_m_a_t function returns the string prefix
associated with the color specification encoding specified
by the format argument.  Otherwise, if no encoding is found,
it returns NULL.  The returned string must be treated as
read‐only.

66..1122..44..  CCrreeaattiinngg AAddddiittiioonnaall CCoolloorr SSppaacceess

Color space specific information necessary for color space
conversion and color string parsing is stored in an _X_c_m_s_C_o_l_­
_o_r_S_p_a_c_e structure.  Therefore, a new structure containing
this information is required for each additional color
space.  In the case of device‐independent color spaces, a
handle to this new structure (that is, by means of a global
variable) is usually made accessible to the client program
for use with the _X_c_m_s_A_d_d_C_o_l_o_r_S_p_a_c_e function.

If a new _X_c_m_s_C_o_l_o_r_S_p_a_c_e structure specifies a color space
not registered with the X Consortium, they should be treated
as private to the client because format values for unregis­
tered color spaces are assigned at run time.  If references



                             117788





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


to an unregistered color space must be made outside the
client (for example, storing color specifications in a file
using the unregistered color space), then reference should
be made by color space prefix (see _X_c_m_s_F_o_r_m_a_t_O_f_P_r_e_f_i_x and
_X_c_m_s_P_r_e_f_i_x_O_f_F_o_r_m_a_t).
__
││

typedef (*XcmsConversionProc)();
typedef XcmsConversionProc *XcmsFuncListPtr;
                         /* A NULL terminated list of function pointers*/

typedef struct _XcmsColorSpace {
     char *prefix;
     XcmsColorFormat format;
     XcmsParseStringProc parseString;
     XcmsFuncListPtr to_CIEXYZ;
     XcmsFuncListPtr from_CIEXYZ;
     int inverse_flag;
} XcmsColorSpace;

││__

The prefix member specifies the prefix that indicates a
color string is in this color space’s string format.  For
example, the strings ‘‘ciexyz’’ or ‘‘CIEXYZ’’ for CIE XYZ,
and ‘‘rgb’’ or ‘‘RGB’’ for RGB.  The prefix is case insensi­
tive.  The format member specifies the color specification
format.  Formats for unregistered color spaces are assigned
at run time.  The parseString member contains a pointer to
the function that can parse a color string into an _X_c_m_s_C_o_l_o_r
structure.  This function returns an integer (int): nonzero
if it succeeded and zero otherwise.  The to_CIEXYZ and
from_CIEXYZ members contain pointers, each to a NULL termi­
nated list of function pointers.  When the list of functions
is executed in series, it will convert the color specified
in an _X_c_m_s_C_o_l_o_r structure from/to the current color space
format to/from the CIE XYZ format.  Each function returns an
integer (int): nonzero if it succeeded and zero otherwise.
The white point to be associated with the colors is speci­
fied explicitly, even though white points can be found in
the CCC.  The inverse_flag member, if nonzero, specifies
that for each function listed in to_CIEXYZ, its inverse
function can be found in from_CIEXYZ such that:


Given:  n = number of functions in each list

for each i, such that 0 <= i < n
    from_CIEXYZ[n ‐ i ‐ 1] is the inverse of to_CIEXYZ[i].


This allows Xlib to use the shortest conversion path, thus
bypassing CIE XYZ if possible (for example, TekHVC to CIE



                             117799





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


L*u*v*).

66..1122..55..  PPaarrssee SSttrriinngg CCaallllbbaacckk

The callback in the _X_c_m_s_C_o_l_o_r_S_p_a_c_e structure for parsing a
color string for the particular color space must adhere to
the following software interface specification:
__
││
typedef int (*XcmsParseStringProc)(_c_o_l_o_r___s_t_r_i_n_g, _c_o_l_o_r___r_e_t_u_r_n)
      char *_c_o_l_o_r___s_t_r_i_n_g;
      XcmsColor *_c_o_l_o_r___r_e_t_u_r_n;


_c_o_l_o_r___s_t_r_i_n_g
          Specifies the color string to parse.

_c_o_l_o_r___r_e_t_u_r_n
          Returns the color specification in the color
          space’s format.
││__


66..1122..66..  CCoolloorr SSppeecciiffiiccaattiioonn CCoonnvveerrssiioonn CCaallllbbaacckk

Callback functions in the _X_c_m_s_C_o_l_o_r_S_p_a_c_e structure for con­
verting a color specification between device‐independent
spaces must adhere to the following software interface spec­
ification:




























                             118800





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status ConversionProc(_c_c_c, _w_h_i_t_e___p_o_i_n_t, _c_o_l_o_r_s___i_n___o_u_t, _n_c_o_l_o_r_s)
      XcmsCCC _c_c_c;
      XcmsColor *_w_h_i_t_e___p_o_i_n_t;
      XcmsColor *_c_o_l_o_r_s___i_n___o_u_t;
      unsigned int _n_c_o_l_o_r_s;


_c_c_c       Specifies the CCC.

_w_h_i_t_e___p_o_i_n_t
          Specifies the white point associated with color
          specifications.  The pixel member should be
          ignored, and the entire structure remain unchanged
          upon return.

_c_o_l_o_r_s___i_n___o_u_t
          Specifies an array of color specifications.  Pixel
          members should be ignored and must remain
          unchanged upon return.

_n_c_o_l_o_r_s   Specifies the number of _X_c_m_s_C_o_l_o_r structures in
          the color‐specification array.
││__


Callback functions in the _X_c_m_s_C_o_l_o_r_S_p_a_c_e structure for con­
verting a color specification to or from a device‐dependent
space must adhere to the following software interface speci­
fication:



























                             118811





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status ConversionProc(_c_c_c, _c_o_l_o_r_s___i_n___o_u_t, _n_c_o_l_o_r_s, _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n)
      XcmsCCC _c_c_c;
      XcmsColor *_c_o_l_o_r_s___i_n___o_u_t;
      unsigned int _n_c_o_l_o_r_s;
      Bool _c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n[];


_c_c_c       Specifies the CCC.

_c_o_l_o_r_s___i_n___o_u_t
          Specifies an array of color specifications.  Pixel
          members should be ignored and must remain
          unchanged upon return.

_n_c_o_l_o_r_s   Specifies the number of _X_c_m_s_C_o_l_o_r structures in
          the color‐specification array.

_c_o_m_p_r_e_s_s_i_o_n___f_l_a_g_s___r_e_t_u_r_n
          Returns an array of Boolean values for indicating
          compression status.  If a non‐NULL pointer is sup­
          plied and a color at a given index is compressed,
          then _T_r_u_e should be stored at the corresponding
          index in this array; otherwise, the array should
          not be modified.
││__

Conversion functions are available globally for use by other
color spaces.  The conversion functions provided by Xlib
are:

-------------------------------------------------------------
FFuunnccttiioonn             CCoonnvveerrttss ffrroomm        CCoonnvveerrttss ttoo
-------------------------------------------------------------
_X_c_m_s_C_I_E_L_a_b_T_o_C_I_E_X_Y_Z   _X_c_m_s_C_I_E_L_a_b_F_o_r_m_a_t     _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t
_X_c_m_s_C_I_E_L_u_v_T_o_C_I_E_u_v_Y   _X_c_m_s_C_I_E_L_u_v_F_o_r_m_a_t     _X_c_m_s_C_I_E_u_v_Y_F_o_r_m_a_t
_X_c_m_s_C_I_E_X_Y_Z_T_o_C_I_E_L_a_b   _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t     _X_c_m_s_C_I_E_L_a_b_F_o_r_m_a_t
_X_c_m_s_C_I_E_X_Y_Z_T_o_C_I_E_u_v_Y   _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t     _X_c_m_s_C_I_E_u_v_Y_F_o_r_m_a_t
_X_c_m_s_C_I_E_X_Y_Z_T_o_C_I_E_x_y_Y   _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t     _X_c_m_s_C_I_E_x_y_Y_F_o_r_m_a_t
_X_c_m_s_C_I_E_X_Y_Z_T_o_R_G_B_i     _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t     _X_c_m_s_R_G_B_i_F_o_r_m_a_t
_X_c_m_s_C_I_E_u_v_Y_T_o_C_I_E_L_u_v   _X_c_m_s_C_I_E_u_v_Y_F_o_r_m_a_t     _X_c_m_s_C_I_E_L_a_b_F_o_r_m_a_t
_X_c_m_s_C_I_E_u_v_Y_T_o_C_I_E_X_Y_Z   _X_c_m_s_C_I_E_u_v_Y_F_o_r_m_a_t     _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t
_X_c_m_s_C_I_E_u_v_Y_T_o_T_e_k_H_V_C   _X_c_m_s_C_I_E_u_v_Y_F_o_r_m_a_t     _X_c_m_s_T_e_k_H_V_C_F_o_r_m_a_t
_X_c_m_s_C_I_E_x_y_Y_T_o_C_I_E_X_Y_Z   _X_c_m_s_C_I_E_x_y_Y_F_o_r_m_a_t     _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t
_X_c_m_s_R_G_B_T_o_R_G_B_i        _X_c_m_s_R_G_B_F_o_r_m_a_t        _X_c_m_s_R_G_B_i_F_o_r_m_a_t
_X_c_m_s_R_G_B_i_T_o_C_I_E_X_Y_Z     _X_c_m_s_R_G_B_i_F_o_r_m_a_t       _X_c_m_s_C_I_E_X_Y_Z_F_o_r_m_a_t
_X_c_m_s_R_G_B_i_T_o_R_G_B        _X_c_m_s_R_G_B_i_F_o_r_m_a_t       _X_c_m_s_R_G_B_F_o_r_m_a_t
_X_c_m_s_T_e_k_H_V_C_T_o_C_I_E_u_v_Y   _X_c_m_s_T_e_k_H_V_C_F_o_r_m_a_t     _X_c_m_s_C_I_E_u_v_Y_F_o_r_m_a_t
-------------------------------------------------------------








                             118822





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


66..1122..77..  FFuunnccttiioonn SSeettss

Functions to convert between device‐dependent color spaces
and CIE XYZ may differ for different classes of output
devices (for example, color versus gray monitors).  There­
fore, the notion of a Color Characterization Function Set
has been developed.  A function set consists of device‐
dependent color spaces and the functions that convert color
specifications between these device‐dependent color spaces
and the CIE XYZ color space appropriate for a particular
class of output devices.  The function set also contains a
function that reads color characterization data off root
window properties.  It is this characterization data that
will differ between devices within a class of output
devices.  For details about how color characterization data
is stored in root window properties, see the section on
Device Color Characterization in the _I_n_t_e_r_‐_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_­
_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l.  The LINEAR_RGB function set is
provided by Xlib and will support most color monitors.
Function sets may require data that differs from those
needed for the LINEAR_RGB function set.  In that case, its
corresponding data may be stored on different root window
properties.

66..1122..88..  AAddddiinngg FFuunnccttiioonn SSeettss

To add a function set, use _X_c_m_s_A_d_d_F_u_n_c_t_i_o_n_S_e_t.
__
││
Status XcmsAddFunctionSet(_f_u_n_c_t_i_o_n___s_e_t)
      XcmsFunctionSet *_f_u_n_c_t_i_o_n___s_e_t;


_f_u_n_c_t_i_o_n___s_e_t
          Specifies the function set to add.
││__

The _X_c_m_s_A_d_d_F_u_n_c_t_i_o_n_S_e_t function adds a function set to the
color management system.  If the function set uses device‐
dependent _X_c_m_s_C_o_l_o_r_S_p_a_c_e structures not accessible in the
color management system, _X_c_m_s_A_d_d_F_u_n_c_t_i_o_n_S_e_t adds them.  If
an added _X_c_m_s_C_o_l_o_r_S_p_a_c_e structure is for a device‐dependent
color space not registered with the X Consortium, they
should be treated as private to the client because format
values for unregistered color spaces are assigned at run
time.  If references to an unregistered color space must be
made outside the client (for example, storing color specifi­
cations in a file using the unregistered color space), then
reference should be made by color space prefix (see _X_c_m_s_F_o_r_­
_m_a_t_O_f_P_r_e_f_i_x and _X_c_m_s_P_r_e_f_i_x_O_f_F_o_r_m_a_t).

Additional function sets should be added before any calls to
other Xlib routines are made.  If not, the _X_c_m_s_P_e_r_S_c_r_n_I_n_f_o
member of a previously created _X_c_m_s_C_C_C does not have the



                             118833





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


opportunity to initialize with the added function set.

66..1122..99..  CCrreeaattiinngg AAddddiittiioonnaall FFuunnccttiioonn SSeettss

The creation of additional function sets should be required
only when an output device does not conform to existing
function sets or when additional device‐dependent color
spaces are necessary.  A function set consists primarily of
a collection of device‐dependent _X_c_m_s_C_o_l_o_r_S_p_a_c_e structures
and a means to read and store a screen’s color characteriza­
tion data.  This data is stored in an _X_c_m_s_F_u_n_c_t_i_o_n_S_e_t struc­
ture.  A handle to this structure (that is, by means of
global variable) is usually made accessible to the client
program for use with _X_c_m_s_A_d_d_F_u_n_c_t_i_o_n_S_e_t.

If a function set uses new device‐dependent _X_c_m_s_C_o_l_o_r_S_p_a_c_e
structures, they will be transparently processed into the
color management system.  Function sets can share an _X_c_m_s_­
_C_o_l_o_r_S_p_a_c_e structure for a device‐dependent color space.  In
addition, multiple _X_c_m_s_C_o_l_o_r_S_p_a_c_e structures are allowed for
a device‐dependent color space; however, a function set can
reference only one of them.  These _X_c_m_s_C_o_l_o_r_S_p_a_c_e structures
will differ in the functions to convert to and from CIE XYZ,
thus tailored for the specific function set.
__
││

typedef struct _XcmsFunctionSet {
     XcmsColorSpace **DDColorSpaces;
     XcmsScreenInitProc screenInitProc;
     XcmsScreenFreeProc screenFreeProc;
} XcmsFunctionSet;

││__

The DDColorSpaces member is a pointer to a NULL terminated
list of pointers to _X_c_m_s_C_o_l_o_r_S_p_a_c_e structures for the
device‐dependent color spaces that are supported by the
function set.  The screenInitProc member is set to the call­
back procedure (see the following interface specification)
that initializes the _X_c_m_s_P_e_r_S_c_r_n_I_n_f_o structure for a partic­
ular screen.

The screen initialization callback must adhere to the fol­
lowing software interface specification:












                             118844





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef Status (*XcmsScreenInitProc)(_d_i_s_p_l_a_y, _s_c_r_e_e_n___n_u_m_b_e_r, _s_c_r_e_e_n___i_n_f_o)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n___n_u_m_b_e_r;
      XcmsPerScrnInfo *_s_c_r_e_e_n___i_n_f_o;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.

_s_c_r_e_e_n___i_n_f_o
          Specifies the _X_c_m_s_P_e_r_S_c_r_n_I_n_f_o structure, which
          contains the per screen information.
││__

The screen initialization callback in the _X_c_m_s_F_u_n_c_t_i_o_n_S_e_t
structure fetches the color characterization data (device
profile) for the specified screen, typically off properties
on the screen’s root window.  It then initializes the speci­
fied _X_c_m_s_P_e_r_S_c_r_n_I_n_f_o structure.  If successful, the proce­
dure fills in the _X_c_m_s_P_e_r_S_c_r_n_I_n_f_o structure as follows:

⋅    It sets the screenData member to the address of the
     created device profile data structure (contents known
     only by the function set).

⋅    It next sets the screenWhitePoint member.

⋅    It next sets the functionSet member to the address of
     the _X_c_m_s_F_u_n_c_t_i_o_n_S_e_t structure.

⋅    It then sets the state member to _X_c_m_s_I_n_i_t_S_u_c_c_e_s_s and
     finally returns _X_c_m_s_S_u_c_c_e_s_s.

If unsuccessful, the procedure sets the state member to _X_c_m_­
_s_I_n_i_t_F_a_i_l_u_r_e and returns _X_c_m_s_F_a_i_l_u_r_e.

The _X_c_m_s_P_e_r_S_c_r_n_I_n_f_o structure contains:
















                             118855





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││

typedef struct _XcmsPerScrnInfo {
     XcmsColor screenWhitePoint;
     XPointer functionSet;
     XPointer screenData;
     unsigned char state;
     char pad[3];
} XcmsPerScrnInfo;

││__

The screenWhitePoint member specifies the white point inher­
ent to the screen.  The functionSet member specifies the
appropriate function set.  The screenData member specifies
the device profile.  The state member is set to one of the
following:

⋅    _X_c_m_s_I_n_i_t_N_o_n_e indicates initialization has not been pre­
     viously attempted.

⋅    _X_c_m_s_I_n_i_t_F_a_i_l_u_r_e indicates initialization has been pre­
     viously attempted but failed.

⋅    _X_c_m_s_I_n_i_t_S_u_c_c_e_s_s indicates initialization has been pre­
     viously attempted and succeeded.

The screen free callback must adhere to the following soft­
ware interface specification:
__
││
typedef void (*XcmsScreenFreeProc)(_s_c_r_e_e_n_D_a_t_a)
      XPointer _s_c_r_e_e_n_D_a_t_a;


_s_c_r_e_e_n_D_a_t_a
          Specifies the data to be freed.
││__

This function is called to free the screenData stored in an
_X_c_m_s_P_e_r_S_c_r_n_I_n_f_o structure.
















                             118866





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 77

                 GGrraapphhiiccss CCoonntteexxtt FFuunnccttiioonnss



A number of resources are used when performing graphics
operations in X.  Most information about performing graphics
(for example, foreground color, background color, line
style, and so on) is stored in resources called graphics
contexts (GCs).  Most graphics operations (see chapter 8)
take a GC as an argument.  Although in theory the X protocol
permits sharing of GCs between applications, it is expected
that applications will use their own GCs when performing
operations.  Sharing of GCs is highly discouraged because
the library may cache GC state.

Graphics operations can be performed to either windows or
pixmaps, which collectively are called drawables.  Each
drawable exists on a single screen.  A GC is created for a
specific screen and drawable depth and can only be used with
drawables of matching screen and depth.

This chapter discusses how to:

⋅    Manipulate graphics context/state

⋅    Use graphics context convenience functions

77..11..  MMaanniippuullaattiinngg GGrraapphhiiccss CCoonntteexxtt//SSttaattee

Most attributes of graphics operations are stored in GCs.
These include line width, line style, plane mask, fore­
ground, background, tile, stipple, clipping region, end
style, join style, and so on.  Graphics operations (for
example, drawing lines) use these values to determine the
actual drawing operation.  Extensions to X may add addi­
tional components to GCs.  The contents of a GC are private
to Xlib.

Xlib implements a write‐back cache for all elements of a GC
that are not resource IDs to allow Xlib to implement the
transparent coalescing of changes to GCs.  For example, a
call to _X_S_e_t_F_o_r_e_g_r_o_u_n_d of a GC followed by a call to _X_S_e_t_­
_L_i_n_e_A_t_t_r_i_b_u_t_e_s results in only a single‐change GC protocol
request to the server.  GCs are neither expected nor encour­
aged to be shared between client applications, so this
write‐back caching should present no problems.  Applications
cannot share GCs without external synchronization.  There­
fore, sharing GCs between applications is highly discour­
aged.




                             118877





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To set an attribute of a GC, set the appropriate member of
the _X_G_C_V_a_l_u_e_s structure and OR in the corresponding value
bitmask in your subsequent calls to _X_C_r_e_a_t_e_G_C.  The symbols
for the value mask bits and the _X_G_C_V_a_l_u_e_s structure are:





















































                             118888





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
/* GC attribute value mask bits */

#define   _G_C_F_u_n_c_t_i_o_n                  (1L<<0)
#define   _G_C_P_l_a_n_e_M_a_s_k                 (1L<<1)
#define   _G_C_F_o_r_e_g_r_o_u_n_d                (1L<<2)
#define   _G_C_B_a_c_k_g_r_o_u_n_d                (1L<<3)
#define   _G_C_L_i_n_e_W_i_d_t_h                 (1L<<4)
#define   _G_C_L_i_n_e_S_t_y_l_e                 (1L<<5)
#define   _G_C_C_a_p_S_t_y_l_e                  (1L<<6)
#define   _G_C_J_o_i_n_S_t_y_l_e                 (1L<<7)
#define   _G_C_F_i_l_l_S_t_y_l_e                 (1L<<8)
#define   _G_C_F_i_l_l_R_u_l_e                  (1L<<9)
#define   _G_C_T_i_l_e                      (1L<<10)
#define   _G_C_S_t_i_p_p_l_e                   (1L<<11)
#define   _G_C_T_i_l_e_S_t_i_p_X_O_r_i_g_i_n           (1L<<12)
#define   _G_C_T_i_l_e_S_t_i_p_Y_O_r_i_g_i_n           (1L<<13)
#define   _G_C_F_o_n_t                      (1L<<14)
#define   _G_C_S_u_b_w_i_n_d_o_w_M_o_d_e             (1L<<15)
#define   _G_C_G_r_a_p_h_i_c_s_E_x_p_o_s_u_r_e_s         (1L<<16)
#define   _G_C_C_l_i_p_X_O_r_i_g_i_n               (1L<<17)
#define   _G_C_C_l_i_p_Y_O_r_i_g_i_n               (1L<<18)
#define   _G_C_C_l_i_p_M_a_s_k                  (1L<<19)
#define   _G_C_D_a_s_h_O_f_f_s_e_t                (1L<<20)
#define   _G_C_D_a_s_h_L_i_s_t                  (1L<<21)
#define   _G_C_A_r_c_M_o_d_e                   (1L<<22)


/* Values */

typedef struct {
     int function;            /* logical operation */
     unsigned long plane_mask;/* plane mask */
     unsigned long foreground;/* foreground pixel */
     unsigned long background;/* background pixel */
     int line_width;          /* line width (in pixels) */
     int line_style;          /* LineSolid, LineOnOffDash, LineDoubleDash */
     int cap_style;           /* CapNotLast, CapButt, CapRound, CapProjecting */
     int join_style;          /* JoinMiter, JoinRound, JoinBevel */
     int fill_style;          /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
     int fill_rule;           /* EvenOddRule, WindingRule */
     int arc_mode;            /* ArcChord, ArcPieSlice */
     Pixmap tile;             /* tile pixmap for tiling operations */
     Pixmap stipple;          /* stipple 1 plane pixmap for stippling */
     int ts_x_origin;         /* offset for tile or stipple operations */
     int ts_y_origin;
     Font font;               /* default text font for text operations */
     int subwindow_mode;      /* ClipByChildren, IncludeInferiors */
     Bool graphics_exposures; /* boolean, should exposures be generated */
     int clip_x_origin;       /* origin for clipping */
     int clip_y_origin;
     Pixmap clip_mask;        /* bitmap clipping; other calls for rects */
     int dash_offset;         /* patterned/dashed line information */
     char dashes;



                             118899





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


} XGCValues;

││__

The default GC values are:

----------------------------------------------------------------------------------
CCoommppoonneenntt            DDeeffaauulltt
----------------------------------------------------------------------------------
function             _G_X_c_o_p_y
plane_mask           All ones
foreground           0
background           1
line_width           0
line_style           _L_i_n_e_S_o_l_i_d
cap_style            _C_a_p_B_u_t_t
join_style           _J_o_i_n_M_i_t_e_r
fill_style           _F_i_l_l_S_o_l_i_d
fill_rule            _E_v_e_n_O_d_d_R_u_l_e
arc_mode             _A_r_c_P_i_e_S_l_i_c_e
tile                 Pixmap of unspecified size filled with foreground pixel
                     (that is, client specified pixel if any, else 0)
                     (subsequent changes to foreground do not affect this pixmap)
stipple              Pixmap of unspecified size filled with ones
ts_x_origin          0
ts_y_origin          0
font                 <implementation dependent>
subwindow_mode       _C_l_i_p_B_y_C_h_i_l_d_r_e_n
graphics_exposures   _T_r_u_e
clip_x_origin        0
clip_y_origin        0
clip_mask            _N_o_n_e
dash_offset          0
dashes               4 (that is, the list [4, 4])
----------------------------------------------------------------------------------


Note that foreground and background are not set to any val­
ues likely to be useful in a window.

The function attributes of a GC are used when you update a
section of a drawable (the destination) with bits from some­
where else (the source).  The function in a GC defines how
the new destination bits are to be computed from the source
bits and the old destination bits.  _G_X_c_o_p_y is typically the
most useful because it will work on a color display, but
special applications may use other functions, particularly
in concert with particular planes of a color display.  The
16 GC functions, defined in <_X_1_1_/_X_._h>, are:








                             119900





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-----------------------------------------------
FFuunnccttiioonn NNaammee     VVaalluuee   OOppeerraattiioonn
-----------------------------------------------
_G_X_c_l_e_a_r            0x0    0
_G_X_a_n_d              0x1    src AND dst
_G_X_a_n_d_R_e_v_e_r_s_e       0x2    src AND NOT dst
_G_X_c_o_p_y             0x3    src
_G_X_a_n_d_I_n_v_e_r_t_e_d      0x4    (NOT src) AND dst
_G_X_n_o_o_p             0x5    dst
_G_X_x_o_r              0x6    src XOR dst
_G_X_o_r               0x7    src OR dst
_G_X_n_o_r              0x8    (NOT src) AND (NOT
                          dst)
_G_X_e_q_u_i_v            0x9    (NOT src) XOR dst
_G_X_i_n_v_e_r_t           0xa    NOT dst
_G_X_o_r_R_e_v_e_r_s_e        0xb    src OR (NOT dst)
_G_X_c_o_p_y_I_n_v_e_r_t_e_d     0xc    NOT src
_G_X_o_r_I_n_v_e_r_t_e_d       0xd    (NOT src) OR dst
_G_X_n_a_n_d             0xe    (NOT src) OR (NOT
                          dst)
_G_X_s_e_t              0xf    1
-----------------------------------------------


Many graphics operations depend on either pixel values or
planes in a GC.  The planes attribute is of type long, and
it specifies which planes of the destination are to be modi­
fied, one bit per plane.  A monochrome display has only one
plane and will be the least significant bit of the word.  As
planes are added to the display hardware, they will occupy
more significant bits in the plane mask.

In graphics operations, given a source and destination
pixel, the result is computed bitwise on corresponding bits
of the pixels.  That is, a Boolean operation is performed in
each bit plane.  The plane_mask restricts the operation to a
subset of planes.  A macro constant _A_l_l_P_l_a_n_e_s can be used to
refer to all planes of the screen simultaneously.  The
result is computed by the following:


     ((src FUNC dst) AND plane‐mask) OR (dst AND (NOT plane‐mask))


Range checking is not performed on the values for fore­
ground, background, or plane_mask.  They are simply trun­
cated to the appropriate number of bits.  The line‐width is
measured in pixels and either can be greater than or equal
to one (wide line) or can be the special value zero (thin
line).

Wide lines are drawn centered on the path described by the
graphics request.  Unless otherwise specified by the join‐
style or cap‐style, the bounding box of a wide line with



                             119911





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


endpoints [x1, y1], [x2, y2] and width w is a rectangle with
vertices at the following real coordinates:


     [x1‐(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1‐(w*cs/2)],
     [x2‐(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2‐(w*cs/2)]


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

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

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

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

A wide line drawn from [x1,y1] to [x2,y2] always draws the
same pixels as a wide line drawn from [x2,y2] to [x1,y1],
not counting cap‐style and join‐style.  It is recommended
that this property be true for thin lines, but this is not
required.  A line‐width of zero may differ from a line‐width
of one in which pixels are drawn.  This permits the use of
many manufacturers’ line drawing hardware, which may run
many times faster than the more precisely specified wide
lines.

In general, drawing a thin line will be faster than drawing
a wide line of width one.  However, because of their differ­
ent drawing algorithms, thin lines may not mix well aesthet­
ically with wide lines.  If it is desirable to obtain pre­
cise and uniform results across all displays, a client
should always use a line‐width of one rather than a line‐



                             119922





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


width of zero.

The line‐style defines which sections of a line are drawn:

_L_i_n_e_S_o_l_i_d       The full path of the line is drawn.
_L_i_n_e_D_o_u_­        The full path of the line is drawn, but the
_b_l_e_D_a_s_h         even dashes are filled differently from the
                odd dashes (see fill‐style) with _C_a_p_B_u_t_t
                style used where even and odd dashes meet.
_L_i_n_e_O_n_O_f_f_D_a_s_h   Only the even dashes are drawn, and cap‐style
                applies to all internal ends of the individ­
                ual dashes, except _C_a_p_N_o_t_L_a_s_t is treated as
                _C_a_p_B_u_t_t.


The cap‐style defines how the endpoints of a path are drawn:

_C_a_p_N_o_t_L_a_s_t      This is equivalent to _C_a_p_B_u_t_t except that for
                a line‐width of zero the final endpoint is
                not drawn.
_C_a_p_B_u_t_t         The line is square at the endpoint (perpen­
                dicular to the slope of the line) with no
                projection beyond.
_C_a_p_R_o_u_n_d        The line has a circular arc with the diameter
                equal to the line‐width, centered on the end­
                point.  (This is equivalent to _C_a_p_B_u_t_t for
                line‐width of zero).
_C_a_p_P_r_o_j_e_c_t_i_n_g   The line is square at the end, but the path
                continues beyond the endpoint for a distance
                equal to half the line‐width.  (This is
                equivalent to _C_a_p_B_u_t_t for line‐width of
                zero).


The join‐style defines how corners are drawn for wide lines:

_J_o_i_n_M_i_t_e_r       The outer edges of two lines extend to meet
                at an angle.  However, if the angle is less
                than 11 degrees, then a _J_o_i_n_B_e_v_e_l join‐style
                is used instead.
_J_o_i_n_R_o_u_n_d       The corner is a circular arc with the diame­
                ter equal to the line‐width, centered on the
                joinpoint.
_J_o_i_n_B_e_v_e_l       The corner has _C_a_p_B_u_t_t endpoint styles with
                the triangular notch filled.


For a line with coincident endpoints (x1=x2, y1=y2), when
the cap‐style is applied to both endpoints, the semantics
depends on the line‐width and the cap‐style:







                             119933





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_C_a_p_N_o_t_L_a_s_t      thin    The results are device dependent, but
                        the desired effect is that nothing is
                        drawn.
_C_a_p_B_u_t_t         thin    The results are device dependent, but
                        the desired effect is that a single
                        pixel is drawn.
_C_a_p_R_o_u_n_d        thin    The results are the same as for _C_a_p_­
                        _B_u_t_t/thin.
_C_a_p_P_r_o_j_e_c_t_i_n_g   thin    The results are the same as for _C_a_p_­
                        _B_u_t_t/thin.
_C_a_p_B_u_t_t         wide    Nothing is drawn.
_C_a_p_R_o_u_n_d        wide    The closed path is a circle, centered at
                        the endpoint, and with the diameter
                        equal to the line‐width.
_C_a_p_P_r_o_j_e_c_t_i_n_g   wide    The closed path is a square, aligned
                        with the coordinate axes, centered at
                        the endpoint, and with the sides equal
                        to the line‐width.


For a line with coincident endpoints (x1=x2, y1=y2), when
the join‐style is applied at one or both endpoints, the
effect is as if the line was removed from the overall path.
However, if the total path consists of or is reduced to a
single point joined with itself, the effect is the same as
when the cap‐style is applied at both endpoints.

The tile/stipple represents an infinite two‐dimensional
plane, with the tile/stipple replicated in all dimensions.
When that plane is superimposed on the drawable for use in a
graphics operation, the upper‐left corner of some instance
of the tile/stipple is at the coordinates within the draw­
able specified by the tile/stipple origin.  The tile/stipple
and clip origins are interpreted relative to the origin of
whatever destination drawable is specified in a graphics
request.  The tile pixmap must have the same root and depth
as the GC, or a _B_a_d_M_a_t_c_h error results.  The stipple pixmap
must have depth one and must have the same root as the GC,
or a _B_a_d_M_a_t_c_h error results.  For stipple operations where
the fill‐style is _F_i_l_l_S_t_i_p_p_l_e_d but not _F_i_l_l_O_p_a_q_u_e_S_t_i_p_p_l_e_d,
the stipple pattern is tiled in a single plane and acts as
an additional clip mask to be ANDed with the clip‐mask.
Although some sizes may be faster to use than others, any
size pixmap can be used for tiling or stippling.

The fill‐style defines the contents of the source for line,
text, and fill requests.  For all text and fill requests
(for example, _X_D_r_a_w_T_e_x_t, _X_D_r_a_w_T_e_x_t_1_6, _X_F_i_l_l_R_e_c_t_a_n_g_l_e,
_X_F_i_l_l_P_o_l_y_g_o_n, and _X_F_i_l_l_A_r_c); for line requests with line‐
style _L_i_n_e_S_o_l_i_d (for example, _X_D_r_a_w_L_i_n_e, _X_D_r_a_w_S_e_g_m_e_n_t_s,
_X_D_r_a_w_R_e_c_t_a_n_g_l_e, _X_D_r_a_w_A_r_c); and for the even dashes for line
requests with line‐style _L_i_n_e_O_n_O_f_f_D_a_s_h or _L_i_n_e_D_o_u_b_l_e_D_a_s_h,
the following apply:




                             119944





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_F_i_l_l_S_o_l_i_d            Foreground
_F_i_l_l_T_i_l_e_d            Tile
_F_i_l_l_O_p_a_q_u_e_S_t_i_p_p_l_e_d   A tile with the same width and height as
                     stipple, but with background everywhere
                     stipple has a zero and with foreground
                     everywhere stipple has a one
_F_i_l_l_S_t_i_p_p_l_e_d         Foreground masked by stipple


When drawing lines with line‐style _L_i_n_e_D_o_u_b_l_e_D_a_s_h, the odd
dashes are controlled by the fill‐style in the following
manner:

_F_i_l_l_S_o_l_i_d            Background
_F_i_l_l_T_i_l_e_d            Same as for even dashes
_F_i_l_l_O_p_a_q_u_e_S_t_i_p_p_l_e_d   Same as for even dashes
_F_i_l_l_S_t_i_p_p_l_e_d         Background masked by stipple


Storing a pixmap in a GC might or might not result in a copy
being made.  If the pixmap is later used as the destination
for a graphics request, the change might or might not be
reflected in the GC.  If the pixmap is used simultaneously
in a graphics request both as a destination and as a tile or
stipple, the results are undefined.

For optimum performance, you should draw as much as possible
with the same GC (without changing its components).  The
costs of changing GC components relative to using different
GCs depend on the display hardware and the server implemen­
tation.  It is quite likely that some amount of GC informa­
tion will be cached in display hardware and that such hard­
ware can only cache a small number of GCs.

The dashes value is actually a simplified form of the more
general patterns that can be set with _X_S_e_t_D_a_s_h_e_s.  Specify­
ing a value of N is equivalent to specifying the two‐element
list [N, N] in _X_S_e_t_D_a_s_h_e_s.  The value must be nonzero, or a
_B_a_d_V_a_l_u_e error results.

The clip‐mask restricts writes to the destination drawable.
If the clip‐mask is set to a pixmap, it must have depth one
and have the same root as the GC, or a _B_a_d_M_a_t_c_h error
results.  If clip‐mask is set to _N_o_n_e, the pixels are always
drawn regardless of the clip origin.  The clip‐mask also can
be set by calling the _X_S_e_t_C_l_i_p_R_e_c_t_a_n_g_l_e_s or _X_S_e_t_R_e_g_i_o_n func­
tions.  Only pixels where the clip‐mask has a bit set to 1
are drawn.  Pixels are not drawn outside the area covered by
the clip‐mask or where the clip‐mask has a bit set to 0.
The clip‐mask affects all graphics requests.  The clip‐mask
does not clip sources.  The clip‐mask origin is interpreted
relative to the origin of whatever destination drawable is
specified in a graphics request.




                             119955





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


You can set the subwindow‐mode to _C_l_i_p_B_y_C_h_i_l_d_r_e_n or _I_n_c_l_u_d_e_­
_I_n_f_e_r_i_o_r_s.  For _C_l_i_p_B_y_C_h_i_l_d_r_e_n, both source and destination
windows are additionally clipped by all viewable _I_n_p_u_t_O_u_t_p_u_t
children.  For _I_n_c_l_u_d_e_I_n_f_e_r_i_o_r_s, neither source nor destina­
tion window is clipped by inferiors.  This will result in
including subwindow contents in the source and drawing
through subwindow boundaries of the destination.  The use of
_I_n_c_l_u_d_e_I_n_f_e_r_i_o_r_s on a window of one depth with mapped infe­
riors of differing depth is not illegal, but the semantics
are undefined by the core protocol.

The fill‐rule defines what pixels are inside (drawn) for
paths given in _X_F_i_l_l_P_o_l_y_g_o_n requests and can be set to _E_v_e_n_­
_O_d_d_R_u_l_e or _W_i_n_d_i_n_g_R_u_l_e.  For _E_v_e_n_O_d_d_R_u_l_e, a point is inside
if an infinite ray with the point as origin crosses the path
an odd number of times.  For _W_i_n_d_i_n_g_R_u_l_e, a point is inside
if an infinite ray with the point as origin crosses an
unequal number of clockwise and counterclockwise directed
path segments.  A clockwise directed path segment is one
that crosses the ray from left to right as observed from the
point.  A counterclockwise segment is one that crosses the
ray from right to left as observed from the point.  The case
where a directed line segment is coincident with the ray is
uninteresting because you can simply choose a different ray
that is not coincident with a segment.

For both _E_v_e_n_O_d_d_R_u_l_e and _W_i_n_d_i_n_g_R_u_l_e, a point is infinitely
small, and the path is an infinitely thin line.  A pixel is
inside if the center point of the pixel is inside and the
center point is not on the boundary.  If the center point is
on the boundary, the pixel is inside if and only if the
polygon interior is immediately to its right (x increasing
direction).  Pixels with centers on a horizontal edge are a
special case and are inside if and only if the polygon inte­
rior is immediately below (y increasing direction).

The arc‐mode controls filling in the _X_F_i_l_l_A_r_c_s function and
can be set to _A_r_c_P_i_e_S_l_i_c_e or _A_r_c_C_h_o_r_d.  For _A_r_c_P_i_e_S_l_i_c_e, the
arcs are pie‐slice filled.  For _A_r_c_C_h_o_r_d, the arcs are chord
filled.

The graphics‐exposure flag controls _G_r_a_p_h_i_c_s_E_x_p_o_s_e event
generation for _X_C_o_p_y_A_r_e_a and _X_C_o_p_y_P_l_a_n_e requests (and any
similar requests defined by extensions).


To create a new GC that is usable on a given screen with a
depth of drawable, use _X_C_r_e_a_t_e_G_C.









                             119966





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
GC XCreateGC(_d_i_s_p_l_a_y, _d, _v_a_l_u_e_m_a_s_k, _v_a_l_u_e_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      unsigned long _v_a_l_u_e_m_a_s_k;
      XGCValues *_v_a_l_u_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_v_a_l_u_e_m_a_s_k Specifies which components in the GC are to be set
          using the information in the specified values
          structure.  This argument is the bitwise inclusive
          OR of zero or more of the valid GC component mask
          bits.

_v_a_l_u_e_s    Specifies any values as specified by the value­
          mask.
││__

The _X_C_r_e_a_t_e_G_C function creates a graphics context and
returns a GC.  The GC can be used with any destination draw­
able having the same root and depth as the specified draw­
able.  Use with other drawables results in a _B_a_d_M_a_t_c_h error.

_X_C_r_e_a_t_e_G_C can generate _B_a_d_A_l_l_o_c, _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_F_o_n_t, _B_a_d_­
_M_a_t_c_h, _B_a_d_P_i_x_m_a_p, and _B_a_d_V_a_l_u_e errors.


To copy components from a source GC to a destination GC, use
_X_C_o_p_y_G_C.
__
││
XCopyGC(_d_i_s_p_l_a_y, _s_r_c, _v_a_l_u_e_m_a_s_k, _d_e_s_t)
      Display *_d_i_s_p_l_a_y;
      GC _s_r_c, _d_e_s_t;
      unsigned long _v_a_l_u_e_m_a_s_k;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_r_c       Specifies the components of the source GC.

_v_a_l_u_e_m_a_s_k Specifies which components in the GC are to be
          copied to the destination GC.  This argument is
          the bitwise inclusive OR of zero or more of the
          valid GC component mask bits.

_d_e_s_t      Specifies the destination GC.
││__

The _X_C_o_p_y_G_C function copies the specified components from



                             119977





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the source GC to the destination GC.  The source and desti­
nation GCs must have the same root and depth, or a _B_a_d_M_a_t_c_h
error results.  The valuemask specifies which component to
copy, as for _X_C_r_e_a_t_e_G_C.

_X_C_o_p_y_G_C can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_M_a_t_c_h errors.


To change the components in a given GC, use _X_C_h_a_n_g_e_G_C.
__
││
XChangeGC(_d_i_s_p_l_a_y, _g_c, _v_a_l_u_e_m_a_s_k, _v_a_l_u_e_s)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      unsigned long _v_a_l_u_e_m_a_s_k;
      XGCValues *_v_a_l_u_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_v_a_l_u_e_m_a_s_k Specifies which components in the GC are to be
          changed using information in the specified values
          structure.  This argument is the bitwise inclusive
          OR of zero or more of the valid GC component mask
          bits.

_v_a_l_u_e_s    Specifies any values as specified by the value­
          mask.
││__

The _X_C_h_a_n_g_e_G_C function changes the components specified by
valuemask for the specified GC.  The values argument con­
tains the values to be set.  The values and restrictions are
the same as for _X_C_r_e_a_t_e_G_C.  Changing the clip‐mask overrides
any previous _X_S_e_t_C_l_i_p_R_e_c_t_a_n_g_l_e_s request on the context.
Changing the dash‐offset or dash‐list overrides any previous
_X_S_e_t_D_a_s_h_e_s request on the context.  The order in which com­
ponents are verified and altered is server dependent.  If an
error is generated, a subset of the components may have been
altered.

_X_C_h_a_n_g_e_G_C can generate _B_a_d_A_l_l_o_c, _B_a_d_F_o_n_t, _B_a_d_G_C, _B_a_d_M_a_t_c_h,
_B_a_d_P_i_x_m_a_p, and _B_a_d_V_a_l_u_e errors.


To obtain components of a given GC, use _X_G_e_t_G_C_V_a_l_u_e_s.









                             119988





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetGCValues(_d_i_s_p_l_a_y, _g_c, _v_a_l_u_e_m_a_s_k, _v_a_l_u_e_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      unsigned long _v_a_l_u_e_m_a_s_k;
      XGCValues *_v_a_l_u_e_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_v_a_l_u_e_m_a_s_k Specifies which components in the GC are to be
          returned in the values_return argument.  This
          argument is the bitwise inclusive OR of zero or
          more of the valid GC component mask bits.

_v_a_l_u_e_s___r_e_t_u_r_n
          Returns the GC values in the specified _X_G_C_V_a_l_u_e_s
          structure.
││__

The _X_G_e_t_G_C_V_a_l_u_e_s function returns the components specified
by valuemask for the specified GC.  If the valuemask con­
tains a valid set of GC mask bits (_G_C_F_u_n_c_t_i_o_n, _G_C_P_l_a_n_e_M_a_s_k,
_G_C_F_o_r_e_g_r_o_u_n_d, _G_C_B_a_c_k_g_r_o_u_n_d, _G_C_L_i_n_e_W_i_d_t_h, _G_C_L_i_n_e_S_t_y_l_e, _G_C_C_a_p_­
_S_t_y_l_e, _G_C_J_o_i_n_S_t_y_l_e, _G_C_F_i_l_l_S_t_y_l_e, _G_C_F_i_l_l_R_u_l_e, _G_C_T_i_l_e, _G_C_S_t_i_p_­
_p_l_e, _G_C_T_i_l_e_S_t_i_p_X_O_r_i_g_i_n, _G_C_T_i_l_e_S_t_i_p_Y_O_r_i_g_i_n, _G_C_F_o_n_t, _G_C_S_u_b_w_i_n_­
_d_o_w_M_o_d_e, _G_C_G_r_a_p_h_i_c_s_E_x_p_o_s_u_r_e_s, _G_C_C_l_i_p_X_O_r_i_g_i_n, _G_C_C_L_i_p_Y_O_r_i_g_i_n,
_G_C_D_a_s_h_O_f_f_s_e_t, or _G_C_A_r_c_M_o_d_e) and no error occurs, _X_G_e_t_G_C_V_a_l_­
_u_e_s sets the requested components in values_return and
returns a nonzero status.  Otherwise, it returns a zero sta­
tus.  Note that the clip‐mask and dash‐list (represented by
the _G_C_C_l_i_p_M_a_s_k and _G_C_D_a_s_h_L_i_s_t bits, respectively, in the
valuemask) cannot be requested.  Also note that an invalid
resource ID (with one or more of the three most significant
bits set to 1) will be returned for _G_C_F_o_n_t, _G_C_T_i_l_e, and
_G_C_S_t_i_p_p_l_e if the component has never been explicitly set by
the client.


To free a given GC, use _X_F_r_e_e_G_C.















                             119999





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XFreeGC(_d_i_s_p_l_a_y, _g_c)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.
││__

The _X_F_r_e_e_G_C function destroys the specified GC as well as
all the associated storage.

_X_F_r_e_e_G_C can generate a _B_a_d_G_C error.


To obtain the _G_C_o_n_t_e_x_t resource ID for a given GC, use
_X_G_C_o_n_t_e_x_t_F_r_o_m_G_C.
__
││
GContext XGContextFromGC(_g_c)
      GC _g_c;


_g_c        Specifies the GC for which you want the resource
          ID.
││__


Xlib usually defers sending changes to the components of a
GC to the server until a graphics function is actually
called with that GC.  This permits batching of component
changes into a single server request.  In some circum­
stances, however, it may be necessary for the client to
explicitly force sending the changes to the server.  An
example might be when a protocol extension uses the GC indi­
rectly, in such a way that the extension interface cannot
know what GC will be used.  To force sending GC component
changes, use _X_F_l_u_s_h_G_C.
__
││
void XFlushGC(_d_i_s_p_l_a_y, _g_c)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.
││__






                             220000





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


77..22..  UUssiinngg GGrraapphhiiccss CCoonntteexxtt CCoonnvveenniieennccee RRoouuttiinneess

This section discusses how to set the:

⋅    Foreground, background, plane mask, or function compo­
     nents

⋅    Line attributes and dashes components

⋅    Fill style and fill rule components

⋅    Fill tile and stipple components

⋅    Font component

⋅    Clip region component

⋅    Arc mode, subwindow mode, and graphics exposure compo­
     nents

77..22..11..  SSeettttiinngg tthhee FFoorreeggrroouunndd,, BBaacckkggrroouunndd,, FFuunnccttiioonn,, oorr
PPllaannee MMaasskk

To set the foreground, background, plane mask, and function
components for a given GC, use _X_S_e_t_S_t_a_t_e.
































                             220011





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetState(_d_i_s_p_l_a_y, _g_c, _f_o_r_e_g_r_o_u_n_d, _b_a_c_k_g_r_o_u_n_d, _f_u_n_c_t_i_o_n, _p_l_a_n_e___m_a_s_k)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      unsigned long _f_o_r_e_g_r_o_u_n_d, _b_a_c_k_g_r_o_u_n_d;
      int _f_u_n_c_t_i_o_n;
      unsigned long _p_l_a_n_e___m_a_s_k;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_f_o_r_e_g_r_o_u_n_d
          Specifies the foreground you want to set for the
          specified GC.

_b_a_c_k_g_r_o_u_n_d
          Specifies the background you want to set for the
          specified GC.

_f_u_n_c_t_i_o_n  Specifies the function you want to set for the
          specified GC.

_p_l_a_n_e___m_a_s_k
          Specifies the plane mask.
││__

_X_S_e_t_S_t_a_t_e can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_V_a_l_u_e errors.


To set the foreground of a given GC, use _X_S_e_t_F_o_r_e_g_r_o_u_n_d.
__
││
XSetForeground(_d_i_s_p_l_a_y, _g_c, _f_o_r_e_g_r_o_u_n_d)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      unsigned long _f_o_r_e_g_r_o_u_n_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_f_o_r_e_g_r_o_u_n_d
          Specifies the foreground you want to set for the
          specified GC.
││__

_X_S_e_t_F_o_r_e_g_r_o_u_n_d can generate _B_a_d_A_l_l_o_c and _B_a_d_G_C errors.


To set the background of a given GC, use _X_S_e_t_B_a_c_k_g_r_o_u_n_d.




                             220022





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetBackground(_d_i_s_p_l_a_y, _g_c, _b_a_c_k_g_r_o_u_n_d)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      unsigned long _b_a_c_k_g_r_o_u_n_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_b_a_c_k_g_r_o_u_n_d
          Specifies the background you want to set for the
          specified GC.
││__

_X_S_e_t_B_a_c_k_g_r_o_u_n_d can generate _B_a_d_A_l_l_o_c and _B_a_d_G_C errors.


To set the display function in a given GC, use _X_S_e_t_F_u_n_c_t_i_o_n.
__
││
XSetFunction(_d_i_s_p_l_a_y, _g_c, _f_u_n_c_t_i_o_n)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      int _f_u_n_c_t_i_o_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_f_u_n_c_t_i_o_n  Specifies the function you want to set for the
          specified GC.
││__

_X_S_e_t_F_u_n_c_t_i_o_n can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_V_a_l_u_e
errors.


To set the plane mask of a given GC, use _X_S_e_t_P_l_a_n_e_M_a_s_k.
















                             220033





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetPlaneMask(_d_i_s_p_l_a_y, _g_c, _p_l_a_n_e___m_a_s_k)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      unsigned long _p_l_a_n_e___m_a_s_k;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_p_l_a_n_e___m_a_s_k
          Specifies the plane mask.
││__

_X_S_e_t_P_l_a_n_e_M_a_s_k can generate _B_a_d_A_l_l_o_c and _B_a_d_G_C errors.

77..22..22..  SSeettttiinngg tthhee LLiinnee AAttttrriibbuutteess aanndd DDaasshheess

To set the line drawing components of a given GC, use _X_S_e_t_­
_L_i_n_e_A_t_t_r_i_b_u_t_e_s.




































                             220044





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetLineAttributes(_d_i_s_p_l_a_y, _g_c, _l_i_n_e___w_i_d_t_h, _l_i_n_e___s_t_y_l_e, _c_a_p___s_t_y_l_e, _j_o_i_n___s_t_y_l_e)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      unsigned int _l_i_n_e___w_i_d_t_h;
      int _l_i_n_e___s_t_y_l_e;
      int _c_a_p___s_t_y_l_e;
      int _j_o_i_n___s_t_y_l_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_l_i_n_e___w_i_d_t_h
          Specifies the line‐width you want to set for the
          specified GC.

_l_i_n_e___s_t_y_l_e
          Specifies the line‐style you want to set for the
          specified GC.  You can pass _L_i_n_e_S_o_l_i_d, _L_i_n_e_O_n_O_f_f_­
          _D_a_s_h, or _L_i_n_e_D_o_u_b_l_e_D_a_s_h.

_c_a_p___s_t_y_l_e Specifies the line‐style and cap‐style you want to
          set for the specified GC.  You can pass _C_a_p_N_o_t_­
          _L_a_s_t, _C_a_p_B_u_t_t, _C_a_p_R_o_u_n_d, or _C_a_p_P_r_o_j_e_c_t_i_n_g.

_j_o_i_n___s_t_y_l_e
          Specifies the line join‐style you want to set for
          the specified GC.  You can pass _J_o_i_n_M_i_t_e_r, _J_o_i_n_­
          _R_o_u_n_d, or _J_o_i_n_B_e_v_e_l.
││__

_X_S_e_t_L_i_n_e_A_t_t_r_i_b_u_t_e_s can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_­
_V_a_l_u_e errors.


To set the dash‐offset and dash‐list for dashed line styles
of a given GC, use _X_S_e_t_D_a_s_h_e_s.


















                             220055





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetDashes(_d_i_s_p_l_a_y, _g_c, _d_a_s_h___o_f_f_s_e_t, _d_a_s_h___l_i_s_t, _n)
        Display *_d_i_s_p_l_a_y;
        GC _g_c;
        int _d_a_s_h___o_f_f_s_e_t;
        char _d_a_s_h___l_i_s_t[];
        int _n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_d_a_s_h___o_f_f_s_e_t
          Specifies the phase of the pattern for the dashed
          line‐style you want to set for the specified GC.

_d_a_s_h___l_i_s_t Specifies the dash‐list for the dashed line‐style
          you want to set for the specified GC.

_n         Specifies the number of elements in dash_list.
││__

The _X_S_e_t_D_a_s_h_e_s function sets the dash‐offset and dash‐list
attributes for dashed line styles in the specified GC.
There must be at least one element in the specified
dash_list, or a _B_a_d_V_a_l_u_e error results.  The initial and
alternating elements (second, fourth, and so on) of the
dash_list are the even dashes, and the others are the odd
dashes.  Each element specifies a dash length in pixels.
All of the elements must be nonzero, or a _B_a_d_V_a_l_u_e error
results.  Specifying an odd‐length list is equivalent to
specifying the same list concatenated with itself to produce
an even‐length list.

The dash‐offset defines the phase of the pattern, specifying
how many pixels into the dash‐list the pattern should actu­
ally begin in any single graphics request.  Dashing is con­
tinuous through path elements combined with a join‐style but
is reset to the dash‐offset between each sequence of joined
lines.

The unit of measure for dashes is the same for the ordinary
coordinate system.  Ideally, a dash length is measured along
the slope of the line, but implementations are only required
to match this ideal for horizontal and vertical lines.
Failing the ideal semantics, it is suggested that the length
be measured along the major axis of the line.  The major
axis is defined as the x axis for lines drawn at an angle of
between −45 and +45 degrees or between 135 and 225 degrees
from the x axis.  For all other lines, the major axis is the
y axis.





                             220066





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_S_e_t_D_a_s_h_e_s can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_V_a_l_u_e
errors.

77..22..33..  SSeettttiinngg tthhee FFiillll SSttyyllee aanndd FFiillll RRuullee

To set the fill‐style of a given GC, use _X_S_e_t_F_i_l_l_S_t_y_l_e.
__
││
XSetFillStyle(_d_i_s_p_l_a_y, _g_c, _f_i_l_l___s_t_y_l_e)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      int _f_i_l_l___s_t_y_l_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_f_i_l_l___s_t_y_l_e
          Specifies the fill‐style you want to set for the
          specified GC.  You can pass _F_i_l_l_S_o_l_i_d, _F_i_l_l_T_i_l_e_d,
          _F_i_l_l_S_t_i_p_p_l_e_d, or _F_i_l_l_O_p_a_q_u_e_S_t_i_p_p_l_e_d.
││__

_X_S_e_t_F_i_l_l_S_t_y_l_e can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_V_a_l_u_e
errors.


To set the fill‐rule of a given GC, use _X_S_e_t_F_i_l_l_R_u_l_e.
__
││
XSetFillRule(_d_i_s_p_l_a_y, _g_c, _f_i_l_l___r_u_l_e)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      int _f_i_l_l___r_u_l_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_f_i_l_l___r_u_l_e Specifies the fill‐rule you want to set for the
          specified GC.  You can pass _E_v_e_n_O_d_d_R_u_l_e or _W_i_n_d_i_n_­
          _g_R_u_l_e.
││__

_X_S_e_t_F_i_l_l_R_u_l_e can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_V_a_l_u_e
errors.

77..22..44..  SSeettttiinngg tthhee FFiillll TTiillee aanndd SSttiippppllee

Some displays have hardware support for tiling or stippling
with patterns of specific sizes.  Tiling and stippling oper­
ations that restrict themselves to those specific sizes run



                             220077





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


much faster than such operations with arbitrary size pat­
terns.  Xlib provides functions that you can use to deter­
mine the best size, tile, or stipple for the display as well
as to set the tile or stipple shape and the tile or stipple
origin.


To obtain the best size of a tile, stipple, or cursor, use
_X_Q_u_e_r_y_B_e_s_t_S_i_z_e.
__
││
Status XQueryBestSize(_d_i_s_p_l_a_y, _c_l_a_s_s, _w_h_i_c_h___s_c_r_e_e_n, _w_i_d_t_h, _h_e_i_g_h_t, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int _c_l_a_s_s;
      Drawable _w_h_i_c_h___s_c_r_e_e_n;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      unsigned int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_l_a_s_s     Specifies the class that you are interested in.
          You can pass _T_i_l_e_S_h_a_p_e, _C_u_r_s_o_r_S_h_a_p_e, or _S_t_i_p_p_l_e_­
          _S_h_a_p_e.

_w_h_i_c_h___s_c_r_e_e_n
          Specifies any drawable on the screen.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the width and height of the object best
          supported by the display hardware.
││__

The _X_Q_u_e_r_y_B_e_s_t_S_i_z_e function returns the best or closest size
to the specified size.  For _C_u_r_s_o_r_S_h_a_p_e, this is the largest
size that can be fully displayed on the screen specified by
which_screen.  For _T_i_l_e_S_h_a_p_e, this is the size that can be
tiled fastest.  For _S_t_i_p_p_l_e_S_h_a_p_e, this is the size that can
be stippled fastest.  For _C_u_r_s_o_r_S_h_a_p_e, the drawable indi­
cates the desired screen.  For _T_i_l_e_S_h_a_p_e and _S_t_i_p_p_l_e_S_h_a_p_e,
the drawable indicates the screen and possibly the window
class and depth.  An _I_n_p_u_t_O_n_l_y window cannot be used as the
drawable for _T_i_l_e_S_h_a_p_e or _S_t_i_p_p_l_e_S_h_a_p_e, or a _B_a_d_M_a_t_c_h error
results.

_X_Q_u_e_r_y_B_e_s_t_S_i_z_e can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_M_a_t_c_h, and _B_a_d_­
_V_a_l_u_e errors.


To obtain the best fill tile shape, use _X_Q_u_e_r_y_B_e_s_t_T_i_l_e.



                             220088





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XQueryBestTile(_d_i_s_p_l_a_y, _w_h_i_c_h___s_c_r_e_e_n, _w_i_d_t_h, _h_e_i_g_h_t, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Drawable _w_h_i_c_h___s_c_r_e_e_n;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      unsigned int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w_h_i_c_h___s_c_r_e_e_n
          Specifies any drawable on the screen.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the width and height of the object best
          supported by the display hardware.
││__

The _X_Q_u_e_r_y_B_e_s_t_T_i_l_e function returns the best or closest
size, that is, the size that can be tiled fastest on the
screen specified by which_screen.  The drawable indicates
the screen and possibly the window class and depth.  If an
_I_n_p_u_t_O_n_l_y window is used as the drawable, a _B_a_d_M_a_t_c_h error
results.

_X_Q_u_e_r_y_B_e_s_t_T_i_l_e can generate _B_a_d_D_r_a_w_a_b_l_e and _B_a_d_M_a_t_c_h errors.


To obtain the best stipple shape, use _X_Q_u_e_r_y_B_e_s_t_S_t_i_p_p_l_e.
























                             220099





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XQueryBestStipple(_d_i_s_p_l_a_y, _w_h_i_c_h___s_c_r_e_e_n, _w_i_d_t_h, _h_e_i_g_h_t, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Drawable _w_h_i_c_h___s_c_r_e_e_n;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      unsigned int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w_h_i_c_h___s_c_r_e_e_n
          Specifies any drawable on the screen.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the width and height of the object best
          supported by the display hardware.
││__

The _X_Q_u_e_r_y_B_e_s_t_S_t_i_p_p_l_e function returns the best or closest
size, that is, the size that can be stippled fastest on the
screen specified by which_screen.  The drawable indicates
the screen and possibly the window class and depth.  If an
_I_n_p_u_t_O_n_l_y window is used as the drawable, a _B_a_d_M_a_t_c_h error
results.

_X_Q_u_e_r_y_B_e_s_t_S_t_i_p_p_l_e can generate _B_a_d_D_r_a_w_a_b_l_e and _B_a_d_M_a_t_c_h
errors.


To set the fill tile of a given GC, use _X_S_e_t_T_i_l_e.
__
││
XSetTile(_d_i_s_p_l_a_y, _g_c, _t_i_l_e)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      Pixmap _t_i_l_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_t_i_l_e      Specifies the fill tile you want to set for the
          specified GC.
││__

The tile and GC must have the same depth, or a _B_a_d_M_a_t_c_h
error results.





                             221100





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_S_e_t_T_i_l_e can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, _B_a_d_M_a_t_c_h, and _B_a_d_­
_P_i_x_m_a_p errors.


To set the stipple of a given GC, use _X_S_e_t_S_t_i_p_p_l_e.
__
││
XSetStipple(_d_i_s_p_l_a_y, _g_c, _s_t_i_p_p_l_e)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      Pixmap _s_t_i_p_p_l_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_s_t_i_p_p_l_e   Specifies the stipple you want to set for the
          specified GC.
││__

The stipple must have a depth of one, or a _B_a_d_M_a_t_c_h error
results.

_X_S_e_t_S_t_i_p_p_l_e can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, _B_a_d_M_a_t_c_h, and _B_a_d_­
_P_i_x_m_a_p errors.


To set the tile or stipple origin of a given GC, use
_X_S_e_t_T_S_O_r_i_g_i_n.
__
││
XSetTSOrigin(_d_i_s_p_l_a_y, _g_c, _t_s___x___o_r_i_g_i_n, _t_s___y___o_r_i_g_i_n)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      int _t_s___x___o_r_i_g_i_n, _t_s___y___o_r_i_g_i_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_t_s___x___o_r_i_g_i_n
_t_s___y___o_r_i_g_i_n
          Specify the x and y coordinates of the tile and
          stipple origin.
││__

When graphics requests call for tiling or stippling, the
parent’s origin will be interpreted relative to whatever
destination drawable is specified in the graphics request.

_X_S_e_t_T_S_O_r_i_g_i_n can generate _B_a_d_A_l_l_o_c and _B_a_d_G_C errors.




                             221111





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


77..22..55..  SSeettttiinngg tthhee CCuurrrreenntt FFoonntt

To set the current font of a given GC, use _X_S_e_t_F_o_n_t.
__
││
XSetFont(_d_i_s_p_l_a_y, _g_c, _f_o_n_t)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      Font _f_o_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_f_o_n_t      Specifies the font.
││__

_X_S_e_t_F_o_n_t can generate _B_a_d_A_l_l_o_c, _B_a_d_F_o_n_t, and _B_a_d_G_C errors.

77..22..66..  SSeettttiinngg tthhee CClliipp RReeggiioonn

Xlib provides functions that you can use to set the clip‐
origin and the clip‐mask or set the clip‐mask to a list of
rectangles.


To set the clip‐origin of a given GC, use _X_S_e_t_C_l_i_p_O_r_i_g_i_n.
__
││
XSetClipOrigin(_d_i_s_p_l_a_y, _g_c, _c_l_i_p___x___o_r_i_g_i_n, _c_l_i_p___y___o_r_i_g_i_n)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      int _c_l_i_p___x___o_r_i_g_i_n, _c_l_i_p___y___o_r_i_g_i_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_c_l_i_p___x___o_r_i_g_i_n
_c_l_i_p___y___o_r_i_g_i_n
          Specify the x and y coordinates of the clip‐mask
          origin.
││__

The clip‐mask origin is interpreted relative to the origin
of whatever destination drawable is specified in the graph­
ics request.

_X_S_e_t_C_l_i_p_O_r_i_g_i_n can generate _B_a_d_A_l_l_o_c and _B_a_d_G_C errors.


To set the clip‐mask of a given GC to the specified pixmap,



                             221122





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


use _X_S_e_t_C_l_i_p_M_a_s_k.
__
││
XSetClipMask(_d_i_s_p_l_a_y, _g_c, _p_i_x_m_a_p)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      Pixmap _p_i_x_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_p_i_x_m_a_p    Specifies the pixmap or _N_o_n_e.
││__

If the clip‐mask is set to _N_o_n_e, the pixels are always drawn
(regardless of the clip‐origin).

_X_S_e_t_C_l_i_p_M_a_s_k can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, _B_a_d_M_a_t_c_h, and
_B_a_d_P_i_x_m_a_p errors.


To set the clip‐mask of a given GC to the specified list of
rectangles, use _X_S_e_t_C_l_i_p_R_e_c_t_a_n_g_l_e_s.
































                             221133





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetClipRectangles(_d_i_s_p_l_a_y, _g_c, _c_l_i_p___x___o_r_i_g_i_n, _c_l_i_p___y___o_r_i_g_i_n, _r_e_c_t_a_n_g_l_e_s, _n, _o_r_d_e_r_i_n_g)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      int _c_l_i_p___x___o_r_i_g_i_n, _c_l_i_p___y___o_r_i_g_i_n;
      XRectangle _r_e_c_t_a_n_g_l_e_s[];
      int _n;
      int _o_r_d_e_r_i_n_g;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_c_l_i_p___x___o_r_i_g_i_n
_c_l_i_p___y___o_r_i_g_i_n
          Specify the x and y coordinates of the clip‐mask
          origin.

_r_e_c_t_a_n_g_l_e_s
          Specifies an array of rectangles that define the
          clip‐mask.

_n         Specifies the number of rectangles.

_o_r_d_e_r_i_n_g  Specifies the ordering relations on the rectan­
          gles.  You can pass _U_n_s_o_r_t_e_d, _Y_S_o_r_t_e_d, _Y_X_S_o_r_t_e_d,
          or _Y_X_B_a_n_d_e_d.
││__

The _X_S_e_t_C_l_i_p_R_e_c_t_a_n_g_l_e_s function changes the clip‐mask in the
specified GC to the specified list of rectangles and sets
the clip origin.  The output is clipped to remain contained
within the rectangles.  The clip‐origin is interpreted rela­
tive to the origin of whatever destination drawable is spec­
ified in a graphics request.  The rectangle coordinates are
interpreted relative to the clip‐origin.  The rectangles
should be nonintersecting, or the graphics results will be
undefined.  Note that the list of rectangles can be empty,
which effectively disables output.  This is the opposite of
passing _N_o_n_e as the clip‐mask in _X_C_r_e_a_t_e_G_C, _X_C_h_a_n_g_e_G_C, and
_X_S_e_t_C_l_i_p_M_a_s_k.

If known by the client, ordering relations on the rectangles
can be specified with the ordering argument.  This may pro­
vide faster operation by the server.  If an incorrect order­
ing is specified, the X server may generate a _B_a_d_M_a_t_c_h
error, but it is not required to do so.  If no error is gen­
erated, the graphics results are undefined.  _U_n_s_o_r_t_e_d means
the rectangles are in arbitrary order.  _Y_S_o_r_t_e_d means that
the rectangles are nondecreasing in their Y origin.
_Y_X_S_o_r_t_e_d additionally constrains _Y_S_o_r_t_e_d order in that all
rectangles with an equal Y origin are nondecreasing in their
X origin.  _Y_X_B_a_n_d_e_d additionally constrains _Y_X_S_o_r_t_e_d by



                             221144





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


requiring that, for every possible Y scanline, all rectan­
gles that include that scanline have an identical Y origins
and Y extents.

_X_S_e_t_C_l_i_p_R_e_c_t_a_n_g_l_e_s can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, _B_a_d_M_a_t_c_h,
and _B_a_d_V_a_l_u_e errors.

Xlib provides a set of basic functions for performing region
arithmetic.  For information about these functions, see sec­
tion 16.5.

77..22..77..  SSeettttiinngg tthhee AArrcc MMooddee,, SSuubbwwiinnddooww MMooddee,, aanndd GGrraapphhiiccss
EExxppoossuurree

To set the arc mode of a given GC, use _X_S_e_t_A_r_c_M_o_d_e.
__
││
XSetArcMode(_d_i_s_p_l_a_y, _g_c, _a_r_c___m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      int _a_r_c___m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_a_r_c___m_o_d_e  Specifies the arc mode.  You can pass _A_r_c_C_h_o_r_d or
          _A_r_c_P_i_e_S_l_i_c_e.
││__

_X_S_e_t_A_r_c_M_o_d_e can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_V_a_l_u_e
errors.


To set the subwindow mode of a given GC, use _X_S_e_t_S_u_b_w_i_n_d_o_w_­
_M_o_d_e.




















                             221155





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetSubwindowMode(_d_i_s_p_l_a_y, _g_c, _s_u_b_w_i_n_d_o_w___m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      int _s_u_b_w_i_n_d_o_w___m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_s_u_b_w_i_n_d_o_w___m_o_d_e
          Specifies the subwindow mode.  You can pass _C_l_i_p_­
          _B_y_C_h_i_l_d_r_e_n or _I_n_c_l_u_d_e_I_n_f_e_r_i_o_r_s.
││__

_X_S_e_t_S_u_b_w_i_n_d_o_w_M_o_d_e can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_V_a_l_u_e
errors.


To set the graphics‐exposures flag of a given GC, use _X_S_e_t_­
_G_r_a_p_h_i_c_s_E_x_p_o_s_u_r_e_s.
__
││
XSetGraphicsExposures(_d_i_s_p_l_a_y, _g_c, _g_r_a_p_h_i_c_s___e_x_p_o_s_u_r_e_s)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      Bool _g_r_a_p_h_i_c_s___e_x_p_o_s_u_r_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_g_r_a_p_h_i_c_s___e_x_p_o_s_u_r_e_s
          Specifies a Boolean value that indicates whether
          you want _G_r_a_p_h_i_c_s_E_x_p_o_s_e and _N_o_E_x_p_o_s_e events to be
          reported when calling _X_C_o_p_y_A_r_e_a and _X_C_o_p_y_P_l_a_n_e
          with this GC.
││__

_X_S_e_t_G_r_a_p_h_i_c_s_E_x_p_o_s_u_r_e_s can generate _B_a_d_A_l_l_o_c, _B_a_d_G_C, and _B_a_d_­
_V_a_l_u_e errors.














                             221166





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 88

                     GGrraapphhiiccss FFuunnccttiioonnss



Once you have established a connection to a display, you can
use the Xlib graphics functions to:

⋅    Clear and copy areas

⋅    Draw points, lines, rectangles, and arcs

⋅    Fill areas

⋅    Manipulate fonts

⋅    Draw text

⋅    Transfer images between clients and the server

If the same drawable and GC is used for each call, Xlib
batches back‐to‐back calls to _X_D_r_a_w_P_o_i_n_t, _X_D_r_a_w_L_i_n_e,
_X_D_r_a_w_R_e_c_t_a_n_g_l_e, _X_F_i_l_l_A_r_c, and _X_F_i_l_l_R_e_c_t_a_n_g_l_e.  Note that
this reduces the total number of requests sent to the
server.

88..11..  CClleeaarriinngg AArreeaass

Xlib provides functions that you can use to clear an area or
the entire window.  Because pixmaps do not have defined
backgrounds, they cannot be filled by using the functions
described in this section.  Instead, to accomplish an analo­
gous operation on a pixmap, you should use _X_F_i_l_l_R_e_c_t_a_n_g_l_e,
which sets the pixmap to a known value.


To clear a rectangular area of a given window, use _X_C_l_e_a_r_­
_A_r_e_a.
















                             221177





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XClearArea(_d_i_s_p_l_a_y, _w, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _e_x_p_o_s_u_r_e_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      Bool _e_x_p_o_s_u_r_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the window and specify the
          upper‐left corner of the rectangle.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the dimen­
          sions of the rectangle.

_e_x_p_o_s_u_r_e_s Specifies a Boolean value that indicates if _E_x_p_o_s_e
          events are to be generated.
││__

The _X_C_l_e_a_r_A_r_e_a function paints a rectangular area in the
specified window according to the specified dimensions with
the window’s background pixel or pixmap.  The subwindow‐mode
effectively is _C_l_i_p_B_y_C_h_i_l_d_r_e_n.  If width is zero, it is
replaced with the current width of the window minus x.  If
height is zero, it is replaced with the current height of
the window minus y.  If the window has a defined background
tile, the rectangle clipped by any children is filled with
this tile.  If the window has background _N_o_n_e, the contents
of the window are not changed.  In either case, if exposures
is _T_r_u_e, one or more _E_x_p_o_s_e events are generated for regions
of the rectangle that are either visible or are being
retained in a backing store.  If you specify a window whose
class is _I_n_p_u_t_O_n_l_y, a _B_a_d_M_a_t_c_h error results.

_X_C_l_e_a_r_A_r_e_a can generate _B_a_d_M_a_t_c_h, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w
errors.


To clear the entire area in a given window, use _X_C_l_e_a_r_W_i_n_­
_d_o_w.










                             221188





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XClearWindow(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_C_l_e_a_r_W_i_n_d_o_w function clears the entire area in the
specified window and is equivalent to _X_C_l_e_a_r_A_r_e_a (display,
w, 0, 0, 0, 0, _F_a_l_s_e).  If the window has a defined back­
ground tile, the rectangle is tiled with a plane‐mask of all
ones and _G_X_c_o_p_y function.  If the window has background
_N_o_n_e, the contents of the window are not changed.  If you
specify a window whose class is _I_n_p_u_t_O_n_l_y, a _B_a_d_M_a_t_c_h error
results.

_X_C_l_e_a_r_W_i_n_d_o_w can generate _B_a_d_M_a_t_c_h and _B_a_d_W_i_n_d_o_w errors.

88..22..  CCooppyyiinngg AArreeaass

Xlib provides functions that you can use to copy an area or
a bit plane.


To copy an area between drawables of the same root and
depth, use _X_C_o_p_y_A_r_e_a.



























                             221199





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XCopyArea(_d_i_s_p_l_a_y, _s_r_c, _d_e_s_t, _g_c, _s_r_c___x, _s_r_c___y, _w_i_d_t_h, _h_e_i_g_h_t,  _d_e_s_t___x, _d_e_s_t___y)
      Display *_d_i_s_p_l_a_y;
      Drawable _s_r_c, _d_e_s_t;
      GC _g_c;
      int _s_r_c___x, _s_r_c___y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      int _d_e_s_t___x, _d_e_s_t___y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_r_c
_d_e_s_t      Specify the source and destination rectangles to
          be combined.

_g_c        Specifies the GC.

_s_r_c___x
_s_r_c___y     Specify the x and y coordinates, which are rela­
          tive to the origin of the source rectangle and
          specify its upper‐left corner.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the dimen­
          sions of both the source and destination rectan­
          gles.

_d_e_s_t___x
_d_e_s_t___y    Specify the x and y coordinates, which are rela­
          tive to the origin of the destination rectangle
          and specify its upper‐left corner.
││__

The _X_C_o_p_y_A_r_e_a function combines the specified rectangle of
src with the specified rectangle of dest.  The drawables
must have the same root and depth, or a _B_a_d_M_a_t_c_h error
results.

If regions of the source rectangle are obscured and have not
been retained in backing store or if regions outside the
boundaries of the source drawable are specified, those
regions are not copied.  Instead, the following occurs on
all corresponding destination regions that are either visi­
ble or are retained in backing store.  If the destination is
a window with a background other than _N_o_n_e, corresponding
regions of the destination are tiled with that background
(with plane‐mask of all ones and _G_X_c_o_p_y function).  Regard­
less of tiling or whether the destination is a window or a
pixmap, if graphics‐exposures is _T_r_u_e, then _G_r_a_p_h_i_c_s_E_x_p_o_s_e
events for all corresponding destination regions are gener­
ated.  If graphics‐exposures is _T_r_u_e but no _G_r_a_p_h_i_c_s_E_x_p_o_s_e
events are generated, a _N_o_E_x_p_o_s_e event is generated.  Note
that by default graphics‐exposures is _T_r_u_e in new GCs.



                             222200





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


This function uses these GC components: function, plane‐
mask, subwindow‐mode, graphics‐exposures, clip‐x‐origin,
clip‐y‐origin, and clip‐mask.

_X_C_o_p_y_A_r_e_a can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, and _B_a_d_M_a_t_c_h
errors.


To copy a single bit plane of a given drawable, use _X_C_o_p_y_­
_P_l_a_n_e.
__
││
XCopyPlane(_d_i_s_p_l_a_y, _s_r_c, _d_e_s_t, _g_c, _s_r_c___x, _s_r_c___y, _w_i_d_t_h, _h_e_i_g_h_t, _d_e_s_t___x, _d_e_s_t___y, _p_l_a_n_e)
      Display *_d_i_s_p_l_a_y;
      Drawable _s_r_c, _d_e_s_t;
      GC _g_c;
      int _s_r_c___x, _s_r_c___y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      int _d_e_s_t___x, _d_e_s_t___y;
      unsigned long _p_l_a_n_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_r_c
_d_e_s_t      Specify the source and destination rectangles to
          be combined.

_g_c        Specifies the GC.

_s_r_c___x
_s_r_c___y     Specify the x and y coordinates, which are rela­
          tive to the origin of the source rectangle and
          specify its upper‐left corner.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the dimen­
          sions of both the source and destination rectan­
          gles.

_d_e_s_t___x
_d_e_s_t___y    Specify the x and y coordinates, which are rela­
          tive to the origin of the destination rectangle
          and specify its upper‐left corner.

_p_l_a_n_e     Specifies the bit plane.  You must set exactly one
          bit to 1.
││__

The _X_C_o_p_y_P_l_a_n_e function uses a single bit plane of the spec­
ified source rectangle combined with the specified GC to
modify the specified rectangle of dest.  The drawables must
have the same root but need not have the same depth.  If the
drawables do not have the same root, a _B_a_d_M_a_t_c_h error



                             222211





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


results.  If plane does not have exactly one bit set to 1
and the value of plane is not less than 2_n, where _n is the
depth of src, a _B_a_d_V_a_l_u_e error results.

Effectively, _X_C_o_p_y_P_l_a_n_e forms a pixmap of the same depth as
the rectangle of dest and with a size specified by the
source region.  It uses the foreground/background pixels in
the GC (foreground everywhere the bit plane in src contains
a bit set to 1, background everywhere the bit plane in src
contains a bit set to 0) and the equivalent of a _C_o_p_y_A_r_e_a
protocol request is performed with all the same exposure
semantics.  This can also be thought of as using the speci­
fied region of the source bit plane as a stipple with a
fill‐style of _F_i_l_l_O_p_a_q_u_e_S_t_i_p_p_l_e_d for filling a rectangular
area of the destination.

This function uses these GC components: function, plane‐
mask, foreground, background, subwindow‐mode, graphics‐expo­
sures, clip‐x‐origin, clip‐y‐origin, and clip‐mask.

_X_C_o_p_y_P_l_a_n_e can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, _B_a_d_M_a_t_c_h, and
_B_a_d_V_a_l_u_e errors.

88..33..  DDrraawwiinngg PPooiinnttss,, LLiinneess,, RReeccttaanngglleess,, aanndd AArrccss

Xlib provides functions that you can use to draw:

⋅    A single point or multiple points

⋅    A single line or multiple lines

⋅    A single rectangle or multiple rectangles

⋅    A single arc or multiple arcs

Some of the functions described in the following sections
use these structures:

__
││
typedef struct {
     short x1, y1, x2, y2;
} XSegment;

││__












                             222222





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     short x, y;
} XPoint;

││__

__
││
typedef struct {
     short x, y;
     unsigned short width, height;
} XRectangle;

││__

__
││
typedef struct {
     short x, y;
     unsigned short width, height;
     short angle1, angle2;             /* Degrees * 64 */
} XArc;

││__

All x and y members are signed integers.  The width and
height members are 16‐bit unsigned integers.  You should be
careful not to generate coordinates and sizes out of the
16‐bit ranges, because the protocol only has 16‐bit fields
for these values.

88..33..11..  DDrraawwiinngg SSiinnggllee aanndd MMuullttiippllee PPooiinnttss


To draw a single point in a given drawable, use _X_D_r_a_w_P_o_i_n_t.





















                             222233





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawPoint(_d_i_s_p_l_a_y, _d, _g_c, _x, _y)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates where you want the
          point drawn.
││__


To draw multiple points in a given drawable, use _X_D_r_a_w_­
_P_o_i_n_t_s.
__
││
XDrawPoints(_d_i_s_p_l_a_y, _d, _g_c, _p_o_i_n_t_s, _n_p_o_i_n_t_s, _m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      XPoint *_p_o_i_n_t_s;
      int _n_p_o_i_n_t_s;
      int _m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_p_o_i_n_t_s    Specifies an array of points.

_n_p_o_i_n_t_s   Specifies the number of points in the array.

_m_o_d_e      Specifies the coordinate mode.  You can pass
          _C_o_o_r_d_M_o_d_e_O_r_i_g_i_n or _C_o_o_r_d_M_o_d_e_P_r_e_v_i_o_u_s.
││__

The _X_D_r_a_w_P_o_i_n_t function uses the foreground pixel and func­
tion components of the GC to draw a single point into the
specified drawable; _X_D_r_a_w_P_o_i_n_t_s draws multiple points this
way.  _C_o_o_r_d_M_o_d_e_O_r_i_g_i_n treats all coordinates as relative to
the origin, and _C_o_o_r_d_M_o_d_e_P_r_e_v_i_o_u_s treats all coordinates
after the first as relative to the previous point.  _X_D_r_a_w_­
_P_o_i_n_t_s draws the points in the order listed in the array.



                             222244





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Both functions use these GC components: function, plane‐
mask, foreground, subwindow‐mode, clip‐x‐origin, clip‐y‐ori­
gin, and clip‐mask.

_X_D_r_a_w_P_o_i_n_t can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, and _B_a_d_M_a_t_c_h
errors.  _X_D_r_a_w_P_o_i_n_t_s can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, _B_a_d_­
_M_a_t_c_h, and _B_a_d_V_a_l_u_e errors.

88..33..22..  DDrraawwiinngg SSiinnggllee aanndd MMuullttiippllee LLiinneess


To draw a single line between two points in a given draw­
able, use _X_D_r_a_w_L_i_n_e.
__
││
XDrawLine(_d_i_s_p_l_a_y, _d, _g_c, _x_1, _y_1, _x_2, _y_2)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x_1, _y_1, _x_2, _y_2;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x_1
_y_1
_x_2
_y_2        Specify the points (x1, y1) and (x2, y2) to be
          connected.
││__


To draw multiple lines in a given drawable, use _X_D_r_a_w_L_i_n_e_s.




















                             222255





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawLines(_d_i_s_p_l_a_y, _d, _g_c, _p_o_i_n_t_s, _n_p_o_i_n_t_s, _m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      XPoint *_p_o_i_n_t_s;
      int _n_p_o_i_n_t_s;
      int _m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_p_o_i_n_t_s    Specifies an array of points.

_n_p_o_i_n_t_s   Specifies the number of points in the array.

_m_o_d_e      Specifies the coordinate mode.  You can pass
          _C_o_o_r_d_M_o_d_e_O_r_i_g_i_n or _C_o_o_r_d_M_o_d_e_P_r_e_v_i_o_u_s.
││__


To draw multiple, unconnected lines in a given drawable, use
_X_D_r_a_w_S_e_g_m_e_n_t_s.
__
││
XDrawSegments(_d_i_s_p_l_a_y, _d, _g_c, _s_e_g_m_e_n_t_s, _n_s_e_g_m_e_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      XSegment *_s_e_g_m_e_n_t_s;
      int _n_s_e_g_m_e_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_s_e_g_m_e_n_t_s  Specifies an array of segments.

_n_s_e_g_m_e_n_t_s Specifies the number of segments in the array.
││__

The _X_D_r_a_w_L_i_n_e function uses the components of the specified
GC to draw a line between the specified set of points (x1,
y1) and (x2, y2).  It does not perform joining at coincident
endpoints.  For any given line, _X_D_r_a_w_L_i_n_e does not draw a
pixel more than once.  If lines intersect, the intersecting
pixels are drawn multiple times.



                             222266





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The _X_D_r_a_w_L_i_n_e_s function uses the components of the specified
GC to draw npoints−1 lines between each pair of points
(point[i], point[i+1]) in the array of _X_P_o_i_n_t structures.
It draws the lines in the order listed in the array.  The
lines join correctly at all intermediate points, and if the
first and last points coincide, the first and last lines
also join correctly.  For any given line, _X_D_r_a_w_L_i_n_e_s does
not draw a pixel more than once.  If thin (zero line‐width)
lines intersect, the intersecting pixels are drawn multiple
times.  If wide lines intersect, the intersecting pixels are
drawn only once, as though the entire _P_o_l_y_L_i_n_e protocol
request were a single, filled shape.  _C_o_o_r_d_M_o_d_e_O_r_i_g_i_n treats
all coordinates as relative to the origin, and _C_o_o_r_d_M_o_d_e_P_r_e_­
_v_i_o_u_s treats all coordinates after the first as relative to
the previous point.

The _X_D_r_a_w_S_e_g_m_e_n_t_s function draws multiple, unconnected
lines.  For each segment, _X_D_r_a_w_S_e_g_m_e_n_t_s draws a line between
(x1, y1) and (x2, y2).  It draws the lines in the order
listed in the array of _X_S_e_g_m_e_n_t structures and does not per­
form joining at coincident endpoints.  For any given line,
_X_D_r_a_w_S_e_g_m_e_n_t_s does not draw a pixel more than once.  If
lines intersect, the intersecting pixels are drawn multiple
times.

All three functions use these GC components: function,
plane‐mask, line‐width, line‐style, cap‐style, fill‐style,
subwindow‐mode, clip‐x‐origin, clip‐y‐origin, and clip‐mask.
The _X_D_r_a_w_L_i_n_e_s function also uses the join‐style GC compo­
nent.  All three functions also use these GC mode‐dependent
components: foreground, background, tile, stipple, tile‐
stipple‐x‐origin, tile‐stipple‐y‐origin, dash‐offset, and
dash‐list.

_X_D_r_a_w_L_i_n_e, _X_D_r_a_w_L_i_n_e_s, and _X_D_r_a_w_S_e_g_m_e_n_t_s can generate _B_a_d_­
_D_r_a_w_a_b_l_e, _B_a_d_G_C, and _B_a_d_M_a_t_c_h errors.  _X_D_r_a_w_L_i_n_e_s also can
generate _B_a_d_V_a_l_u_e errors.

88..33..33..  DDrraawwiinngg SSiinnggllee aanndd MMuullttiippllee RReeccttaanngglleess


To draw the outline of a single rectangle in a given draw­
able, use _X_D_r_a_w_R_e_c_t_a_n_g_l_e.














                             222277





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawRectangle(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which specify the
          upper‐left corner of the rectangle.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which specify the
          dimensions of the rectangle.
││__


To draw the outline of multiple rectangles in a given draw­
able, use _X_D_r_a_w_R_e_c_t_a_n_g_l_e_s.
__
││
XDrawRectangles(_d_i_s_p_l_a_y, _d, _g_c, _r_e_c_t_a_n_g_l_e_s, _n_r_e_c_t_a_n_g_l_e_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      XRectangle _r_e_c_t_a_n_g_l_e_s[];
      int _n_r_e_c_t_a_n_g_l_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_r_e_c_t_a_n_g_l_e_s
          Specifies an array of rectangles.

_n_r_e_c_t_a_n_g_l_e_s
          Specifies the number of rectangles in the array.
││__

The _X_D_r_a_w_R_e_c_t_a_n_g_l_e and _X_D_r_a_w_R_e_c_t_a_n_g_l_e_s functions draw the
outlines of the specified rectangle or rectangles as if a
five‐point _P_o_l_y_L_i_n_e protocol request were specified for each
rectangle:



                             222288





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


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

For the specified rectangle or rectangles, these functions
do not draw a pixel more than once.  _X_D_r_a_w_R_e_c_t_a_n_g_l_e_s draws
the rectangles in the order listed in the array.  If rectan­
gles intersect, the intersecting pixels are drawn multiple
times.

Both functions use these GC components: function, plane‐
mask, line‐width, line‐style, cap‐style, join‐style, fill‐
style, subwindow‐mode, clip‐x‐origin, clip‐y‐origin, and
clip‐mask.  They also use these GC mode‐dependent compo­
nents: foreground, background, tile, stipple, tile‐stipple‐
x‐origin, tile‐stipple‐y‐origin, dash‐offset, and dash‐list.

_X_D_r_a_w_R_e_c_t_a_n_g_l_e and _X_D_r_a_w_R_e_c_t_a_n_g_l_e_s can generate _B_a_d_D_r_a_w_a_b_l_e,
_B_a_d_G_C, and _B_a_d_M_a_t_c_h errors.

88..33..44..  DDrraawwiinngg SSiinnggllee aanndd MMuullttiippllee AArrccss



To draw a single arc in a given drawable, use _X_D_r_a_w_A_r_c.


































                             222299





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawArc(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _a_n_g_l_e_1, _a_n_g_l_e_2)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      int _a_n_g_l_e_1, _a_n_g_l_e_2;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the drawable and specify the
          upper‐left corner of the bounding rectangle.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the major
          and minor axes of the arc.

_a_n_g_l_e_1    Specifies the start of the arc relative to the
          three‐o’clock position from the center, in units
          of degrees * 64.

_a_n_g_l_e_2    Specifies the path and extent of the arc relative
          to the start of the arc, in units of degrees * 64.
││__


To draw multiple arcs in a given drawable, use _X_D_r_a_w_A_r_c_s.






















                             223300





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawArcs(_d_i_s_p_l_a_y, _d, _g_c, _a_r_c_s, _n_a_r_c_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      XArc *_a_r_c_s;
      int _n_a_r_c_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_a_r_c_s      Specifies an array of arcs.

_n_a_r_c_s     Specifies the number of arcs in the array.
││__

_X_D_r_a_w_A_r_c draws a single circular or elliptical arc, and
_X_D_r_a_w_A_r_c_s draws multiple circular or elliptical arcs.  Each
arc is specified by a rectangle and two angles.  The center
of the circle or ellipse is the center of the rectangle, and
the major and minor axes are specified by the width and
height.  Positive angles indicate counterclockwise motion,
and negative angles indicate clockwise motion.  If the mag­
nitude of angle2 is greater than 360 degrees, _X_D_r_a_w_A_r_c or
_X_D_r_a_w_A_r_c_s truncates it to 360 degrees.

For an arc specified as [_x,_y,_w_i_d_t_h,_h_e_i_g_h_t,_a_n_g_l_e1,_a_n_g_l_e2],
the origin of the major and minor axes is at
[_x+_w___i___d2___t___h__,_y+_h___e___i___g2___h___t__], and the infinitely thin path describing
the entire circle or ellipse intersects the horizontal axis
at [_x,_y+_h___e___i___g2___h___t__] and [_x+_w_i_d_t_h,_y+_h___e___i___g2___h___t__] and intersects the
vertical axis at [_x+_w___i___d2___t___h__,_y] and [_x+_w___i___d2___t___h__,_y+_h_e_i_g_h_t].  These
coordinates can be fractional and so are not truncated to
discrete coordinates.  The path should be defined by the
ideal mathematical path.  For a wide line with line‐width
lw, the bounding outlines for filling are given by the two
infinitely thin paths consisting of all points whose perpen­
dicular distance from the path of the circle/ellipse is
equal to lw/2 (which may be a fractional value).  The cap‐
style and join‐style are applied the same as for a line cor­
responding to the tangent of the circle/ellipse at the end­
point.

For an arc specified as [_x,_y,_w_i_d_t_h,_h_e_i_g_h_t,_a_n_g_l_e1,_a_n_g_l_e2],
the angles must be specified in the effectively skewed coor­
dinate system of the ellipse (for a circle, the angles and
coordinate systems are identical).  The relationship between
these angles and angles expressed in the normal coordinate
system of the screen (as measured with a protractor) is as
follows:



                             223311





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     skewed‐angle=_a_t_a_n(tan(normal‐angle)*_h___w_e___i_i___d_g___t_h___h_t__)+_a_d_j_u_s_t


The skewed‐angle and normal‐angle are expressed in radians
(rather than in degrees scaled by 64) in the range [0,2π]
and where atan returns a value in the range [−π2__,π2__] and
adjust is:


     0         for normal‐angle in the range [0,π2__]
     π         for normal‐angle in the range [π2__,3__π2__]
     2π        for normal‐angle in the range [3__π2__,2π]


For any given arc, _X_D_r_a_w_A_r_c and _X_D_r_a_w_A_r_c_s do not draw a
pixel more than once.  If two arcs join correctly and if the
line‐width is greater than zero and the arcs intersect,
_X_D_r_a_w_A_r_c and _X_D_r_a_w_A_r_c_s do not draw a pixel more than once.
Otherwise, the intersecting pixels of intersecting arcs are
drawn multiple times.  Specifying an arc with one endpoint
and a clockwise extent draws the same pixels as specifying
the other endpoint and an equivalent counterclockwise
extent, except as it affects joins.

If the last point in one arc coincides with the first point
in the following arc, the two arcs will join correctly.  If
the first point in the first arc coincides with the last
point in the last arc, the two arcs will join correctly.  By
specifying one axis to be zero, a horizontal or vertical
line can be drawn.  Angles are computed based solely on the
coordinate system and ignore the aspect ratio.

Both functions use these GC components: function, plane‐
mask, line‐width, line‐style, cap‐style, join‐style, fill‐
style, subwindow‐mode, clip‐x‐origin, clip‐y‐origin, and
clip‐mask.  They also use these GC mode‐dependent compo­
nents: foreground, background, tile, stipple, tile‐stipple‐
x‐origin, tile‐stipple‐y‐origin, dash‐offset, and dash‐list.

_X_D_r_a_w_A_r_c and _X_D_r_a_w_A_r_c_s can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, and
_B_a_d_M_a_t_c_h errors.

88..44..  FFiilllliinngg AArreeaass

Xlib provides functions that you can use to fill:

⋅    A single rectangle or multiple rectangles

⋅    A single polygon

⋅    A single arc or multiple arcs






                             223322





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


88..44..11..  FFiilllliinngg SSiinnggllee aanndd MMuullttiippllee RReeccttaanngglleess



To fill a single rectangular area in a given drawable, use
_X_F_i_l_l_R_e_c_t_a_n_g_l_e.
__
││
XFillRectangle(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the drawable and specify the
          upper‐left corner of the rectangle.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the dimen­
          sions of the rectangle to be filled.
││__


To fill multiple rectangular areas in a given drawable, use
_X_F_i_l_l_R_e_c_t_a_n_g_l_e_s.






















                             223333





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XFillRectangles(_d_i_s_p_l_a_y, _d, _g_c, _r_e_c_t_a_n_g_l_e_s, _n_r_e_c_t_a_n_g_l_e_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      XRectangle *_r_e_c_t_a_n_g_l_e_s;
      int _n_r_e_c_t_a_n_g_l_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_r_e_c_t_a_n_g_l_e_s
          Specifies an array of rectangles.

_n_r_e_c_t_a_n_g_l_e_s
          Specifies the number of rectangles in the array.
││__

The _X_F_i_l_l_R_e_c_t_a_n_g_l_e and _X_F_i_l_l_R_e_c_t_a_n_g_l_e_s functions fill the
specified rectangle or rectangles as if a four‐point
_F_i_l_l_P_o_l_y_g_o_n protocol request were specified for each rectan­
gle:


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


Each function uses the x and y coordinates, width and height
dimensions, and GC you specify.

_X_F_i_l_l_R_e_c_t_a_n_g_l_e_s fills the rectangles in the order listed in
the array.  For any given rectangle, _X_F_i_l_l_R_e_c_t_a_n_g_l_e and
_X_F_i_l_l_R_e_c_t_a_n_g_l_e_s do not draw a pixel more than once.  If
rectangles intersect, the intersecting pixels are drawn mul­
tiple times.

Both functions use these GC components: function, plane‐
mask, fill‐style, subwindow‐mode, clip‐x‐origin, clip‐y‐ori­
gin, and clip‐mask.  They also use these GC mode‐dependent
components: foreground, background, tile, stipple, tile‐
stipple‐x‐origin, and tile‐stipple‐y‐origin.

_X_F_i_l_l_R_e_c_t_a_n_g_l_e and _X_F_i_l_l_R_e_c_t_a_n_g_l_e_s can generate _B_a_d_D_r_a_w_a_b_l_e,
_B_a_d_G_C, and _B_a_d_M_a_t_c_h errors.

88..44..22..  FFiilllliinngg aa SSiinnggllee PPoollyyggoonn


To fill a polygon area in a given drawable, use _X_F_i_l_l_P_o_l_y_­
_g_o_n.



                             223344





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XFillPolygon(_d_i_s_p_l_a_y, _d, _g_c, _p_o_i_n_t_s, _n_p_o_i_n_t_s, _s_h_a_p_e, _m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      XPoint *_p_o_i_n_t_s;
      int _n_p_o_i_n_t_s;
      int _s_h_a_p_e;
      int _m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_p_o_i_n_t_s    Specifies an array of points.

_n_p_o_i_n_t_s   Specifies the number of points in the array.

_s_h_a_p_e     Specifies a shape that helps the server to improve
          performance.  You can pass _C_o_m_p_l_e_x, _C_o_n_v_e_x, or
          _N_o_n_c_o_n_v_e_x.

_m_o_d_e      Specifies the coordinate mode.  You can pass
          _C_o_o_r_d_M_o_d_e_O_r_i_g_i_n or _C_o_o_r_d_M_o_d_e_P_r_e_v_i_o_u_s.
││__

_X_F_i_l_l_P_o_l_y_g_o_n fills the region closed by the specified path.
The path is closed automatically if the last point in the
list does not coincide with the first point.  _X_F_i_l_l_P_o_l_y_g_o_n
does not draw a pixel of the region more than once.  _C_o_o_r_d_­
_M_o_d_e_O_r_i_g_i_n treats all coordinates as relative to the origin,
and _C_o_o_r_d_M_o_d_e_P_r_e_v_i_o_u_s treats all coordinates after the first
as relative to the previous point.

Depending on the specified shape, the following occurs:

⋅    If shape is _C_o_m_p_l_e_x, the path may self‐intersect.  Note
     that contiguous coincident points in the path are not
     treated as self‐intersection.

⋅    If shape is _C_o_n_v_e_x, for every pair of points inside the
     polygon, the line segment connecting them does not
     intersect the path.  If known by the client, specifying
     _C_o_n_v_e_x can improve performance.  If you specify _C_o_n_v_e_x
     for a path that is not convex, the graphics results are
     undefined.

⋅    If shape is _N_o_n_c_o_n_v_e_x, the path does not self‐inter­
     sect, but the shape is not wholly convex.  If known by
     the client, specifying _N_o_n_c_o_n_v_e_x instead of _C_o_m_p_l_e_x may
     improve performance.  If you specify _N_o_n_c_o_n_v_e_x for a



                             223355





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     self‐intersecting path, the graphics results are unde­
     fined.

The fill‐rule of the GC controls the filling behavior of
self‐intersecting polygons.

This function uses these GC components: function, plane‐
mask, fill‐style, fill‐rule, subwindow‐mode, clip‐x‐origin,
clip‐y‐origin, and clip‐mask.  It also uses these GC mode‐
dependent components: foreground, background, tile, stipple,
tile‐stipple‐x‐origin, and tile‐stipple‐y‐origin.

_X_F_i_l_l_P_o_l_y_g_o_n can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, _B_a_d_M_a_t_c_h, and
_B_a_d_V_a_l_u_e errors.

88..44..33..  FFiilllliinngg SSiinnggllee aanndd MMuullttiippllee AArrccss

To fill a single arc in a given drawable, use _X_F_i_l_l_A_r_c.
__
││
XFillArc(_d_i_s_p_l_a_y, _d, _g_c,  _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _a_n_g_l_e_1, _a_n_g_l_e_2)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      int _a_n_g_l_e_1, _a_n_g_l_e_2;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the drawable and specify the
          upper‐left corner of the bounding rectangle.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which are the major
          and minor axes of the arc.

_a_n_g_l_e_1    Specifies the start of the arc relative to the
          three‐o’clock position from the center, in units
          of degrees * 64.

_a_n_g_l_e_2    Specifies the path and extent of the arc relative
          to the start of the arc, in units of degrees * 64.
││__


To fill multiple arcs in a given drawable, use _X_F_i_l_l_A_r_c_s.



                             223366





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XFillArcs(_d_i_s_p_l_a_y, _d, _g_c, _a_r_c_s, _n_a_r_c_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      XArc *_a_r_c_s;
      int _n_a_r_c_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_a_r_c_s      Specifies an array of arcs.

_n_a_r_c_s     Specifies the number of arcs in the array.
││__

For each arc, _X_F_i_l_l_A_r_c or _X_F_i_l_l_A_r_c_s fills the region closed
by the infinitely thin path described by the specified arc
and, depending on the arc‐mode specified in the GC, one or
two line segments.  For _A_r_c_C_h_o_r_d, the single line segment
joining the endpoints of the arc is used.  For _A_r_c_P_i_e_S_l_i_c_e,
the two line segments joining the endpoints of the arc with
the center point are used.  _X_F_i_l_l_A_r_c_s fills the arcs in the
order listed in the array.  For any given arc, _X_F_i_l_l_A_r_c and
_X_F_i_l_l_A_r_c_s do not draw a pixel more than once.  If regions
intersect, the intersecting pixels are drawn multiple times.

Both functions use these GC components: function, plane‐
mask, fill‐style, arc‐mode, subwindow‐mode, clip‐x‐origin,
clip‐y‐origin, and clip‐mask.  They also use these GC mode‐
dependent components: foreground, background, tile, stipple,
tile‐stipple‐x‐origin, and tile‐stipple‐y‐origin.

_X_F_i_l_l_A_r_c and _X_F_i_l_l_A_r_c_s can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, and
_B_a_d_M_a_t_c_h errors.

88..55..  FFoonntt MMeettrriiccss

A font is a graphical description of a set of characters
that are used to increase efficiency whenever a set of
small, similar sized patterns are repeatedly used.

This section discusses how to:

⋅    Load and free fonts

⋅    Obtain and free font names

⋅    Compute character string sizes




                             223377





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    Compute logical extents

⋅    Query character string sizes

The X server loads fonts whenever a program requests a new
font.  The server can cache fonts for quick lookup.  Fonts
are global across all screens in a server.  Several levels
are possible when dealing with fonts.  Most applications
simply use _X_L_o_a_d_Q_u_e_r_y_F_o_n_t to load a font and query the font
metrics.

Characters in fonts are regarded as masks.  Except for image
text requests, the only pixels modified are those in which
bits are set to 1 in the character.  This means that it
makes sense to draw text using stipples or tiles (for exam­
ple, many menus gray‐out unusable entries).









































                             223388





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││    The _X_F_o_n_t_S_t_r_u_c_t structure contains all of the information
for the font and consists of the font‐specific information
as well as a pointer to an array of _X_C_h_a_r_S_t_r_u_c_t structures
for the characters contained in the font.  The _X_F_o_n_t_S_t_r_u_c_t,
_X_F_o_n_t_P_r_o_p, and _X_C_h_a_r_S_t_r_u_c_t structures contain:


typedef struct {
     short lbearing;          /* origin to left edge of raster */
     short rbearing;          /* origin to right edge of raster */
     short width;             /* advance to next char’s origin */
     short ascent;            /* baseline to top edge of raster */
     short descent;           /* baseline to bottom edge of raster */
     unsigned short attributes;/* per char flags (not predefined) */
} XCharStruct;



typedef struct {
     Atom name;
     unsigned long card32;
} XFontProp;



typedef struct {              /* normal 16 bit characters are two bytes */
    unsigned char byte1;
    unsigned char byte2;
} XChar2b;



typedef struct {
     XExtData *ext_data;      /* hook for extension to hang data */
     Font fid;                /* Font id for this font */
     unsigned direction;      /* hint about the direction font is painted */
     unsigned min_char_or_byte2;/* first character */
     unsigned max_char_or_byte2;/* last character */
     unsigned min_byte1;      /* first row that exists */
     unsigned max_byte1;      /* last row that exists */
     Bool all_chars_exist;    /* flag if all characters have nonzero size */
     unsigned default_char;   /* char to print for undefined character */
     int n_properties;        /* how many properties there are */
     XFontProp *properties;   /* pointer to array of additional properties */
     XCharStruct min_bounds;  /* minimum bounds over all existing char */
     XCharStruct max_bounds;  /* maximum bounds over all existing char */
     XCharStruct *per_char;   /* first_char to last_char information */
     int ascent;              /* logical extent above baseline for spacing */
     int descent;             /* logical descent below baseline for spacing */
} XFontStruct;

││__

X supports single byte/character, two bytes/character



                             223399





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


matrix, and 16‐bit character text operations.  Note that any
of these forms can be used with a font, but a single
byte/character text request can only specify a single byte
(that is, the first row of a 2‐byte font).  You should view
2‐byte fonts as a two‐dimensional matrix of defined charac­
ters: byte1 specifies the range of defined rows and byte2
defines the range of defined columns of the font.  Single
byte/character fonts have one row defined, and the byte2
range specified in the structure defines a range of charac­
ters.

The bounding box of a character is defined by the
_X_C_h_a_r_S_t_r_u_c_t of that character.  When characters are absent
from a font, the default_char is used.  When fonts have all
characters of the same size, only the information in the
_X_F_o_n_t_S_t_r_u_c_t min and max bounds are used.

The members of the _X_F_o_n_t_S_t_r_u_c_t have the following semantics:

⋅    The direction member can be either _F_o_n_t_L_e_f_t_T_o_R_i_g_h_t or
     _F_o_n_t_R_i_g_h_t_T_o_L_e_f_t.  It is just a hint as to whether most
     _X_C_h_a_r_S_t_r_u_c_t elements have a positive (_F_o_n_t_L_e_f_t_T_o_R_i_g_h_t)
     or a negative (_F_o_n_t_R_i_g_h_t_T_o_L_e_f_t) character width metric.
     The core protocol defines no support for vertical text.

⋅    If the min_byte1 and max_byte1 members are both zero,
     min_char_or_byte2 specifies the linear character index
     corresponding to the first element of the per_char
     array, and max_char_or_byte2 specifies the linear char­
     acter index of the last element.

     If either min_byte1 or max_byte1 are nonzero, both
     min_char_or_byte2 and max_char_or_byte2 are less than
     256, and the 2‐byte character index values correspond­
     ing to the per_char array element N (counting from 0)
     are:

          byte1 = N/D + min_byte1
          byte2 = N\D + min_char_or_byte2

     where:

             D = max_char_or_byte2 − min_char_or_byte2 + 1
             / = integer division
             \ = integer modulus

⋅    If the per_char pointer is NULL, all glyphs between the
     first and last character indexes inclusive have the
     same information, as given by both min_bounds and
     max_bounds.

⋅    If all_chars_exist is _T_r_u_e, all characters in the
     per_char array have nonzero bounding boxes.




                             224400





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    The default_char member specifies the character that
     will be used when an undefined or nonexistent character
     is printed.  The default_char is a 16‐bit character
     (not a 2‐byte character).  For a font using 2‐byte
     matrix format, the default_char has byte1 in the most‐
     significant byte and byte2 in the least significant
     byte.  If the default_char itself specifies an unde­
     fined or nonexistent character, no printing is per­
     formed for an undefined or nonexistent character.

⋅    The min_bounds and max_bounds members contain the most
     extreme values of each individual _X_C_h_a_r_S_t_r_u_c_t component
     over all elements of this array (and ignore nonexistent
     characters).  The bounding box of the font (the small­
     est rectangle enclosing the shape obtained by superim­
     posing all of the characters at the same origin [x,y])
     has its upper‐left coordinate at:

               [x + min_bounds.lbearing, y − max_bounds.ascent]


     Its width is:

               max_bounds.rbearing − min_bounds.lbearing


     Its height is:

               max_bounds.ascent + max_bounds.descent


⋅    The ascent member is the logical extent of the font
     above the baseline that is used for determining line
     spacing.  Specific characters may extend beyond this.

⋅    The descent member is the logical extent of the font at
     or below the baseline that is used for determining line
     spacing.  Specific characters may extend beyond this.

⋅    If the baseline is at Y‐coordinate y, the logical
     extent of the font is inclusive between the Y‐coordi­
     nate values (y − font.ascent) and (y + font.descent −
     1).  Typically, the minimum interline spacing between
     rows of text is given by ascent + descent.

For a character origin at [x,y], the bounding box of a char­
acter (that is, the smallest rectangle that encloses the
character’s shape) described in terms of _X_C_h_a_r_S_t_r_u_c_t compo­
nents is a rectangle with its upper‐left corner at:


     [x + lbearing, y − ascent]





                             224411





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Its width is:


     rbearing − lbearing


Its height is:


     ascent + descent


The origin for the next character is defined to be:


     [x + width, y]


The lbearing member defines the extent of the left edge of
the character ink from the origin.  The rbearing member
defines the extent of the right edge of the character ink
from the origin.  The ascent member defines the extent of
the top edge of the character ink from the origin.  The
descent member defines the extent of the bottom edge of the
character ink from the origin.  The width member defines the
logical width of the character.

Note that the baseline (the y position of the character ori­
gin) is logically viewed as being the scanline just below
nondescending characters.  When descent is zero, only pixels
with Y‐coordinates less than y are drawn, and the origin is
logically viewed as being coincident with the left edge of a
nonkerned character.  When lbearing is zero, no pixels with
X‐coordinate less than x are drawn.  Any of the _X_C_h_a_r_S_t_r_u_c_t
metric members could be negative.  If the width is negative,
the next character will be placed to the left of the current
origin.

The X protocol does not define the interpretation of the
attributes member in the _X_C_h_a_r_S_t_r_u_c_t structure.  A nonexis­
tent character is represented with all members of its
_X_C_h_a_r_S_t_r_u_c_t set to zero.

A font is not guaranteed to have any properties.  The inter­
pretation of the property value (for example, long or
unsigned long) must be derived from _a _p_r_i_o_r_i knowledge of
the property.  A basic set of font properties is specified
in the X Consortium standard _X _L_o_g_i_c_a_l _F_o_n_t _D_e_s_c_r_i_p_t_i_o_n _C_o_n_­
_v_e_n_t_i_o_n_s.

88..55..11..  LLooaaddiinngg aanndd FFrreeeeiinngg FFoonnttss

Xlib provides functions that you can use to load fonts, get
font information, unload fonts, and free font information.



                             224422





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


A few font functions use a _G_C_o_n_t_e_x_t resource ID or a font ID
interchangeably.


To load a given font, use _X_L_o_a_d_F_o_n_t.
__
││
Font XLoadFont(_d_i_s_p_l_a_y, _n_a_m_e)
      Display *_d_i_s_p_l_a_y;
      char *_n_a_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_a_m_e      Specifies the name of the font, which is a null‐
          terminated string.
││__

The _X_L_o_a_d_F_o_n_t function loads the specified font and returns
its associated font ID.  If the font name is not in the Host
Portable Character Encoding, the result is implementation‐
dependent.  Use of uppercase or lowercase does not matter.
When the characters ‘‘?’’ and ‘‘*’’ are used in a font name,
a pattern match is performed and any matching font is used.
In the pattern, the ‘‘?’’ character will match any single
character, and the ‘‘*’’ character will match any number of
characters.  A structured format for font names is specified
in the X Consortium standard _X _L_o_g_i_c_a_l _F_o_n_t _D_e_s_c_r_i_p_t_i_o_n _C_o_n_­
_v_e_n_t_i_o_n_s.  If _X_L_o_a_d_F_o_n_t was unsuccessful at loading the
specified font, a _B_a_d_N_a_m_e error results.  Fonts are not
associated with a particular screen and can be stored as a
component of any GC.  When the font is no longer needed,
call _X_U_n_l_o_a_d_F_o_n_t.

_X_L_o_a_d_F_o_n_t can generate _B_a_d_A_l_l_o_c and _B_a_d_N_a_m_e errors.


To return information about an available font, use _X_Q_u_e_r_y_­
_F_o_n_t.
__
││
XFontStruct *XQueryFont(_d_i_s_p_l_a_y, _f_o_n_t___I_D)
      Display *_d_i_s_p_l_a_y;
      XID _f_o_n_t___I_D;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_o_n_t___I_D   Specifies the font ID or the _G_C_o_n_t_e_x_t ID.
││__

The _X_Q_u_e_r_y_F_o_n_t function returns a pointer to the _X_F_o_n_t_S_t_r_u_c_t
structure, which contains information associated with the
font.  You can query a font or the font stored in a GC.  The



                             224433





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


font ID stored in the _X_F_o_n_t_S_t_r_u_c_t structure will be the
_G_C_o_n_t_e_x_t ID, and you need to be careful when using this ID
in other functions (see _X_G_C_o_n_t_e_x_t_F_r_o_m_G_C).  If the font does
not exist, _X_Q_u_e_r_y_F_o_n_t returns NULL.  To free this data, use
_X_F_r_e_e_F_o_n_t_I_n_f_o.


To perform a _X_L_o_a_d_F_o_n_t and _X_Q_u_e_r_y_F_o_n_t in a single operation,
use _X_L_o_a_d_Q_u_e_r_y_F_o_n_t.
__
││
XFontStruct *XLoadQueryFont(_d_i_s_p_l_a_y, _n_a_m_e)
      Display *_d_i_s_p_l_a_y;
      char *_n_a_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_a_m_e      Specifies the name of the font, which is a null‐
          terminated string.
││__

The _X_L_o_a_d_Q_u_e_r_y_F_o_n_t function provides the most common way for
accessing a font.  _X_L_o_a_d_Q_u_e_r_y_F_o_n_t both opens (loads) the
specified font and returns a pointer to the appropriate
_X_F_o_n_t_S_t_r_u_c_t structure.  If the font name is not in the Host
Portable Character Encoding, the result is implementation‐
dependent.  If the font does not exist, _X_L_o_a_d_Q_u_e_r_y_F_o_n_t
returns NULL.

_X_L_o_a_d_Q_u_e_r_y_F_o_n_t can generate a _B_a_d_A_l_l_o_c error.


To unload the font and free the storage used by the font
structure that was allocated by _X_Q_u_e_r_y_F_o_n_t or _X_L_o_a_d_Q_u_e_r_y_­
_F_o_n_t, use _X_F_r_e_e_F_o_n_t.
__
││
XFreeFont(_d_i_s_p_l_a_y, _f_o_n_t___s_t_r_u_c_t)
      Display *_d_i_s_p_l_a_y;
      XFontStruct *_f_o_n_t___s_t_r_u_c_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_o_n_t___s_t_r_u_c_t
          Specifies the storage associated with the font.
││__

The _X_F_r_e_e_F_o_n_t function deletes the association between the
font resource ID and the specified font and frees the
_X_F_o_n_t_S_t_r_u_c_t structure.  The font itself will be freed when
no other resource references it.  The data and the font
should not be referenced again.



                             224444





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_F_r_e_e_F_o_n_t can generate a _B_a_d_F_o_n_t error.


To return a given font property, use _X_G_e_t_F_o_n_t_P_r_o_p_e_r_t_y.
__
││
Bool XGetFontProperty(_f_o_n_t___s_t_r_u_c_t, _a_t_o_m, _v_a_l_u_e___r_e_t_u_r_n)
      XFontStruct *_f_o_n_t___s_t_r_u_c_t;
      Atom _a_t_o_m;
      unsigned long *_v_a_l_u_e___r_e_t_u_r_n;


_f_o_n_t___s_t_r_u_c_t
          Specifies the storage associated with the font.

_a_t_o_m      Specifies the atom for the property name you want
          returned.

_v_a_l_u_e___r_e_t_u_r_n
          Returns the value of the font property.
││__

Given the atom for that property, the _X_G_e_t_F_o_n_t_P_r_o_p_e_r_t_y func­
tion returns the value of the specified font property.
_X_G_e_t_F_o_n_t_P_r_o_p_e_r_t_y also returns _F_a_l_s_e if the property was not
defined or _T_r_u_e if it was defined.  A set of predefined
atoms exists for font properties, which can be found in
<_X_1_1_/_X_a_t_o_m_._h>.  This set contains the standard properties
associated with a font.  Although it is not guaranteed, it
is likely that the predefined font properties will be pre­
sent.


To unload a font that was loaded by _X_L_o_a_d_F_o_n_t, use _X_U_n_l_o_a_d_­
_F_o_n_t.
__
││
XUnloadFont(_d_i_s_p_l_a_y, _f_o_n_t)
      Display *_d_i_s_p_l_a_y;
      Font _f_o_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_o_n_t      Specifies the font.
││__

The _X_U_n_l_o_a_d_F_o_n_t function deletes the association between the
font resource ID and the specified font.  The font itself
will be freed when no other resource references it.  The
font should not be referenced again.

_X_U_n_l_o_a_d_F_o_n_t can generate a _B_a_d_F_o_n_t error.




                             224455





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


88..55..22..  OObbttaaiinniinngg aanndd FFrreeeeiinngg FFoonntt NNaammeess aanndd IInnffoorrmmaattiioonn

You obtain font names and information by matching a wildcard
specification when querying a font type for a list of avail­
able sizes and so on.


To return a list of the available font names, use _X_L_i_s_t_­
_F_o_n_t_s.
__
││
char **XListFonts(_d_i_s_p_l_a_y, _p_a_t_t_e_r_n, _m_a_x_n_a_m_e_s, _a_c_t_u_a_l___c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      char *_p_a_t_t_e_r_n;
      int _m_a_x_n_a_m_e_s;
      int *_a_c_t_u_a_l___c_o_u_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_a_t_t_e_r_n   Specifies the null‐terminated pattern string that
          can contain wildcard characters.

_m_a_x_n_a_m_e_s  Specifies the maximum number of names to be
          returned.

_a_c_t_u_a_l___c_o_u_n_t___r_e_t_u_r_n
          Returns the actual number of font names.
││__

The _X_L_i_s_t_F_o_n_t_s function returns an array of available font
names (as controlled by the font search path; see _X_S_e_t_F_o_n_t_­
_P_a_t_h) that match the string you passed to the pattern argu­
ment.  The pattern string can contain any characters, but
each asterisk (*) is a wildcard for any number of charac­
ters, and each question mark (?) is a wildcard for a single
character.  If the pattern string is not in the Host
Portable Character Encoding, the result is implementation‐
dependent.  Use of uppercase or lowercase does not matter.
Each returned string is null‐terminated.  If the data
returned by the server is in the Latin Portable Character
Encoding, then the returned strings are in the Host Portable
Character Encoding.  Otherwise, the result is implementa­
tion‐dependent.  If there are no matching font names, _X_L_i_s_t_­
_F_o_n_t_s returns NULL.  The client should call _X_F_r_e_e_F_o_n_t_N_a_m_e_s
when finished with the result to free the memory.


To free a font name array, use _X_F_r_e_e_F_o_n_t_N_a_m_e_s.








                             224466





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XFreeFontNames(_l_i_s_t)
      char *_l_i_s_t[];


_l_i_s_t      Specifies the array of strings you want to free.
││__

The _X_F_r_e_e_F_o_n_t_N_a_m_e_s function frees the array and strings
returned by _X_L_i_s_t_F_o_n_t_s or _X_L_i_s_t_F_o_n_t_s_W_i_t_h_I_n_f_o.


To obtain the names and information about available fonts,
use _X_L_i_s_t_F_o_n_t_s_W_i_t_h_I_n_f_o.
__
││
char **XListFontsWithInfo(_d_i_s_p_l_a_y, _p_a_t_t_e_r_n, _m_a_x_n_a_m_e_s, _c_o_u_n_t___r_e_t_u_r_n, _i_n_f_o___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      char *_p_a_t_t_e_r_n;
      int _m_a_x_n_a_m_e_s;
      int *_c_o_u_n_t___r_e_t_u_r_n;
      XFontStruct **_i_n_f_o___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_a_t_t_e_r_n   Specifies the null‐terminated pattern string that
          can contain wildcard characters.

_m_a_x_n_a_m_e_s  Specifies the maximum number of names to be
          returned.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the actual number of matched font names.

_i_n_f_o___r_e_t_u_r_n
          Returns the font information.
││__

The _X_L_i_s_t_F_o_n_t_s_W_i_t_h_I_n_f_o function returns a list of font names
that match the specified pattern and their associated font
information.  The list of names is limited to size specified
by maxnames.  The information returned for each font is
identical to what _X_L_o_a_d_Q_u_e_r_y_F_o_n_t would return except that
the per‐character metrics are not returned.  The pattern
string can contain any characters, but each asterisk (*) is
a wildcard for any number of characters, and each question
mark (?) is a wildcard for a single character.  If the pat­
tern string is not in the Host Portable Character Encoding,
the result is implementation‐dependent.  Use of uppercase or
lowercase does not matter.  Each returned string is null‐
terminated.  If the data returned by the server is in the
Latin Portable Character Encoding, then the returned strings
are in the Host Portable Character Encoding.  Otherwise, the



                             224477





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


result is implementation‐dependent.  If there are no match­
ing font names, _X_L_i_s_t_F_o_n_t_s_W_i_t_h_I_n_f_o returns NULL.

To free only the allocated name array, the client should
call _X_F_r_e_e_F_o_n_t_N_a_m_e_s.  To free both the name array and the
font information array or to free just the font information
array, the client should call _X_F_r_e_e_F_o_n_t_I_n_f_o.


To free font structures and font names, use _X_F_r_e_e_F_o_n_t_I_n_f_o.
__
││
XFreeFontInfo(_n_a_m_e_s, _f_r_e_e___i_n_f_o, _a_c_t_u_a_l___c_o_u_n_t)
      char **_n_a_m_e_s;
      XFontStruct *_f_r_e_e___i_n_f_o;
      int _a_c_t_u_a_l___c_o_u_n_t;


_n_a_m_e_s     Specifies the list of font names.


_f_r_e_e___i_n_f_o Specifies the font information.


_a_c_t_u_a_l___c_o_u_n_t
          Specifies the actual number of font names.

││__

The _X_F_r_e_e_F_o_n_t_I_n_f_o function frees a font structure or an
array of font structures and optionally an array of font
names.  If NULL is passed for names, no font names are
freed.  If a font structure for an open font (returned by
_X_L_o_a_d_Q_u_e_r_y_F_o_n_t) is passed, the structure is freed, but the
font is not closed; use _X_U_n_l_o_a_d_F_o_n_t to close the font.

88..55..33..  CCoommppuuttiinngg CChhaarraacctteerr SSttrriinngg SSiizzeess

Xlib provides functions that you can use to compute the
width, the logical extents, and the server information about
8‐bit and 2‐byte text strings.  The width is computed by
adding the character widths of all the characters.  It does
not matter if the font is an 8‐bit or 2‐byte font.  These
functions return the sum of the character metrics in pixels.


To determine the width of an 8‐bit character string, use
_X_T_e_x_t_W_i_d_t_h.









                             224488





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XTextWidth(_f_o_n_t___s_t_r_u_c_t, _s_t_r_i_n_g, _c_o_u_n_t)
      XFontStruct *_f_o_n_t___s_t_r_u_c_t;
      char *_s_t_r_i_n_g;
      int _c_o_u_n_t;


_f_o_n_t___s_t_r_u_c_t
          Specifies the font used for the width computation.

_s_t_r_i_n_g    Specifies the character string.

_c_o_u_n_t     Specifies the character count in the specified
          string.
││__


To determine the width of a 2‐byte character string, use
_X_T_e_x_t_W_i_d_t_h_1_6.
__
││
int XTextWidth16(_f_o_n_t___s_t_r_u_c_t, _s_t_r_i_n_g, _c_o_u_n_t)
      XFontStruct *_f_o_n_t___s_t_r_u_c_t;
      XChar2b *_s_t_r_i_n_g;
      int _c_o_u_n_t;


_f_o_n_t___s_t_r_u_c_t
          Specifies the font used for the width computation.

_s_t_r_i_n_g    Specifies the character string.

_c_o_u_n_t     Specifies the character count in the specified
          string.
││__


88..55..44..  CCoommppuuttiinngg LLooggiiccaall EExxtteennttss

To compute the bounding box of an 8‐bit character string in
a given font, use _X_T_e_x_t_E_x_t_e_n_t_s.
















                             224499





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XTextExtents(_f_o_n_t___s_t_r_u_c_t, _s_t_r_i_n_g, _n_c_h_a_r_s, _d_i_r_e_c_t_i_o_n___r_e_t_u_r_n, _f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n,
              _f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n, _o_v_e_r_a_l_l___r_e_t_u_r_n)
      XFontStruct *_f_o_n_t___s_t_r_u_c_t;
      char *_s_t_r_i_n_g;
      int _n_c_h_a_r_s;
      int *_d_i_r_e_c_t_i_o_n___r_e_t_u_r_n;
      int *_f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n, *_f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n;
      XCharStruct *_o_v_e_r_a_l_l___r_e_t_u_r_n;



_f_o_n_t___s_t_r_u_c_t
          Specifies the _X_F_o_n_t_S_t_r_u_c_t structure.

_s_t_r_i_n_g    Specifies the character string.

_n_c_h_a_r_s    Specifies the number of characters in the charac­
          ter string.

_d_i_r_e_c_t_i_o_n___r_e_t_u_r_n
          Returns the value of the direction hint (_F_o_n_t_L_e_f_t_­
          _T_o_R_i_g_h_t or _F_o_n_t_R_i_g_h_t_T_o_L_e_f_t).

_f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n
          Returns the font ascent.

_f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n
          Returns the font descent.

_o_v_e_r_a_l_l___r_e_t_u_r_n
          Returns the overall size in the specified
          _X_C_h_a_r_S_t_r_u_c_t structure.
││__


To compute the bounding box of a 2‐byte character string in
a given font, use _X_T_e_x_t_E_x_t_e_n_t_s_1_6.



















                             225500





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XTextExtents16(_f_o_n_t___s_t_r_u_c_t, _s_t_r_i_n_g, _n_c_h_a_r_s, _d_i_r_e_c_t_i_o_n___r_e_t_u_r_n, _f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n,
                _f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n, _o_v_e_r_a_l_l___r_e_t_u_r_n)
      XFontStruct *_f_o_n_t___s_t_r_u_c_t;
      XChar2b *_s_t_r_i_n_g;
      int _n_c_h_a_r_s;
      int *_d_i_r_e_c_t_i_o_n___r_e_t_u_r_n;
      int *_f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n, *_f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n;
      XCharStruct *_o_v_e_r_a_l_l___r_e_t_u_r_n;



_f_o_n_t___s_t_r_u_c_t
          Specifies the _X_F_o_n_t_S_t_r_u_c_t structure.

_s_t_r_i_n_g    Specifies the character string.

_n_c_h_a_r_s    Specifies the number of characters in the charac­
          ter string.

_d_i_r_e_c_t_i_o_n___r_e_t_u_r_n
          Returns the value of the direction hint (_F_o_n_t_L_e_f_t_­
          _T_o_R_i_g_h_t or _F_o_n_t_R_i_g_h_t_T_o_L_e_f_t).

_f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n
          Returns the font ascent.

_f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n
          Returns the font descent.

_o_v_e_r_a_l_l___r_e_t_u_r_n
          Returns the overall size in the specified
          _X_C_h_a_r_S_t_r_u_c_t structure.
││__

The _X_T_e_x_t_E_x_t_e_n_t_s and _X_T_e_x_t_E_x_t_e_n_t_s_1_6 functions perform the
size computation locally and, thereby, avoid the round‐trip
overhead of _X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s and _X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s_1_6.  Both
functions return an _X_C_h_a_r_S_t_r_u_c_t structure, whose members are
set to the values as follows.

The ascent member is set to the maximum of the ascent met­
rics of all characters in the string.  The descent member is
set to the maximum of the descent metrics.  The width member
is set to the sum of the character‐width metrics of all
characters in the string.  For each character in the string,
let W be the sum of the character‐width metrics of all char­
acters preceding it in the string.  Let L be the left‐side‐
bearing metric of the character plus W.  Let R be the right‐
side‐bearing metric of the character plus W.  The lbearing
member is set to the minimum L of all characters in the
string.  The rbearing member is set to the maximum R.





                             225511





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


For fonts defined with linear indexing rather than 2‐byte
matrix indexing, each _X_C_h_a_r_2_b structure is interpreted as a
16‐bit number with byte1 as the most significant byte.  If
the font has no defined default character, undefined charac­
ters in the string are taken to have all zero metrics.

88..55..55..  QQuueerryyiinngg CChhaarraacctteerr SSttrriinngg SSiizzeess

To query the server for the bounding box of an 8‐bit charac­
ter string in a given font, use _X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s.
__
││
XQueryTextExtents(_d_i_s_p_l_a_y, _f_o_n_t___I_D, _s_t_r_i_n_g, _n_c_h_a_r_s, _d_i_r_e_c_t_i_o_n___r_e_t_u_r_n, _f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n,
                    _f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n, _o_v_e_r_a_l_l___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      XID _f_o_n_t___I_D;
      char *_s_t_r_i_n_g;
      int _n_c_h_a_r_s;
      int *_d_i_r_e_c_t_i_o_n___r_e_t_u_r_n;
      int *_f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n, *_f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n;
      XCharStruct *_o_v_e_r_a_l_l___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_o_n_t___I_D   Specifies either the font ID or the _G_C_o_n_t_e_x_t ID
          that contains the font.

_s_t_r_i_n_g    Specifies the character string.

_n_c_h_a_r_s    Specifies the number of characters in the charac­
          ter string.

_d_i_r_e_c_t_i_o_n___r_e_t_u_r_n
          Returns the value of the direction hint (_F_o_n_t_L_e_f_t_­
          _T_o_R_i_g_h_t or _F_o_n_t_R_i_g_h_t_T_o_L_e_f_t).

_f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n
          Returns the font ascent.

_f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n
          Returns the font descent.

_o_v_e_r_a_l_l___r_e_t_u_r_n
          Returns the overall size in the specified
          _X_C_h_a_r_S_t_r_u_c_t structure.
││__


To query the server for the bounding box of a 2‐byte charac­
ter string in a given font, use _X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s_1_6.






                             225522





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XQueryTextExtents16(_d_i_s_p_l_a_y, _f_o_n_t___I_D, _s_t_r_i_n_g, _n_c_h_a_r_s, _d_i_r_e_c_t_i_o_n___r_e_t_u_r_n, _f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n,
                        _f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n, _o_v_e_r_a_l_l___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      XID _f_o_n_t___I_D;
      XChar2b *_s_t_r_i_n_g;
      int _n_c_h_a_r_s;
      int *_d_i_r_e_c_t_i_o_n___r_e_t_u_r_n;
      int *_f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n, *_f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n;
      XCharStruct *_o_v_e_r_a_l_l___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_o_n_t___I_D   Specifies either the font ID or the _G_C_o_n_t_e_x_t ID
          that contains the font.

_s_t_r_i_n_g    Specifies the character string.

_n_c_h_a_r_s    Specifies the number of characters in the charac­
          ter string.

_d_i_r_e_c_t_i_o_n___r_e_t_u_r_n
          Returns the value of the direction hint (_F_o_n_t_L_e_f_t_­
          _T_o_R_i_g_h_t or _F_o_n_t_R_i_g_h_t_T_o_L_e_f_t).

_f_o_n_t___a_s_c_e_n_t___r_e_t_u_r_n
          Returns the font ascent.

_f_o_n_t___d_e_s_c_e_n_t___r_e_t_u_r_n
          Returns the font descent.

_o_v_e_r_a_l_l___r_e_t_u_r_n
          Returns the overall size in the specified
          _X_C_h_a_r_S_t_r_u_c_t structure.
││__

The _X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s and _X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s_1_6 functions
return the bounding box of the specified 8‐bit and 16‐bit
character string in the specified font or the font contained
in the specified GC.  These functions query the X server
and, therefore, suffer the round‐trip overhead that is
avoided by _X_T_e_x_t_E_x_t_e_n_t_s and _X_T_e_x_t_E_x_t_e_n_t_s_1_6.  Both functions
return a _X_C_h_a_r_S_t_r_u_c_t structure, whose members are set to the
values as follows.

The ascent member is set to the maximum of the ascent met­
rics of all characters in the string.  The descent member is
set to the maximum of the descent metrics.  The width member
is set to the sum of the character‐width metrics of all
characters in the string.  For each character in the string,
let W be the sum of the character‐width metrics of all char­
acters preceding it in the string.  Let L be the left‐side‐
bearing metric of the character plus W.  Let R be the right‐



                             225533





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


side‐bearing metric of the character plus W.  The lbearing
member is set to the minimum L of all characters in the
string.  The rbearing member is set to the maximum R.

For fonts defined with linear indexing rather than 2‐byte
matrix indexing, each _X_C_h_a_r_2_b structure is interpreted as a
16‐bit number with byte1 as the most significant byte.  If
the font has no defined default character, undefined charac­
ters in the string are taken to have all zero metrics.

Characters with all zero metrics are ignored.  If the font
has no defined default_char, the undefined characters in the
string are also ignored.

_X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s and _X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s_1_6 can generate _B_a_d_­
_F_o_n_t and _B_a_d_G_C errors.

88..66..  DDrraawwiinngg TTeexxtt

This section discusses how to draw:

⋅    Complex text

⋅    Text characters

⋅    Image text characters

The fundamental text functions _X_D_r_a_w_T_e_x_t and _X_D_r_a_w_T_e_x_t_1_6 use
the following structures:

__
││
typedef struct {
     char *chars;             /* pointer to string */
     int nchars;              /* number of characters */
     int delta;               /* delta between strings */
     Font font;               /* Font to print it in, None don’t change */
} XTextItem;



typedef struct {
     XChar2b *chars;          /* pointer to two‐byte characters */
     int nchars;              /* number of characters */
     int delta;               /* delta between strings */
     Font font;               /* font to print it in, None don’t change */
} XTextItem16;

││__

If the font member is not _N_o_n_e, the font is changed before
printing and also is stored in the GC.  If an error was gen­
erated during text drawing, the previous items may have been
drawn.  The baseline of the characters are drawn starting at



                             225544





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the x and y coordinates that you pass in the text drawing
functions.

For example, consider the background rectangle drawn by
_X_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g.  If you want the upper‐left corner of the
background rectangle to be at pixel coordinate (x,y), pass
the (x,y + ascent) as the baseline origin coordinates to the
text functions.  The ascent is the font ascent, as given in
the _X_F_o_n_t_S_t_r_u_c_t structure.  If you want the lower‐left cor­
ner of the background rectangle to be at pixel coordinate
(x,y), pass the (x,y − descent + 1) as the baseline origin
coordinates to the text functions.  The descent is the font
descent, as given in the _X_F_o_n_t_S_t_r_u_c_t structure.

88..66..11..  DDrraawwiinngg CCoommpplleexx TTeexxtt


To draw 8‐bit characters in a given drawable, use _X_D_r_a_w_T_e_x_t.
__
││
XDrawText(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _i_t_e_m_s, _n_i_t_e_m_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      XTextItem *_i_t_e_m_s;
      int _n_i_t_e_m_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the specified drawable and
          define the origin of the first character.

_i_t_e_m_s     Specifies an array of text items.

_n_i_t_e_m_s    Specifies the number of text items in the array.
││__


To draw 2‐byte characters in a given drawable, use _X_D_r_a_w_­
_T_e_x_t_1_6.









                             225555





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawText16(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _i_t_e_m_s, _n_i_t_e_m_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      XTextItem16 *_i_t_e_m_s;
      int _n_i_t_e_m_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the specified drawable and
          define the origin of the first character.

_i_t_e_m_s     Specifies an array of text items.

_n_i_t_e_m_s    Specifies the number of text items in the array.
││__

The _X_D_r_a_w_T_e_x_t_1_6 function is similar to _X_D_r_a_w_T_e_x_t except that
it uses 2‐byte or 16‐bit characters.  Both functions allow
complex spacing and font shifts between counted strings.

Each text item is processed in turn.  A font member other
than _N_o_n_e in an item causes the font to be stored in the GC
and used for subsequent text.  A text element delta speci­
fies an additional change in the position along the x axis
before the string is drawn.  The delta is always added to
the character origin and is not dependent on any character­
istics of the font.  Each character image, as defined by the
font in the GC, is treated as an additional mask for a fill
operation on the drawable.  The drawable is modified only
where the font character has a bit set to 1.  If a text item
generates a _B_a_d_F_o_n_t error, the previous text items may have
been drawn.

For fonts defined with linear indexing rather than 2‐byte
matrix indexing, each _X_C_h_a_r_2_b structure is interpreted as a
16‐bit number with byte1 as the most significant byte.

Both functions use these GC components: function, plane‐
mask, fill‐style, font, subwindow‐mode, clip‐x‐origin, clip‐
y‐origin, and clip‐mask.  They also use these GC mode‐depen­
dent components: foreground, background, tile, stipple,
tile‐stipple‐x‐origin, and tile‐stipple‐y‐origin.





                             225566





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_D_r_a_w_T_e_x_t and _X_D_r_a_w_T_e_x_t_1_6 can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_F_o_n_t,
_B_a_d_G_C, and _B_a_d_M_a_t_c_h errors.

88..66..22..  DDrraawwiinngg TTeexxtt CChhaarraacctteerrss

To draw 8‐bit characters in a given drawable, use _X_D_r_a_w_­
_S_t_r_i_n_g.
__
││
XDrawString(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _s_t_r_i_n_g, _l_e_n_g_t_h)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      char *_s_t_r_i_n_g;
      int _l_e_n_g_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the specified drawable and
          define the origin of the first character.

_s_t_r_i_n_g    Specifies the character string.

_l_e_n_g_t_h    Specifies the number of characters in the string
          argument.
││__


To draw 2‐byte characters in a given drawable, use _X_D_r_a_w_­
_S_t_r_i_n_g_1_6.



















                             225577





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawString16(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _s_t_r_i_n_g, _l_e_n_g_t_h)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      XChar2b *_s_t_r_i_n_g;
      int _l_e_n_g_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the specified drawable and
          define the origin of the first character.

_s_t_r_i_n_g    Specifies the character string.

_l_e_n_g_t_h    Specifies the number of characters in the string
          argument.
││__

Each character image, as defined by the font in the GC, is
treated as an additional mask for a fill operation on the
drawable.  The drawable is modified only where the font
character has a bit set to 1.  For fonts defined with 2‐byte
matrix indexing and used with _X_D_r_a_w_S_t_r_i_n_g_1_6, each byte is
used as a byte2 with a byte1 of zero.

Both functions use these GC components: function, plane‐
mask, fill‐style, font, subwindow‐mode, clip‐x‐origin, clip‐
y‐origin, and clip‐mask.  They also use these GC mode‐depen­
dent components: foreground, background, tile, stipple,
tile‐stipple‐x‐origin, and tile‐stipple‐y‐origin.

_X_D_r_a_w_S_t_r_i_n_g and _X_D_r_a_w_S_t_r_i_n_g_1_6 can generate _B_a_d_D_r_a_w_a_b_l_e,
_B_a_d_G_C, and _B_a_d_M_a_t_c_h errors.

88..66..33..  DDrraawwiinngg IImmaaggee TTeexxtt CChhaarraacctteerrss

Some applications, in particular terminal emulators, need to
print image text in which both the foreground and background
bits of each character are painted.  This prevents annoying
flicker on many displays.


To draw 8‐bit image text characters in a given drawable, use
_X_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g.




                             225588





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawImageString(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _s_t_r_i_n_g, _l_e_n_g_t_h)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      char *_s_t_r_i_n_g;
      int _l_e_n_g_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the specified drawable and
          define the origin of the first character.

_s_t_r_i_n_g    Specifies the character string.

_l_e_n_g_t_h    Specifies the number of characters in the string
          argument.
││__


To draw 2‐byte image text characters in a given drawable,
use _X_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g_1_6.



























                             225599





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDrawImageString16(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _s_t_r_i_n_g, _l_e_n_g_t_h)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      XChar2b *_s_t_r_i_n_g;
      int _l_e_n_g_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the specified drawable and
          define the origin of the first character.

_s_t_r_i_n_g    Specifies the character string.

_l_e_n_g_t_h    Specifies the number of characters in the string
          argument.
││__

The _X_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g_1_6 function is similar to _X_D_r_a_w_I_m_­
_a_g_e_S_t_r_i_n_g except that it uses 2‐byte or 16‐bit characters.
Both functions also use both the foreground and background
pixels of the GC in the destination.

The effect is first to fill a destination rectangle with the
background pixel defined in the GC and then to paint the
text with the foreground pixel.  The upper‐left corner of
the filled rectangle is at:


     [x, y − font‐ascent]


The width is:


     overall‐width


The height is:


     font‐ascent + font‐descent






                             226600





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The overall‐width, font‐ascent, and font‐descent are as
would be returned by _X_Q_u_e_r_y_T_e_x_t_E_x_t_e_n_t_s using gc and string.
The function and fill‐style defined in the GC are ignored
for these functions.  The effective function is _G_X_c_o_p_y, and
the effective fill‐style is _F_i_l_l_S_o_l_i_d.

For fonts defined with 2‐byte matrix indexing and used with
_X_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g, each byte is used as a byte2 with a byte1
of zero.

Both functions use these GC components: plane‐mask, fore­
ground, background, font, subwindow‐mode, clip‐x‐origin,
clip‐y‐origin, and clip‐mask.

_X_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g and _X_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g_1_6 can generate _B_a_d_­
_D_r_a_w_a_b_l_e, _B_a_d_G_C, and _B_a_d_M_a_t_c_h errors.


88..77..  TTrraannssffeerrrriinngg IImmaaggeess bbeettwweeeenn CClliieenntt aanndd SSeerrvveerr

Xlib provides functions that you can use to transfer images
between a client and the server.  Because the server may
require diverse data formats, Xlib provides an image object
that fully describes the data in memory and that provides
for basic operations on that data.  You should reference the
data through the image object rather than referencing the
data directly.  However, some implementations of the Xlib
library may efficiently deal with frequently used data for­
mats by replacing functions in the procedure vector with
special case functions.  Supported operations include
destroying the image, getting a pixel, storing a pixel,
extracting a subimage of an image, and adding a constant to
an image (see section 16.8).

All the image manipulation functions discussed in this sec­
tion make use of the _X_I_m_a_g_e structure, which describes an
image as it exists in the client’s memory.




















                             226611





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct _XImage {
     int width, height;       /* size of image */
     int xoffset;             /* number of pixels offset in X direction */
     int format;              /* XYBitmap, XYPixmap, ZPixmap */
     char *data;              /* pointer to image data */
     int byte_order;          /* data byte order, LSBFirst, MSBFirst */
     int bitmap_unit;         /* quant. of scanline 8, 16, 32 */
     int bitmap_bit_order;    /* LSBFirst, MSBFirst */
     int bitmap_pad;          /* 8, 16, 32 either XY or ZPixmap */
     int depth;               /* depth of image */
     int bytes_per_line;      /* accelerator to next scanline */
     int bits_per_pixel;      /* bits per pixel (ZPixmap) */
     unsigned long red_mask;  /* bits in z arrangement */
     unsigned long green_mask;
     unsigned long blue_mask;
     XPointer obdata;         /* hook for the object routines to hang on */
     struct funcs {           /* image manipulation routines */
          struct _XImage *(*create_image)();
          int (*destroy_image)();
          unsigned long (*get_pixel)();
          int (*put_pixel)();
          struct _XImage *(*sub_image)();
          int (*add_pixel)();
     } f;
} XImage;

││__


To initialize the image manipulation routines of an image
structure, use _X_I_n_i_t_I_m_a_g_e.
__
││
Status XInitImage(_i_m_a_g_e)
      XImage *_i_m_a_g_e;


_x_i_m_a_g_e    Specifies the image.
││__

The _X_I_n_i_t_I_m_a_g_e function initializes the internal image
manipulation routines of an image structure, based on the
values of the various structure members.  All fields other
than the manipulation routines must already be initialized.
If the bytes_per_line member is zero, _X_I_n_i_t_I_m_a_g_e will assume
the image data is contiguous in memory and set the
bytes_per_line member to an appropriate value based on the
other members; otherwise, the value of bytes_per_line is not
changed.  All of the manipulation routines are initialized
to functions that other Xlib image manipulation functions
need to operate on the type of image specified by the rest
of the structure.




                             226622





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


This function must be called for any image constructed by
the client before passing it to any other Xlib function.
Image structures created or returned by Xlib do not need to
be initialized in this fashion.

This function returns a nonzero status if initialization of
the structure is successful.  It returns zero if it detected
some error or inconsistency in the structure, in which case
the image is not changed.


To combine an image with a rectangle of a drawable on the
display, use _X_P_u_t_I_m_a_g_e.
__
││
XPutImage(_d_i_s_p_l_a_y, _d, _g_c, _i_m_a_g_e, _s_r_c___x, _s_r_c___y, _d_e_s_t___x, _d_e_s_t___y, _w_i_d_t_h, _h_e_i_g_h_t)
        Display *_d_i_s_p_l_a_y;
        Drawable _d;
        GC _g_c;
        XImage *_i_m_a_g_e;
        int _s_r_c___x, _s_r_c___y;
        int _d_e_s_t___x, _d_e_s_t___y;
        unsigned int _w_i_d_t_h, _h_e_i_g_h_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_i_m_a_g_e     Specifies the image you want combined with the
          rectangle.

_s_r_c___x     Specifies the offset in X from the left edge of
          the image defined by the _X_I_m_a_g_e structure.

_s_r_c___y     Specifies the offset in Y from the top edge of the
          image defined by the _X_I_m_a_g_e structure.

_d_e_s_t___x
_d_e_s_t___y    Specify the x and y coordinates, which are rela­
          tive to the origin of the drawable and are the
          coordinates of the subimage.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height of the subimage,
          which define the dimensions of the rectangle.
││__

The _X_P_u_t_I_m_a_g_e function combines an image with a rectangle of
the specified drawable.  The section of the image defined by
the src_x, src_y, width, and height arguments is drawn on
the specified part of the drawable.  If _X_Y_B_i_t_m_a_p format is



                             226633





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


used, the depth of the image must be one, or a _B_a_d_M_a_t_c_h
error results.  The foreground pixel in the GC defines the
source for the one bits in the image, and the background
pixel defines the source for the zero bits.  For _X_Y_P_i_x_m_a_p
and _Z_P_i_x_m_a_p, the depth of the image must match the depth of
the drawable, or a _B_a_d_M_a_t_c_h error results.

If the characteristics of the image (for example, byte_order
and bitmap_unit) differ from what the server requires,
_X_P_u_t_I_m_a_g_e automatically makes the appropriate conversions.

This function uses these GC components: function, plane‐
mask, subwindow‐mode, clip‐x‐origin, clip‐y‐origin, and
clip‐mask.  It also uses these GC mode‐dependent components:
foreground and background.

_X_P_u_t_I_m_a_g_e can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, _B_a_d_M_a_t_c_h, and
_B_a_d_V_a_l_u_e errors.


To return the contents of a rectangle in a given drawable on
the display, use _X_G_e_t_I_m_a_g_e.  This function specifically sup­
ports rudimentary screen dumps.


































                             226644





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XImage *XGetImage(_d_i_s_p_l_a_y, _d, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _p_l_a_n_e___m_a_s_k, _f_o_r_m_a_t)
        Display *_d_i_s_p_l_a_y;
        Drawable _d;
        int _x, _y;
        unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
        unsigned long _p_l_a_n_e___m_a_s_k;
        int _f_o_r_m_a_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the drawable and define the
          upper‐left corner of the rectangle.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height of the subimage,
          which define the dimensions of the rectangle.

_p_l_a_n_e___m_a_s_k
          Specifies the plane mask.

_f_o_r_m_a_t    Specifies the format for the image.  You can pass
          _X_Y_P_i_x_m_a_p or _Z_P_i_x_m_a_p.
││__

The _X_G_e_t_I_m_a_g_e function returns a pointer to an _X_I_m_a_g_e struc­
ture.  This structure provides you with the contents of the
specified rectangle of the drawable in the format you spec­
ify.  If the format argument is _X_Y_P_i_x_m_a_p, the image contains
only the bit planes you passed to the plane_mask argument.
If the plane_mask argument only requests a subset of the
planes of the display, the depth of the returned image will
be the number of planes requested.  If the format argument
is _Z_P_i_x_m_a_p, _X_G_e_t_I_m_a_g_e returns as zero the bits in all planes
not specified in the plane_mask argument.  The function per­
forms no range checking on the values in plane_mask and
ignores extraneous bits.

_X_G_e_t_I_m_a_g_e returns the depth of the image to the depth member
of the _X_I_m_a_g_e structure.  The depth of the image is as spec­
ified when the drawable was created, except when getting a
subset of the planes in _X_Y_P_i_x_m_a_p format, when the depth is
given by the number of bits set to 1 in plane_mask.

If the drawable is a pixmap, the given rectangle must be
wholly contained within the pixmap, or a _B_a_d_M_a_t_c_h error
results.  If the drawable is a window, the window must be
viewable, and it must be the case that if there were no
inferiors or overlapping windows, the specified rectangle of



                             226655





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the window would be fully visible on the screen and wholly
contained within the outside edges of the window, or a _B_a_d_­
_M_a_t_c_h error results.  Note that the borders of the window
can be included and read with this request.  If the window
has backing‐store, the backing‐store contents are returned
for regions of the window that are obscured by noninferior
windows.  If the window does not have backing‐store, the
returned contents of such obscured regions are undefined.
The returned contents of visible regions of inferiors of a
different depth than the specified window’s depth are also
undefined.  The pointer cursor image is not included in the
returned contents.  If a problem occurs, _X_G_e_t_I_m_a_g_e returns
NULL.

_X_G_e_t_I_m_a_g_e can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_M_a_t_c_h, and _B_a_d_V_a_l_u_e
errors.


To copy the contents of a rectangle on the display to a
location within a preexisting image structure, use _X_G_e_t_­
_S_u_b_I_m_a_g_e.




































                             226666





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XImage *XGetSubImage(_d_i_s_p_l_a_y, _d, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _p_l_a_n_e___m_a_s_k, _f_o_r_m_a_t, _d_e_s_t___i_m_a_g_e, _d_e_s_t___x,
                     _d_e_s_t___y)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      unsigned long _p_l_a_n_e___m_a_s_k;
      int _f_o_r_m_a_t;
      XImage *_d_e_s_t___i_m_a_g_e;
      int _d_e_s_t___x, _d_e_s_t___y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_x
_y         Specify the x and y coordinates, which are rela­
          tive to the origin of the drawable and define the
          upper‐left corner of the rectangle.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height of the subimage,
          which define the dimensions of the rectangle.

_p_l_a_n_e___m_a_s_k
          Specifies the plane mask.

_f_o_r_m_a_t    Specifies the format for the image.  You can pass
          _X_Y_P_i_x_m_a_p or _Z_P_i_x_m_a_p.

_d_e_s_t___i_m_a_g_e
          Specifies the destination image.

_d_e_s_t___x
_d_e_s_t___y    Specify the x and y coordinates, which are rela­
          tive to the origin of the destination rectangle,
          specify its upper‐left corner, and determine where
          the subimage is placed in the destination image.
││__

The _X_G_e_t_S_u_b_I_m_a_g_e function updates dest_image with the speci­
fied subimage in the same manner as _X_G_e_t_I_m_a_g_e.  If the for­
mat argument is _X_Y_P_i_x_m_a_p, the image contains only the bit
planes you passed to the plane_mask argument.  If the format
argument is _Z_P_i_x_m_a_p, _X_G_e_t_S_u_b_I_m_a_g_e returns as zero the bits
in all planes not specified in the plane_mask argument.  The
function performs no range checking on the values in
plane_mask and ignores extraneous bits.  As a convenience,
_X_G_e_t_S_u_b_I_m_a_g_e returns a pointer to the same _X_I_m_a_g_e structure
specified by dest_image.





                             226677





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The depth of the destination _X_I_m_a_g_e structure must be the
same as that of the drawable.  If the specified subimage
does not fit at the specified location on the destination
image, the right and bottom edges are clipped.  If the draw­
able is a pixmap, the given rectangle must be wholly con­
tained within the pixmap, or a _B_a_d_M_a_t_c_h error results.  If
the drawable is a window, the window must be viewable, and
it must be the case that if there were no inferiors or over­
lapping windows, the specified rectangle of the window would
be fully visible on the screen and wholly contained within
the outside edges of the window, or a _B_a_d_M_a_t_c_h error
results.  If the window has backing‐store, then the backing‐
store contents are returned for regions of the window that
are obscured by noninferior windows.  If the window does not
have backing‐store, the returned contents of such obscured
regions are undefined.  The returned contents of visible
regions of inferiors of a different depth than the specified
window’s depth are also undefined.  If a problem occurs,
_X_G_e_t_S_u_b_I_m_a_g_e returns NULL.

_X_G_e_t_S_u_b_I_m_a_g_e can generate _B_a_d_D_r_a_w_a_b_l_e, _B_a_d_G_C, _B_a_d_M_a_t_c_h, and
_B_a_d_V_a_l_u_e errors.



































                             226688





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 99

            WWiinnddooww aanndd SSeessssiioonn MMaannaaggeerr FFuunnccttiioonnss



Although it is difficult to categorize functions as exclu­
sively for an application, a window manager, or a session
manager, the functions in this chapter are most often used
by window managers and session managers.  It is not expected
that these functions will be used by most application pro­
grams.  Xlib provides management functions to:

⋅    Change the parent of a window

⋅    Control the lifetime of a window

⋅    Manage installed colormaps

⋅    Set and retrieve the font search path

⋅    Grab the server

⋅    Kill a client

⋅    Control the screen saver

⋅    Control host access

99..11..  CChhaannggiinngg tthhee PPaarreenntt ooff aa WWiinnddooww

To change a window’s parent to another window on the same
screen, use _X_R_e_p_a_r_e_n_t_W_i_n_d_o_w.  There is no way to move a win­
dow between screens.





















                             226699





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XReparentWindow(_d_i_s_p_l_a_y, _w, _p_a_r_e_n_t, _x, _y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Window _p_a_r_e_n_t;
      int _x, _y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_p_a_r_e_n_t    Specifies the parent window.

_x
_y         Specify the x and y coordinates of the position in
          the new parent window.
││__

If the specified window is mapped, _X_R_e_p_a_r_e_n_t_W_i_n_d_o_w automati­
cally performs an _U_n_m_a_p_W_i_n_d_o_w request on it, removes it from
its current position in the hierarchy, and inserts it as the
child of the specified parent.  The window is placed in the
stacking order on top with respect to sibling windows.

After reparenting the specified window, _X_R_e_p_a_r_e_n_t_W_i_n_d_o_w
causes the X server to generate a _R_e_p_a_r_e_n_t_N_o_t_i_f_y event.  The
override_redirect member returned in this event is set to
the window’s corresponding attribute.  Window manager
clients usually should ignore this window if this member is
set to _T_r_u_e.  Finally, if the specified window was origi­
nally mapped, the X server automatically performs a _M_a_p_W_i_n_­
_d_o_w request on it.

The X server performs normal exposure processing on formerly
obscured windows.  The X server might not generate _E_x_p_o_s_e
events for regions from the initial _U_n_m_a_p_W_i_n_d_o_w request that
are immediately obscured by the final _M_a_p_W_i_n_d_o_w request.  A
_B_a_d_M_a_t_c_h error results if:

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

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

⋅    The new parent is _I_n_p_u_t_O_n_l_y, and the window is not.

⋅    The specified window has a _P_a_r_e_n_t_R_e_l_a_t_i_v_e background,
     and the new parent window is not the same depth as the
     specified window.

_X_R_e_p_a_r_e_n_t_W_i_n_d_o_w can generate _B_a_d_M_a_t_c_h and _B_a_d_W_i_n_d_o_w errors.




                             227700





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


99..22..  CCoonnttrroolllliinngg tthhee LLiiffeettiimmee ooff aa WWiinnddooww

The save‐set of a client is a list of other clients’ windows
that, if they are inferiors of one of the client’s windows
at connection close, should not be destroyed and should be
remapped if they are unmapped.  For further information
about close‐connection processing, see section 2.6.  To
allow an application’s window to survive when a window man­
ager that has reparented a window fails, Xlib provides the
save‐set functions that you can use to control the longevity
of subwindows that are normally destroyed when the parent is
destroyed.  For example, a window manager that wants to add
decoration to a window by adding a frame might reparent an
application’s window.  When the frame is destroyed, the
application’s window should not be destroyed but be returned
to its previous place in the window hierarchy.

The X server automatically removes windows from the save‐set
when they are destroyed.


To add or remove a window from the client’s save‐set, use
_X_C_h_a_n_g_e_S_a_v_e_S_e_t.
__
││
XChangeSaveSet(_d_i_s_p_l_a_y, _w, _c_h_a_n_g_e___m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _c_h_a_n_g_e___m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window that you want to add to or
          delete from the client’s save‐set.

_c_h_a_n_g_e___m_o_d_e
          Specifies the mode.  You can pass _S_e_t_M_o_d_e_I_n_s_e_r_t or
          _S_e_t_M_o_d_e_D_e_l_e_t_e.
││__

Depending on the specified mode, _X_C_h_a_n_g_e_S_a_v_e_S_e_t either
inserts or deletes the specified window from the client’s
save‐set.  The specified window must have been created by
some other client, or a _B_a_d_M_a_t_c_h error results.

_X_C_h_a_n_g_e_S_a_v_e_S_e_t can generate _B_a_d_M_a_t_c_h, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_­
_d_o_w errors.


To add a window to the client’s save‐set, use _X_A_d_d_T_o_S_a_v_e_S_e_t.






                             227711





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XAddToSaveSet(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window that you want to add to the
          client’s save‐set.
││__

The _X_A_d_d_T_o_S_a_v_e_S_e_t function adds the specified window to the
client’s save‐set.  The specified window must have been cre­
ated by some other client, or a _B_a_d_M_a_t_c_h error results.

_X_A_d_d_T_o_S_a_v_e_S_e_t can generate _B_a_d_M_a_t_c_h and _B_a_d_W_i_n_d_o_w errors.


To remove a window from the client’s save‐set, use _X_R_e_m_o_v_e_­
_F_r_o_m_S_a_v_e_S_e_t.
__
││
XRemoveFromSaveSet(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window that you want to delete from
          the client’s save‐set.
││__

The _X_R_e_m_o_v_e_F_r_o_m_S_a_v_e_S_e_t function removes the specified window
from the client’s save‐set.  The specified window must have
been created by some other client, or a _B_a_d_M_a_t_c_h error
results.

_X_R_e_m_o_v_e_F_r_o_m_S_a_v_e_S_e_t can generate _B_a_d_M_a_t_c_h and _B_a_d_W_i_n_d_o_w
errors.

99..33..  MMaannaaggiinngg IInnssttaalllleedd CCoolloorrmmaappss

The X server maintains a list of installed colormaps.  Win­
dows using these colormaps are guaranteed to display with
correct colors; windows using other colormaps may or may not
display with correct colors.  Xlib provides functions that
you can use to install a colormap, uninstall a colormap, and
obtain a list of installed colormaps.

At any time, there is a subset of the installed maps that is
viewed as an ordered list and is called the required list.
The length of the required list is at most M, where M is the



                             227722





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


minimum number of installed colormaps specified for the
screen in the connection setup.  The required list is main­
tained as follows.  When a colormap is specified to _X_I_n_­
_s_t_a_l_l_C_o_l_o_r_m_a_p, it is added to the head of the list; the list
is truncated at the tail, if necessary, to keep its length
to at most M.  When a colormap is specified to _X_U_n_i_n_s_t_a_l_l_­
_C_o_l_o_r_m_a_p and it is in the required list, it is removed from
the list.  A colormap is not added to the required list when
it is implicitly installed by the X server, and the X server
cannot implicitly uninstall a colormap that is in the
required list.


To install a colormap, use _X_I_n_s_t_a_l_l_C_o_l_o_r_m_a_p.
__
││
XInstallColormap(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.
││__

The _X_I_n_s_t_a_l_l_C_o_l_o_r_m_a_p function installs the specified col­
ormap for its associated screen.  All windows associated
with this colormap immediately display with true colors.
You associated the windows with this colormap when you cre­
ated them by calling _X_C_r_e_a_t_e_W_i_n_d_o_w, _X_C_r_e_a_t_e_S_i_m_p_l_e_W_i_n_d_o_w,
_X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s, or _X_S_e_t_W_i_n_d_o_w_C_o_l_o_r_m_a_p.

If the specified colormap is not already an installed col­
ormap, the X server generates a _C_o_l_o_r_m_a_p_N_o_t_i_f_y event on each
window that has that colormap.  In addition, for every other
colormap that is installed as a result of a call to _X_I_n_­
_s_t_a_l_l_C_o_l_o_r_m_a_p, the X server generates a _C_o_l_o_r_m_a_p_N_o_t_i_f_y event
on each window that has that colormap.

_X_I_n_s_t_a_l_l_C_o_l_o_r_m_a_p can generate a _B_a_d_C_o_l_o_r error.


To uninstall a colormap, use _X_U_n_i_n_s_t_a_l_l_C_o_l_o_r_m_a_p.













                             227733





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XUninstallColormap(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p)
      Display *_d_i_s_p_l_a_y;
      Colormap _c_o_l_o_r_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_l_o_r_m_a_p  Specifies the colormap.
││__

The _X_U_n_i_n_s_t_a_l_l_C_o_l_o_r_m_a_p function removes the specified col­
ormap from the required list for its screen.  As a result,
the specified colormap might be uninstalled, and the X
server might implicitly install or uninstall additional col­
ormaps.  Which colormaps get installed or uninstalled is
server dependent except that the required list must remain
installed.

If the specified colormap becomes uninstalled, the X server
generates a _C_o_l_o_r_m_a_p_N_o_t_i_f_y event on each window that has
that colormap.  In addition, for every other colormap that
is installed or uninstalled as a result of a call to _X_U_n_i_n_­
_s_t_a_l_l_C_o_l_o_r_m_a_p, the X server generates a _C_o_l_o_r_m_a_p_N_o_t_i_f_y event
on each window that has that colormap.

_X_U_n_i_n_s_t_a_l_l_C_o_l_o_r_m_a_p can generate a _B_a_d_C_o_l_o_r error.


To obtain a list of the currently installed colormaps for a
given screen, use _X_L_i_s_t_I_n_s_t_a_l_l_e_d_C_o_l_o_r_m_a_p_s.
__
││
Colormap *XListInstalledColormaps(_d_i_s_p_l_a_y, _w, _n_u_m___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int *_n_u_m___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window that determines the screen.

_n_u_m___r_e_t_u_r_n
          Returns the number of currently installed col­
          ormaps.
││__

The _X_L_i_s_t_I_n_s_t_a_l_l_e_d_C_o_l_o_r_m_a_p_s function returns a list of the
currently installed colormaps for the screen of the speci­
fied window.  The order of the colormaps in the list is not
significant and is no explicit indication of the required
list.  When the allocated list is no longer needed, free it
by using _X_F_r_e_e.



                             227744





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_L_i_s_t_I_n_s_t_a_l_l_e_d_C_o_l_o_r_m_a_p_s can generate a _B_a_d_W_i_n_d_o_w error.

99..44..  SSeettttiinngg aanndd RReettrriieevviinngg tthhee FFoonntt SSeeaarrcchh PPaatthh

The set of fonts available from a server depends on a font
search path.  Xlib provides functions to set and retrieve
the search path for a server.


To set the font search path, use _X_S_e_t_F_o_n_t_P_a_t_h.
__
││
XSetFontPath(_d_i_s_p_l_a_y, _d_i_r_e_c_t_o_r_i_e_s, _n_d_i_r_s)
      Display *_d_i_s_p_l_a_y;
      char **_d_i_r_e_c_t_o_r_i_e_s;
      int _n_d_i_r_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_i_r_e_c_t_o_r_i_e_s
          Specifies the directory path used to look for a
          font.  Setting the path to the empty list restores
          the default path defined for the X server.

_n_d_i_r_s     Specifies the number of directories in the path.
││__

The _X_S_e_t_F_o_n_t_P_a_t_h function defines the directory search path
for font lookup.  There is only one search path per X
server, not one per client.  The encoding and interpretation
of the strings are implementation‐dependent, but typically
they specify directories or font servers to be searched in
the order listed.  An X server is permitted to cache font
information internally; for example, it might cache an
entire font from a file and not check on subsequent opens of
that font to see if the underlying font file has changed.
However, when the font path is changed, the X server is
guaranteed to flush all cached information about fonts for
which there currently are no explicit resource IDs allo­
cated.  The meaning of an error from this request is imple­
mentation‐dependent.

_X_S_e_t_F_o_n_t_P_a_t_h can generate a _B_a_d_V_a_l_u_e error.


To get the current font search path, use _X_G_e_t_F_o_n_t_P_a_t_h.










                             227755





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char **XGetFontPath(_d_i_s_p_l_a_y, _n_p_a_t_h_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int *_n_p_a_t_h_s___r_e_t_u_r_n;



_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_p_a_t_h_s___r_e_t_u_r_n
          Returns the number of strings in the font path
          array.
││__

The _X_G_e_t_F_o_n_t_P_a_t_h function allocates and returns an array of
strings containing the search path.  The contents of these
strings are implementation‐dependent and are not intended to
be interpreted by client applications.  When it is no longer
needed, the data in the font path should be freed by using
_X_F_r_e_e_F_o_n_t_P_a_t_h.


To free data returned by _X_G_e_t_F_o_n_t_P_a_t_h, use _X_F_r_e_e_F_o_n_t_P_a_t_h.
__
││
XFreeFontPath(_l_i_s_t)
      char **_l_i_s_t;



_l_i_s_t      Specifies the array of strings you want to free.
││__

The _X_F_r_e_e_F_o_n_t_P_a_t_h function frees the data allocated by _X_G_e_t_­
_F_o_n_t_P_a_t_h.

99..55..  GGrraabbbbiinngg tthhee SSeerrvveerr

Xlib provides functions that you can use to grab and ungrab
the server.  These functions can be used to control process­
ing of output on other connections by the window system
server.  While the server is grabbed, no processing of
requests or close downs on any other connection will occur.
A client closing its connection automatically ungrabs the
server.  Although grabbing the server is highly discouraged,
it is sometimes necessary.


To grab the server, use _X_G_r_a_b_S_e_r_v_e_r.








                             227766





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XGrabServer(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_G_r_a_b_S_e_r_v_e_r function disables processing of requests and
close downs on all other connections than the one this
request arrived on.  You should not grab the X server any
more than is absolutely necessary.


To ungrab the server, use _X_U_n_g_r_a_b_S_e_r_v_e_r.
__
││
XUngrabServer(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_U_n_g_r_a_b_S_e_r_v_e_r function restarts processing of requests
and close downs on other connections.  You should avoid
grabbing the X server as much as possible.

99..66..  KKiilllliinngg CClliieennttss

Xlib provides a function to cause the connection to a client
to be closed and its resources to be destroyed.  To destroy
a client, use _X_K_i_l_l_C_l_i_e_n_t.
__
││
XKillClient(_d_i_s_p_l_a_y, _r_e_s_o_u_r_c_e)
      Display *_d_i_s_p_l_a_y;
      XID _r_e_s_o_u_r_c_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_r_e_s_o_u_r_c_e  Specifies any resource associated with the client
          that you want to destroy or _A_l_l_T_e_m_p_o_r_a_r_y.
││__

The _X_K_i_l_l_C_l_i_e_n_t function forces a close down of the client
that created the resource if a valid resource is specified.
If the client has already terminated in either _R_e_t_a_i_n_P_e_r_m_a_­
_n_e_n_t or _R_e_t_a_i_n_T_e_m_p_o_r_a_r_y mode, all of the client’s resources
are destroyed.  If _A_l_l_T_e_m_p_o_r_a_r_y is specified, the resources
of all clients that have terminated in _R_e_t_a_i_n_T_e_m_p_o_r_a_r_y are
destroyed (see section 2.5).  This permits implementation of
window manager facilities that aid debugging.  A client can



                             227777





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


set its close‐down mode to _R_e_t_a_i_n_T_e_m_p_o_r_a_r_y.  If the client
then crashes, its windows would not be destroyed.  The pro­
grammer can then inspect the application’s window tree and
use the window manager to destroy the zombie windows.

_X_K_i_l_l_C_l_i_e_n_t can generate a _B_a_d_V_a_l_u_e error.

99..77..  CCoonnttrroolllliinngg tthhee SSccrreeeenn SSaavveerr

Xlib provides functions that you can use to set or reset the
mode of the screen saver, to force or activate the screen
saver, or to obtain the current screen saver values.


To set the screen saver mode, use _X_S_e_t_S_c_r_e_e_n_S_a_v_e_r.
__
││
XSetScreenSaver(_d_i_s_p_l_a_y, _t_i_m_e_o_u_t, _i_n_t_e_r_v_a_l, _p_r_e_f_e_r___b_l_a_n_k_i_n_g, _a_l_l_o_w___e_x_p_o_s_u_r_e_s)
      Display *_d_i_s_p_l_a_y;
      int _t_i_m_e_o_u_t, _i_n_t_e_r_v_a_l;
      int _p_r_e_f_e_r___b_l_a_n_k_i_n_g;
      int _a_l_l_o_w___e_x_p_o_s_u_r_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_t_i_m_e_o_u_t   Specifies the timeout, in seconds, until the
          screen saver turns on.

_i_n_t_e_r_v_a_l  Specifies the interval, in seconds, between screen
          saver alterations.

_p_r_e_f_e_r___b_l_a_n_k_i_n_g
          Specifies how to enable screen blanking.  You can
          pass _D_o_n_t_P_r_e_f_e_r_B_l_a_n_k_i_n_g, _P_r_e_f_e_r_B_l_a_n_k_i_n_g, or
          _D_e_f_a_u_l_t_B_l_a_n_k_i_n_g.

_a_l_l_o_w___e_x_p_o_s_u_r_e_s
          Specifies the screen save control values.  You can
          pass _D_o_n_t_A_l_l_o_w_E_x_p_o_s_u_r_e_s, _A_l_l_o_w_E_x_p_o_s_u_r_e_s, or
          _D_e_f_a_u_l_t_E_x_p_o_s_u_r_e_s.
││__

Timeout and interval are specified in seconds.  A timeout of
0 disables the screen saver (but an activated screen saver
is not deactivated), and a timeout of −1 restores the
default.  Other negative values generate a _B_a_d_V_a_l_u_e error.
If the timeout value is nonzero, _X_S_e_t_S_c_r_e_e_n_S_a_v_e_r enables the
screen saver.  An interval of 0 disables the random‐pattern
motion.  If no input from devices (keyboard, mouse, and so
on) is generated for the specified number of timeout seconds
once the screen saver is enabled, the screen saver is acti­
vated.




                             227788





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


For each screen, if blanking is preferred and the hardware
supports video blanking, the screen simply goes blank.  Oth­
erwise, if either exposures are allowed or the screen can be
regenerated without sending _E_x_p_o_s_e events to clients, the
screen is tiled with the root window background tile ran­
domly re‐origined each interval seconds.  Otherwise, the
screens’ state do not change, and the screen saver is not
activated.  The screen saver is deactivated, and all screen
states are restored at the next keyboard or pointer input or
at the next call to _X_F_o_r_c_e_S_c_r_e_e_n_S_a_v_e_r with mode _S_c_r_e_e_n_S_a_v_e_r_­
_R_e_s_e_t.

If the server‐dependent screen saver method supports peri­
odic change, the interval argument serves as a hint about
how long the change period should be, and zero hints that no
periodic change should be made.  Examples of ways to change
the screen include scrambling the colormap periodically,
moving an icon image around the screen periodically, or
tiling the screen with the root window background tile, ran­
domly re‐origined periodically.

_X_S_e_t_S_c_r_e_e_n_S_a_v_e_r can generate a _B_a_d_V_a_l_u_e error.


To force the screen saver on or off, use _X_F_o_r_c_e_S_c_r_e_e_n_S_a_v_e_r.
__
││
XForceScreenSaver(_d_i_s_p_l_a_y, _m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      int _m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_m_o_d_e      Specifies the mode that is to be applied.  You can
          pass _S_c_r_e_e_n_S_a_v_e_r_A_c_t_i_v_e or _S_c_r_e_e_n_S_a_v_e_r_R_e_s_e_t.
││__

If the specified mode is _S_c_r_e_e_n_S_a_v_e_r_A_c_t_i_v_e and the screen
saver currently is deactivated, _X_F_o_r_c_e_S_c_r_e_e_n_S_a_v_e_r activates
the screen saver even if the screen saver had been disabled
with a timeout of zero.  If the specified mode is _S_c_r_e_e_n_­
_S_a_v_e_r_R_e_s_e_t and the screen saver currently is enabled,
_X_F_o_r_c_e_S_c_r_e_e_n_S_a_v_e_r deactivates the screen saver if it was
activated, and the activation timer is reset to its initial
state (as if device input had been received).

_X_F_o_r_c_e_S_c_r_e_e_n_S_a_v_e_r can generate a _B_a_d_V_a_l_u_e error.


To activate the screen saver, use _X_A_c_t_i_v_a_t_e_S_c_r_e_e_n_S_a_v_e_r.






                             227799





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XActivateScreenSaver(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__


To reset the screen saver, use _X_R_e_s_e_t_S_c_r_e_e_n_S_a_v_e_r.
__
││
XResetScreenSaver(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__


To get the current screen saver values, use _X_G_e_t_S_c_r_e_e_n_S_a_v_e_r.
__
││
XGetScreenSaver(_d_i_s_p_l_a_y, _t_i_m_e_o_u_t___r_e_t_u_r_n, _i_n_t_e_r_v_a_l___r_e_t_u_r_n, _p_r_e_f_e_r___b_l_a_n_k_i_n_g___r_e_t_u_r_n,
                  _a_l_l_o_w___e_x_p_o_s_u_r_e_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int *_t_i_m_e_o_u_t___r_e_t_u_r_n, *_i_n_t_e_r_v_a_l___r_e_t_u_r_n;
      int *_p_r_e_f_e_r___b_l_a_n_k_i_n_g___r_e_t_u_r_n;
      int *_a_l_l_o_w___e_x_p_o_s_u_r_e_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_t_i_m_e_o_u_t___r_e_t_u_r_n
          Returns the timeout, in seconds, until the screen
          saver turns on.

_i_n_t_e_r_v_a_l___r_e_t_u_r_n
          Returns the interval between screen saver invoca­
          tions.

_p_r_e_f_e_r___b_l_a_n_k_i_n_g___r_e_t_u_r_n
          Returns the current screen blanking preference
          (_D_o_n_t_P_r_e_f_e_r_B_l_a_n_k_i_n_g, _P_r_e_f_e_r_B_l_a_n_k_i_n_g, or _D_e_f_a_u_l_t_­
          _B_l_a_n_k_i_n_g).

_a_l_l_o_w___e_x_p_o_s_u_r_e_s___r_e_t_u_r_n
          Returns the current screen save control value
          (_D_o_n_t_A_l_l_o_w_E_x_p_o_s_u_r_e_s, _A_l_l_o_w_E_x_p_o_s_u_r_e_s, or _D_e_f_a_u_l_t_E_x_­
          _p_o_s_u_r_e_s).
││__






                             228800





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


99..88..  CCoonnttrroolllliinngg HHoosstt AAcccceessss

This section discusses how to:

⋅    Add, get, or remove hosts from the access control list

⋅    Change, enable, or disable access

X does not provide any protection on a per‐window basis.  If
you find out the resource ID of a resource, you can manipu­
late it.  To provide some minimal level of protection, how­
ever, connections are permitted only from machines you
trust.  This is adequate on single‐user workstations but
obviously breaks down on timesharing machines.  Although
provisions exist in the X protocol for proper connection
authentication, the lack of a standard authentication server
leaves host‐level access control as the only common mecha­
nism.

The initial set of hosts allowed to open connections typi­
cally consists of:

⋅    The host the window system is running on.

⋅    On POSIX‐conformant systems, each host listed in the
     _/_e_t_c_/_X_?_._h_o_s_t_s file.  The ? indicates the number of the
     display.  This file should consist of host names sepa­
     rated by newlines.  DECnet nodes must terminate in ::
     to distinguish them from Internet hosts.

If a host is not in the access control list when the access
control mechanism is enabled and if the host attempts to
establish a connection, the server refuses the connection.
To change the access list, the client must reside on the
same host as the server and/or must have been granted per­
mission in the initial authorization at connection setup.

Servers also can implement other access control policies in
addition to or in place of this host access facility.  For
further information about other access control implementa­
tions, see ‘‘X Window System Protocol.’’

99..88..11..  AAddddiinngg,, GGeettttiinngg,, oorr RReemmoovviinngg HHoossttss

Xlib provides functions that you can use to add, get, or
remove hosts from the access control list.  All the host
access control functions use the _X_H_o_s_t_A_d_d_r_e_s_s structure,
which contains:









                             228811





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     int family;              /* for example FamilyInternet */
     int length;              /* length of address, in bytes */
     char *address;           /* pointer to where to find the address */
} XHostAddress;

││__

The family member specifies which protocol address family to
use (for example, TCP/IP or DECnet) and can be _F_a_m_i_l_y_I_n_t_e_r_­
_n_e_t, _F_a_m_i_l_y_I_n_t_e_r_n_e_t_6, _F_a_m_i_l_y_S_e_r_v_e_r_I_n_t_e_r_p_r_e_t_e_d, _F_a_m_i_l_y_D_E_C_n_e_t,
or _F_a_m_i_l_y_C_h_a_o_s.  The length member specifies the length of
the address in bytes.  The address member specifies a
pointer to the address.

For TCP/IP, the address should be in network byte order.
For IP version 4 addresses, the family should be FamilyIn­
ternet and the length should be 4 bytes.  For IP version 6
addresses, the family should be FamilyInternet6 and the
length should be 16 bytes.

For the DECnet family, the server performs no automatic
swapping on the address bytes.  A Phase IV address is 2
bytes long.  The first byte contains the least significant 8
bits of the node number.  The second byte contains the most
significant 2 bits of the node number in the least signifi­
cant 2 bits of the byte and the area in the most significant
6 bits of the byte.

For the ServerInterpreted family, the length is ignored and
the address member is a pointer to a _X_S_e_r_v_e_r_I_n_t_e_r_p_r_e_t_e_d_A_d_­
_d_r_e_s_s structure, which contains:

__
││
typedef struct {
     int typelength;          /* length of type string, in bytes */
     int valuelength;/* length of value string, in bytes */
     char *type;              /* pointer to where to find the type string */
     char *value;             /* pointer to where to find the address */
} XServerInterpretedAddress;

││__

The type and value members point to strings representing the
type and value of the server interpreted entry.  These
strings may not be NULL‐terminated so care should be used
when accessing them.  The typelength and valuelength members
specify the length in byte of the type and value strings.


To add a single host, use _X_A_d_d_H_o_s_t.




                             228822





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XAddHost(_d_i_s_p_l_a_y, _h_o_s_t)
      Display *_d_i_s_p_l_a_y;
      XHostAddress *_h_o_s_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_h_o_s_t      Specifies the host that is to be added.
││__

The _X_A_d_d_H_o_s_t function adds the specified host to the access
control list for that display.  The server must be on the
same host as the client issuing the command, or a _B_a_d_A_c_c_e_s_s
error results.

_X_A_d_d_H_o_s_t can generate _B_a_d_A_c_c_e_s_s and _B_a_d_V_a_l_u_e errors.


To add multiple hosts at one time, use _X_A_d_d_H_o_s_t_s.
__
││
XAddHosts(_d_i_s_p_l_a_y, _h_o_s_t_s, _n_u_m___h_o_s_t_s)
      Display *_d_i_s_p_l_a_y;
      XHostAddress *_h_o_s_t_s;
      int _n_u_m___h_o_s_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_h_o_s_t_s     Specifies each host that is to be added.

_n_u_m___h_o_s_t_s Specifies the number of hosts.
││__

The _X_A_d_d_H_o_s_t_s function adds each specified host to the
access control list for that display.  The server must be on
the same host as the client issuing the command, or a _B_a_d_A_c_­
_c_e_s_s error results.

_X_A_d_d_H_o_s_t_s can generate _B_a_d_A_c_c_e_s_s and _B_a_d_V_a_l_u_e errors.


To obtain a host list, use _X_L_i_s_t_H_o_s_t_s.













                             228833





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XHostAddress *XListHosts(_d_i_s_p_l_a_y, _n_h_o_s_t_s___r_e_t_u_r_n, _s_t_a_t_e___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int *_n_h_o_s_t_s___r_e_t_u_r_n;
      Bool *_s_t_a_t_e___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_h_o_s_t_s___r_e_t_u_r_n
          Returns the number of hosts currently in the
          access control list.

_s_t_a_t_e___r_e_t_u_r_n
          Returns the state of the access control.
││__

The _X_L_i_s_t_H_o_s_t_s function returns the current access control
list as well as whether the use of the list at connection
setup was enabled or disabled.  _X_L_i_s_t_H_o_s_t_s allows a program
to find out what machines can make connections.  It also
returns a pointer to a list of host structures that were
allocated by the function.  When no longer needed, this mem­
ory should be freed by calling _X_F_r_e_e.


To remove a single host, use _X_R_e_m_o_v_e_H_o_s_t.
__
││
XRemoveHost(_d_i_s_p_l_a_y, _h_o_s_t)
      Display *_d_i_s_p_l_a_y;
      XHostAddress *_h_o_s_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_h_o_s_t      Specifies the host that is to be removed.
││__

The _X_R_e_m_o_v_e_H_o_s_t function removes the specified host from the
access control list for that display.  The server must be on
the same host as the client process, or a _B_a_d_A_c_c_e_s_s error
results.  If you remove your machine from the access list,
you can no longer connect to that server, and this operation
cannot be reversed unless you reset the server.

_X_R_e_m_o_v_e_H_o_s_t can generate _B_a_d_A_c_c_e_s_s and _B_a_d_V_a_l_u_e errors.


To remove multiple hosts at one time, use _X_R_e_m_o_v_e_H_o_s_t_s.







                             228844





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XRemoveHosts(_d_i_s_p_l_a_y, _h_o_s_t_s, _n_u_m___h_o_s_t_s)
      Display *_d_i_s_p_l_a_y;
      XHostAddress *_h_o_s_t_s;
      int _n_u_m___h_o_s_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_h_o_s_t_s     Specifies each host that is to be removed.

_n_u_m___h_o_s_t_s Specifies the number of hosts.
││__

The _X_R_e_m_o_v_e_H_o_s_t_s function removes each specified host from
the access control list for that display.  The X server must
be on the same host as the client process, or a _B_a_d_A_c_c_e_s_s
error results.  If you remove your machine from the access
list, you can no longer connect to that server, and this
operation cannot be reversed unless you reset the server.

_X_R_e_m_o_v_e_H_o_s_t_s can generate _B_a_d_A_c_c_e_s_s and _B_a_d_V_a_l_u_e errors.

99..88..22..  CChhaannggiinngg,, EEnnaabblliinngg,, oorr DDiissaabblliinngg AAcccceessss CCoonnttrrooll

Xlib provides functions that you can use to enable, disable,
or change access control.

For these functions to execute successfully, the client
application must reside on the same host as the X server
and/or have been given permission in the initial authoriza­
tion at connection setup.


To change access control, use _X_S_e_t_A_c_c_e_s_s_C_o_n_t_r_o_l.
__
││
XSetAccessControl(_d_i_s_p_l_a_y, _m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      int _m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_m_o_d_e      Specifies the mode.  You can pass _E_n_a_b_l_e_A_c_c_e_s_s or
          _D_i_s_a_b_l_e_A_c_c_e_s_s.
││__

The _X_S_e_t_A_c_c_e_s_s_C_o_n_t_r_o_l function either enables or disables
the use of the access control list at each connection setup.

_X_S_e_t_A_c_c_e_s_s_C_o_n_t_r_o_l can generate _B_a_d_A_c_c_e_s_s and _B_a_d_V_a_l_u_e
errors.




                             228855





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To enable access control, use _X_E_n_a_b_l_e_A_c_c_e_s_s_C_o_n_t_r_o_l.
__
││
XEnableAccessControl(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_E_n_a_b_l_e_A_c_c_e_s_s_C_o_n_t_r_o_l function enables the use of the
access control list at each connection setup.

_X_E_n_a_b_l_e_A_c_c_e_s_s_C_o_n_t_r_o_l can generate a _B_a_d_A_c_c_e_s_s error.


To disable access control, use _X_D_i_s_a_b_l_e_A_c_c_e_s_s_C_o_n_t_r_o_l.
__
││
XDisableAccessControl(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_D_i_s_a_b_l_e_A_c_c_e_s_s_C_o_n_t_r_o_l function disables the use of the
access control list at each connection setup.

_X_D_i_s_a_b_l_e_A_c_c_e_s_s_C_o_n_t_r_o_l can generate a _B_a_d_A_c_c_e_s_s error.



























                             228866





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 1100

                           EEvveennttss



A client application communicates with the X server through
the connection you establish with the _X_O_p_e_n_D_i_s_p_l_a_y function.
A client application sends requests to the X server over
this connection.  These requests are made by the Xlib func­
tions that are called in the client application.  Many Xlib
functions cause the X server to generate events, and the
user’s typing or moving the pointer can generate events
asynchronously.  The X server returns events to the client
on the same connection.

This chapter discusses the following topics associated with
events:

⋅    Event types

⋅    Event structures

⋅    Event masks

⋅    Event processing

Functions for handling events are dealt with in the next
chapter.

1100..11..  EEvveenntt TTyyppeess

An event is data generated asynchronously by the X server as
a result of some device activity or as side effects of a
request sent by an Xlib function.  Device‐related events
propagate from the source window to ancestor windows until
some client application has selected that event type or
until the event is explicitly discarded.  The X server gen­
erally sends an event to a client application only if the
client has specifically asked to be informed of that event
type, typically by setting the event‐mask attribute of the
window.  The mask can also be set when you create a window
or by changing the window’s event‐mask.  You can also mask
out events that would propagate to ancestor windows by
manipulating the do‐not‐propagate mask of the window’s
attributes.  However, _M_a_p_p_i_n_g_N_o_t_i_f_y events are always sent
to all clients.

An event type describes a specific event generated by the X
server.  For each event type, a corresponding constant name
is defined in <_X_1_1_/_X_._h>, which is used when referring to an
event type.  The following table lists the event category



                             228877





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


and its associated event type or types.  The processing
associated with these events is discussed in section 10.5.



-------------------------------------------------------------
EEvveenntt CCaatteeggoorryy           EEvveenntt TTyyppee
-------------------------------------------------------------
Keyboard events          _K_e_y_P_r_e_s_s, _K_e_y_R_e_l_e_a_s_e
Pointer events           _B_u_t_t_o_n_P_r_e_s_s, _B_u_t_t_o_n_R_e_l_e_a_s_e, _M_o_t_i_o_n_­
                         _N_o_t_i_f_y
Window crossing events   _E_n_t_e_r_N_o_t_i_f_y, _L_e_a_v_e_N_o_t_i_f_y
Input focus events       _F_o_c_u_s_I_n, _F_o_c_u_s_O_u_t
Keymap state notifica­   _K_e_y_m_a_p_N_o_t_i_f_y
tion event
Exposure events          _E_x_p_o_s_e, _G_r_a_p_h_i_c_s_E_x_p_o_s_e, _N_o_E_x_p_o_s_e
Structure control        _C_i_r_c_u_l_a_t_e_R_e_q_u_e_s_t, _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t,
events                   _M_a_p_R_e_q_u_e_s_t, _R_e_s_i_z_e_R_e_q_u_e_s_t
Window state notifica­   _C_i_r_c_u_l_a_t_e_N_o_t_i_f_y, _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y,
tion events              _C_r_e_a_t_e_N_o_t_i_f_y, _D_e_s_t_r_o_y_N_o_t_i_f_y, _G_r_a_v_i_­
                         _t_y_N_o_t_i_f_y, _M_a_p_N_o_t_i_f_y, _M_a_p_p_i_n_g_N_o_t_i_f_y,
                         _R_e_p_a_r_e_n_t_N_o_t_i_f_y, _U_n_m_a_p_N_o_t_i_f_y,
                         _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y
Colormap state notifi­   _C_o_l_o_r_m_a_p_N_o_t_i_f_y
cation event
Client communication     _C_l_i_e_n_t_M_e_s_s_a_g_e, _P_r_o_p_e_r_t_y_N_o_t_i_f_y,
events                   _S_e_l_e_c_t_i_o_n_C_l_e_a_r, _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y,
                         _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t
-------------------------------------------------------------


1100..22..  EEvveenntt SSttrruuccttuurreess

For each event type, a corresponding structure is declared
in <_X_1_1_/_X_l_i_b_._h>.  All the event structures have the follow­
ing common members:

__
││
typedef struct {
     int type;
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
} XAnyEvent;

││__

The type member is set to the event type constant name that
uniquely identifies it.  For example, when the X server
reports a _G_r_a_p_h_i_c_s_E_x_p_o_s_e event to a client application, it
sends an _X_G_r_a_p_h_i_c_s_E_x_p_o_s_e_E_v_e_n_t structure with the type member
set to _G_r_a_p_h_i_c_s_E_x_p_o_s_e.  The display member is set to a



                             228888





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


pointer to the display the event was read on.  The
send_event member is set to _T_r_u_e if the event came from a
_S_e_n_d_E_v_e_n_t protocol request.  The serial member is set from
the serial number reported in the protocol but expanded from
the 16‐bit least‐significant bits to a full 32‐bit value.
The window member is set to the window that is most useful
to toolkit dispatchers.

The X server can send events at any time in the input
stream.  Xlib stores any events received while waiting for a
reply in an event queue for later use.  Xlib also provides
functions that allow you to check events in the event queue
(see section 11.3).

In addition to the individual structures declared for each
event type, the _X_E_v_e_n_t structure is a union of the individ­
ual structures declared for each event type.  Depending on
the type, you should access members of each event by using
the _X_E_v_e_n_t union.






































                             228899





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef union _XEvent {
     int type;                /* must not be changed */
     XAnyEvent xany;
     XKeyEvent xkey;
     XButtonEvent xbutton;
     XMotionEvent xmotion;
     XCrossingEvent xcrossing;
     XFocusChangeEvent xfocus;
     XExposeEvent xexpose;
     XGraphicsExposeEvent xgraphicsexpose;
     XNoExposeEvent xnoexpose;
     XVisibilityEvent xvisibility;
     XCreateWindowEvent xcreatewindow;
     XDestroyWindowEvent xdestroywindow;
     XUnmapEvent xunmap;
     XMapEvent xmap;
     XMapRequestEvent xmaprequest;
     XReparentEvent xreparent;
     XConfigureEvent xconfigure;
     XGravityEvent xgravity;
     XResizeRequestEvent xresizerequest;
     XConfigureRequestEvent xconfigurerequest;
     XCirculateEvent xcirculate;
     XCirculateRequestEvent xcirculaterequest;
     XPropertyEvent xproperty;
     XSelectionClearEvent xselectionclear;
     XSelectionRequestEvent xselectionrequest;
     XSelectionEvent xselection;
     XColormapEvent xcolormap;
     XClientMessageEvent xclient;
     XMappingEvent xmapping;
     XErrorEvent xerror;
     XKeymapEvent xkeymap;
     long pad[24];
} XEvent;

││__

An _X_E_v_e_n_t structure’s first entry always is the type member,
which is set to the event type.  The second member always is
the serial number of the protocol request that generated the
event.  The third member always is send_event, which is a
_B_o_o_l that indicates if the event was sent by a different
client.  The fourth member always is a display, which is the
display that the event was read from.  Except for keymap
events, the fifth member always is a window, which has been
carefully selected to be useful to toolkit dispatchers.  To
avoid breaking toolkits, the order of these first five
entries is not to change.  Most events also contain a time
member, which is the time at which an event occurred.  In
addition, a pointer to the generic event must be cast before
it is used to access any other information in the structure.




                             229900





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1100..33..  EEvveenntt MMaasskkss

Clients select event reporting of most events relative to a
window.  To do this, pass an event mask to an Xlib event‐
handling function that takes an event_mask argument.  The
bits of the event mask are defined in <_X_1_1_/_X_._h>.  Each bit
in the event mask maps to an event mask name, which
describes the event or events you want the X server to
return to a client application.

Unless the client has specifically asked for them, most
events are not reported to clients when they are generated.
Unless the client suppresses them by setting graphics‐expo­
sures in the GC to _F_a_l_s_e, _G_r_a_p_h_i_c_s_E_x_p_o_s_e and _N_o_E_x_p_o_s_e are
reported by default as a result of _X_C_o_p_y_P_l_a_n_e and _X_C_o_p_y_A_r_e_a.
_S_e_l_e_c_t_i_o_n_C_l_e_a_r, _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t, _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y, or
_C_l_i_e_n_t_M_e_s_s_a_g_e cannot be masked.  Selection‐related events
are only sent to clients cooperating with selections (see
section 4.5).  When the keyboard or pointer mapping is
changed, _M_a_p_p_i_n_g_N_o_t_i_f_y is always sent to clients.

The following table lists the event mask constants you can
pass to the event_mask argument and the circumstances in
which you would want to specify the event mask:


-----------------------------------------------------------
EEvveenntt MMaasskk             CCiirrccuummssttaanncceess
-----------------------------------------------------------
_N_o_E_v_e_n_t_M_a_s_k            No events wanted
_K_e_y_P_r_e_s_s_M_a_s_k           Keyboard down events wanted
_K_e_y_R_e_l_e_a_s_e_M_a_s_k         Keyboard up events wanted
_B_u_t_t_o_n_P_r_e_s_s_M_a_s_k        Pointer button down events wanted
_B_u_t_t_o_n_R_e_l_e_a_s_e_M_a_s_k      Pointer button up events wanted
_E_n_t_e_r_W_i_n_d_o_w_M_a_s_k        Pointer window entry events wanted
_L_e_a_v_e_W_i_n_d_o_w_M_a_s_k        Pointer window leave events wanted
_P_o_i_n_t_e_r_M_o_t_i_o_n_M_a_s_k      Pointer motion events wanted
_P_o_i_n_t_e_r_M_o_t_i_o_n_H_i_n_t_­     Pointer motion hints wanted
_M_a_s_k
_B_u_t_t_o_n_1_M_o_t_i_o_n_M_a_s_k      Pointer motion while button 1 down
_B_u_t_t_o_n_2_M_o_t_i_o_n_M_a_s_k      Pointer motion while button 2 down
_B_u_t_t_o_n_3_M_o_t_i_o_n_M_a_s_k      Pointer motion while button 3 down
_B_u_t_t_o_n_4_M_o_t_i_o_n_M_a_s_k      Pointer motion while button 4 down
_B_u_t_t_o_n_5_M_o_t_i_o_n_M_a_s_k      Pointer motion while button 5 down
_B_u_t_t_o_n_M_o_t_i_o_n_M_a_s_k       Pointer motion while any button
                       down
_K_e_y_m_a_p_S_t_a_t_e_M_a_s_k        Keyboard state wanted at window
                       entry and focus in
_E_x_p_o_s_u_r_e_M_a_s_k           Any exposure wanted
_V_i_s_i_b_i_l_i_t_y_C_h_a_n_g_e_M_a_s_k   Any change in visibility wanted
_S_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k    Any change in window structure
                       wanted
_R_e_s_i_z_e_R_e_d_i_r_e_c_t_M_a_s_k     Redirect resize of this window




                             229911





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-----------------------------------------------------------
EEvveenntt MMaasskk             CCiirrccuummssttaanncceess
-----------------------------------------------------------
_S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_­    Substructure notification wanted
_M_a_s_k
_S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_­      Redirect structure requests on
_r_e_c_t_M_a_s_k               children
_F_o_c_u_s_C_h_a_n_g_e_M_a_s_k        Any change in input focus wanted
_P_r_o_p_e_r_t_y_C_h_a_n_g_e_M_a_s_k     Any change in property wanted
_C_o_l_o_r_m_a_p_C_h_a_n_g_e_M_a_s_k     Any change in colormap wanted
_O_w_n_e_r_G_r_a_b_B_u_t_t_o_n_M_a_s_k    Automatic grabs should activate
                       with owner_events set to _T_r_u_e
-----------------------------------------------------------



1100..44..  EEvveenntt PPrroocceessssiinngg OOvveerrvviieeww

The event reported to a client application during event pro­
cessing depends on which event masks you provide as the
event‐mask attribute for a window.  For some event masks,
there is a one‐to‐one correspondence between the event mask
constant and the event type constant.  For example, if you
pass the event mask _B_u_t_t_o_n_P_r_e_s_s_M_a_s_k, the X server sends back
only _B_u_t_t_o_n_P_r_e_s_s events.  Most events contain a time member,
which is the time at which an event occurred.

In other cases, one event mask constant can map to several
event type constants.  For example, if you pass the event
mask _S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k, the X server can send back _C_i_r_­
_c_u_l_a_t_e_N_o_t_i_f_y, _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y, _C_r_e_a_t_e_N_o_t_i_f_y, _D_e_s_t_r_o_y_N_o_t_i_f_y,
_G_r_a_v_i_t_y_N_o_t_i_f_y, _M_a_p_N_o_t_i_f_y, _R_e_p_a_r_e_n_t_N_o_t_i_f_y, or _U_n_m_a_p_N_o_t_i_f_y
events.

In another case, two event masks can map to one event type.
For example, if you pass either _P_o_i_n_t_e_r_M_o_t_i_o_n_M_a_s_k or _B_u_t_t_o_n_­
_M_o_t_i_o_n_M_a_s_k, the X server sends back a _M_o_t_i_o_n_N_o_t_i_f_y event.

The following table lists the event mask, its associated
event type or types, and the structure name associated with
the event type.  Some of these structures actually are type­
defs to a generic structure that is shared between two event
types.  Note that N.A. appears in columns for which the
information is not applicable.


------------------------------------------------------------------------------------------
EEvveenntt MMaasskk                  EEvveenntt TTyyppee         SSttrruuccttuurree                GGeenneerriicc SSttrruuccttuurree
------------------------------------------------------------------------------------------
ButtonMotionMask            MotionNotify       XPointerMovedEvent       XMotionEvent
Button1MotionMask
Button2MotionMask
Button3MotionMask




                             229922





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


------------------------------------------------------------------------------------------
EEvveenntt MMaasskk                  EEvveenntt TTyyppee         SSttrruuccttuurree                GGeenneerriicc SSttrruuccttuurree
------------------------------------------------------------------------------------------
Button4MotionMask
Button5MotionMask
ButtonPressMask             ButtonPress        XButtonPressedEvent      XButtonEvent
ButtonReleaseMask           ButtonRelease      XButtonReleasedEvent     XButtonEvent
ColormapChangeMask          ColormapNotify     XColormapEvent
EnterWindowMask             EnterNotify        XEnterWindowEvent        XCrossingEvent
LeaveWindowMask             LeaveNotify        XLeaveWindowEvent        XCrossingEvent
ExposureMask                Expose             XExposeEvent
GCGraphicsExposures in GC   GraphicsExpose     XGraphicsExposeEvent
                            NoExpose           XNoExposeEvent
FocusChangeMask             FocusIn            XFocusInEvent            XFocusChangeEvent
                            FocusOut           XFocusOutEvent           XFocusChangeEvent
KeymapStateMask             KeymapNotify       XKeymapEvent
KeyPressMask                KeyPress           XKeyPressedEvent         XKeyEvent
KeyReleaseMask              KeyRelease         XKeyReleasedEvent        XKeyEvent
OwnerGrabButtonMask         N.A.               N.A.
PointerMotionMask           MotionNotify       XPointerMovedEvent       XMotionEvent
PointerMotionHintMask       N.A.               N.A.
PropertyChangeMask          PropertyNotify     XPropertyEvent
ResizeRedirectMask          ResizeRequest      XResizeRequestEvent
StructureNotifyMask         CirculateNotify    XCirculateEvent
                            ConfigureNotify    XConfigureEvent
                            DestroyNotify      XDestroyWindowEvent
                            GravityNotify      XGravityEvent
                            MapNotify          XMapEvent
                            ReparentNotify     XReparentEvent
                            UnmapNotify        XUnmapEvent
SubstructureNotifyMask      CirculateNotify    XCirculateEvent
                            ConfigureNotify    XConfigureEvent
                            CreateNotify       XCreateWindowEvent
                            DestroyNotify      XDestroyWindowEvent
                            GravityNotify      XGravityEvent
                            MapNotify          XMapEvent
                            ReparentNotify     XReparentEvent
                            UnmapNotify        XUnmapEvent
SubstructureRedirectMask    CirculateRequest   XCirculateRequestEvent
                            ConfigureRequest   XConfigureRequestEvent
                            MapRequest         XMapRequestEvent
N.A.                        ClientMessage      XClientMessageEvent
N.A.                        MappingNotify      XMappingEvent
N.A.                        SelectionClear     XSelectionClearEvent
N.A.                        SelectionNotify    XSelectionEvent
N.A.                        SelectionRequest   XSelectionRequestEvent
VisibilityChangeMask        VisibilityNotify   XVisibilityEvent
------------------------------------------------------------------------------------------


The sections that follow describe the processing that occurs
when you select the different event masks.  The sections are
organized according to these processing categories:




                             229933





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    Keyboard and pointer events

⋅    Window crossing events

⋅    Input focus events

⋅    Keymap state notification events

⋅    Exposure events

⋅    Window state notification events

⋅    Structure control events

⋅    Colormap state notification events

⋅    Client communication events

1100..55..  KKeeyybbooaarrdd aanndd PPooiinntteerr EEvveennttss

This section discusses:

⋅    Pointer button events

⋅    Keyboard and pointer events

1100..55..11..  PPooiinntteerr BBuuttttoonn EEvveennttss

The following describes the event processing that occurs
when a pointer button press is processed with the pointer in
some window w and when no active pointer grab is in
progress.

The X server searches the ancestors of w from the root down,
looking for a passive grab to activate.  If no matching pas­
sive grab on the button exists, the X server automatically
starts an active grab for the client receiving the event and
sets the last‐pointer‐grab time to the current server time.
The effect is essentially equivalent to an _X_G_r_a_b_B_u_t_t_o_n with
these client passed arguments:

------------------------------------------------------
AArrgguummeenntt          VVaalluuee
------------------------------------------------------
_w                 The event window
_e_v_e_n_t___m_a_s_k        The client’s selected pointer
                  events on the event window
_p_o_i_n_t_e_r___m_o_d_e      _G_r_a_b_M_o_d_e_A_s_y_n_c
_k_e_y_b_o_a_r_d___m_o_d_e     _G_r_a_b_M_o_d_e_A_s_y_n_c
_o_w_n_e_r___e_v_e_n_t_s      _T_r_u_e, if the client has selected
                  _O_w_n_e_r_G_r_a_b_B_u_t_t_o_n_M_a_s_k on the event
                  window, otherwise _F_a_l_s_e
_c_o_n_f_i_n_e___t_o        _N_o_n_e




                             229944





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


------------------------------------------------------
AArrgguummeenntt          VVaalluuee
------------------------------------------------------
_c_u_r_s_o_r            _N_o_n_e
------------------------------------------------------


The active grab is automatically terminated when the logical
state of the pointer has all buttons released.  Clients can
modify the active grab by calling _X_U_n_g_r_a_b_P_o_i_n_t_e_r and
_X_C_h_a_n_g_e_A_c_t_i_v_e_P_o_i_n_t_e_r_G_r_a_b.

1100..55..22..  KKeeyybbooaarrdd aanndd PPooiinntteerr EEvveennttss

This section discusses the processing that occurs for the
keyboard events _K_e_y_P_r_e_s_s and _K_e_y_R_e_l_e_a_s_e and the pointer
events _B_u_t_t_o_n_P_r_e_s_s, _B_u_t_t_o_n_R_e_l_e_a_s_e, and _M_o_t_i_o_n_N_o_t_i_f_y.  For
information about the keyboard event‐handling utilities, see
chapter 11.

The X server reports _K_e_y_P_r_e_s_s or _K_e_y_R_e_l_e_a_s_e events to
clients wanting information about keys that logically change
state.  Note that these events are generated for all keys,
even those mapped to modifier bits.  The X server reports
_B_u_t_t_o_n_P_r_e_s_s or _B_u_t_t_o_n_R_e_l_e_a_s_e events to clients wanting
information about buttons that logically change state.

The X server reports _M_o_t_i_o_n_N_o_t_i_f_y events to clients wanting
information about when the pointer logically moves.  The X
server generates this event whenever the pointer is moved
and the pointer motion begins and ends in the window.  The
granularity of _M_o_t_i_o_n_N_o_t_i_f_y events is not guaranteed, but a
client that selects this event type is guaranteed to receive
at least one event when the pointer moves and then rests.

The generation of the logical changes lags the physical
changes if device event processing is frozen.

To receive _K_e_y_P_r_e_s_s, _K_e_y_R_e_l_e_a_s_e, _B_u_t_t_o_n_P_r_e_s_s, and _B_u_t_t_o_n_R_e_­
_l_e_a_s_e events, set _K_e_y_P_r_e_s_s_M_a_s_k, _K_e_y_R_e_l_e_a_s_e_M_a_s_k, _B_u_t_t_o_n_P_r_e_s_s_­
_M_a_s_k, and _B_u_t_t_o_n_R_e_l_e_a_s_e_M_a_s_k bits in the event‐mask attribute
of the window.

To receive _M_o_t_i_o_n_N_o_t_i_f_y events, set one or more of the fol­
lowing event masks bits in the event‐mask attribute of the
window.

⋅    _B_u_t_t_o_n_1_M_o_t_i_o_n_M_a_s_k − _B_u_t_t_o_n_5_M_o_t_i_o_n_M_a_s_k

     The client application receives _M_o_t_i_o_n_N_o_t_i_f_y events
     only when one or more of the specified buttons is
     pressed.





                             229955





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    _B_u_t_t_o_n_M_o_t_i_o_n_M_a_s_k

     The client application receives _M_o_t_i_o_n_N_o_t_i_f_y events
     only when at least one button is pressed.

⋅    _P_o_i_n_t_e_r_M_o_t_i_o_n_M_a_s_k

     The client application receives _M_o_t_i_o_n_N_o_t_i_f_y events
     independent of the state of the pointer buttons.

⋅    _P_o_i_n_t_e_r_M_o_t_i_o_n_H_i_n_t_M_a_s_k

     If _P_o_i_n_t_e_r_M_o_t_i_o_n_H_i_n_t_M_a_s_k is selected in combination
     with one or more of the above masks, the X server is
     free to send only one _M_o_t_i_o_n_N_o_t_i_f_y event (with the
     is_hint member  of the _X_P_o_i_n_t_e_r_M_o_v_e_d_E_v_e_n_t structure set
     to _N_o_t_i_f_y_H_i_n_t) to the client for the event window,
     until either the key or button state changes, the
     pointer leaves the event window, or the client calls
     _X_Q_u_e_r_y_P_o_i_n_t_e_r or _X_G_e_t_M_o_t_i_o_n_E_v_e_n_t_s.  The server still
     may send _M_o_t_i_o_n_N_o_t_i_f_y events without is_hint set to
     _N_o_t_i_f_y_H_i_n_t.

The source of the event is the viewable window that the
pointer is in.  The window used by the X server to report
these events depends on the window’s position in the window
hierarchy and whether any intervening window prohibits the
generation of these events.  Starting with the source win­
dow, the X server searches up the window hierarchy until it
locates the first window specified by a client as having an
interest in these events.  If one of the intervening windows
has its do‐not‐propagate‐mask set to prohibit generation of
the event type, the events of those types will be sup­
pressed.  Clients can modify the actual window used for
reporting by performing active grabs and, in the case of
keyboard events, by using the focus window.

The structures for these event types contain:



















                             229966





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     int type;                /* ButtonPress or ButtonRelease */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;           /* ‘‘event’’ window it is reported relative to */
     Window root;             /* root window that the event occurred on */
     Window subwindow;        /* child window */
     Time time;               /* milliseconds */
     int x, y;                /* pointer x, y coordinates in event window */
     int x_root, y_root;      /* coordinates relative to root */
     unsigned int state;      /* key or button mask */
     unsigned int button;     /* detail */
     Bool same_screen;        /* same screen flag */
} XButtonEvent;
typedef XButtonEvent XButtonPressedEvent;
typedef XButtonEvent XButtonReleasedEvent;



typedef struct {
     int type;                /* KeyPress or KeyRelease */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;           /* ‘‘event’’ window it is reported relative to */
     Window root;             /* root window that the event occurred on */
     Window subwindow;        /* child window */
     Time time;               /* milliseconds */
     int x, y;                /* pointer x, y coordinates in event window */
     int x_root, y_root;      /* coordinates relative to root */
     unsigned int state;      /* key or button mask */
     unsigned int keycode;    /* detail */
     Bool same_screen;        /* same screen flag */
} XKeyEvent;
typedef XKeyEvent XKeyPressedEvent;
typedef XKeyEvent XKeyReleasedEvent;



typedef struct {
     int type;                /* MotionNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;           /* ‘‘event’’ window reported relative to */
     Window root;             /* root window that the event occurred on */
     Window subwindow;        /* child window */
     Time time;               /* milliseconds */
     int x, y;                /* pointer x, y coordinates in event window */
     int x_root, y_root;      /* coordinates relative to root */
     unsigned int state;      /* key or button mask */
     char is_hint;            /* detail */



                             229977





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     Bool same_screen;        /* same screen flag */
} XMotionEvent;
typedef XMotionEvent XPointerMovedEvent;

││__

These structures have the following common members: window,
root, subwindow, time, x, y, x_root, y_root, state, and
same_screen.  The window member is set to the window on
which the event was generated and is referred to as the
event window.  As long as the conditions previously dis­
cussed are met, this is the window used by the X server to
report the event.  The root member is set to the source win­
dow’s root window.  The x_root and y_root members are set to
the pointer’s coordinates relative to the root window’s ori­
gin at the time of the event.

The same_screen member is set to indicate whether the event
window is on the same screen as the root window and can be
either _T_r_u_e or _F_a_l_s_e.  If _T_r_u_e, the event and root windows
are on the same screen.  If _F_a_l_s_e, the event and root win­
dows are not on the same screen.

If the source window is an inferior of the event window, the
subwindow member of the structure is set to the child of the
event window that is the source window or the child of the
event window that is an ancestor of the source window.  Oth­
erwise, the X server sets the subwindow member to _N_o_n_e.  The
time member is set to the time when the event was generated
and is expressed in milliseconds.

If the event window is on the same screen as the root win­
dow, the x and y members are set to the coordinates relative
to the event window’s origin.  Otherwise, these members are
set to zero.

The state member is set to indicate the logical state of the
pointer buttons and modifier keys just prior to the event,
which is the bitwise inclusive OR of one or more of the but­
ton or modifier key masks: _B_u_t_t_o_n_1_M_a_s_k, _B_u_t_t_o_n_2_M_a_s_k, _B_u_t_­
_t_o_n_3_M_a_s_k, _B_u_t_t_o_n_4_M_a_s_k, _B_u_t_t_o_n_5_M_a_s_k, _S_h_i_f_t_M_a_s_k, _L_o_c_k_M_a_s_k,
_C_o_n_t_r_o_l_M_a_s_k, _M_o_d_1_M_a_s_k, _M_o_d_2_M_a_s_k, _M_o_d_3_M_a_s_k, _M_o_d_4_M_a_s_k, and
_M_o_d_5_M_a_s_k.

Each of these structures also has a member that indicates
the detail.  For the _X_K_e_y_P_r_e_s_s_e_d_E_v_e_n_t and _X_K_e_y_R_e_l_e_a_s_e_d_E_v_e_n_t
structures, this member is called a keycode.  It is set to a
number that represents a physical key on the keyboard.  The
keycode is an arbitrary representation for any key on the
keyboard (see sections 12.7 and 16.1).

For the _X_B_u_t_t_o_n_P_r_e_s_s_e_d_E_v_e_n_t and _X_B_u_t_t_o_n_R_e_l_e_a_s_e_d_E_v_e_n_t struc­
tures, this member is called button.  It represents the
pointer button that changed state and can be the _B_u_t_t_o_n_1,



                             229988





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_B_u_t_t_o_n_2, _B_u_t_t_o_n_3, _B_u_t_t_o_n_4, or _B_u_t_t_o_n_5 value.  For the
_X_P_o_i_n_t_e_r_M_o_v_e_d_E_v_e_n_t structure, this member is called is_hint.
It can be set to _N_o_t_i_f_y_N_o_r_m_a_l or _N_o_t_i_f_y_H_i_n_t.

Some of the symbols mentioned in this section have fixed
values, as follows:

-----------------------------------------------------------
SSyymmbbooll                 VVaalluuee
-----------------------------------------------------------
_B_u_t_t_o_n_1_M_o_t_i_o_n_M_a_s_k      (1L<<8)
_B_u_t_t_o_n_2_M_o_t_i_o_n_M_a_s_k      (1L<<9)
_B_u_t_t_o_n_3_M_o_t_i_o_n_M_a_s_k      (1L<<10)
_B_u_t_t_o_n_4_M_o_t_i_o_n_M_a_s_k      (1L<<11)
_B_u_t_t_o_n_5_M_o_t_i_o_n_M_a_s_k      (1L<<12)
_B_u_t_t_o_n_1_M_a_s_k            (1<<8)
_B_u_t_t_o_n_2_M_a_s_k            (1<<9)
_B_u_t_t_o_n_3_M_a_s_k            (1<<10)
_B_u_t_t_o_n_4_M_a_s_k            (1<<11)
_B_u_t_t_o_n_5_M_a_s_k            (1<<12)
_S_h_i_f_t_M_a_s_k              (1<<0)
_L_o_c_k_M_a_s_k               (1<<1)
_C_o_n_t_r_o_l_M_a_s_k            (1<<2)
_M_o_d_1_M_a_s_k               (1<<3)
_M_o_d_2_M_a_s_k               (1<<4)
_M_o_d_3_M_a_s_k               (1<<5)
_M_o_d_4_M_a_s_k               (1<<6)
_M_o_d_5_M_a_s_k               (1<<7)
_B_u_t_t_o_n_1                1
_B_u_t_t_o_n_2                2
_B_u_t_t_o_n_3                3
_B_u_t_t_o_n_4                4
_B_u_t_t_o_n_5                5
-----------------------------------------------------------


1100..66..  WWiinnddooww EEnnttrryy//EExxiitt EEvveennttss

This section describes the processing that occurs for the
window crossing events _E_n_t_e_r_N_o_t_i_f_y and _L_e_a_v_e_N_o_t_i_f_y.  If a
pointer motion or a window hierarchy change causes the
pointer to be in a different window than before, the X
server reports _E_n_t_e_r_N_o_t_i_f_y or _L_e_a_v_e_N_o_t_i_f_y events to clients
who have selected for these events.  All _E_n_t_e_r_N_o_t_i_f_y and
_L_e_a_v_e_N_o_t_i_f_y events caused by a hierarchy change are gener­
ated after any hierarchy event (_U_n_m_a_p_N_o_t_i_f_y, _M_a_p_N_o_t_i_f_y, _C_o_n_­
_f_i_g_u_r_e_N_o_t_i_f_y, _G_r_a_v_i_t_y_N_o_t_i_f_y, _C_i_r_c_u_l_a_t_e_N_o_t_i_f_y) caused by that
change; however, the X protocol does not constrain the
ordering of _E_n_t_e_r_N_o_t_i_f_y and _L_e_a_v_e_N_o_t_i_f_y events with respect
to _F_o_c_u_s_O_u_t, _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y, and _E_x_p_o_s_e events.

This contrasts with _M_o_t_i_o_n_N_o_t_i_f_y events, which are also gen­
erated when the pointer moves but only when the pointer
motion begins and ends in a single window.  An _E_n_t_e_r_N_o_t_i_f_y



                             229999





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


or _L_e_a_v_e_N_o_t_i_f_y event also can be generated when some client
application calls _X_G_r_a_b_P_o_i_n_t_e_r and _X_U_n_g_r_a_b_P_o_i_n_t_e_r.

To receive _E_n_t_e_r_N_o_t_i_f_y or _L_e_a_v_e_N_o_t_i_f_y events, set the _E_n_t_e_r_­
_W_i_n_d_o_w_M_a_s_k or _L_e_a_v_e_W_i_n_d_o_w_M_a_s_k bits of the event‐mask
attribute of the window.

The structure for these event types contains:

__
││
typedef struct {
     int type;                /* EnterNotify or LeaveNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;           /* ‘‘event’’ window reported relative to */
     Window root;             /* root window that the event occurred on */
     Window subwindow;        /* child window */
     Time time;               /* milliseconds */
     int x, y;                /* pointer x, y coordinates in event window */
     int x_root, y_root;      /* coordinates relative to root */
     int mode;                /* NotifyNormal, NotifyGrab, NotifyUngrab */
     int detail;
                              /*
                              * NotifyAncestor, NotifyVirtual, NotifyInferior,
                              * NotifyNonlinear,NotifyNonlinearVirtual
                              */
     Bool same_screen;        /* same screen flag */
     Bool focus;              /* boolean focus */
     unsigned int state;      /* key or button mask */
} XCrossingEvent;
typedef XCrossingEvent XEnterWindowEvent;
typedef XCrossingEvent XLeaveWindowEvent;

││__

The window member is set to the window on which the _E_n_t_e_r_­
_N_o_t_i_f_y or _L_e_a_v_e_N_o_t_i_f_y event was generated and is referred to
as the event window.  This is the window used by the X
server to report the event, and is relative to the root win­
dow on which the event occurred.  The root member is set to
the root window of the screen on which the event occurred.

For a _L_e_a_v_e_N_o_t_i_f_y event, if a child of the event window con­
tains the initial position of the pointer, the subwindow
component is set to that child.  Otherwise, the X server
sets the subwindow member to _N_o_n_e.  For an _E_n_t_e_r_N_o_t_i_f_y
event, if a child of the event window contains the final
pointer position, the subwindow component is set to that
child or _N_o_n_e.

The time member is set to the time when the event was gener­
ated and is expressed in milliseconds.  The x and y members



                             330000





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


are set to the coordinates of the pointer position in the
event window.  This position is always the pointer’s final
position, not its initial position.  If the event window is
on the same screen as the root window, x and y are the
pointer coordinates relative to the event window’s origin.
Otherwise, x and y are set to zero.  The x_root and y_root
members are set to the pointer’s coordinates relative to the
root window’s origin at the time of the event.

The same_screen member is set to indicate whether the event
window is on the same screen as the root window and can be
either _T_r_u_e or _F_a_l_s_e.  If _T_r_u_e, the event and root windows
are on the same screen.  If _F_a_l_s_e, the event and root win­
dows are not on the same screen.

The focus member is set to indicate whether the event window
is the focus window or an inferior of the focus window.  The
X server can set this member to either _T_r_u_e or _F_a_l_s_e.  If
_T_r_u_e, the event window is the focus window or an inferior of
the focus window.  If _F_a_l_s_e, the event window is not the
focus window or an inferior of the focus window.

The state member is set to indicate the state of the pointer
buttons and modifier keys just prior to the event.  The X
server can set this member to the bitwise inclusive OR of
one or more of the button or modifier key masks: _B_u_t_­
_t_o_n_1_M_a_s_k, _B_u_t_t_o_n_2_M_a_s_k, _B_u_t_t_o_n_3_M_a_s_k, _B_u_t_t_o_n_4_M_a_s_k, _B_u_t_­
_t_o_n_5_M_a_s_k, _S_h_i_f_t_M_a_s_k, _L_o_c_k_M_a_s_k, _C_o_n_t_r_o_l_M_a_s_k, _M_o_d_1_M_a_s_k,
_M_o_d_2_M_a_s_k, _M_o_d_3_M_a_s_k, _M_o_d_4_M_a_s_k, _M_o_d_5_M_a_s_k.

The mode member is set to indicate whether the events are
normal events, pseudo‐motion events when a grab activates,
or pseudo‐motion events when a grab deactivates.  The X
server can set this member to _N_o_t_i_f_y_N_o_r_m_a_l, _N_o_t_i_f_y_G_r_a_b, or
_N_o_t_i_f_y_U_n_g_r_a_b.

The detail member is set to indicate the notify detail and
can be _N_o_t_i_f_y_A_n_c_e_s_t_o_r, _N_o_t_i_f_y_V_i_r_t_u_a_l, _N_o_t_i_f_y_I_n_f_e_r_i_o_r, _N_o_t_i_­
_f_y_N_o_n_l_i_n_e_a_r, or _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r_V_i_r_t_u_a_l.

1100..66..11..  NNoorrmmaall EEnnttrryy//EExxiitt EEvveennttss

_E_n_t_e_r_N_o_t_i_f_y and _L_e_a_v_e_N_o_t_i_f_y events are generated when the
pointer moves from one window to another window.  Normal
events are identified by _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t or _X_L_e_a_v_e_W_i_n_d_o_w_­
_E_v_e_n_t structures whose mode member is set to _N_o_t_i_f_y_N_o_r_m_a_l.

⋅    When the pointer moves from window A to window B and A
     is an inferior of B, the X server does the following:

     −    It generates a _L_e_a_v_e_N_o_t_i_f_y event on window A, with
          the detail member of the _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t struc­
          ture set to _N_o_t_i_f_y_A_n_c_e_s_t_o_r.




                             330011





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     −    It generates a _L_e_a_v_e_N_o_t_i_f_y event on each window
          between window A and window B, exclusive, with the
          detail member of each _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t structure
          set to _N_o_t_i_f_y_V_i_r_t_u_a_l.

     −    It generates an _E_n_t_e_r_N_o_t_i_f_y event on window B,
          with the detail member of the _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t
          structure set to _N_o_t_i_f_y_I_n_f_e_r_i_o_r.

⋅    When the pointer moves from window A to window B and B
     is an inferior of A, the X server does the following:

     −    It generates a _L_e_a_v_e_N_o_t_i_f_y event on window A, with
          the detail member of the _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t struc­
          ture set to _N_o_t_i_f_y_I_n_f_e_r_i_o_r.

     −    It generates an _E_n_t_e_r_N_o_t_i_f_y event on each window
          between window A and window B, exclusive, with the
          detail member of each _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t structure
          set to _N_o_t_i_f_y_V_i_r_t_u_a_l.

     −    It generates an _E_n_t_e_r_N_o_t_i_f_y event on window B,
          with the detail member of the _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t
          structure set to _N_o_t_i_f_y_A_n_c_e_s_t_o_r.

⋅    When the pointer moves from window A to window B and
     window C is their least common ancestor, the X server
     does the following:

     −    It generates a _L_e_a_v_e_N_o_t_i_f_y event on window A, with
          the detail member of the _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t struc­
          ture set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

     −    It generates a _L_e_a_v_e_N_o_t_i_f_y event on each window
          between window A and window C, exclusive, with the
          detail member of each _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t structure
          set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r_V_i_r_t_u_a_l.

     −    It generates an _E_n_t_e_r_N_o_t_i_f_y event on each window
          between window C and window B, exclusive, with the
          detail member of each _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t structure
          set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r_V_i_r_t_u_a_l.

     −    It generates an _E_n_t_e_r_N_o_t_i_f_y event on window B,
          with the detail member of the _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t
          structure set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

⋅    When the pointer moves from window A to window B on
     different screens, the X server does the following:

     −    It generates a _L_e_a_v_e_N_o_t_i_f_y event on window A, with
          the detail member of the _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t struc­
          ture set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.




                             330022





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     −    If window A is not a root window, it generates a
          _L_e_a_v_e_N_o_t_i_f_y event on each window above window A up
          to and including its root, with the detail member
          of each _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t structure set to _N_o_t_i_­
          _f_y_N_o_n_l_i_n_e_a_r_V_i_r_t_u_a_l.

     −    If window B is not a root window, it generates an
          _E_n_t_e_r_N_o_t_i_f_y event on each window from window B’s
          root down to but not including window B, with the
          detail member of each _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t structure
          set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r_V_i_r_t_u_a_l.

     −    It generates an _E_n_t_e_r_N_o_t_i_f_y event on window B,
          with the detail member of the _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t
          structure set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

1100..66..22..  GGrraabb aanndd UUnnggrraabb EEnnttrryy//EExxiitt EEvveennttss

Pseudo‐motion mode _E_n_t_e_r_N_o_t_i_f_y and _L_e_a_v_e_N_o_t_i_f_y events are
generated when a pointer grab activates or deactivates.
Events in which the pointer grab activates are identified by
_X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t or _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t structures whose mode
member is set to _N_o_t_i_f_y_G_r_a_b.  Events in which the pointer
grab deactivates are identified by _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t or
_X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t structures whose mode member is set to
_N_o_t_i_f_y_U_n_g_r_a_b (see _X_G_r_a_b_P_o_i_n_t_e_r).

⋅    When a pointer grab activates after any initial warp
     into a confine_to window and before generating any
     actual _B_u_t_t_o_n_P_r_e_s_s event that activates the grab, G is
     the grab_window for the grab, and P is the window the
     pointer is in, the X server does the following:

     −    It generates _E_n_t_e_r_N_o_t_i_f_y and _L_e_a_v_e_N_o_t_i_f_y events
          (see section 10.6.1) with the mode members of the
          _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t and _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t structures
          set to _N_o_t_i_f_y_G_r_a_b.  These events are generated as
          if the pointer were to suddenly warp from its cur­
          rent position in P to some position in G.  How­
          ever, the pointer does not warp, and the X server
          uses the pointer position as both the initial and
          final positions for the events.

⋅    When a pointer grab deactivates after generating any
     actual _B_u_t_t_o_n_R_e_l_e_a_s_e event that deactivates the grab, G
     is the grab_window for the grab, and P is the window
     the pointer is in, the X server does the following:

     −    It generates _E_n_t_e_r_N_o_t_i_f_y and _L_e_a_v_e_N_o_t_i_f_y events
          (see section 10.6.1) with the mode members of the
          _X_E_n_t_e_r_W_i_n_d_o_w_E_v_e_n_t and _X_L_e_a_v_e_W_i_n_d_o_w_E_v_e_n_t structures
          set to _N_o_t_i_f_y_U_n_g_r_a_b.  These events are generated
          as if the pointer were to suddenly warp from some
          position in G to its current position in P.



                             330033





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


          However, the pointer does not warp, and the X
          server uses the current pointer position as both
          the initial and final positions for the events.

1100..77..  IInnppuutt FFooccuuss EEvveennttss

This section describes the processing that occurs for the
input focus events _F_o_c_u_s_I_n and _F_o_c_u_s_O_u_t.  The X server can
report _F_o_c_u_s_I_n or _F_o_c_u_s_O_u_t events to clients wanting infor­
mation about when the input focus changes.  The keyboard is
always attached to some window (typically, the root window
or a top‐level window), which is called the focus window.
The focus window and the position of the pointer determine
the window that receives keyboard input.  Clients may need
to know when the input focus changes to control highlighting
of areas on the screen.

To receive _F_o_c_u_s_I_n or _F_o_c_u_s_O_u_t events, set the _F_o_c_u_s_C_h_a_n_g_e_­
_M_a_s_k bit in the event‐mask attribute of the window.

The structure for these event types contains:

__
││
typedef struct {
     int type;                /* FocusIn or FocusOut */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;           /* window of event */
     int mode;                /* NotifyNormal, NotifyGrab, NotifyUngrab */
     int detail;
                              /*
                              * NotifyAncestor, NotifyVirtual, NotifyInferior,
                              * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
                              * NotifyPointerRoot, NotifyDetailNone
                              */
} XFocusChangeEvent;
typedef XFocusChangeEvent XFocusInEvent;
typedef XFocusChangeEvent XFocusOutEvent;

││__

The window member is set to the window on which the _F_o_c_u_s_I_n
or _F_o_c_u_s_O_u_t event was generated.  This is the window used by
the X server to report the event.  The mode member is set to
indicate whether the focus events are normal focus events,
focus events while grabbed, focus events when a grab acti­
vates, or focus events when a grab deactivates.  The X
server can set the mode member to _N_o_t_i_f_y_N_o_r_m_a_l, _N_o_t_i_f_y_W_h_i_l_e_­
_G_r_a_b_b_e_d, _N_o_t_i_f_y_G_r_a_b, or _N_o_t_i_f_y_U_n_g_r_a_b.

All _F_o_c_u_s_O_u_t events caused by a window unmap are generated
after any _U_n_m_a_p_N_o_t_i_f_y event; however, the X protocol does



                             330044





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


not constrain the ordering of _F_o_c_u_s_O_u_t events with respect
to generated _E_n_t_e_r_N_o_t_i_f_y, _L_e_a_v_e_N_o_t_i_f_y, _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y, and
_E_x_p_o_s_e events.

Depending on the event mode, the detail member is set to
indicate the notify detail and can be _N_o_t_i_f_y_A_n_c_e_s_t_o_r, _N_o_t_i_­
_f_y_V_i_r_t_u_a_l, _N_o_t_i_f_y_I_n_f_e_r_i_o_r, _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r, _N_o_t_i_f_y_N_o_n_l_i_n_­
_e_a_r_V_i_r_t_u_a_l, _N_o_t_i_f_y_P_o_i_n_t_e_r, _N_o_t_i_f_y_P_o_i_n_t_e_r_R_o_o_t, or _N_o_t_i_f_y_D_e_­
_t_a_i_l_N_o_n_e.

1100..77..11..  NNoorrmmaall FFooccuuss EEvveennttss aanndd FFooccuuss EEvveennttss WWhhiillee GGrraabbbbeedd

Normal focus events are identified by _X_F_o_c_u_s_I_n_E_v_e_n_t or _X_F_o_­
_c_u_s_O_u_t_E_v_e_n_t structures whose mode member is set to _N_o_t_i_­
_f_y_N_o_r_m_a_l.  Focus events while grabbed are identified by _X_F_o_­
_c_u_s_I_n_E_v_e_n_t or _X_F_o_c_u_s_O_u_t_E_v_e_n_t structures whose mode member is
set to _N_o_t_i_f_y_W_h_i_l_e_G_r_a_b_b_e_d.  The X server processes normal
focus and focus events while grabbed according to the fol­
lowing:

⋅    When the focus moves from window A to window B, A is an
     inferior of B, and the pointer is in window P, the X
     server does the following:

     −    It generates a _F_o_c_u_s_O_u_t event on window A, with
          the detail member of the _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure
          set to _N_o_t_i_f_y_A_n_c_e_s_t_o_r.

     −    It generates a _F_o_c_u_s_O_u_t event on each window
          between window A and window B, exclusive, with the
          detail member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set
          to _N_o_t_i_f_y_V_i_r_t_u_a_l.

     −    It generates a _F_o_c_u_s_I_n event on window B, with the
          detail member of the _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set
          to _N_o_t_i_f_y_I_n_f_e_r_i_o_r.

     −    If window P is an inferior of window B but window
          P is not window A or an inferior or ancestor of
          window A, it generates a _F_o_c_u_s_I_n event on each
          window below window B, down to and including win­
          dow P, with the detail member of each _X_F_o_c_u_s_I_n_­
          _E_v_e_n_t structure set to _N_o_t_i_f_y_P_o_i_n_t_e_r.

⋅    When the focus moves from window A to window B, B is an
     inferior of A, and the pointer is in window P, the X
     server does the following:

     −    If window P is an inferior of window A but P is
          not an inferior of window B or an ancestor of B,
          it generates a _F_o_c_u_s_O_u_t event on each window from
          window P up to but not including window A, with
          the detail member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure
          set to _N_o_t_i_f_y_P_o_i_n_t_e_r.



                             330055





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     −    It generates a _F_o_c_u_s_O_u_t event on window A, with
          the detail member of the _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure
          set to _N_o_t_i_f_y_I_n_f_e_r_i_o_r.

     −    It generates a _F_o_c_u_s_I_n event on each window
          between window A and window B, exclusive, with the
          detail member of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set
          to _N_o_t_i_f_y_V_i_r_t_u_a_l.

     −    It generates a _F_o_c_u_s_I_n event on window B, with the
          detail member of the _X_F_o_c_u_s_I_n_E_v_e_n_t structure set
          to _N_o_t_i_f_y_A_n_c_e_s_t_o_r.

⋅    When the focus moves from window A to window B, window
     C is their least common ancestor, and the pointer is in
     window P, the X server does the following:

     −    If window P is an inferior of window A, it gener­
          ates a _F_o_c_u_s_O_u_t event on each window from window P
          up to but not including window A, with the detail
          member of the _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

     −    It generates a _F_o_c_u_s_O_u_t event on window A, with
          the detail member of the _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure
          set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

     −    It generates a _F_o_c_u_s_O_u_t event on each window
          between window A and window C, exclusive, with the
          detail member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set
          to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r_V_i_r_t_u_a_l.

     −    It generates a _F_o_c_u_s_I_n event on each window
          between C and B, exclusive, with the detail member
          of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set to _N_o_t_i_f_y_N_o_n_­
          _l_i_n_e_a_r_V_i_r_t_u_a_l.

     −    It generates a _F_o_c_u_s_I_n event on window B, with the
          detail member of the _X_F_o_c_u_s_I_n_E_v_e_n_t structure set
          to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

     −    If window P is an inferior of window B, it gener­
          ates a _F_o_c_u_s_I_n event on each window below window B
          down to and including window P, with the detail
          member of the _X_F_o_c_u_s_I_n_E_v_e_n_t structure set to _N_o_t_i_­
          _f_y_P_o_i_n_t_e_r.

⋅    When the focus moves from window A to window B on dif­
     ferent screens and the pointer is in window P, the X
     server does the following:

     −    If window P is an inferior of window A, it gener­
          ates a _F_o_c_u_s_O_u_t event on each window from window P
          up to but not including window A, with the detail



                             330066





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


          member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

     −    It generates a _F_o_c_u_s_O_u_t event on window A, with
          the detail member of the _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure
          set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

     −    If window A is not a root window, it generates a
          _F_o_c_u_s_O_u_t event on each window above window A up to
          and including its root, with the detail member of
          each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set to _N_o_t_i_f_y_N_o_n_l_i_n_­
          _e_a_r_V_i_r_t_u_a_l.

     −    If window B is not a root window, it generates a
          _F_o_c_u_s_I_n event on each window from window B’s root
          down to but not including window B, with the
          detail member of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set
          to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r_V_i_r_t_u_a_l.

     −    It generates a _F_o_c_u_s_I_n event on window B, with the
          detail member of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set
          to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

     −    If window P is an inferior of window B, it gener­
          ates a _F_o_c_u_s_I_n event on each window below window B
          down to and including window P, with the detail
          member of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

⋅    When the focus moves from window A to _P_o_i_n_t_e_r_R_o_o_t
     (events sent to the window under the pointer) or _N_o_n_e
     (discard), and the pointer is in window P, the X server
     does the following:

     −    If window P is an inferior of window A, it gener­
          ates a _F_o_c_u_s_O_u_t event on each window from window P
          up to but not including window A, with the detail
          member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

     −    It generates a _F_o_c_u_s_O_u_t event on window A, with
          the detail member of the _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure
          set to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

     −    If window A is not a root window, it generates a
          _F_o_c_u_s_O_u_t event on each window above window A up to
          and including its root, with the detail member of
          each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set to _N_o_t_i_f_y_N_o_n_l_i_n_­
          _e_a_r_V_i_r_t_u_a_l.

     −    It generates a _F_o_c_u_s_I_n event on the root window of
          all screens, with the detail member of each _X_F_o_­
          _c_u_s_I_n_E_v_e_n_t structure set to _N_o_t_i_f_y_P_o_i_n_t_e_r_R_o_o_t (or
          _N_o_t_i_f_y_D_e_t_a_i_l_N_o_n_e).



                             330077





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     −    If the new focus is _P_o_i_n_t_e_r_R_o_o_t, it generates a
          _F_o_c_u_s_I_n event on each window from window P’s root
          down to and including window P, with the detail
          member of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

⋅    When the focus moves from _P_o_i_n_t_e_r_R_o_o_t (events sent to
     the window under the pointer) or _N_o_n_e to window A, and
     the pointer is in window P, the X server does the fol­
     lowing:

     −    If the old focus is _P_o_i_n_t_e_r_R_o_o_t, it generates a
          _F_o_c_u_s_O_u_t event on each window from window P up to
          and including window P’s root, with the detail
          member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

     −    It generates a _F_o_c_u_s_O_u_t event on all root windows,
          with the detail member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t
          structure set to _N_o_t_i_f_y_P_o_i_n_t_e_r_R_o_o_t (or _N_o_t_i_f_y_D_e_­
          _t_a_i_l_N_o_n_e).

     −    If window A is not a root window, it generates a
          _F_o_c_u_s_I_n event on each window from window A’s root
          down to but not including window A, with the
          detail member of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set
          to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r_V_i_r_t_u_a_l.

     −    It generates a _F_o_c_u_s_I_n event on window A, with the
          detail member of the _X_F_o_c_u_s_I_n_E_v_e_n_t structure set
          to _N_o_t_i_f_y_N_o_n_l_i_n_e_a_r.

     −    If window P is an inferior of window A, it gener­
          ates a _F_o_c_u_s_I_n event on each window below window A
          down to and including window P, with the detail
          member of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

⋅    When the focus moves from _P_o_i_n_t_e_r_R_o_o_t (events sent to
     the window under the pointer) to _N_o_n_e (or vice versa),
     and the pointer is in window P, the X server does the
     following:

     −    If the old focus is _P_o_i_n_t_e_r_R_o_o_t, it generates a
          _F_o_c_u_s_O_u_t event on each window from window P up to
          and including window P’s root, with the detail
          member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

     −    It generates a _F_o_c_u_s_O_u_t event on all root windows,
          with the detail member of each _X_F_o_c_u_s_O_u_t_E_v_e_n_t
          structure set to either _N_o_t_i_f_y_P_o_i_n_t_e_r_R_o_o_t or _N_o_t_i_­
          _f_y_D_e_t_a_i_l_N_o_n_e.




                             330088





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     −    It generates a _F_o_c_u_s_I_n event on all root windows,
          with the detail member of each _X_F_o_c_u_s_I_n_E_v_e_n_t
          structure set to _N_o_t_i_f_y_D_e_t_a_i_l_N_o_n_e or _N_o_t_i_f_y_P_o_i_n_t_­
          _e_r_R_o_o_t.

     −    If the new focus is _P_o_i_n_t_e_r_R_o_o_t, it generates a
          _F_o_c_u_s_I_n event on each window from window P’s root
          down to and including window P, with the detail
          member of each _X_F_o_c_u_s_I_n_E_v_e_n_t structure set to
          _N_o_t_i_f_y_P_o_i_n_t_e_r.

1100..77..22..  FFooccuuss EEvveennttss GGeenneerraatteedd bbyy GGrraabbss

Focus events in which the keyboard grab activates are iden­
tified by _X_F_o_c_u_s_I_n_E_v_e_n_t or _X_F_o_c_u_s_O_u_t_E_v_e_n_t structures whose
mode member is set to _N_o_t_i_f_y_G_r_a_b.  Focus events in which the
keyboard grab deactivates are identified by _X_F_o_c_u_s_I_n_E_v_e_n_t or
_X_F_o_c_u_s_O_u_t_E_v_e_n_t structures whose mode member is set to _N_o_t_i_­
_f_y_U_n_g_r_a_b (see _X_G_r_a_b_K_e_y_b_o_a_r_d).

⋅    When a keyboard grab activates before generating any
     actual _K_e_y_P_r_e_s_s event that activates the grab, G is the
     grab_window, and F is the current focus, the X server
     does the following:

     −    It generates _F_o_c_u_s_I_n and _F_o_c_u_s_O_u_t events, with the
          mode members of the _X_F_o_c_u_s_I_n_E_v_e_n_t and _X_F_o_c_u_­
          _s_O_u_t_E_v_e_n_t structures set to _N_o_t_i_f_y_G_r_a_b.  These
          events are generated as if the focus were to
          change from F to G.

⋅    When a keyboard grab deactivates after generating any
     actual _K_e_y_R_e_l_e_a_s_e event that deactivates the grab, G is
     the grab_window, and F is the current focus, the X
     server does the following:

     −    It generates _F_o_c_u_s_I_n and _F_o_c_u_s_O_u_t events, with the
          mode members of the _X_F_o_c_u_s_I_n_E_v_e_n_t and _X_F_o_c_u_­
          _s_O_u_t_E_v_e_n_t structures set to _N_o_t_i_f_y_U_n_g_r_a_b.  These
          events are generated as if the focus were to
          change from G to F.

1100..88..  KKeeyy MMaapp SSttaattee NNoottiiffiiccaattiioonn EEvveennttss

The X server can report _K_e_y_m_a_p_N_o_t_i_f_y events to clients that
want information about changes in their keyboard state.

To receive _K_e_y_m_a_p_N_o_t_i_f_y events, set the _K_e_y_m_a_p_S_t_a_t_e_M_a_s_k bit
in the event‐mask attribute of the window.  The X server
generates this event immediately after every _E_n_t_e_r_N_o_t_i_f_y and
_F_o_c_u_s_I_n event.

The structure for this event type contains:




                             330099





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
/* generated on EnterWindow and FocusIn when KeymapState selected */
typedef struct {
     int type;                /* KeymapNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
     char key_vector[32];
} XKeymapEvent;

││__

The window member is not used but is present to aid some
toolkits.  The key_vector member is set to the bit vector of
the keyboard.  Each bit set to 1 indicates that the corre­
sponding key is currently pressed.  The vector is repre­
sented as 32 bytes.  Byte N (from 0) contains the bits for
keys 8N to 8N + 7 with the least significant bit in the byte
representing key 8N.

1100..99..  EExxppoossuurree EEvveennttss

The X protocol does not guarantee to preserve the contents
of window regions when the windows are obscured or reconfig­
ured.  Some implementations may preserve the contents of
windows.  Other implementations are free to destroy the con­
tents of windows when exposed.  X expects client applica­
tions to assume the responsibility for restoring the con­
tents of an exposed window region.  (An exposed window
region describes a formerly obscured window whose region
becomes visible.)  Therefore, the X server sends _E_x_p_o_s_e
events describing the window and the region of the window
that has been exposed.  A naive client application usually
redraws the entire window.  A more sophisticated client
application redraws only the exposed region.

1100..99..11..  EExxppoossee EEvveennttss

The X server can report _E_x_p_o_s_e events to clients wanting
information about when the contents of window regions have
been lost.  The circumstances in which the X server gener­
ates _E_x_p_o_s_e events are not as definite as those for other
events.  However, the X server never generates _E_x_p_o_s_e events
on windows whose class you specified as _I_n_p_u_t_O_n_l_y.  The X
server can generate _E_x_p_o_s_e events when no valid contents are
available for regions of a window and either the regions are
visible, the regions are viewable and the server is (perhaps
newly) maintaining backing store on the window, or the win­
dow is not viewable but the server is (perhaps newly) honor­
ing the window’s backing‐store attribute of _A_l_w_a_y_s or _W_h_e_n_­
_M_a_p_p_e_d.  The regions decompose into an (arbitrary) set of
rectangles, and an _E_x_p_o_s_e event is generated for each rect­
angle.  For any given window, the X server guarantees to



                             331100





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


report contiguously all of the regions exposed by some
action that causes _E_x_p_o_s_e events, such as raising a window.

To receive _E_x_p_o_s_e events, set the _E_x_p_o_s_u_r_e_M_a_s_k bit in the
event‐mask attribute of the window.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* Expose */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
     int x, y;
     int width, height;
     int count;               /* if nonzero, at least this many more */
} XExposeEvent;

││__

The window member is set to the exposed (damaged) window.
The x and y members are set to the coordinates relative to
the window’s origin and indicate the upper‐left corner of
the rectangle.  The width and height members are set to the
size (extent) of the rectangle.  The count member is set to
the number of _E_x_p_o_s_e events that are to follow.  If count is
zero, no more _E_x_p_o_s_e events follow for this window.  How­
ever, if count is nonzero, at least that number of _E_x_p_o_s_e
events (and possibly more) follow for this window.  Simple
applications that do not want to optimize redisplay by dis­
tinguishing between subareas of its window can just ignore
all _E_x_p_o_s_e events with nonzero counts and perform full
redisplays on events with zero counts.

1100..99..22..  GGrraapphhiiccssEExxppoossee aanndd NNooEExxppoossee EEvveennttss

The X server can report _G_r_a_p_h_i_c_s_E_x_p_o_s_e events to clients
wanting information about when a destination region could
not be computed during certain graphics requests: _X_C_o_p_y_A_r_e_a
or _X_C_o_p_y_P_l_a_n_e.  The X server generates this event whenever a
destination region could not be computed because of an
obscured or out‐of‐bounds source region.  In addition, the X
server guarantees to report contiguously all of the regions
exposed by some graphics request (for example, copying an
area of a drawable to a destination drawable).

The X server generates a _N_o_E_x_p_o_s_e event whenever a graphics
request that might produce a _G_r_a_p_h_i_c_s_E_x_p_o_s_e event does not
produce any.  In other words, the client is really asking
for a _G_r_a_p_h_i_c_s_E_x_p_o_s_e event but instead receives a _N_o_E_x_p_o_s_e
event.



                             331111





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To receive _G_r_a_p_h_i_c_s_E_x_p_o_s_e or _N_o_E_x_p_o_s_e events, you must first
set the graphics‐exposure attribute of the graphics context
to _T_r_u_e.  You also can set the graphics‐expose attribute
when creating a graphics context using _X_C_r_e_a_t_e_G_C or by call­
ing _X_S_e_t_G_r_a_p_h_i_c_s_E_x_p_o_s_u_r_e_s.

The structures for these event types contain:

__
││
typedef struct {
     int type;                /* GraphicsExpose */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Drawable drawable;
     int x, y;
     int width, height;
     int count;               /* if nonzero, at least this many more */
     int major_code;          /* core is CopyArea or CopyPlane */
     int minor_code;          /* not defined in the core */
} XGraphicsExposeEvent;



typedef struct {
     int type;                /* NoExpose */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Drawable drawable;
     int major_code;          /* core is CopyArea or CopyPlane */
     int minor_code;          /* not defined in the core */
} XNoExposeEvent;

││__

Both structures have these common members: drawable,
major_code, and minor_code.  The drawable member is set to
the drawable of the destination region on which the graphics
request was to be performed.  The major_code member is set
to the graphics request initiated by the client and can be
either _X___C_o_p_y_A_r_e_a or _X___C_o_p_y_P_l_a_n_e.  If it is _X___C_o_p_y_A_r_e_a, a
call to _X_C_o_p_y_A_r_e_a initiated the request.  If it is _X___C_o_p_y_­
_P_l_a_n_e, a call to _X_C_o_p_y_P_l_a_n_e initiated the request.  These
constants are defined in <_X_1_1_/_X_p_r_o_t_o_._h>.  The minor_code
member, like the major_code member, indicates which graphics
request was initiated by the client.  However, the
minor_code member is not defined by the core X protocol and
will be zero in these cases, although it may be used by an
extension.

The _X_G_r_a_p_h_i_c_s_E_x_p_o_s_e_E_v_e_n_t structure has these additional mem­
bers: x, y, width, height, and count.  The x and y members



                             331122





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


are set to the coordinates relative to the drawable’s origin
and indicate the upper‐left corner of the rectangle.  The
width and height members are set to the size (extent) of the
rectangle.  The count member is set to the number of _G_r_a_p_h_­
_i_c_s_E_x_p_o_s_e events to follow.  If count is zero, no more
_G_r_a_p_h_i_c_s_E_x_p_o_s_e events follow for this window.  However, if
count is nonzero, at least that number of _G_r_a_p_h_i_c_s_E_x_p_o_s_e
events (and possibly more) are to follow for this window.

1100..1100..  WWiinnddooww SSttaattee CChhaannggee EEvveennttss

The following sections discuss:

⋅    _C_i_r_c_u_l_a_t_e_N_o_t_i_f_y events

⋅    _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y events

⋅    _C_r_e_a_t_e_N_o_t_i_f_y events

⋅    _D_e_s_t_r_o_y_N_o_t_i_f_y events

⋅    _G_r_a_v_i_t_y_N_o_t_i_f_y events

⋅    _M_a_p_N_o_t_i_f_y events

⋅    _M_a_p_p_i_n_g_N_o_t_i_f_y events

⋅    _R_e_p_a_r_e_n_t_N_o_t_i_f_y events

⋅    _U_n_m_a_p_N_o_t_i_f_y events

⋅    _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y events

1100..1100..11..  CCiirrccuullaatteeNNoottiiffyy EEvveennttss

The X server can report _C_i_r_c_u_l_a_t_e_N_o_t_i_f_y events to clients
wanting information about when a window changes its position
in the stack.  The X server generates this event type when­
ever a window is actually restacked as a result of a client
application calling _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s, _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_­
_d_o_w_s_U_p, or _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s_D_o_w_n.

To receive _C_i_r_c_u_l_a_t_e_N_o_t_i_f_y events, set the _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y_­
_M_a_s_k bit in the event‐mask attribute of the window or the
_S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k bit in the event‐mask attribute of
the parent window (in which case, circulating any child gen­
erates an event).

The structure for this event type contains:








                             331133





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     int type;                /* CirculateNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window event;
     Window window;
     int place;               /* PlaceOnTop, PlaceOnBottom */
} XCirculateEvent;

││__

The event member is set either to the restacked window or to
its parent, depending on whether _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y or _S_u_b_­
_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y was selected.  The window member is set to
the window that was restacked.  The place member is set to
the window’s position after the restack occurs and is either
_P_l_a_c_e_O_n_T_o_p or _P_l_a_c_e_O_n_B_o_t_t_o_m.  If it is _P_l_a_c_e_O_n_T_o_p, the win­
dow is now on top of all siblings.  If it is _P_l_a_c_e_O_n_B_o_t_t_o_m,
the window is now below all siblings.

1100..1100..22..  CCoonnffiigguurreeNNoottiiffyy EEvveennttss

The X server can report _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y events to clients
wanting information about actual changes to a window’s
state, such as size, position, border, and stacking order.
The X server generates this event type whenever one of the
following configure window requests made by a client appli­
cation actually completes:

⋅    A window’s size, position, border, and/or stacking
     order is reconfigured by calling _X_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w.

⋅    The window’s position in the stacking order is changed
     by calling _X_L_o_w_e_r_W_i_n_d_o_w, _X_R_a_i_s_e_W_i_n_d_o_w, or _X_R_e_s_t_a_c_k_W_i_n_­
     _d_o_w_s.

⋅    A window is moved by calling _X_M_o_v_e_W_i_n_d_o_w.

⋅    A window’s size is changed by calling _X_R_e_s_i_z_e_W_i_n_d_o_w.

⋅    A window’s size and location is changed by calling
     _X_M_o_v_e_R_e_s_i_z_e_W_i_n_d_o_w.

⋅    A window is mapped and its position in the stacking
     order is changed by calling _X_M_a_p_R_a_i_s_e_d.

⋅    A window’s border width is changed by calling _X_S_e_t_W_i_n_­
     _d_o_w_B_o_r_d_e_r_W_i_d_t_h.

To receive _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y events, set the _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y_­
_M_a_s_k bit in the event‐mask attribute of the window or the
_S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k bit in the event‐mask attribute of



                             331144





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the parent window (in which case, configuring any child gen­
erates an event).

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* ConfigureNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window event;
     Window window;
     int x, y;
     int width, height;
     int border_width;
     Window above;
     Bool override_redirect;
} XConfigureEvent;

││__

The event member is set either to the reconfigured window or
to its parent, depending on whether _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y or _S_u_b_­
_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y was selected.  The window member is set to
the window whose size, position, border, and/or stacking
order was changed.

The x and y members are set to the coordinates relative to
the parent window’s origin and indicate the position of the
upper‐left outside corner of the window.  The width and
height members are set to the inside size of the window, not
including the border.  The border_width member is set to the
width of the window’s border, in pixels.

The above member is set to the sibling window and is used
for stacking operations.  If the X server sets this member
to _N_o_n_e, the window whose state was changed is on the bottom
of the stack with respect to sibling windows.  However, if
this member is set to a sibling window, the window whose
state was changed is placed on top of this sibling window.

The override_redirect member is set to the override‐redirect
attribute of the window.  Window manager clients normally
should ignore this window if the override_redirect member is
_T_r_u_e.

1100..1100..33..  CCrreeaatteeNNoottiiffyy EEvveennttss

The X server can report _C_r_e_a_t_e_N_o_t_i_f_y events to clients want­
ing information about creation of windows.  The X server
generates this event whenever a client application creates a
window by calling _X_C_r_e_a_t_e_W_i_n_d_o_w or _X_C_r_e_a_t_e_S_i_m_p_l_e_W_i_n_d_o_w.



                             331155





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To receive _C_r_e_a_t_e_N_o_t_i_f_y events, set the _S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_­
_M_a_s_k bit in the event‐mask attribute of the window.  Creat­
ing any children then generates an event.

The structure for the event type contains:

__
││
typedef struct {
     int type;                /* CreateNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window parent;           /* parent of the window */
     Window window;           /* window id of window created */
     int x, y;                /* window location */
     int width, height;       /* size of window */
     int border_width;        /* border width */
     Bool override_redirect;  /* creation should be overridden */
} XCreateWindowEvent;

││__

The parent member is set to the created window’s parent.
The window member specifies the created window.  The x and y
members are set to the created window’s coordinates relative
to the parent window’s origin and indicate the position of
the upper‐left outside corner of the created window.  The
width and height members are set to the inside size of the
created window (not including the border) and are always
nonzero.  The border_width member is set to the width of the
created window’s border, in pixels.  The override_redirect
member is set to the override‐redirect attribute of the win­
dow.  Window manager clients normally should ignore this
window if the override_redirect member is _T_r_u_e.

1100..1100..44..  DDeessttrrooyyNNoottiiffyy EEvveennttss

The X server can report _D_e_s_t_r_o_y_N_o_t_i_f_y events to clients
wanting information about which windows are destroyed.  The
X server generates this event whenever a client application
destroys a window by calling _X_D_e_s_t_r_o_y_W_i_n_d_o_w or _X_D_e_s_t_r_o_y_S_u_b_­
_w_i_n_d_o_w_s.

The ordering of the _D_e_s_t_r_o_y_N_o_t_i_f_y events is such that for
any given window, _D_e_s_t_r_o_y_N_o_t_i_f_y is generated on all inferi­
ors of the window before being generated on the window
itself.  The X protocol does not constrain the ordering
among siblings and across subhierarchies.

To receive _D_e_s_t_r_o_y_N_o_t_i_f_y events, set the _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k
bit in the event‐mask attribute of the window or the _S_u_b_­
_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k bit in the event‐mask attribute of the
parent window (in which case, destroying any child generates



                             331166





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


an event).

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* DestroyNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window event;
     Window window;
} XDestroyWindowEvent;

││__

The event member is set either to the destroyed window or to
its parent, depending on whether _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y or _S_u_b_­
_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y was selected.  The window member is set to
the window that is destroyed.

1100..1100..55..  GGrraavviittyyNNoottiiffyy EEvveennttss

The X server can report _G_r_a_v_i_t_y_N_o_t_i_f_y events to clients
wanting information about when a window is moved because of
a change in the size of its parent.  The X server generates
this event whenever a client application actually moves a
child window as a result of resizing its parent by calling
_X_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w, _X_M_o_v_e_R_e_s_i_z_e_W_i_n_d_o_w, or _X_R_e_s_i_z_e_W_i_n_d_o_w.

To receive _G_r_a_v_i_t_y_N_o_t_i_f_y events, set the _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k
bit in the event‐mask attribute of the window or the _S_u_b_­
_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k bit in the event‐mask attribute of the
parent window (in which case, any child that is moved
because its parent has been resized generates an event).

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* GravityNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window event;
     Window window;
     int x, y;
} XGravityEvent;

││__

The event member is set either to the window that was moved



                             331177





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


or to its parent, depending on whether _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y or
_S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y was selected.  The window member is set
to the child window that was moved.  The x and y members are
set to the coordinates relative to the new parent window’s
origin and indicate the position of the upper‐left outside
corner of the window.

1100..1100..66..  MMaappNNoottiiffyy EEvveennttss

The X server can report _M_a_p_N_o_t_i_f_y events to clients wanting
information about which windows are mapped.  The X server
generates this event type whenever a client application
changes the window’s state from unmapped to mapped by call­
ing _X_M_a_p_W_i_n_d_o_w, _X_M_a_p_R_a_i_s_e_d, _X_M_a_p_S_u_b_w_i_n_d_o_w_s, _X_R_e_p_a_r_e_n_t_W_i_n_d_o_w,
or as a result of save‐set processing.

To receive _M_a_p_N_o_t_i_f_y events, set the _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k bit
in the event‐mask attribute of the window or the _S_u_b_s_t_r_u_c_­
_t_u_r_e_N_o_t_i_f_y_M_a_s_k bit in the event‐mask attribute of the parent
window (in which case, mapping any child generates an
event).

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* MapNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window event;
     Window window;
     Bool override_redirect;  /* boolean, is override set... */
} XMapEvent;

││__

The event member is set either to the window that was mapped
or to its parent, depending on whether _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y or
_S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y was selected.  The window member is set
to the window that was mapped.  The override_redirect member
is set to the override‐redirect attribute of the window.
Window manager clients normally should ignore this window if
the override‐redirect attribute is _T_r_u_e, because these
events usually are generated from pop‐ups, which override
structure control.

1100..1100..77..  MMaappppiinnggNNoottiiffyy EEvveennttss

The X server reports _M_a_p_p_i_n_g_N_o_t_i_f_y events to all clients.
There is no mechanism to express disinterest in this event.
The X server generates this event type whenever a client
application successfully calls:



                             331188





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    _X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g to indicate which KeyCodes are to
     be used as modifiers

⋅    _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g to change the keyboard mapping

⋅    _X_S_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g to set the pointer mapping

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* MappingNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;           /* unused */
     int request;             /* one of MappingModifier, MappingKeyboard,
                                 MappingPointer */
     int first_keycode;       /* first keycode */
     int count;               /* defines range of change w. first_keycode*/
} XMappingEvent;

││__

The request member is set to indicate the kind of mapping
change that occurred and can be _M_a_p_p_i_n_g_M_o_d_i_f_i_e_r, _M_a_p_p_i_n_g_K_e_y_­
_b_o_a_r_d, or _M_a_p_p_i_n_g_P_o_i_n_t_e_r.  If it is _M_a_p_p_i_n_g_M_o_d_i_f_i_e_r, the
modifier mapping was changed.  If it is _M_a_p_p_i_n_g_K_e_y_b_o_a_r_d, the
keyboard mapping was changed.  If it is _M_a_p_p_i_n_g_P_o_i_n_t_e_r, the
pointer button mapping was changed.  The first_keycode and
count members are set only if the request member was set to
_M_a_p_p_i_n_g_K_e_y_b_o_a_r_d.  The number in first_keycode represents the
first number in the range of the altered mapping, and count
represents the number of keycodes altered.

To update the client application’s knowledge of the key­
board, you should call _X_R_e_f_r_e_s_h_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g.

1100..1100..88..  RReeppaarreennttNNoottiiffyy EEvveennttss

The X server can report _R_e_p_a_r_e_n_t_N_o_t_i_f_y events to clients
wanting information about changing a window’s parent.  The X
server generates this event whenever a client application
calls _X_R_e_p_a_r_e_n_t_W_i_n_d_o_w and the window is actually reparented.

To receive _R_e_p_a_r_e_n_t_N_o_t_i_f_y events, set the _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y_­
_M_a_s_k bit in the event‐mask attribute of the window or the
_S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k bit in the event‐mask attribute of
either the old or the new parent window (in which case,
reparenting any child generates an event).

The structure for this event type contains:




                             331199





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     int type;                /* ReparentNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window event;
     Window window;
     Window parent;
     int x, y;
     Bool override_redirect;
} XReparentEvent;

││__

The event member is set either to the reparented window or
to the old or the new parent, depending on whether _S_t_r_u_c_­
_t_u_r_e_N_o_t_i_f_y or _S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y was selected.  The window
member is set to the window that was reparented.  The parent
member is set to the new parent window.  The x and y members
are set to the reparented window’s coordinates relative to
the new parent window’s origin and define the upper‐left
outer corner of the reparented window.  The override_redi­
rect member is set to the override‐redirect attribute of the
window specified by the window member.  Window manager
clients normally should ignore this window if the over­
ride_redirect member is _T_r_u_e.

1100..1100..99..  UUnnmmaappNNoottiiffyy EEvveennttss

The X server can report _U_n_m_a_p_N_o_t_i_f_y events to clients want­
ing information about which windows are unmapped.  The X
server generates this event type whenever a client applica­
tion changes the window’s state from mapped to unmapped.

To receive _U_n_m_a_p_N_o_t_i_f_y events, set the _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k
bit in the event‐mask attribute of the window or the _S_u_b_­
_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k bit in the event‐mask attribute of the
parent window (in which case, unmapping any child window
generates an event).

The structure for this event type contains:















                             332200





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     int type;                /* UnmapNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window event;
     Window window;
     Bool from_configure;
} XUnmapEvent;

││__

The event member is set either to the unmapped window or to
its parent, depending on whether _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y or _S_u_b_­
_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y was selected.  This is the window used by
the X server to report the event.  The window member is set
to the window that was unmapped.  The from_configure member
is set to _T_r_u_e if the event was generated as a result of a
resizing of the window’s parent when the window itself had a
win_gravity of _U_n_m_a_p_G_r_a_v_i_t_y.

1100..1100..1100..  VViissiibbiilliittyyNNoottiiffyy EEvveennttss

The X server can report _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y events to clients
wanting any change in the visibility of the specified win­
dow.  A region of a window is visible if someone looking at
the screen can actually see it.  The X server generates this
event whenever the visibility changes state.  However, this
event is never generated for windows whose class is _I_n_p_u_­
_t_O_n_l_y.

All _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y events caused by a hierarchy change are
generated after any hierarchy event (_U_n_m_a_p_N_o_t_i_f_y, _M_a_p_N_o_t_i_f_y,
_C_o_n_f_i_g_u_r_e_N_o_t_i_f_y, _G_r_a_v_i_t_y_N_o_t_i_f_y, _C_i_r_c_u_l_a_t_e_N_o_t_i_f_y) caused by
that change.  Any _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y event on a given window
is generated before any _E_x_p_o_s_e events on that window, but it
is not required that all _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y events on all win­
dows be generated before all _E_x_p_o_s_e events on all windows.
The X protocol does not constrain the ordering of _V_i_s_i_b_i_l_i_­
_t_y_N_o_t_i_f_y events with respect to _F_o_c_u_s_O_u_t, _E_n_t_e_r_N_o_t_i_f_y, and
_L_e_a_v_e_N_o_t_i_f_y events.

To receive _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y events, set the _V_i_s_i_b_i_l_i_t_y_­
_C_h_a_n_g_e_M_a_s_k bit in the event‐mask attribute of the window.

The structure for this event type contains:










                             332211





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     int type;                /* VisibilityNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
     int state;
} XVisibilityEvent;

││__

The window member is set to the window whose visibility
state changes.  The state member is set to the state of the
window’s visibility and can be _V_i_s_i_b_i_l_i_t_y_U_n_o_b_s_c_u_r_e_d, _V_i_s_i_­
_b_i_l_i_t_y_P_a_r_t_i_a_l_l_y_O_b_s_c_u_r_e_d, or _V_i_s_i_b_i_l_i_t_y_F_u_l_l_y_O_b_s_c_u_r_e_d.  The X
server ignores all of a window’s subwindows when determining
the visibility state of the window and processes _V_i_s_i_b_i_l_i_­
_t_y_N_o_t_i_f_y events according to the following:

⋅    When the window changes state from partially obscured,
     fully obscured, or not viewable to viewable and com­
     pletely unobscured, the X server generates the event
     with the state member of the _X_V_i_s_i_b_i_l_i_t_y_E_v_e_n_t structure
     set to _V_i_s_i_b_i_l_i_t_y_U_n_o_b_s_c_u_r_e_d.

⋅    When the window changes state from viewable and com­
     pletely unobscured or not viewable to viewable and par­
     tially obscured, the X server generates the event with
     the state member of the _X_V_i_s_i_b_i_l_i_t_y_E_v_e_n_t structure set
     to _V_i_s_i_b_i_l_i_t_y_P_a_r_t_i_a_l_l_y_O_b_s_c_u_r_e_d.

⋅    When the window changes state from viewable and com­
     pletely unobscured, viewable and partially obscured, or
     not viewable to viewable and fully obscured, the X
     server generates the event with the state member of the
     _X_V_i_s_i_b_i_l_i_t_y_E_v_e_n_t structure set to _V_i_s_i_b_i_l_i_t_y_F_u_l_l_y_O_b_­
     _s_c_u_r_e_d.

1100..1111..  SSttrruuccttuurree CCoonnttrrooll EEvveennttss

This section discusses:

⋅    _C_i_r_c_u_l_a_t_e_R_e_q_u_e_s_t events

⋅    _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t events

⋅    _M_a_p_R_e_q_u_e_s_t events

⋅    _R_e_s_i_z_e_R_e_q_u_e_s_t events







                             332222





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1100..1111..11..  CCiirrccuullaatteeRReeqquueesstt EEvveennttss

The X server can report _C_i_r_c_u_l_a_t_e_R_e_q_u_e_s_t events to clients
wanting information about when another client initiates a
circulate window request on a specified window.  The X
server generates this event type whenever a client initiates
a circulate window request on a window and a subwindow actu­
ally needs to be restacked.  The client initiates a circu­
late window request on the window by calling _X_C_i_r_c_u_l_a_t_e_S_u_b_­
_w_i_n_d_o_w_s, _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s_U_p, or _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s_­
_D_o_w_n.

To receive _C_i_r_c_u_l_a_t_e_R_e_q_u_e_s_t events, set the _S_u_b_s_t_r_u_c_t_u_r_­
_e_R_e_d_i_r_e_c_t_M_a_s_k in the event‐mask attribute of the window.
Then, in the future, the circulate window request for the
specified window is not executed, and thus, any subwindow’s
position in the stack is not changed.  For example, suppose
a client application calls _X_C_i_r_c_u_l_a_t_e_S_u_b_w_i_n_d_o_w_s_U_p to raise a
subwindow to the top of the stack.  If you had selected _S_u_b_­
_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on the window, the X server reports to
you a _C_i_r_c_u_l_a_t_e_R_e_q_u_e_s_t event and does not raise the subwin­
dow to the top of the stack.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* CirculateRequest */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window parent;
     Window window;
     int place;               /* PlaceOnTop, PlaceOnBottom */
} XCirculateRequestEvent;

││__

The parent member is set to the parent window.  The window
member is set to the subwindow to be restacked.  The place
member is set to what the new position in the stacking order
should be and is either _P_l_a_c_e_O_n_T_o_p or _P_l_a_c_e_O_n_B_o_t_t_o_m.  If it
is _P_l_a_c_e_O_n_T_o_p, the subwindow should be on top of all sib­
lings.  If it is _P_l_a_c_e_O_n_B_o_t_t_o_m, the subwindow should be
below all siblings.

1100..1111..22..  CCoonnffiigguurreeRReeqquueesstt EEvveennttss

The X server can report _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t events to clients
wanting information about when a different client initiates
a configure window request on any child of a specified win­
dow.  The configure window request attempts to reconfigure a
window’s size, position, border, and stacking order.  The X



                             332233





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


server generates this event whenever a different client ini­
tiates a configure window request on a window by calling
_X_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w, _X_L_o_w_e_r_W_i_n_d_o_w, _X_R_a_i_s_e_W_i_n_d_o_w, _X_M_a_p_R_a_i_s_e_d,
_X_M_o_v_e_R_e_s_i_z_e_W_i_n_d_o_w, _X_M_o_v_e_W_i_n_d_o_w, _X_R_e_s_i_z_e_W_i_n_d_o_w, _X_R_e_s_t_a_c_k_W_i_n_­
_d_o_w_s, or _X_S_e_t_W_i_n_d_o_w_B_o_r_d_e_r_W_i_d_t_h.

To receive _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t events, set the _S_u_b_s_t_r_u_c_t_u_r_­
_e_R_e_d_i_r_e_c_t_M_a_s_k bit in the event‐mask attribute of the window.
_C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t events are generated when a _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w
protocol request is issued on a child window by another
client.  For example, suppose a client application calls
_X_L_o_w_e_r_W_i_n_d_o_w to lower a window.  If you had selected _S_u_b_­
_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on the parent window and if the over­
ride‐redirect attribute of the window is set to _F_a_l_s_e, the X
server reports a _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t event to you and does not
lower the specified window.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* ConfigureRequest */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window parent;
     Window window;
     int x, y;
     int width, height;
     int border_width;
     Window above;
     int detail;              /* Above, Below, TopIf, BottomIf, Opposite */
     unsigned long value_mask;
} XConfigureRequestEvent;

││__

The parent member is set to the parent window.  The window
member is set to the window whose size, position, border
width, and/or stacking order is to be reconfigured.  The
value_mask member indicates which components were specified
in the _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w protocol request.  The corresponding
values are reported as given in the request.  The remaining
values are filled in from the current geometry of the win­
dow, except in the case of above (sibling) and detail
(stack‐mode), which are reported as _N_o_n_e and _A_b_o_v_e, respec­
tively, if they are not given in the request.

1100..1111..33..  MMaappRReeqquueesstt EEvveennttss

The X server can report _M_a_p_R_e_q_u_e_s_t events to clients wanting
information about a different client’s desire to map win­
dows.  A window is considered mapped when a map window



                             332244





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


request completes.  The X server generates this event when­
ever a different client initiates a map window request on an
unmapped window whose override_redirect member is set to
_F_a_l_s_e.  Clients initiate map window requests by calling
_X_M_a_p_W_i_n_d_o_w, _X_M_a_p_R_a_i_s_e_d, or _X_M_a_p_S_u_b_w_i_n_d_o_w_s.

To receive _M_a_p_R_e_q_u_e_s_t events, set the _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_­
_M_a_s_k bit in the event‐mask attribute of the window.  This
means another client’s attempts to map a child window by
calling one of the map window request functions is inter­
cepted, and you are sent a _M_a_p_R_e_q_u_e_s_t instead.  For example,
suppose a client application calls _X_M_a_p_W_i_n_d_o_w to map a win­
dow.  If you (usually a window manager) had selected _S_u_b_­
_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k on the parent window and if the over­
ride‐redirect attribute of the window is set to _F_a_l_s_e, the X
server reports a _M_a_p_R_e_q_u_e_s_t event to you and does not map
the specified window.  Thus, this event gives your window
manager client the ability to control the placement of sub­
windows.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* MapRequest */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window parent;
     Window window;
} XMapRequestEvent;

││__

The parent member is set to the parent window.  The window
member is set to the window to be mapped.

1100..1111..44..  RReessiizzeeRReeqquueesstt EEvveennttss

The X server can report _R_e_s_i_z_e_R_e_q_u_e_s_t events to clients
wanting information about another client’s attempts to
change the size of a window.  The X server generates this
event whenever some other client attempts to change the size
of the specified window by calling _X_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w, _X_R_e_­
_s_i_z_e_W_i_n_d_o_w, or _X_M_o_v_e_R_e_s_i_z_e_W_i_n_d_o_w.

To receive _R_e_s_i_z_e_R_e_q_u_e_s_t events, set the _R_e_s_i_z_e_R_e_d_i_r_e_c_t bit
in the event‐mask attribute of the window.  Any attempts to
change the size by other clients are then redirected.

The structure for this event type contains:





                             332255





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     int type;                /* ResizeRequest */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
     int width, height;
} XResizeRequestEvent;

││__

The window member is set to the window whose size another
client attempted to change.  The width and height members
are set to the inside size of the window, excluding the bor­
der.

1100..1122..  CCoolloorrmmaapp SSttaattee CChhaannggee EEvveennttss

The X server can report _C_o_l_o_r_m_a_p_N_o_t_i_f_y events to clients
wanting information about when the colormap changes and when
a colormap is installed or uninstalled.  The X server gener­
ates this event type whenever a client application:

⋅    Changes the colormap member of the _X_S_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s
     structure by calling _X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s, _X_F_r_e_e_C_o_l_­
     _o_r_m_a_p, or _X_S_e_t_W_i_n_d_o_w_C_o_l_o_r_m_a_p

⋅    Installs or uninstalls the colormap by calling _X_I_n_­
     _s_t_a_l_l_C_o_l_o_r_m_a_p or _X_U_n_i_n_s_t_a_l_l_C_o_l_o_r_m_a_p

To receive _C_o_l_o_r_m_a_p_N_o_t_i_f_y events, set the _C_o_l_o_r_m_a_p_C_h_a_n_g_e_M_a_s_k
bit in the event‐mask attribute of the window.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* ColormapNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
     Colormap colormap;       /* colormap or None */
     Bool new;
     int state;               /* ColormapInstalled, ColormapUninstalled */
} XColormapEvent;

││__

The window member is set to the window whose associated col­
ormap is changed, installed, or uninstalled.  For a colormap
that is changed, installed, or uninstalled, the colormap



                             332266





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


member is set to the colormap associated with the window.
For a colormap that is changed by a call to _X_F_r_e_e_C_o_l_o_r_m_a_p,
the colormap member is set to _N_o_n_e.  The new member is set
to indicate whether the colormap for the specified window
was changed or installed or uninstalled and can be _T_r_u_e or
_F_a_l_s_e.  If it is _T_r_u_e, the colormap was changed.  If it is
_F_a_l_s_e, the colormap was installed or uninstalled.  The state
member is always set to indicate whether the colormap is
installed or uninstalled and can be _C_o_l_o_r_m_a_p_I_n_s_t_a_l_l_e_d or
_C_o_l_o_r_m_a_p_U_n_i_n_s_t_a_l_l_e_d.

1100..1133..  CClliieenntt CCoommmmuunniiccaattiioonn EEvveennttss

This section discusses:

⋅    _C_l_i_e_n_t_M_e_s_s_a_g_e events

⋅    _P_r_o_p_e_r_t_y_N_o_t_i_f_y events

⋅    _S_e_l_e_c_t_i_o_n_C_l_e_a_r events

⋅    _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y events

⋅    _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t events

1100..1133..11..  CClliieennttMMeessssaaggee EEvveennttss

The X server generates _C_l_i_e_n_t_M_e_s_s_a_g_e events only when a
client calls the function _X_S_e_n_d_E_v_e_n_t.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* ClientMessage */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
     Atom message_type;
     int format;
     union {
          char b[20];
          short s[10];
          long l[5];
             } data;
} XClientMessageEvent;

││__

The message_type member is set to an atom that indicates how
the data should be interpreted by the receiving client.  The
format member is set to 8, 16, or 32 and specifies whether



                             332277





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the data should be viewed as a list of bytes, shorts, or
longs.  The data member is a union that contains the members
b, s, and l.  The b, s, and l members represent data of
twenty 8‐bit values, ten 16‐bit values, and five 32‐bit val­
ues.  Particular message types might not make use of all
these values.  The X server places no interpretation on the
values in the window, message_type, or data members.

1100..1133..22..  PPrrooppeerrttyyNNoottiiffyy EEvveennttss

The X server can report _P_r_o_p_e_r_t_y_N_o_t_i_f_y events to clients
wanting information about property changes for a specified
window.

To receive _P_r_o_p_e_r_t_y_N_o_t_i_f_y events, set the _P_r_o_p_e_r_t_y_C_h_a_n_g_e_M_a_s_k
bit in the event‐mask attribute of the window.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* PropertyNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
     Atom atom;
     Time time;
     int state;               /* PropertyNewValue or PropertyDelete */
} XPropertyEvent;

││__

The window member is set to the window whose associated
property was changed.  The atom member is set to the prop­
erty’s atom and indicates which property was changed or
desired.  The time member is set to the server time when the
property was changed.  The state member is set to indicate
whether the property was changed to a new value or deleted
and can be _P_r_o_p_e_r_t_y_N_e_w_V_a_l_u_e or _P_r_o_p_e_r_t_y_D_e_l_e_t_e.  The state
member is set to _P_r_o_p_e_r_t_y_N_e_w_V_a_l_u_e when a property of the
window is changed using _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y or _X_R_o_t_a_t_e_W_i_n_d_o_w_­
_P_r_o_p_e_r_t_i_e_s (even when adding zero‐length data using _X_C_h_a_n_g_e_­
_P_r_o_p_e_r_t_y) and when replacing all or part of a property with
identical data using _X_C_h_a_n_g_e_P_r_o_p_e_r_t_y or _X_R_o_t_a_t_e_W_i_n_d_o_w_P_r_o_p_e_r_­
_t_i_e_s.  The state member is set to _P_r_o_p_e_r_t_y_D_e_l_e_t_e when a
property of the window is deleted using _X_D_e_l_e_t_e_P_r_o_p_e_r_t_y or,
if the delete argument is _T_r_u_e, _X_G_e_t_W_i_n_d_o_w_P_r_o_p_e_r_t_y.

1100..1133..33..  SSeelleeccttiioonnCClleeaarr EEvveennttss

The X server reports _S_e_l_e_c_t_i_o_n_C_l_e_a_r events to the client
losing ownership of a selection.  The X server generates



                             332288





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


this event type when another client asserts ownership of the
selection by calling _X_S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* SelectionClear */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window window;
     Atom selection;
     Time time;
} XSelectionClearEvent;

││__

The selection member is set to the selection atom.  The time
member is set to the last change time recorded for the
selection.  The window member is the window that was speci­
fied by the current owner (the owner losing the selection)
in its _X_S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r call.

1100..1133..44..  SSeelleeccttiioonnRReeqquueesstt EEvveennttss

The X server reports _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t events to the owner of
a selection.  The X server generates this event whenever a
client requests a selection conversion by calling _X_C_o_n_v_e_r_t_S_­
_e_l_e_c_t_i_o_n for the owned selection.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* SelectionRequest */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window owner;
     Window requestor;
     Atom selection;
     Atom target;
     Atom property;
     Time time;
} XSelectionRequestEvent;

││__

The owner member is set to the window that was specified by
the current owner in its _X_S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r call.  The
requestor member is set to the window requesting the



                             332299





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


selection.  The selection member is set to the atom that
names the selection.  For example, PRIMARY is used to indi­
cate the primary selection.  The target member is set to the
atom that indicates the type the selection is desired in.
The property member can be a property name or _N_o_n_e.  The
time member is set to the timestamp or _C_u_r_r_e_n_t_T_i_m_e value
from the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request.

The owner should convert the selection based on the speci­
fied target type and send a _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event back to
the requestor.  A complete specification for using selec­
tions is given in the X Consortium standard _I_n_t_e_r_‐_C_l_i_e_n_t
_C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l.

1100..1133..55..  SSeelleeccttiioonnNNoottiiffyy EEvveennttss

This event is generated by the X server in response to a
_C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n protocol request when there is no owner for
the selection.  When there is an owner, it should be gener­
ated by the owner of the selection by using _X_S_e_n_d_E_v_e_n_t.  The
owner of a selection should send this event to a requestor
when a selection has been converted and stored as a property
or when a selection conversion could not be performed (which
is indicated by setting the property member to _N_o_n_e).

If _N_o_n_e is specified as the property in the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n
protocol request, the owner should choose a property name,
store the result as that property on the requestor window,
and then send a _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y giving that actual property
name.

The structure for this event type contains:

__
││
typedef struct {
     int type;                /* SelectionNotify */
     unsigned long serial;    /* # of last request processed by server */
     Bool send_event;         /* true if this came from a SendEvent request */
     Display *display;        /* Display the event was read from */
     Window requestor;
     Atom selection;
     Atom target;
     Atom property;           /* atom or None */
     Time time;
} XSelectionEvent;

││__

The requestor member is set to the window associated with
the requestor of the selection.  The selection member is set
to the atom that indicates the selection.  For example, PRI­
MARY is used for the primary selection.  The target member
is set to the atom that indicates the converted type.  For



                             333300





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


example, PIXMAP is used for a pixmap.  The property member
is set to the atom that indicates which property the result
was stored on.  If the conversion failed, the property mem­
ber is set to _N_o_n_e.  The time member is set to the time the
conversion took place and can be a timestamp or _C_u_r_r_e_n_t_T_i_m_e.




















































                             333311





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 1111

                  EEvveenntt HHaannddlliinngg FFuunnccttiioonnss



This chapter discusses the Xlib functions you can use to:

⋅    Select events

⋅    Handle the output buffer and the event queue

⋅    Select events from the event queue

⋅    Send and get events

⋅    Handle protocol errors

                              Note

          Some toolkits use their own event‐handling
          functions and do not allow you to interchange
          these event‐handling functions with those in
          Xlib.  For further information, see the docu­
          mentation supplied with the toolkit.


Most applications simply are event loops: they wait for an
event, decide what to do with it, execute some amount of
code that results in changes to the display, and then wait
for the next event.

1111..11..  SSeelleeccttiinngg EEvveennttss

There are two ways to select the events you want reported to
your client application.  One way is to set the event_mask
member of the _X_S_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s structure when you call
_X_C_r_e_a_t_e_W_i_n_d_o_w and _X_C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s.  Another way is
to use _X_S_e_l_e_c_t_I_n_p_u_t.
















                             333322





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSelectInput(_d_i_s_p_l_a_y, _w, _e_v_e_n_t___m_a_s_k)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      long _e_v_e_n_t___m_a_s_k;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose events you are inter­
          ested in.

_e_v_e_n_t___m_a_s_k
          Specifies the event mask.
││__

The _X_S_e_l_e_c_t_I_n_p_u_t function requests that the X server report
the events associated with the specified event mask.  Ini­
tially, X will not report any of these events.  Events are
reported relative to a window.  If a window is not inter­
ested in a device event, it usually propagates to the clos­
est ancestor that is interested, unless the do_not_propagate
mask prohibits it.

Setting the event‐mask attribute of a window overrides any
previous call for the same window but not for other clients.
Multiple clients can select for the same events on the same
window with the following restrictions:

⋅    Multiple clients can select events on the same window
     because their event masks are disjoint.  When the X
     server generates an event, it reports it to all inter­
     ested clients.

⋅    Only one client at a time can select _C_i_r_c_u_l_a_t_e_R_e_q_u_e_s_t,
     _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t, or _M_a_p_R_e_q_u_e_s_t events, which are asso­
     ciated with the event mask _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_M_a_s_k.

⋅    Only one client at a time can select a _R_e_s_i_z_e_R_e_q_u_e_s_t
     event, which is associated with the event mask _R_e_s_i_z_­
     _e_R_e_d_i_r_e_c_t_M_a_s_k.

⋅    Only one client at a time can select a _B_u_t_t_o_n_P_r_e_s_s
     event, which is associated with the event mask _B_u_t_t_o_n_­
     _P_r_e_s_s_M_a_s_k.

The server reports the event to all interested clients.

_X_S_e_l_e_c_t_I_n_p_u_t can generate a _B_a_d_W_i_n_d_o_w error.

1111..22..  HHaannddlliinngg tthhee OOuuttppuutt BBuuffffeerr

The output buffer is an area used by Xlib to store requests.
The functions described in this section flush the output



                             333333





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


buffer if the function would block or not return an event.
That is, all requests residing in the output buffer that
have not yet been sent are transmitted to the X server.
These functions differ in the additional tasks they might
perform.


To flush the output buffer, use _X_F_l_u_s_h.
__
││
XFlush(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_F_l_u_s_h function flushes the output buffer.  Most client
applications need not use this function because the output
buffer is automatically flushed as needed by calls to _X_P_e_n_d_­
_i_n_g, _X_N_e_x_t_E_v_e_n_t, and _X_W_i_n_d_o_w_E_v_e_n_t.  Events generated by the
server may be enqueued into the library’s event queue.


To flush the output buffer and then wait until all requests
have been processed, use _X_S_y_n_c.
__
││
XSync(_d_i_s_p_l_a_y, _d_i_s_c_a_r_d)
      Display *_d_i_s_p_l_a_y;
      Bool _d_i_s_c_a_r_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_i_s_c_a_r_d   Specifies a Boolean value that indicates whether
          _X_S_y_n_c discards all events on the event queue.
││__

The _X_S_y_n_c function flushes the output buffer and then waits
until all requests have been received and processed by the X
server.  Any errors generated must be handled by the error
handler.  For each protocol error received by Xlib, _X_S_y_n_c
calls the client application’s error handling routine (see
section 11.8.2).  Any events generated by the server are
enqueued into the library’s event queue.

Finally, if you passed _F_a_l_s_e, _X_S_y_n_c does not discard the
events in the queue.  If you passed _T_r_u_e, _X_S_y_n_c discards all
events in the queue, including those events that were on the
queue before _X_S_y_n_c was called.  Client applications seldom
need to call _X_S_y_n_c.





                             333344





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1111..33..  EEvveenntt QQuueeuuee MMaannaaggeemmeenntt

Xlib maintains an event queue.  However, the operating sys­
tem also may be buffering data in its network connection
that is not yet read into the event queue.


To check the number of events in the event queue, use
_X_E_v_e_n_t_s_Q_u_e_u_e_d.
__
││
int XEventsQueued(_d_i_s_p_l_a_y, _m_o_d_e)
     Display *_d_i_s_p_l_a_y;
     int _m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_m_o_d_e      Specifies the mode.  You can pass _Q_u_e_u_e_d_A_l_r_e_a_d_y,
          _Q_u_e_u_e_d_A_f_t_e_r_F_l_u_s_h, or _Q_u_e_u_e_d_A_f_t_e_r_R_e_a_d_i_n_g.
││__

If mode is _Q_u_e_u_e_d_A_l_r_e_a_d_y, _X_E_v_e_n_t_s_Q_u_e_u_e_d returns the number
of events already in the event queue (and never performs a
system call).  If mode is _Q_u_e_u_e_d_A_f_t_e_r_F_l_u_s_h, _X_E_v_e_n_t_s_Q_u_e_u_e_d
returns the number of events already in the queue if the
number is nonzero.  If there are no events in the queue,
_X_E_v_e_n_t_s_Q_u_e_u_e_d flushes the output buffer, attempts to read
more events out of the application’s connection, and returns
the number read.  If mode is _Q_u_e_u_e_d_A_f_t_e_r_R_e_a_d_i_n_g,
_X_E_v_e_n_t_s_Q_u_e_u_e_d returns the number of events already in the
queue if the number is nonzero.  If there are no events in
the queue, _X_E_v_e_n_t_s_Q_u_e_u_e_d attempts to read more events out of
the application’s connection without flushing the output
buffer and returns the number read.

_X_E_v_e_n_t_s_Q_u_e_u_e_d always returns immediately without I/O if
there are events already in the queue.  _X_E_v_e_n_t_s_Q_u_e_u_e_d with
mode _Q_u_e_u_e_d_A_f_t_e_r_F_l_u_s_h is identical in behavior to _X_P_e_n_d_i_n_g.
_X_E_v_e_n_t_s_Q_u_e_u_e_d with mode _Q_u_e_u_e_d_A_l_r_e_a_d_y is identical to the
_X_Q_L_e_n_g_t_h function.


To return the number of events that are pending, use _X_P_e_n_d_­
_i_n_g.












                             333355





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XPending(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_P_e_n_d_i_n_g function returns the number of events that have
been received from the X server but have not been removed
from the event queue.  _X_P_e_n_d_i_n_g is identical to
_X_E_v_e_n_t_s_Q_u_e_u_e_d with the mode _Q_u_e_u_e_d_A_f_t_e_r_F_l_u_s_h specified.

1111..44..  MMaanniippuullaattiinngg tthhee EEvveenntt QQuueeuuee

Xlib provides functions that let you manipulate the event
queue.  This section discusses how to:

⋅    Obtain events, in order, and remove them from the queue

⋅    Peek at events in the queue without removing them

⋅    Obtain events that match the event mask or the arbi­
     trary predicate procedures that you provide

1111..44..11..  RReettuurrnniinngg tthhee NNeexxtt EEvveenntt

To get the next event and remove it from the queue, use
_X_N_e_x_t_E_v_e_n_t.
__
││
XNextEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___r_e_t_u_r_n
          Returns the next event in the queue.
││__

The _X_N_e_x_t_E_v_e_n_t function copies the first event from the
event queue into the specified _X_E_v_e_n_t structure and then
removes it from the queue.  If the event queue is empty,
_X_N_e_x_t_E_v_e_n_t flushes the output buffer and blocks until an
event is received.


To peek at the event queue, use _X_P_e_e_k_E_v_e_n_t.







                             333366





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XPeekEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___r_e_t_u_r_n
          Returns a copy of the matched event’s associated
          structure.
││__

The _X_P_e_e_k_E_v_e_n_t function returns the first event from the
event queue, but it does not remove the event from the
queue.  If the queue is empty, _X_P_e_e_k_E_v_e_n_t flushes the output
buffer and blocks until an event is received.  It then
copies the event into the client‐supplied _X_E_v_e_n_t structure
without removing it from the event queue.

1111..44..22..  SSeelleeccttiinngg EEvveennttss UUssiinngg aa PPrreeddiiccaattee PPrroocceedduurree

Each of the functions discussed in this section requires you
to pass a predicate procedure that determines if an event
matches what you want.  Your predicate procedure must decide
if the event is useful without calling any Xlib functions.
If the predicate directly or indirectly causes the state of
the event queue to change, the result is not defined.  If
Xlib has been initialized for threads, the predicate is
called with the display locked and the result of a call by
the predicate to any Xlib function that locks the display is
not defined unless the caller has first called _X_L_o_c_k_D_i_s_p_l_a_y.

The predicate procedure and its associated arguments are:
__
││
Bool (*_p_r_e_d_i_c_a_t_e)(_d_i_s_p_l_a_y, _e_v_e_n_t, _a_r_g)
     Display *_d_i_s_p_l_a_y;
     XEvent *_e_v_e_n_t;
     XPointer _a_r_g;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t     Specifies the _X_E_v_e_n_t structure.

_a_r_g       Specifies the argument passed in from the
          _X_I_f_E_v_e_n_t, _X_C_h_e_c_k_I_f_E_v_e_n_t, or _X_P_e_e_k_I_f_E_v_e_n_t function.
││__

The predicate procedure is called once for each event in the
queue until it finds a match.  After finding a match, the
predicate procedure must return _T_r_u_e.  If it did not find a
match, it must return _F_a_l_s_e.



                             333377





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To check the event queue for a matching event and, if found,
remove the event from the queue, use _X_I_f_E_v_e_n_t.
__
││
XIfEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___r_e_t_u_r_n, _p_r_e_d_i_c_a_t_e, _a_r_g)
      Display *_d_i_s_p_l_a_y;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;
      Bool (*_p_r_e_d_i_c_a_t_e)();
      XPointer _a_r_g;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___r_e_t_u_r_n
          Returns the matched event’s associated structure.

_p_r_e_d_i_c_a_t_e Specifies the procedure that is to be called to
          determine if the next event in the queue matches
          what you want.

_a_r_g       Specifies the user‐supplied argument that will be
          passed to the predicate procedure.
││__

The _X_I_f_E_v_e_n_t function completes only when the specified
predicate procedure returns _T_r_u_e for an event, which indi­
cates an event in the queue matches.  _X_I_f_E_v_e_n_t flushes the
output buffer if it blocks waiting for additional events.
_X_I_f_E_v_e_n_t removes the matching event from the queue and
copies the structure into the client‐supplied _X_E_v_e_n_t struc­
ture.


To check the event queue for a matching event without block­
ing, use _X_C_h_e_c_k_I_f_E_v_e_n_t.






















                             333388





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XCheckIfEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___r_e_t_u_r_n, _p_r_e_d_i_c_a_t_e, _a_r_g)
      Display *_d_i_s_p_l_a_y;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;
      Bool (*_p_r_e_d_i_c_a_t_e)();
      XPointer _a_r_g;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___r_e_t_u_r_n
          Returns a copy of the matched event’s associated
          structure.

_p_r_e_d_i_c_a_t_e Specifies the procedure that is to be called to
          determine if the next event in the queue matches
          what you want.

_a_r_g       Specifies the user‐supplied argument that will be
          passed to the predicate procedure.
││__

When the predicate procedure finds a match, _X_C_h_e_c_k_I_f_E_v_e_n_t
copies the matched event into the client‐supplied _X_E_v_e_n_t
structure and returns _T_r_u_e.  (This event is removed from the
queue.)  If the predicate procedure finds no match, _X_C_h_e_c_k_­
_I_f_E_v_e_n_t returns _F_a_l_s_e, and the output buffer will have been
flushed.  All earlier events stored in the queue are not
discarded.


To check the event queue for a matching event without remov­
ing the event from the queue, use _X_P_e_e_k_I_f_E_v_e_n_t.
























                             333399





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XPeekIfEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___r_e_t_u_r_n, _p_r_e_d_i_c_a_t_e, _a_r_g)
      Display *_d_i_s_p_l_a_y;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;
      Bool (*_p_r_e_d_i_c_a_t_e)();
      XPointer _a_r_g;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___r_e_t_u_r_n
          Returns a copy of the matched event’s associated
          structure.

_p_r_e_d_i_c_a_t_e Specifies the procedure that is to be called to
          determine if the next event in the queue matches
          what you want.

_a_r_g       Specifies the user‐supplied argument that will be
          passed to the predicate procedure.
││__

The _X_P_e_e_k_I_f_E_v_e_n_t function returns only when the specified
predicate procedure returns _T_r_u_e for an event.  After the
predicate procedure finds a match, _X_P_e_e_k_I_f_E_v_e_n_t copies the
matched event into the client‐supplied _X_E_v_e_n_t structure
without removing the event from the queue.  _X_P_e_e_k_I_f_E_v_e_n_t
flushes the output buffer if it blocks waiting for addi­
tional events.

1111..44..33..  SSeelleeccttiinngg EEvveennttss UUssiinngg aa WWiinnddooww oorr EEvveenntt MMaasskk

The functions discussed in this section let you select
events by window or event types, allowing you to process
events out of order.


To remove the next event that matches both a window and an
event mask, use _X_W_i_n_d_o_w_E_v_e_n_t.


















                             334400





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XWindowEvent(_d_i_s_p_l_a_y, _w, _e_v_e_n_t___m_a_s_k, _e_v_e_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      long _e_v_e_n_t___m_a_s_k;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose events you are inter­
          ested in.

_e_v_e_n_t___m_a_s_k
          Specifies the event mask.

_e_v_e_n_t___r_e_t_u_r_n
          Returns the matched event’s associated structure.
││__

The _X_W_i_n_d_o_w_E_v_e_n_t function searches the event queue for an
event that matches both the specified window and event mask.
When it finds a match, _X_W_i_n_d_o_w_E_v_e_n_t removes that event from
the queue and copies it into the specified _X_E_v_e_n_t structure.
The other events stored in the queue are not discarded.  If
a matching event is not in the queue, _X_W_i_n_d_o_w_E_v_e_n_t flushes
the output buffer and blocks until one is received.


To remove the next event that matches both a window and an
event mask (if any), use _X_C_h_e_c_k_W_i_n_d_o_w_E_v_e_n_t.  This function
is similar to _X_W_i_n_d_o_w_E_v_e_n_t except that it never blocks and
it returns a _B_o_o_l indicating if the event was returned.
























                             334411





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XCheckWindowEvent(_d_i_s_p_l_a_y, _w, _e_v_e_n_t___m_a_s_k, _e_v_e_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      long _e_v_e_n_t___m_a_s_k;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window whose events you are inter­
          ested in.

_e_v_e_n_t___m_a_s_k
          Specifies the event mask.

_e_v_e_n_t___r_e_t_u_r_n
          Returns the matched event’s associated structure.
││__

The _X_C_h_e_c_k_W_i_n_d_o_w_E_v_e_n_t function searches the event queue and
then the events available on the server connection for the
first event that matches the specified window and event
mask.  If it finds a match, _X_C_h_e_c_k_W_i_n_d_o_w_E_v_e_n_t removes that
event, copies it into the specified _X_E_v_e_n_t structure, and
returns _T_r_u_e.  The other events stored in the queue are not
discarded.  If the event you requested is not available,
_X_C_h_e_c_k_W_i_n_d_o_w_E_v_e_n_t returns _F_a_l_s_e, and the output buffer will
have been flushed.


To remove the next event that matches an event mask, use
_X_M_a_s_k_E_v_e_n_t.
__
││
XMaskEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___m_a_s_k, _e_v_e_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      long _e_v_e_n_t___m_a_s_k;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___m_a_s_k
          Specifies the event mask.

_e_v_e_n_t___r_e_t_u_r_n
          Returns the matched event’s associated structure.
││__

The _X_M_a_s_k_E_v_e_n_t function searches the event queue for the
events associated with the specified mask.  When it finds a
match, _X_M_a_s_k_E_v_e_n_t removes that event and copies it into the
specified _X_E_v_e_n_t structure.  The other events stored in the



                             334422





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


queue are not discarded.  If the event you requested is not
in the queue, _X_M_a_s_k_E_v_e_n_t flushes the output buffer and
blocks until one is received.


To return and remove the next event that matches an event
mask (if any), use _X_C_h_e_c_k_M_a_s_k_E_v_e_n_t.  This function is simi­
lar to _X_M_a_s_k_E_v_e_n_t except that it never blocks and it returns
a _B_o_o_l indicating if the event was returned.
__
││
Bool XCheckMaskEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___m_a_s_k, _e_v_e_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      long _e_v_e_n_t___m_a_s_k;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___m_a_s_k
          Specifies the event mask.

_e_v_e_n_t___r_e_t_u_r_n
          Returns the matched event’s associated structure.
││__

The _X_C_h_e_c_k_M_a_s_k_E_v_e_n_t function searches the event queue and
then any events available on the server connection for the
first event that matches the specified mask.  If it finds a
match, _X_C_h_e_c_k_M_a_s_k_E_v_e_n_t removes that event, copies it into
the specified _X_E_v_e_n_t structure, and returns _T_r_u_e.  The other
events stored in the queue are not discarded.  If the event
you requested is not available, _X_C_h_e_c_k_M_a_s_k_E_v_e_n_t returns
_F_a_l_s_e, and the output buffer will have been flushed.


To return and remove the next event in the queue that
matches an event type, use _X_C_h_e_c_k_T_y_p_e_d_E_v_e_n_t.



















                             334433





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XCheckTypedEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___t_y_p_e, _e_v_e_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int _e_v_e_n_t___t_y_p_e;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___t_y_p_e
          Specifies the event type to be compared.


_e_v_e_n_t___r_e_t_u_r_n
          Returns the matched event’s associated structure.
││__

The _X_C_h_e_c_k_T_y_p_e_d_E_v_e_n_t function searches the event queue and
then any events available on the server connection for the
first event that matches the specified type.  If it finds a
match, _X_C_h_e_c_k_T_y_p_e_d_E_v_e_n_t removes that event, copies it into
the specified _X_E_v_e_n_t structure, and returns _T_r_u_e.  The other
events in the queue are not discarded.  If the event is not
available, _X_C_h_e_c_k_T_y_p_e_d_E_v_e_n_t returns _F_a_l_s_e, and the output
buffer will have been flushed.


To return and remove the next event in the queue that
matches an event type and a window, use _X_C_h_e_c_k_T_y_p_e_d_W_i_n_d_o_w_­
_E_v_e_n_t.
__
││
Bool XCheckTypedWindowEvent(_d_i_s_p_l_a_y, _w, _e_v_e_n_t___t_y_p_e, _e_v_e_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _e_v_e_n_t___t_y_p_e;
      XEvent *_e_v_e_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_e_v_e_n_t___t_y_p_e
          Specifies the event type to be compared.


_e_v_e_n_t___r_e_t_u_r_n
          Returns the matched event’s associated structure.
││__

The _X_C_h_e_c_k_T_y_p_e_d_W_i_n_d_o_w_E_v_e_n_t function searches the event queue
and then any events available on the server connection for
the first event that matches the specified type and window.



                             334444





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


If it finds a match, _X_C_h_e_c_k_T_y_p_e_d_W_i_n_d_o_w_E_v_e_n_t removes the
event from the queue, copies it into the specified _X_E_v_e_n_t
structure, and returns _T_r_u_e.  The other events in the queue
are not discarded.  If the event is not available, _X_C_h_e_c_k_­
_T_y_p_e_d_W_i_n_d_o_w_E_v_e_n_t returns _F_a_l_s_e, and the output buffer will
have been flushed.

1111..55..  PPuuttttiinngg aann EEvveenntt BBaacckk iinnttoo tthhee QQuueeuuee

To push an event back into the event queue, use _X_P_u_t_B_a_c_k_­
_E_v_e_n_t.
__
││
XPutBackEvent(_d_i_s_p_l_a_y, _e_v_e_n_t)
      Display *_d_i_s_p_l_a_y;
      XEvent *_e_v_e_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t     Specifies the event.
││__

The _X_P_u_t_B_a_c_k_E_v_e_n_t function pushes an event back onto the
head of the display’s event queue by copying the event into
the queue.  This can be useful if you read an event and then
decide that you would rather deal with it later.  There is
no limit to the number of times in succession that you can
call _X_P_u_t_B_a_c_k_E_v_e_n_t.

1111..66..  SSeennddiinngg EEvveennttss ttoo OOtthheerr AApppplliiccaattiioonnss

To send an event to a specified window, use _X_S_e_n_d_E_v_e_n_t.
This function is often used in selection processing.  For
example, the owner of a selection should use _X_S_e_n_d_E_v_e_n_t to
send a _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event to a requestor when a selection
has been converted and stored as a property.




















                             334455





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XSendEvent(_d_i_s_p_l_a_y, _w, _p_r_o_p_a_g_a_t_e, _e_v_e_n_t___m_a_s_k, _e_v_e_n_t___s_e_n_d)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Bool _p_r_o_p_a_g_a_t_e;
      long _e_v_e_n_t___m_a_s_k;
      XEvent *_e_v_e_n_t___s_e_n_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window the event is to be sent to,
          or _P_o_i_n_t_e_r_W_i_n_d_o_w, or _I_n_p_u_t_F_o_c_u_s.

_p_r_o_p_a_g_a_t_e Specifies a Boolean value.

_e_v_e_n_t___m_a_s_k
          Specifies the event mask.

_e_v_e_n_t___s_e_n_d
          Specifies the event that is to be sent.
││__

The _X_S_e_n_d_E_v_e_n_t function identifies the destination window,
determines which clients should receive the specified
events, and ignores any active grabs.  This function
requires you to pass an event mask.  For a discussion of the
valid event mask names, see section 10.3.  This function
uses the w argument to identify the destination window as
follows:

⋅    If w is _P_o_i_n_t_e_r_W_i_n_d_o_w, the destination window is the
     window that contains the pointer.

⋅    If w is _I_n_p_u_t_F_o_c_u_s and if the focus window contains the
     pointer, the destination window is the window that con­
     tains the pointer; otherwise, the destination window is
     the focus window.

To determine which clients should receive the specified
events, _X_S_e_n_d_E_v_e_n_t uses the propagate argument as follows:

⋅    If event_mask is the empty set, the event is sent to
     the client that created the destination window.  If
     that client no longer exists, no event is sent.

⋅    If propagate is _F_a_l_s_e, the event is sent to every
     client selecting on destination any of the event types
     in the event_mask argument.

⋅    If propagate is _T_r_u_e and no clients have selected on
     destination any of the event types in event‐mask, the
     destination is replaced with the closest ancestor of
     destination for which some client has selected a type



                             334466





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     in event‐mask and for which no intervening window has
     that type in its do‐not‐propagate‐mask.  If no such
     window exists or if the window is an ancestor of the
     focus window and _I_n_p_u_t_F_o_c_u_s was originally specified as
     the destination, the event is not sent to any clients.
     Otherwise, the event is reported to every client
     selecting on the final destination any of the types
     specified in event_mask.

The event in the _X_E_v_e_n_t structure must be one of the core
events or one of the events defined by an extension (or a
_B_a_d_V_a_l_u_e error results) so that the X server can correctly
byte‐swap the contents as necessary.  The contents of the
event are otherwise unaltered and unchecked by the X server
except to force send_event to _T_r_u_e in the forwarded event
and to set the serial number in the event correctly; there­
fore these fields and the display field are ignored by
_X_S_e_n_d_E_v_e_n_t.

_X_S_e_n_d_E_v_e_n_t returns zero if the conversion to wire protocol
format failed and returns nonzero otherwise.

_X_S_e_n_d_E_v_e_n_t can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w errors.

1111..77..  GGeettttiinngg PPooiinntteerr MMoottiioonn HHiissttoorryy

Some X server implementations will maintain a more complete
history of pointer motion than is reported by event notifi­
cation.  The pointer position at each pointer hardware
interrupt may be stored in a buffer for later retrieval.
This buffer is called the motion history buffer.  For exam­
ple, a few applications, such as paint programs, want to
have a precise history of where the pointer traveled.  How­
ever, this historical information is highly excessive for
most applications.


To determine the approximate maximum number of elements in
the motion buffer, use _X_D_i_s_p_l_a_y_M_o_t_i_o_n_B_u_f_f_e_r_S_i_z_e.
__
││
unsigned long XDisplayMotionBufferSize(_d_i_s_p_l_a_y)
        Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The server may retain the recent history of the pointer
motion and do so to a finer granularity than is reported by
_M_o_t_i_o_n_N_o_t_i_f_y events.  The _X_G_e_t_M_o_t_i_o_n_E_v_e_n_t_s function makes
this history available.





                             334477





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To get the motion history for a specified window and time,
use _X_G_e_t_M_o_t_i_o_n_E_v_e_n_t_s.
__
││
XTimeCoord *XGetMotionEvents(_d_i_s_p_l_a_y, _w, _s_t_a_r_t, _s_t_o_p, _n_e_v_e_n_t_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Time _s_t_a_r_t, _s_t_o_p;
      int *_n_e_v_e_n_t_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_s_t_a_r_t
_s_t_o_p      Specify the time interval in which the events are
          returned from the motion history buffer.  You can
          pass a timestamp or _C_u_r_r_e_n_t_T_i_m_e.

_n_e_v_e_n_t_s___r_e_t_u_r_n
          Returns the number of events from the motion his­
          tory buffer.
││__

The _X_G_e_t_M_o_t_i_o_n_E_v_e_n_t_s function returns all events in the
motion history buffer that fall between the specified start
and stop times, inclusive, and that have coordinates that
lie within the specified window (including its borders) at
its present placement.  If the server does not support
motion history, if the start time is later than the stop
time, or if the start time is in the future, no events are
returned; _X_G_e_t_M_o_t_i_o_n_E_v_e_n_t_s returns NULL.  If the stop time
is in the future, it is equivalent to specifying _C_u_r_r_e_n_t_­
_T_i_m_e.  The return type for this function is a structure
defined as follows:

__
││
typedef struct {
     Time time;
     short x, y;
} XTimeCoord;

││__

The time member is set to the time, in milliseconds.  The x
and y members are set to the coordinates of the pointer and
are reported relative to the origin of the specified window.
To free the data returned from this call, use _X_F_r_e_e.

_X_G_e_t_M_o_t_i_o_n_E_v_e_n_t_s can generate a _B_a_d_W_i_n_d_o_w error.





                             334488





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1111..88..  HHaannddlliinngg PPrroottooccooll EErrrroorrss

Xlib provides functions that you can use to enable or dis­
able synchronization and to use the default error handlers.

1111..88..11..  EEnnaabblliinngg oorr DDiissaabblliinngg SSyynncchhrroonniizzaattiioonn

When debugging X applications, it often is very convenient
to require Xlib to behave synchronously so that errors are
reported as they occur.  The following function lets you
disable or enable synchronous behavior.  Note that graphics
may occur 30 or more times more slowly when synchronization
is enabled.  On POSIX‐conformant systems, there is also a
global variable ___X_d_e_b_u_g that, if set to nonzero before
starting a program under a debugger, will force synchronous
library behavior.

After completing their work, all Xlib functions that gener­
ate protocol requests call what is known as an after func­
tion.  _X_S_e_t_A_f_t_e_r_F_u_n_c_t_i_o_n sets which function is to be
called.
__
││
int (*XSetAfterFunction(_d_i_s_p_l_a_y, _p_r_o_c_e_d_u_r_e))()
      Display *_d_i_s_p_l_a_y;
      int (*_p_r_o_c_e_d_u_r_e)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_r_o_c_e_d_u_r_e Specifies the procedure to be called.
││__

The specified procedure is called with only a display
pointer.  _X_S_e_t_A_f_t_e_r_F_u_n_c_t_i_o_n returns the previous after func­
tion.

To enable or disable synchronization, use _X_S_y_n_c_h_r_o_n_i_z_e.
__
││
int (*XSynchronize(_d_i_s_p_l_a_y, _o_n_o_f_f))()
      Display *_d_i_s_p_l_a_y;
      Bool _o_n_o_f_f;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_o_n_o_f_f     Specifies a Boolean value that indicates whether
          to enable or disable synchronization.
││__

The _X_S_y_n_c_h_r_o_n_i_z_e function returns the previous after func­
tion.  If onoff is _T_r_u_e, _X_S_y_n_c_h_r_o_n_i_z_e turns on synchronous
behavior.  If onoff is _F_a_l_s_e, _X_S_y_n_c_h_r_o_n_i_z_e turns off



                             334499





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


synchronous behavior.

1111..88..22..  UUssiinngg tthhee DDeeffaauulltt EErrrroorr HHaannddlleerrss

There are two default error handlers in Xlib: one to handle
typically fatal conditions (for example, the connection to a
display server dying because a machine crashed) and one to
handle protocol errors from the X server.  These error han­
dlers can be changed to user‐supplied routines if you prefer
your own error handling and can be changed as often as you
like.  If either function is passed a NULL pointer, it will
reinvoke the default handler.  The action of the default
handlers is to print an explanatory message and exit.


To set the error handler, use _X_S_e_t_E_r_r_o_r_H_a_n_d_l_e_r.
__
││
int (*XSetErrorHandler(_h_a_n_d_l_e_r))()
      int (*_h_a_n_d_l_e_r)(Display *, XErrorEvent *)


_h_a_n_d_l_e_r   Specifies the program’s supplied error handler.
││__

Xlib generally calls the program’s supplied error handler
whenever an error is received.  It is not called on _B_a_d_N_a_m_e
errors from _O_p_e_n_F_o_n_t, _L_o_o_k_u_p_C_o_l_o_r, or _A_l_l_o_c_N_a_m_e_d_C_o_l_o_r proto­
col requests or on _B_a_d_F_o_n_t errors from a _Q_u_e_r_y_F_o_n_t protocol
request.  These errors generally are reflected back to the
program through the procedural interface.  Because this con­
dition is not assumed to be fatal, it is acceptable for your
error handler to return; the returned value is ignored.
However, the error handler should not call any functions
(directly or indirectly) on the display that will generate
protocol requests or that will look for input events.  The
previous error handler is returned.

The _X_E_r_r_o_r_E_v_e_n_t structure contains:


typedef struct {
     int type;
     Display *display;   /* Display the event was read from */
     unsigned long serial;/* serial number of failed request */
     unsigned char error_code;/* error code of failed request */
     unsigned char request_code;/* Major op‐code of failed request */
     unsigned char minor_code;/* Minor op‐code of failed request */
     XID resourceid;     /* resource id */
} XErrorEvent;


The serial member is the number of requests, starting from
one, sent over the network connection since it was opened.



                             335500





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


It is the number that was the value of _N_e_x_t_R_e_q_u_e_s_t immedi­
ately before the failing call was made.  The request_code
member is a protocol request of the procedure that failed,
as defined in <_X_1_1_/_X_p_r_o_t_o_._h>.  The following error codes can
be returned by the functions described in this chapter:

-------------------------------------------------------------
EErrrroorr CCooddee                        DDeessccrriippttiioonn
-------------------------------------------------------------
_B_a_d_A_c_c_e_s_s           A client attempts to grab a key/button
                    combination already grabbed by another
                    client.
                    A client attempts to free a colormap
                    entry that it had not already allocated
                    or to free an entry in a colormap that
                    was created with all entries writable.
                    A client attempts to store into a read‐
                    only or unallocated colormap entry.
                    A client attempts to modify the access
                    control list from other than the local
                    (or otherwise authorized) host.
                    A client attempts to select an event
                    type that another client has already
                    selected.
_B_a_d_A_l_l_o_c            The server fails to allocate the
                    requested resource.  Note that the
                    explicit listing of _B_a_d_A_l_l_o_c errors in
                    requests only covers allocation errors
                    at a very coarse level and is not
                    intended to (nor can it in practice hope
                    to) cover all cases of a server running
                    out of allocation space in the middle of
                    service.  The semantics when a server
                    runs out of allocation space are left
                    unspecified, but a server may generate a
                    _B_a_d_A_l_l_o_c error on any request for this
                    reason, and clients should be prepared
                    to receive such errors and handle or
                    discard them.
_B_a_d_A_t_o_m             A value for an atom argument does not
                    name a defined atom.
_B_a_d_C_o_l_o_r            A value for a colormap argument does not
                    name a defined colormap.
_B_a_d_C_u_r_s_o_r           A value for a cursor argument does not
                    name a defined cursor.
_B_a_d_D_r_a_w_a_b_l_e         A value for a drawable argument does not
                    name a defined window or pixmap.
_B_a_d_F_o_n_t             A value for a font argument does not
                    name a defined font (or, in some cases,
                    _G_C_o_n_t_e_x_t).
_B_a_d_G_C               A value for a _G_C_o_n_t_e_x_t argument does not
                    name a defined _G_C_o_n_t_e_x_t.





                             335511





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------------
EErrrroorr CCooddee                        DDeessccrriippttiioonn
-------------------------------------------------------------
_B_a_d_I_D_C_h_o_i_c_e         The value chosen for a resource identi­
                    fier either is not included in the range
                    assigned to the client or is already in
                    use.  Under normal circumstances, this
                    cannot occur and should be considered a
                    server or Xlib error.
_B_a_d_I_m_p_l_e_m_e_n_t_a_t_i_o_n   The server does not implement some
                    aspect of the request.  A server that
                    generates this error for a core request
                    is deficient.  As such, this error is
                    not listed for any of the requests, but
                    clients should be prepared to receive
                    such errors and handle or discard them.
_B_a_d_L_e_n_g_t_h           The length of a request is shorter or
                    longer than that required to contain the
                    arguments.  This is an internal Xlib or
                    server error.
                    The length of a request exceeds the max­
                    imum length accepted by the server.
_B_a_d_M_a_t_c_h            In a graphics request, the root and
                    depth of the graphics context do not
                    match those of the drawable.
                    An _I_n_p_u_t_O_n_l_y window is used as a draw­
                    able.
                    Some argument or pair of arguments has
                    the correct type and range, but it fails
                    to match in some other way required by
                    the request.
                    An _I_n_p_u_t_O_n_l_y window lacks this
                    attribute.
_B_a_d_N_a_m_e             A font or color of the specified name
                    does not exist.
_B_a_d_P_i_x_m_a_p           A value for a pixmap argument does not
                    name a defined pixmap.
_B_a_d_R_e_q_u_e_s_t          The major or minor opcode does not spec­
                    ify a valid request.  This usually is an
                    Xlib or server error.
_B_a_d_V_a_l_u_e            Some numeric value falls outside of the
                    range of values accepted by the request.
                    Unless a specific range is specified for
                    an argument, the full range defined by
                    the argument’s type is accepted.  Any
                    argument defined as a set of alterna­
                    tives typically can generate this error
                    (due to the encoding).
_B_a_d_W_i_n_d_o_w           A value for a window argument does not
                    name a defined window.
-------------------------------------------------------------






                             335522





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


                            Note

     The _B_a_d_A_t_o_m, _B_a_d_C_o_l_o_r, _B_a_d_C_u_r_s_o_r, _B_a_d_D_r_a_w_a_b_l_e,
     _B_a_d_F_o_n_t, _B_a_d_G_C, _B_a_d_P_i_x_m_a_p, and _B_a_d_W_i_n_d_o_w errors
     are also used when the argument type is extended
     by a set of fixed alternatives.



To obtain textual descriptions of the specified error code,
use _X_G_e_t_E_r_r_o_r_T_e_x_t.
__
││
XGetErrorText(_d_i_s_p_l_a_y, _c_o_d_e, _b_u_f_f_e_r___r_e_t_u_r_n, _l_e_n_g_t_h)
      Display *_d_i_s_p_l_a_y;
      int _c_o_d_e;
      char *_b_u_f_f_e_r___r_e_t_u_r_n;
      int _l_e_n_g_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_o_d_e      Specifies the error code for which you want to
          obtain a description.

_b_u_f_f_e_r___r_e_t_u_r_n
          Returns the error description.

_l_e_n_g_t_h    Specifies the size of the buffer.
││__

The _X_G_e_t_E_r_r_o_r_T_e_x_t function copies a null‐terminated string
describing the specified error code into the specified
buffer.  The returned text is in the encoding of the current
locale.  It is recommended that you use this function to
obtain an error description because extensions to Xlib may
define their own error codes and error strings.


To obtain error messages from the error database, use
_X_G_e_t_E_r_r_o_r_D_a_t_a_b_a_s_e_T_e_x_t.
















                             335533





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XGetErrorDatabaseText(_d_i_s_p_l_a_y, _n_a_m_e, _m_e_s_s_a_g_e, _d_e_f_a_u_l_t___s_t_r_i_n_g, _b_u_f_f_e_r___r_e_t_u_r_n, _l_e_n_g_t_h)
      Display *_d_i_s_p_l_a_y;
      char *_n_a_m_e, *_m_e_s_s_a_g_e;
      char *_d_e_f_a_u_l_t___s_t_r_i_n_g;
      char *_b_u_f_f_e_r___r_e_t_u_r_n;
      int _l_e_n_g_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_a_m_e      Specifies the name of the application.

_m_e_s_s_a_g_e   Specifies the type of the error message.

_d_e_f_a_u_l_t___s_t_r_i_n_g
          Specifies the default error message if none is
          found in the database.

_b_u_f_f_e_r___r_e_t_u_r_n
          Returns the error description.

_l_e_n_g_t_h    Specifies the size of the buffer.
││__

The _X_G_e_t_E_r_r_o_r_D_a_t_a_b_a_s_e_T_e_x_t function returns a null‐terminated
message (or the default message) from the error message
database.  Xlib uses this function internally to look up its
error messages.  The text in the default_string argument is
assumed to be in the encoding of the current locale, and the
text stored in the buffer_return argument is in the encoding
of the current locale.

The name argument should generally be the name of your
application.  The message argument should indicate which
type of error message you want.  If the name and message are
not in the Host Portable Character Encoding, the result is
implementation‐dependent.  Xlib uses three predefined
‘‘application names’’ to report errors.  In these names,
uppercase and lowercase matter.

XProtoError
          The protocol error number is used as a string for
          the message argument.

XlibMessage
          These are the message strings that are used inter­
          nally by the library.

XRequest  For a core protocol request, the major request
          protocol number is used for the message argument.
          For an extension request, the extension name (as
          given by _I_n_i_t_E_x_t_e_n_s_i_o_n) followed by a period (.)
          and the minor request protocol number is used for



                             335544





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


          the message argument.  If no string is found in
          the error database, the default_string is returned
          to the buffer argument.


To report an error to the user when the requested display
does not exist, use _X_D_i_s_p_l_a_y_N_a_m_e.
__
││
char *XDisplayName(_s_t_r_i_n_g)
      char *_s_t_r_i_n_g;


_s_t_r_i_n_g    Specifies the character string.
││__

The _X_D_i_s_p_l_a_y_N_a_m_e function returns the name of the display
that _X_O_p_e_n_D_i_s_p_l_a_y would attempt to use.  If a NULL string is
specified, _X_D_i_s_p_l_a_y_N_a_m_e looks in the environment for the
display and returns the display name that _X_O_p_e_n_D_i_s_p_l_a_y would
attempt to use.  This makes it easier to report to the user
precisely which display the program attempted to open when
the initial connection attempt failed.


To handle fatal I/O errors, use _X_S_e_t_I_O_E_r_r_o_r_H_a_n_d_l_e_r.
__
││
int (*XSetIOErrorHandler(_h_a_n_d_l_e_r))()
      int (*_h_a_n_d_l_e_r)(Display *);


_h_a_n_d_l_e_r   Specifies the program’s supplied error handler.
││__

The _X_S_e_t_I_O_E_r_r_o_r_H_a_n_d_l_e_r sets the fatal I/O error handler.
Xlib calls the program’s supplied error handler if any sort
of system call error occurs (for example, the connection to
the server was lost).  This is assumed to be a fatal condi­
tion, and the called routine should not return.  If the I/O
error handler does return, the client process exits.

Note that the previous error handler is returned.














                             335555





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 1122

                   IInnppuutt DDeevviiccee FFuunnccttiioonnss



You can use the Xlib input device functions to:

⋅    Grab the pointer and individual buttons on the pointer

⋅    Grab the keyboard and individual keys on the keyboard

⋅    Resume event processing

⋅    Move the pointer

⋅    Set the input focus

⋅    Manipulate the keyboard and pointer settings

⋅    Manipulate the keyboard encoding

1122..11..  PPooiinntteerr GGrraabbbbiinngg

Xlib provides functions that you can use to control input
from the pointer, which usually is a mouse.  Usually, as
soon as keyboard and mouse events occur, the X server deliv­
ers them to the appropriate client, which is determined by
the window and input focus.  The X server provides suffi­
cient control over event delivery to allow window managers
to support mouse ahead and various other styles of user
interface.  Many of these user interfaces depend on syn­
chronous delivery of events.  The delivery of  pointer and
keyboard events can be controlled independently.

When mouse buttons or keyboard keys are grabbed, events will
be sent to the grabbing client rather than the normal client
who would have received the event.  If the keyboard or
pointer is in asynchronous mode, further mouse and keyboard
events will continue to be processed.  If the keyboard or
pointer is in synchronous mode, no further events are pro­
cessed until the grabbing client allows them (see _X_A_l_l_o_w_­
_E_v_e_n_t_s).  The keyboard or pointer is considered frozen dur­
ing this interval.  The event that triggered the grab can
also be replayed.

Note that the logical state of a device (as seen by client
applications) may lag the physical state if device event
processing is frozen.

There are two kinds of grabs: active and passive.  An active
grab occurs when a single client grabs the keyboard and/or



                             335566





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


pointer explicitly (see _X_G_r_a_b_P_o_i_n_t_e_r and _X_G_r_a_b_K_e_y_b_o_a_r_d).  A
passive grab occurs when clients grab a particular keyboard
key or pointer button in a window, and the grab will acti­
vate when the key or button is actually pressed.  Passive
grabs are convenient for implementing reliable pop‐up menus.
For example, you can guarantee that the pop‐up is mapped
before the up pointer button event occurs by grabbing a but­
ton requesting synchronous behavior.  The down event will
trigger the grab and freeze further processing of pointer
events until you have the chance to map the pop‐up window.
You can then allow further event processing.  The up event
will then be correctly processed relative to the pop‐up win­
dow.

For many operations, there are functions that take a time
argument.  The X server includes a timestamp in various
events.  One special time, called _C_u_r_r_e_n_t_T_i_m_e, represents
the current server time.  The X server maintains the time
when the input focus was last changed, when the keyboard was
last grabbed, when the pointer was last grabbed, or when a
selection was last changed.  Your application may be slow
reacting to an event.  You often need some way to specify
that your request should not occur if another application
has in the meanwhile taken control of the keyboard, pointer,
or selection.  By providing the timestamp from the event in
the request, you can arrange that the operation not take
effect if someone else has performed an operation in the
meanwhile.

A timestamp is a time value, expressed in milliseconds.  It
typically is the time since the last server reset.  Times­
tamp values wrap around (after about 49.7 days).  The
server, given its current time is represented by timestamp
T, always interprets timestamps from clients by treating
half of the timestamp space as being later in time than T.
One timestamp value, named _C_u_r_r_e_n_t_T_i_m_e, is never generated
by the server.  This value is reserved for use in requests
to represent the current server time.

For many functions in this section, you pass pointer event
mask bits.  The valid pointer event mask bits are: _B_u_t_t_o_n_­
_P_r_e_s_s_M_a_s_k, _B_u_t_t_o_n_R_e_l_e_a_s_e_M_a_s_k, _E_n_t_e_r_W_i_n_d_o_w_M_a_s_k, _L_e_a_v_e_W_i_n_d_o_w_­
_M_a_s_k, _P_o_i_n_t_e_r_M_o_t_i_o_n_M_a_s_k, _P_o_i_n_t_e_r_M_o_t_i_o_n_H_i_n_t_M_a_s_k, _B_u_t_­
_t_o_n_1_M_o_t_i_o_n_M_a_s_k, _B_u_t_t_o_n_2_M_o_t_i_o_n_M_a_s_k, _B_u_t_t_o_n_3_M_o_t_i_o_n_M_a_s_k, _B_u_t_­
_t_o_n_4_M_o_t_i_o_n_M_a_s_k, _B_u_t_t_o_n_5_M_o_t_i_o_n_M_a_s_k, _B_u_t_t_o_n_M_o_t_i_o_n_M_a_s_k, and
_K_e_y_M_a_p_S_t_a_t_e_M_a_s_k.  For other functions in this section, you
pass keymask bits.  The valid keymask bits are: _S_h_i_f_t_M_a_s_k,
_L_o_c_k_M_a_s_k, _C_o_n_t_r_o_l_M_a_s_k, _M_o_d_1_M_a_s_k, _M_o_d_2_M_a_s_k, _M_o_d_3_M_a_s_k,
_M_o_d_4_M_a_s_k, and _M_o_d_5_M_a_s_k.


To grab the pointer, use _X_G_r_a_b_P_o_i_n_t_e_r.





                             335577





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XGrabPointer(_d_i_s_p_l_a_y, _g_r_a_b___w_i_n_d_o_w, _o_w_n_e_r___e_v_e_n_t_s, _e_v_e_n_t___m_a_s_k, _p_o_i_n_t_e_r___m_o_d_e,
               _k_e_y_b_o_a_r_d___m_o_d_e, _c_o_n_f_i_n_e___t_o, _c_u_r_s_o_r, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      Window _g_r_a_b___w_i_n_d_o_w;
      Bool _o_w_n_e_r___e_v_e_n_t_s;
      unsigned int _e_v_e_n_t___m_a_s_k;
      int _p_o_i_n_t_e_r___m_o_d_e, _k_e_y_b_o_a_r_d___m_o_d_e;
      Window _c_o_n_f_i_n_e___t_o;
      Cursor _c_u_r_s_o_r;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_r_a_b___w_i_n_d_o_w
          Specifies the grab window.

_o_w_n_e_r___e_v_e_n_t_s
          Specifies a Boolean value that indicates whether
          the pointer events are to be reported as usual or
          reported with respect to the grab window if
          selected by the event mask.

_e_v_e_n_t___m_a_s_k
          Specifies which pointer events are reported to the
          client.  The mask is the bitwise inclusive OR of
          the valid pointer event mask bits.

_p_o_i_n_t_e_r___m_o_d_e
          Specifies further processing of pointer events.
          You can pass _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

_k_e_y_b_o_a_r_d___m_o_d_e
          Specifies further processing of keyboard events.
          You can pass _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

_c_o_n_f_i_n_e___t_o
          Specifies the window to confine the pointer in or
          _N_o_n_e.

_c_u_r_s_o_r    Specifies the cursor that is to be displayed dur­
          ing the grab or _N_o_n_e.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

The _X_G_r_a_b_P_o_i_n_t_e_r function actively grabs control of the
pointer and returns _G_r_a_b_S_u_c_c_e_s_s if the grab was successful.
Further pointer events are reported only to the grabbing
client.  _X_G_r_a_b_P_o_i_n_t_e_r overrides any active pointer grab by
this client.  If owner_events is _F_a_l_s_e, all generated
pointer events are reported with respect to grab_window and



                             335588





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


are reported only if selected by event_mask.  If
owner_events is _T_r_u_e and if a generated pointer event would
normally be reported to this client, it is reported as
usual.  Otherwise, the event is reported with respect to the
grab_window and is reported only if selected by event_mask.
For either value of owner_events, unreported events are dis­
carded.

If the pointer_mode is _G_r_a_b_M_o_d_e_A_s_y_n_c, pointer event process­
ing continues as usual.  If the pointer is currently frozen
by this client, the processing of events for the pointer is
resumed.  If the pointer_mode is _G_r_a_b_M_o_d_e_S_y_n_c, the state of
the pointer, as seen by client applications, appears to
freeze, and the X server generates no further pointer events
until the grabbing client calls _X_A_l_l_o_w_E_v_e_n_t_s or until the
pointer grab is released.  Actual pointer changes are not
lost while the pointer is frozen; they are simply queued in
the server for later processing.

If the keyboard_mode is _G_r_a_b_M_o_d_e_A_s_y_n_c, keyboard event pro­
cessing is unaffected by activation of the grab.  If the
keyboard_mode is _G_r_a_b_M_o_d_e_S_y_n_c, the state of the keyboard, as
seen by client applications, appears to freeze, and the X
server generates no further keyboard events until the grab­
bing client calls _X_A_l_l_o_w_E_v_e_n_t_s or until the pointer grab is
released.  Actual keyboard changes are not lost while the
pointer is frozen; they are simply queued in the server for
later processing.

If a cursor is specified, it is displayed regardless of what
window the pointer is in.  If _N_o_n_e is specified, the normal
cursor for that window is displayed when the pointer is in
grab_window or one of its subwindows; otherwise, the cursor
for grab_window is displayed.

If a confine_to window is specified, the pointer is
restricted to stay contained in that window.  The confine_to
window need have no relationship to the grab_window.  If the
pointer is not initially in the confine_to window, it is
warped automatically to the closest edge just before the
grab activates and enter/leave events are generated as
usual.  If the confine_to window is subsequently reconfig­
ured, the pointer is warped automatically, as necessary, to
keep it contained in the window.

The time argument allows you to avoid certain circumstances
that come up if applications take a long time to respond or
if there are long network delays.  Consider a situation
where you have two applications, both of which normally grab
the pointer when clicked on.  If both applications specify
the timestamp from the event, the second application may
wake up faster and successfully grab the pointer before the
first application.  The first application then will get an
indication that the other application grabbed the pointer



                             335599





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


before its request was processed.

_X_G_r_a_b_P_o_i_n_t_e_r generates _E_n_t_e_r_N_o_t_i_f_y and _L_e_a_v_e_N_o_t_i_f_y events.

Either if grab_window or confine_to window is not viewable
or if the confine_to window lies completely outside the
boundaries of the root window, _X_G_r_a_b_P_o_i_n_t_e_r fails and
returns _G_r_a_b_N_o_t_V_i_e_w_a_b_l_e.  If the pointer is actively grabbed
by some other client, it fails and returns _A_l_r_e_a_d_y_G_r_a_b_b_e_d.
If the pointer is frozen by an active grab of another
client, it fails and returns _G_r_a_b_F_r_o_z_e_n.  If the specified
time is earlier than the last‐pointer‐grab time or later
than the current X server time, it fails and returns _G_r_a_b_I_n_­
_v_a_l_i_d_T_i_m_e.  Otherwise, the last‐pointer‐grab time is set to
the specified time (_C_u_r_r_e_n_t_T_i_m_e is replaced by the current X
server time).

_X_G_r_a_b_P_o_i_n_t_e_r can generate _B_a_d_C_u_r_s_o_r, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w
errors.


To ungrab the pointer, use _X_U_n_g_r_a_b_P_o_i_n_t_e_r.
__
││
XUngrabPointer(_d_i_s_p_l_a_y, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

The _X_U_n_g_r_a_b_P_o_i_n_t_e_r function releases the pointer and any
queued events if this client has actively grabbed the
pointer from _X_G_r_a_b_P_o_i_n_t_e_r, _X_G_r_a_b_B_u_t_t_o_n, or from a normal
button press.  _X_U_n_g_r_a_b_P_o_i_n_t_e_r does not release the pointer
if the specified time is earlier than the last‐pointer‐grab
time or is later than the current X server time.  It also
generates _E_n_t_e_r_N_o_t_i_f_y and _L_e_a_v_e_N_o_t_i_f_y events.  The X server
performs an _U_n_g_r_a_b_P_o_i_n_t_e_r request automatically if the event
window or confine_to window for an active pointer grab
becomes not viewable or if window reconfiguration causes the
confine_to window to lie completely outside the boundaries
of the root window.


To change an active pointer grab, use _X_C_h_a_n_g_e_A_c_t_i_v_e_P_o_i_n_t_e_r_­
_G_r_a_b.






                             336600





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XChangeActivePointerGrab(_d_i_s_p_l_a_y, _e_v_e_n_t___m_a_s_k, _c_u_r_s_o_r, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      unsigned int _e_v_e_n_t___m_a_s_k;
      Cursor _c_u_r_s_o_r;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___m_a_s_k
          Specifies which pointer events are reported to the
          client.  The mask is the bitwise inclusive OR of
          the valid pointer event mask bits.

_c_u_r_s_o_r    Specifies the cursor that is to be displayed or
          _N_o_n_e.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

The _X_C_h_a_n_g_e_A_c_t_i_v_e_P_o_i_n_t_e_r_G_r_a_b function changes the specified
dynamic parameters if the pointer is actively grabbed by the
client and if the specified time is no earlier than the
last‐pointer‐grab time and no later than the current X
server time.  This function has no effect on the passive
parameters of an _X_G_r_a_b_B_u_t_t_o_n.  The interpretation of
event_mask and cursor is the same as described in _X_G_r_a_b_­
_P_o_i_n_t_e_r.

_X_C_h_a_n_g_e_A_c_t_i_v_e_P_o_i_n_t_e_r_G_r_a_b can generate _B_a_d_C_u_r_s_o_r and _B_a_d_V_a_l_u_e
errors.


To grab a pointer button, use _X_G_r_a_b_B_u_t_t_o_n.





















                             336611





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XGrabButton(_d_i_s_p_l_a_y, _b_u_t_t_o_n, _m_o_d_i_f_i_e_r_s, _g_r_a_b___w_i_n_d_o_w, _o_w_n_e_r___e_v_e_n_t_s, _e_v_e_n_t___m_a_s_k,
                _p_o_i_n_t_e_r___m_o_d_e, _k_e_y_b_o_a_r_d___m_o_d_e, _c_o_n_f_i_n_e___t_o, _c_u_r_s_o_r)
      Display *_d_i_s_p_l_a_y;
      unsigned int _b_u_t_t_o_n;
      unsigned int _m_o_d_i_f_i_e_r_s;
      Window _g_r_a_b___w_i_n_d_o_w;
      Bool _o_w_n_e_r___e_v_e_n_t_s;
      unsigned int _e_v_e_n_t___m_a_s_k;
      int _p_o_i_n_t_e_r___m_o_d_e, _k_e_y_b_o_a_r_d___m_o_d_e;
      Window _c_o_n_f_i_n_e___t_o;
      Cursor _c_u_r_s_o_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_b_u_t_t_o_n    Specifies the pointer button that is to be grabbed
          or _A_n_y_B_u_t_t_o_n.

_m_o_d_i_f_i_e_r_s Specifies the set of keymasks or _A_n_y_M_o_d_i_f_i_e_r.  The
          mask is the bitwise inclusive OR of the valid key­
          mask bits.

_g_r_a_b___w_i_n_d_o_w
          Specifies the grab window.

_o_w_n_e_r___e_v_e_n_t_s
          Specifies a Boolean value that indicates whether
          the pointer events are to be reported as usual or
          reported with respect to the grab window if
          selected by the event mask.

_e_v_e_n_t___m_a_s_k
          Specifies which pointer events are reported to the
          client.  The mask is the bitwise inclusive OR of
          the valid pointer event mask bits.

_p_o_i_n_t_e_r___m_o_d_e
          Specifies further processing of pointer events.
          You can pass _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

_k_e_y_b_o_a_r_d___m_o_d_e
          Specifies further processing of keyboard events.
          You can pass _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

_c_o_n_f_i_n_e___t_o
          Specifies the window to confine the pointer in or
          _N_o_n_e.

_c_u_r_s_o_r    Specifies the cursor that is to be displayed or
          _N_o_n_e.
││__

The _X_G_r_a_b_B_u_t_t_o_n function establishes a passive grab.  In the



                             336622





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


future, the pointer is actively grabbed (as for _X_G_r_a_b_­
_P_o_i_n_t_e_r), the last‐pointer‐grab time is set to the time at
which the button was pressed (as transmitted in the _B_u_t_t_o_n_­
_P_r_e_s_s event), and the _B_u_t_t_o_n_P_r_e_s_s event is reported if all
of the following conditions are true:

⋅    The pointer is not grabbed, and the specified button is
     logically pressed when the specified modifier keys are
     logically down, and no other buttons or modifier keys
     are logically down.

⋅    The grab_window contains the pointer.

⋅    The confine_to window (if any) is viewable.

⋅    A passive grab on the same button/key combination does
     not exist on any ancestor of grab_window.

The interpretation of the remaining arguments is as for
_X_G_r_a_b_P_o_i_n_t_e_r.  The active grab is terminated automatically
when the logical state of the pointer has all buttons
released (independent of the state of the logical modifier
keys).

Note that the logical state of a device (as seen by client
applications) may lag the physical state if device event
processing is frozen.

This request overrides all previous grabs by the same client
on the same button/key combinations on the same window.  A
modifiers of _A_n_y_M_o_d_i_f_i_e_r is equivalent to issuing the grab
request for all possible modifier combinations (including
the combination of no modifiers).  It is not required that
all modifiers specified have currently assigned KeyCodes.  A
button of _A_n_y_B_u_t_t_o_n is equivalent to issuing the request for
all possible buttons.  Otherwise, it is not required that
the specified button currently be assigned to a physical
button.

If some other client has already issued an _X_G_r_a_b_B_u_t_t_o_n with
the same button/key combination on the same window, a _B_a_d_A_c_­
_c_e_s_s error results.  When using _A_n_y_M_o_d_i_f_i_e_r or _A_n_y_B_u_t_t_o_n,
the request fails completely, and a _B_a_d_A_c_c_e_s_s error results
(no grabs are established) if there is a conflicting grab
for any combination.  _X_G_r_a_b_B_u_t_t_o_n has no effect on an active
grab.

_X_G_r_a_b_B_u_t_t_o_n can generate _B_a_d_C_u_r_s_o_r, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w
errors.


To ungrab a pointer button, use _X_U_n_g_r_a_b_B_u_t_t_o_n.





                             336633





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XUngrabButton(_d_i_s_p_l_a_y, _b_u_t_t_o_n, _m_o_d_i_f_i_e_r_s, _g_r_a_b___w_i_n_d_o_w)
      Display *_d_i_s_p_l_a_y;
      unsigned int _b_u_t_t_o_n;
      unsigned int _m_o_d_i_f_i_e_r_s;
      Window _g_r_a_b___w_i_n_d_o_w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_b_u_t_t_o_n    Specifies the pointer button that is to be
          released or _A_n_y_B_u_t_t_o_n.

_m_o_d_i_f_i_e_r_s Specifies the set of keymasks or _A_n_y_M_o_d_i_f_i_e_r.  The
          mask is the bitwise inclusive OR of the valid key­
          mask bits.

_g_r_a_b___w_i_n_d_o_w
          Specifies the grab window.
││__

The _X_U_n_g_r_a_b_B_u_t_t_o_n function releases the passive button/key
combination on the specified window if it was grabbed by
this client.  A modifiers of _A_n_y_M_o_d_i_f_i_e_r is equivalent to
issuing the ungrab request for all possible modifier combi­
nations, including the combination of no modifiers.  A but­
ton of _A_n_y_B_u_t_t_o_n is equivalent to issuing the request for
all possible buttons.  _X_U_n_g_r_a_b_B_u_t_t_o_n has no effect on an
active grab.

_X_U_n_g_r_a_b_B_u_t_t_o_n can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w errors.

1122..22..  KKeeyybbooaarrdd GGrraabbbbiinngg

Xlib provides functions that you can use to grab or ungrab
the keyboard as well as allow events.

For many functions in this section, you pass keymask bits.
The valid keymask bits are: _S_h_i_f_t_M_a_s_k, _L_o_c_k_M_a_s_k, _C_o_n_t_r_o_l_­
_M_a_s_k, _M_o_d_1_M_a_s_k, _M_o_d_2_M_a_s_k, _M_o_d_3_M_a_s_k, _M_o_d_4_M_a_s_k, and _M_o_d_5_M_a_s_k.


To grab the keyboard, use _X_G_r_a_b_K_e_y_b_o_a_r_d.














                             336644





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XGrabKeyboard(_d_i_s_p_l_a_y, _g_r_a_b___w_i_n_d_o_w, _o_w_n_e_r___e_v_e_n_t_s, _p_o_i_n_t_e_r___m_o_d_e, _k_e_y_b_o_a_r_d___m_o_d_e, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      Window _g_r_a_b___w_i_n_d_o_w;
      Bool _o_w_n_e_r___e_v_e_n_t_s;
      int _p_o_i_n_t_e_r___m_o_d_e, _k_e_y_b_o_a_r_d___m_o_d_e;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_r_a_b___w_i_n_d_o_w
          Specifies the grab window.

_o_w_n_e_r___e_v_e_n_t_s
          Specifies a Boolean value that indicates whether
          the keyboard events are to be reported as usual.

_p_o_i_n_t_e_r___m_o_d_e
          Specifies further processing of pointer events.
          You can pass _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

_k_e_y_b_o_a_r_d___m_o_d_e
          Specifies further processing of keyboard events.
          You can pass _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

The _X_G_r_a_b_K_e_y_b_o_a_r_d function actively grabs control of the
keyboard and generates _F_o_c_u_s_I_n and _F_o_c_u_s_O_u_t events.  Further
key events are reported only to the grabbing client.
_X_G_r_a_b_K_e_y_b_o_a_r_d overrides any active keyboard grab by this
client.  If owner_events is _F_a_l_s_e, all generated key events
are reported with respect to grab_window.  If owner_events
is _T_r_u_e and if a generated key event would normally be
reported to this client, it is reported normally; otherwise,
the event is reported with respect to the grab_window.  Both
_K_e_y_P_r_e_s_s and _K_e_y_R_e_l_e_a_s_e events are always reported, indepen­
dent of any event selection made by the client.

If the keyboard_mode argument is _G_r_a_b_M_o_d_e_A_s_y_n_c, keyboard
event processing continues as usual.  If the keyboard is
currently frozen by this client, then processing of keyboard
events is resumed.  If the keyboard_mode  argument is _G_r_a_b_­
_M_o_d_e_S_y_n_c, the state of the keyboard (as seen by client
applications) appears to freeze, and the X server generates
no further keyboard events until the grabbing client issues
a releasing _X_A_l_l_o_w_E_v_e_n_t_s call or until the keyboard grab is
released.  Actual keyboard changes are not lost while the
keyboard is frozen; they are simply queued in the server for
later processing.




                             336655





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


If pointer_mode is _G_r_a_b_M_o_d_e_A_s_y_n_c, pointer event processing
is unaffected by activation of the grab.  If pointer_mode is
_G_r_a_b_M_o_d_e_S_y_n_c, the state of the pointer (as seen by client
applications) appears to freeze, and the X server generates
no further pointer events until the grabbing client issues a
releasing _X_A_l_l_o_w_E_v_e_n_t_s call or until the keyboard grab is
released.  Actual pointer changes are not lost while the
pointer is frozen; they are simply queued in the server for
later processing.

If the keyboard is actively grabbed by some other client,
_X_G_r_a_b_K_e_y_b_o_a_r_d fails and returns _A_l_r_e_a_d_y_G_r_a_b_b_e_d.  If
grab_window is not viewable, it fails and returns _G_r_a_b_­
_N_o_t_V_i_e_w_a_b_l_e.  If the keyboard is frozen by an active grab of
another client, it fails and returns _G_r_a_b_F_r_o_z_e_n.  If the
specified time is earlier than the last‐keyboard‐grab time
or later than the current X server time, it fails and
returns _G_r_a_b_I_n_v_a_l_i_d_T_i_m_e.  Otherwise, the last‐keyboard‐grab
time is set to the specified time (_C_u_r_r_e_n_t_T_i_m_e is replaced
by the current X server time).

_X_G_r_a_b_K_e_y_b_o_a_r_d can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w errors.


To ungrab the keyboard, use _X_U_n_g_r_a_b_K_e_y_b_o_a_r_d.
__
││
XUngrabKeyboard(_d_i_s_p_l_a_y, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

The _X_U_n_g_r_a_b_K_e_y_b_o_a_r_d function releases the keyboard and any
queued events if this client has it actively grabbed from
either _X_G_r_a_b_K_e_y_b_o_a_r_d or _X_G_r_a_b_K_e_y.  _X_U_n_g_r_a_b_K_e_y_b_o_a_r_d does not
release the keyboard and any queued events if the specified
time is earlier than the last‐keyboard‐grab time or is later
than the current X server time.  It also generates _F_o_c_u_s_I_n
and _F_o_c_u_s_O_u_t events.  The X server automatically performs an
_U_n_g_r_a_b_K_e_y_b_o_a_r_d request if the event window for an active
keyboard grab becomes not viewable.


To passively grab a single key of the keyboard, use
_X_G_r_a_b_K_e_y.






                             336666





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XGrabKey(_d_i_s_p_l_a_y, _k_e_y_c_o_d_e, _m_o_d_i_f_i_e_r_s, _g_r_a_b___w_i_n_d_o_w, _o_w_n_e_r___e_v_e_n_t_s, _p_o_i_n_t_e_r___m_o_d_e,
             _k_e_y_b_o_a_r_d___m_o_d_e)
      Display *_d_i_s_p_l_a_y;
      int _k_e_y_c_o_d_e;
      unsigned int _m_o_d_i_f_i_e_r_s;
      Window _g_r_a_b___w_i_n_d_o_w;
      Bool _o_w_n_e_r___e_v_e_n_t_s;
      int _p_o_i_n_t_e_r___m_o_d_e, _k_e_y_b_o_a_r_d___m_o_d_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_k_e_y_c_o_d_e   Specifies the KeyCode or _A_n_y_K_e_y.

_m_o_d_i_f_i_e_r_s Specifies the set of keymasks or _A_n_y_M_o_d_i_f_i_e_r.  The
          mask is the bitwise inclusive OR of the valid key­
          mask bits.

_g_r_a_b___w_i_n_d_o_w
          Specifies the grab window.

_o_w_n_e_r___e_v_e_n_t_s
          Specifies a Boolean value that indicates whether
          the keyboard events are to be reported as usual.

_p_o_i_n_t_e_r___m_o_d_e
          Specifies further processing of pointer events.
          You can pass _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

_k_e_y_b_o_a_r_d___m_o_d_e
          Specifies further processing of keyboard events.
          You can pass _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.
││__

The _X_G_r_a_b_K_e_y function establishes a passive grab on the key­
board.  In the future, the keyboard is actively grabbed (as
for _X_G_r_a_b_K_e_y_b_o_a_r_d), the last‐keyboard‐grab time is set to
the time at which the key was pressed (as transmitted in the
_K_e_y_P_r_e_s_s event), and the _K_e_y_P_r_e_s_s event is reported if all
of the following conditions are true:

⋅    The keyboard is not grabbed and the specified key
     (which can itself be a modifier key) is logically
     pressed when the specified modifier keys are logically
     down, and no other modifier keys are logically down.

⋅    Either the grab_window is an ancestor of (or is) the
     focus window, or the grab_window is a descendant of the
     focus window and contains the pointer.

⋅    A passive grab on the same key combination does not
     exist on any ancestor of grab_window.




                             336677





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The interpretation of the remaining arguments is as for
_X_G_r_a_b_K_e_y_b_o_a_r_d.  The active grab is terminated automatically
when the logical state of the keyboard has the specified key
released (independent of the logical state of the modifier
keys).

Note that the logical state of a device (as seen by client
applications) may lag the physical state if device event
processing is frozen.

A modifiers argument of _A_n_y_M_o_d_i_f_i_e_r is equivalent to issuing
the request for all possible modifier combinations (includ­
ing the combination of no modifiers).  It is not required
that all modifiers specified have currently assigned Key­
Codes.  A keycode argument of _A_n_y_K_e_y is equivalent to issu­
ing the request for all possible KeyCodes.  Otherwise, the
specified keycode must be in the range specified by min_key­
code and max_keycode in the connection setup, or a _B_a_d_V_a_l_u_e
error results.

If some other client has issued a _X_G_r_a_b_K_e_y with the same key
combination on the same window, a _B_a_d_A_c_c_e_s_s error results.
When using _A_n_y_M_o_d_i_f_i_e_r or _A_n_y_K_e_y, the request fails com­
pletely, and a _B_a_d_A_c_c_e_s_s error results (no grabs are estab­
lished) if there is a conflicting grab for any combination.

_X_G_r_a_b_K_e_y can generate _B_a_d_A_c_c_e_s_s, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w
errors.


To ungrab a key, use _X_U_n_g_r_a_b_K_e_y.
__
││
XUngrabKey(_d_i_s_p_l_a_y, _k_e_y_c_o_d_e, _m_o_d_i_f_i_e_r_s, _g_r_a_b___w_i_n_d_o_w)
      Display *_d_i_s_p_l_a_y;
      int _k_e_y_c_o_d_e;
      unsigned int _m_o_d_i_f_i_e_r_s;
      Window _g_r_a_b___w_i_n_d_o_w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_k_e_y_c_o_d_e   Specifies the KeyCode or _A_n_y_K_e_y.

_m_o_d_i_f_i_e_r_s Specifies the set of keymasks or _A_n_y_M_o_d_i_f_i_e_r.  The
          mask is the bitwise inclusive OR of the valid key­
          mask bits.

_g_r_a_b___w_i_n_d_o_w
          Specifies the grab window.
││__

The _X_U_n_g_r_a_b_K_e_y function releases the key combination on the
specified window if it was grabbed by this client.  It has



                             336688





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


no effect on an active grab.  A modifiers of _A_n_y_M_o_d_i_f_i_e_r is
equivalent to issuing the request for all possible modifier
combinations (including the combination of no modifiers).  A
keycode argument of _A_n_y_K_e_y is equivalent to issuing the
request for all possible key codes.

_X_U_n_g_r_a_b_K_e_y can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w errors.

1122..33..  RReessuummiinngg EEvveenntt PPrroocceessssiinngg

The previous sections discussed grab mechanisms with which
processing of events by the server can be temporarily sus­
pended.  This section describes the mechanism for resuming
event processing.


To allow further events to be processed when the device has
been frozen, use _X_A_l_l_o_w_E_v_e_n_t_s.
__
││
XAllowEvents(_d_i_s_p_l_a_y, _e_v_e_n_t___m_o_d_e, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      int _e_v_e_n_t___m_o_d_e;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___m_o_d_e
          Specifies the event mode.  You can pass _A_s_y_n_c_­
          _P_o_i_n_t_e_r, _S_y_n_c_P_o_i_n_t_e_r, _A_s_y_n_c_K_e_y_b_o_a_r_d, _S_y_n_c_K_e_y_b_o_a_r_d,
          _R_e_p_l_a_y_P_o_i_n_t_e_r, _R_e_p_l_a_y_K_e_y_b_o_a_r_d, _A_s_y_n_c_B_o_t_h, or
          _S_y_n_c_B_o_t_h.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

The _X_A_l_l_o_w_E_v_e_n_t_s function releases some queued events if the
client has caused a device to freeze.  It has no effect if
the specified time is earlier than the last‐grab time of the
most recent active grab for the client or if the specified
time is later than the current X server time.  Depending on
the event_mode argument, the following occurs:

_A_s_y_n_c_P_o_i_n_t_e_r   If the pointer is frozen by the client,
               pointer event processing continues as usual.
               If the pointer is frozen twice by the client
               on behalf of two separate grabs, _A_s_y_n_c_P_o_i_n_t_e_r
               thaws for both.  _A_s_y_n_c_P_o_i_n_t_e_r has no effect
               if the pointer is not frozen by the client,
               but the pointer need not be grabbed by the
               client.




                             336699





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_S_y_n_c_P_o_i_n_t_e_r    If the pointer is frozen and actively grabbed
               by the client, pointer event processing con­
               tinues as usual until the next _B_u_t_t_o_n_P_r_e_s_s or
               _B_u_t_t_o_n_R_e_l_e_a_s_e event is reported to the
               client.  At this time, the pointer again
               appears to freeze.  However, if the reported
               event causes the pointer grab to be released,
               the pointer does not freeze.  _S_y_n_c_P_o_i_n_t_e_r has
               no effect if the pointer is not frozen by the
               client or if the pointer is not grabbed by
               the client.
_R_e_p_l_a_y_­        If the pointer is actively grabbed by the
_P_o_i_n_t_e_r        client and is frozen as the result of an
               event having been sent to the client (either
               from the activation of an _X_G_r_a_b_B_u_t_t_o_n or from
               a previous _X_A_l_l_o_w_E_v_e_n_t_s with mode _S_y_n_c_P_o_i_n_t_e_r
               but not from an _X_G_r_a_b_P_o_i_n_t_e_r), the pointer
               grab is released and that event is completely
               reprocessed.  This time, however, the func­
               tion ignores any passive grabs at or above
               (toward the root of) the grab_window of the
               grab just released.  The request has no
               effect if the pointer is not grabbed by the
               client or if the pointer is not frozen as the
               result of an event.
_A_s_y_n_c_K_e_y_­      If the keyboard is frozen by the client, key­
_b_o_a_r_d          board event processing continues as usual.
               If the keyboard is frozen twice by the client
               on behalf of two separate grabs, _A_s_y_n_c_K_e_y_­
               _b_o_a_r_d thaws for both.  _A_s_y_n_c_K_e_y_b_o_a_r_d has no
               effect if the keyboard is not frozen by the
               client, but the keyboard need not be grabbed
               by the client.
_S_y_n_c_K_e_y_b_o_a_r_d   If the keyboard is frozen and actively
               grabbed by the client, keyboard event pro­
               cessing continues as usual until the next
               _K_e_y_P_r_e_s_s or _K_e_y_R_e_l_e_a_s_e event is reported to
               the client.  At this time, the keyboard again
               appears to freeze.  However, if the reported
               event causes the keyboard grab to be
               released, the keyboard does not freeze.
               _S_y_n_c_K_e_y_b_o_a_r_d has no effect if the keyboard is
               not frozen by the client or if the keyboard
               is not grabbed by the client.













                             337700





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_R_e_p_l_a_y_K_e_y_­     If the keyboard is actively grabbed by the
_b_o_a_r_d          client and is frozen as the result of an
               event having been sent to the client (either
               from the activation of an _X_G_r_a_b_K_e_y or from a
               previous _X_A_l_l_o_w_E_v_e_n_t_s with mode _S_y_n_c_K_e_y_b_o_a_r_d
               but not from an _X_G_r_a_b_K_e_y_b_o_a_r_d), the keyboard
               grab is released and that event is completely
               reprocessed.  This time, however, the func­
               tion ignores any passive grabs at or above
               (toward the root of) the grab_window of the
               grab just released.  The request has no
               effect if the keyboard is not grabbed by the
               client or if the keyboard is not frozen as
               the result of an event.
_S_y_n_c_B_o_t_h       If both pointer and keyboard are frozen by
               the client, event processing for both devices
               continues as usual until the next _B_u_t_t_o_n_­
               _P_r_e_s_s, _B_u_t_t_o_n_R_e_l_e_a_s_e, _K_e_y_P_r_e_s_s, or _K_e_y_R_e_l_e_a_s_e
               event is reported to the client for a grabbed
               device (button event for the pointer, key
               event for the keyboard), at which time the
               devices again appear to freeze.  However, if
               the reported event causes the grab to be
               released, then the devices do not freeze (but
               if the other device is still grabbed, then a
               subsequent event for it will still cause both
               devices to freeze).  _S_y_n_c_B_o_t_h has no effect
               unless both pointer and keyboard are frozen
               by the client.  If the pointer or keyboard is
               frozen twice by the client on behalf of two
               separate grabs, _S_y_n_c_B_o_t_h thaws for both (but
               a subsequent freeze for _S_y_n_c_B_o_t_h will only
               freeze each device once).
_A_s_y_n_c_B_o_t_h      If the pointer and the keyboard are frozen by
               the client, event processing for both devices
               continues as usual.  If a device is frozen
               twice by the client on behalf of two separate
               grabs, _A_s_y_n_c_B_o_t_h thaws for both.  _A_s_y_n_c_B_o_t_h
               has no effect unless both pointer and key­
               board are frozen by the client.


_A_s_y_n_c_P_o_i_n_t_e_r, _S_y_n_c_P_o_i_n_t_e_r, and _R_e_p_l_a_y_P_o_i_n_t_e_r have no effect
on the processing of keyboard events.  _A_s_y_n_c_K_e_y_b_o_a_r_d, _S_y_n_c_K_­
_e_y_b_o_a_r_d, and _R_e_p_l_a_y_K_e_y_b_o_a_r_d have no effect on the processing
of pointer events.  It is possible for both a pointer grab
and a keyboard grab (by the same or different clients) to be
active simultaneously.  If a device is frozen on behalf of
either grab, no event processing is performed for the
device.  It is possible for a single device to be frozen
because of both grabs.  In this case, the freeze must be
released on behalf of both grabs before events can again be
processed.  If a device is frozen twice by a single client,
then a single _A_l_l_o_w_E_v_e_n_t_s releases both.



                             337711





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_A_l_l_o_w_E_v_e_n_t_s can generate a _B_a_d_V_a_l_u_e error.

1122..44..  MMoovviinngg tthhee PPooiinntteerr

Although movement of the pointer normally should be left to
the control of the end user, sometimes it is necessary to
move the pointer to a new position under program control.


To move the pointer to an arbitrary point in a window, use
_X_W_a_r_p_P_o_i_n_t_e_r.
__
││
XWarpPointer(_d_i_s_p_l_a_y, _s_r_c___w, _d_e_s_t___w, _s_r_c___x, _s_r_c___y, _s_r_c___w_i_d_t_h, _s_r_c___h_e_i_g_h_t, _d_e_s_t___x,
                _d_e_s_t___y)
        Display *_d_i_s_p_l_a_y;
        Window _s_r_c___w, _d_e_s_t___w;
        int _s_r_c___x, _s_r_c___y;
        unsigned int _s_r_c___w_i_d_t_h, _s_r_c___h_e_i_g_h_t;
        int _d_e_s_t___x, _d_e_s_t___y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_r_c___w     Specifies the source window or _N_o_n_e.

_d_e_s_t___w    Specifies the destination window or _N_o_n_e.

_s_r_c___x
_s_r_c___y
_s_r_c___w_i_d_t_h
_s_r_c___h_e_i_g_h_t
          Specify a rectangle in the source window.

_d_e_s_t___x
_d_e_s_t___y    Specify the x and y coordinates within the desti­
          nation window.
││__

If dest_w is _N_o_n_e, _X_W_a_r_p_P_o_i_n_t_e_r moves the pointer by the
offsets (dest_x, dest_y) relative to the current position of
the pointer.  If dest_w is a window, _X_W_a_r_p_P_o_i_n_t_e_r moves the
pointer to the offsets (dest_x, dest_y) relative to the ori­
gin of dest_w.  However, if src_w is a window, the move only
takes place if the window src_w contains the pointer and if
the specified rectangle of src_w contains the pointer.

The src_x and src_y coordinates are relative to the origin
of src_w.  If src_height is zero, it is replaced with the
current height of src_w minus src_y.  If src_width is zero,
it is replaced with the current width of src_w minus src_x.

There is seldom any reason for calling this function.  The
pointer should normally be left to the user.  If you do use



                             337722





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


this function, however, it generates events just as if the
user had instantaneously moved the pointer from one position
to another.  Note that you cannot use _X_W_a_r_p_P_o_i_n_t_e_r to move
the pointer outside the confine_to window of an active
pointer grab.  An attempt to do so will only move the
pointer as far as the closest edge of the confine_to window.

_X_W_a_r_p_P_o_i_n_t_e_r can generate a _B_a_d_W_i_n_d_o_w error.

1122..55..  CCoonnttrroolllliinngg IInnppuutt FFooccuuss

Xlib provides functions that you can use to set and get the
input focus.  The input focus is a shared resource, and
cooperation among clients is required for correct interac­
tion.  See the _I_n_t_e_r_‐_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l
for input focus policy.


To set the input focus, use _X_S_e_t_I_n_p_u_t_F_o_c_u_s.
__
││
XSetInputFocus(_d_i_s_p_l_a_y, _f_o_c_u_s, _r_e_v_e_r_t___t_o, _t_i_m_e)
      Display *_d_i_s_p_l_a_y;
      Window _f_o_c_u_s;
      int _r_e_v_e_r_t___t_o;
      Time _t_i_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_o_c_u_s     Specifies the window, _P_o_i_n_t_e_r_R_o_o_t, or _N_o_n_e.

_r_e_v_e_r_t___t_o Specifies where the input focus reverts to if the
          window becomes not viewable.  You can pass _R_e_v_e_r_t_­
          _T_o_P_a_r_e_n_t, _R_e_v_e_r_t_T_o_P_o_i_n_t_e_r_R_o_o_t, or _R_e_v_e_r_t_T_o_N_o_n_e.

_t_i_m_e      Specifies the time.  You can pass either a times­
          tamp or _C_u_r_r_e_n_t_T_i_m_e.
││__

The _X_S_e_t_I_n_p_u_t_F_o_c_u_s function changes the input focus and the
last‐focus‐change time.  It has no effect if the specified
time is earlier than the current last‐focus‐change time or
is later than the current X server time.  Otherwise, the
last‐focus‐change time is set to the specified time (_C_u_r_­
_r_e_n_t_T_i_m_e is replaced by the current X server time).  _X_S_e_t_­
_I_n_p_u_t_F_o_c_u_s causes the X server to generate _F_o_c_u_s_I_n and _F_o_c_u_­
_s_O_u_t events.

Depending on the focus argument, the following occurs:

⋅    If focus is _N_o_n_e, all keyboard events are discarded
     until a new focus window is set, and the revert_to
     argument is ignored.



                             337733





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    If focus is a window, it becomes the keyboard’s focus
     window.  If a generated keyboard event would normally
     be reported to this window or one of its inferiors, the
     event is reported as usual.  Otherwise, the event is
     reported relative to the focus window.

⋅    If focus is _P_o_i_n_t_e_r_R_o_o_t, the focus window is dynami­
     cally taken to be the root window of whatever screen
     the pointer is on at each keyboard event.  In this
     case, the revert_to argument is ignored.

The specified focus window must be viewable at the time
_X_S_e_t_I_n_p_u_t_F_o_c_u_s is called, or a _B_a_d_M_a_t_c_h error results.  If
the focus window later becomes not viewable, the X server
evaluates the revert_to argument to determine the new focus
window as follows:

⋅    If revert_to is _R_e_v_e_r_t_T_o_P_a_r_e_n_t, the focus reverts to
     the parent (or the closest viewable ancestor), and the
     new revert_to value is taken to be _R_e_v_e_r_t_T_o_N_o_n_e.

⋅    If revert_to is _R_e_v_e_r_t_T_o_P_o_i_n_t_e_r_R_o_o_t or _R_e_v_e_r_t_T_o_N_o_n_e,
     the focus reverts to _P_o_i_n_t_e_r_R_o_o_t or _N_o_n_e, respectively.
     When the focus reverts, the X server generates _F_o_c_u_s_I_n
     and _F_o_c_u_s_O_u_t events, but the last‐focus‐change time is
     not affected.

_X_S_e_t_I_n_p_u_t_F_o_c_u_s can generate _B_a_d_M_a_t_c_h, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_­
_d_o_w errors.


To obtain the current input focus, use _X_G_e_t_I_n_p_u_t_F_o_c_u_s.
__
││
XGetInputFocus(_d_i_s_p_l_a_y, _f_o_c_u_s___r_e_t_u_r_n, _r_e_v_e_r_t___t_o___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window *_f_o_c_u_s___r_e_t_u_r_n;
      int *_r_e_v_e_r_t___t_o___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_o_c_u_s___r_e_t_u_r_n
          Returns the focus window, _P_o_i_n_t_e_r_R_o_o_t, or _N_o_n_e.

_r_e_v_e_r_t___t_o___r_e_t_u_r_n
          Returns the current focus state (_R_e_v_e_r_t_T_o_P_a_r_e_n_t,
          _R_e_v_e_r_t_T_o_P_o_i_n_t_e_r_R_o_o_t, or _R_e_v_e_r_t_T_o_N_o_n_e).
││__

The _X_G_e_t_I_n_p_u_t_F_o_c_u_s function returns the focus window and the
current focus state.





                             337744





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1122..66..  MMaanniippuullaattiinngg tthhee KKeeyybbooaarrdd aanndd PPooiinntteerr SSeettttiinnggss

Xlib provides functions that you can use to change the key­
board control, obtain a list of the auto‐repeat keys, turn
keyboard auto‐repeat on or off, ring the bell, set or obtain
the pointer button or keyboard mapping, and obtain a bit
vector for the keyboard.

This section discusses the user‐preference options of bell,
key click, pointer behavior, and so on.  The default values
for many of these options are server dependent.  Not all
implementations will actually be able to control all of
these parameters.

The _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l function changes control of a
keyboard and operates on a _X_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l structure:
__
││
/* Mask bits for ChangeKeyboardControl */

#define   _K_B_K_e_y_C_l_i_c_k_P_e_r_c_e_n_t           (1L<<0)
#define   _K_B_B_e_l_l_P_e_r_c_e_n_t               (1L<<1)
#define   _K_B_B_e_l_l_P_i_t_c_h                 (1L<<2)
#define   _K_B_B_e_l_l_D_u_r_a_t_i_o_n              (1L<<3)
#define   _K_B_L_e_d                       (1L<<4)
#define   _K_B_L_e_d_M_o_d_e                   (1L<<5)
#define   _K_B_K_e_y                       (1L<<6)
#define   _K_B_A_u_t_o_R_e_p_e_a_t_M_o_d_e            (1L<<7)


/* Values */

typedef struct {
     int key_click_percent;
     int bell_percent;
     int bell_pitch;
     int bell_duration;
     int led;
     int led_mode;       /* LedModeOn, LedModeOff */
     int key;
     int auto_repeat_mode;/* AutoRepeatModeOff, AutoRepeatModeOn,
                            AutoRepeatModeDefault */
} XKeyboardControl;

││__

The key_click_percent member sets the volume for key clicks
between 0 (off) and 100 (loud) inclusive, if possible.  A
setting of −1 restores the default.  Other negative values
generate a _B_a_d_V_a_l_u_e error.

The bell_percent sets the base volume for the bell between 0
(off) and 100 (loud) inclusive, if possible.  A setting of
−1 restores the default.  Other negative values generate a



                             337755





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_B_a_d_V_a_l_u_e error.  The bell_pitch member sets the pitch (spec­
ified in Hz) of the bell, if possible.  A setting of −1
restores the default.  Other negative values generate a _B_a_d_­
_V_a_l_u_e error.  The bell_duration member sets the duration of
the bell specified in milliseconds, if possible.  A setting
of −1 restores the default.  Other negative values generate
a _B_a_d_V_a_l_u_e error.

If both the led_mode and led members are specified, the
state of that LED is changed, if possible.  The led_mode
member can be set to _L_e_d_M_o_d_e_O_n or _L_e_d_M_o_d_e_O_f_f.  If only
led_mode is specified, the state of all LEDs are changed, if
possible.  At most 32 LEDs numbered from one are supported.
No standard interpretation of LEDs is defined.  If led is
specified without led_mode, a _B_a_d_M_a_t_c_h error results.

If both the auto_repeat_mode and key members are specified,
the auto_repeat_mode of that key is changed (according to
_A_u_t_o_R_e_p_e_a_t_M_o_d_e_O_n, _A_u_t_o_R_e_p_e_a_t_M_o_d_e_O_f_f, or _A_u_t_o_R_e_p_e_a_t_M_o_d_e_D_e_­
_f_a_u_l_t), if possible.  If only auto_repeat_mode is specified,
the global auto_repeat_mode for the entire keyboard is
changed, if possible, and does not affect the per‐key set­
tings.  If a key is specified without an auto_repeat_mode, a
_B_a_d_M_a_t_c_h error results.  Each key has an individual mode of
whether or not it should auto‐repeat and a default setting
for the mode.  In addition, there is a global mode of
whether auto‐repeat should be enabled or not and a default
setting for that mode.  When global mode is _A_u_t_o_R_e_p_e_a_t_M_o_d_­
_e_O_n, keys should obey their individual auto‐repeat modes.
When global mode is _A_u_t_o_R_e_p_e_a_t_M_o_d_e_O_f_f, no keys should auto‐
repeat.  An auto‐repeating key generates alternating _K_e_y_­
_P_r_e_s_s and _K_e_y_R_e_l_e_a_s_e events.  When a key is used as a modi­
fier, it is desirable for the key not to auto‐repeat,
regardless of its auto‐repeat setting.

A bell generator connected with the console but not directly
on a keyboard is treated as if it were part of the keyboard.
The order in which controls are verified and altered is
server‐dependent.  If an error is generated, a subset of the
controls may have been altered.

















                             337766





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XChangeKeyboardControl(_d_i_s_p_l_a_y, _v_a_l_u_e___m_a_s_k, _v_a_l_u_e_s)
      Display *_d_i_s_p_l_a_y;
      unsigned long _v_a_l_u_e___m_a_s_k;
      XKeyboardControl *_v_a_l_u_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_v_a_l_u_e___m_a_s_k
          Specifies which controls to change.  This mask is
          the bitwise inclusive OR of the valid control mask
          bits.

_v_a_l_u_e_s    Specifies one value for each bit set to 1 in the
          mask.
││__

The _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l function controls the keyboard
characteristics defined by the _X_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l structure.
The value_mask argument specifies which values are to be
changed.

_X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l can generate _B_a_d_M_a_t_c_h and _B_a_d_V_a_l_u_e
errors.


To obtain the current control values for the keyboard, use
_X_G_e_t_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l.
__
││
XGetKeyboardControl(_d_i_s_p_l_a_y, _v_a_l_u_e_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      XKeyboardState *_v_a_l_u_e_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_v_a_l_u_e_s___r_e_t_u_r_n
          Returns the current keyboard controls in the spec­
          ified _X_K_e_y_b_o_a_r_d_S_t_a_t_e structure.
││__

The _X_G_e_t_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l function returns the current control
values for the keyboard to the _X_K_e_y_b_o_a_r_d_S_t_a_t_e structure.












                             337777





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct {
     int key_click_percent;
     int bell_percent;
     unsigned int bell_pitch, bell_duration;
     unsigned long led_mask;
     int global_auto_repeat;
     char auto_repeats[32];
} XKeyboardState;

││__

For the LEDs, the least significant bit of led_mask corre­
sponds to LED one, and each bit set to 1 in led_mask indi­
cates an LED that is lit.  The global_auto_repeat member can
be set to _A_u_t_o_R_e_p_e_a_t_M_o_d_e_O_n or _A_u_t_o_R_e_p_e_a_t_M_o_d_e_O_f_f.  The
auto_repeats member is a bit vector.  Each bit set to 1
indicates that auto‐repeat is enabled for the corresponding
key.  The vector is represented as 32 bytes.  Byte N (from
0) contains the bits for keys 8N to 8N + 7 with the least
significant bit in the byte representing key 8N.


To turn on keyboard auto‐repeat, use _X_A_u_t_o_R_e_p_e_a_t_O_n.
__
││
XAutoRepeatOn(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_A_u_t_o_R_e_p_e_a_t_O_n function turns on auto‐repeat for the key­
board on the specified display.


To turn off keyboard auto‐repeat, use _X_A_u_t_o_R_e_p_e_a_t_O_f_f.
__
││
XAutoRepeatOff(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_A_u_t_o_R_e_p_e_a_t_O_f_f function turns off auto‐repeat for the
keyboard on the specified display.


To ring the bell, use _X_B_e_l_l.





                             337788





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XBell(_d_i_s_p_l_a_y, _p_e_r_c_e_n_t)
      Display *_d_i_s_p_l_a_y;
      int _p_e_r_c_e_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_e_r_c_e_n_t   Specifies the volume for the bell, which can range
          from −100 to 100 inclusive.
││__

The _X_B_e_l_l function rings the bell on the keyboard on the
specified display, if possible.  The specified volume is
relative to the base volume for the keyboard.  If the value
for the percent argument is not in the range −100 to 100
inclusive, a _B_a_d_V_a_l_u_e error results.  The volume at which
the bell rings when the percent argument is nonnegative is:

     base − [(base * percent) / 100] + percent

The volume at which the bell rings when the percent argument
is negative is:

     base + [(base * percent) / 100]

To change the base volume of the bell, use _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_­
_C_o_n_t_r_o_l.

_X_B_e_l_l can generate a _B_a_d_V_a_l_u_e error.


To obtain a bit vector that describes the state of the key­
board, use _X_Q_u_e_r_y_K_e_y_m_a_p.
__
││
XQueryKeymap(_d_i_s_p_l_a_y, _k_e_y_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      char _k_e_y_s___r_e_t_u_r_n[32];


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_k_e_y_s___r_e_t_u_r_n
          Returns an array of bytes that identifies which
          keys are pressed down.  Each bit represents one
          key of the keyboard.
││__

The _X_Q_u_e_r_y_K_e_y_m_a_p function returns a bit vector for the logi­
cal state of the keyboard, where each bit set to 1 indicates
that the corresponding key is currently pressed down.  The
vector is represented as 32 bytes.  Byte N (from 0) contains
the bits for keys 8N to 8N + 7 with the least significant



                             337799





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


bit in the byte representing key 8N.

Note that the logical state of a device (as seen by client
applications) may lag the physical state if device event
processing is frozen.


To set the mapping of the pointer buttons, use _X_S_e_t_P_o_i_n_t_­
_e_r_M_a_p_p_i_n_g.
__
││
int XSetPointerMapping(_d_i_s_p_l_a_y, _m_a_p, _n_m_a_p)
      Display *_d_i_s_p_l_a_y;
      unsigned char _m_a_p[];
      int _n_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_m_a_p       Specifies the mapping list.

_n_m_a_p      Specifies the number of items in the mapping list.
││__

The _X_S_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g function sets the mapping of the
pointer.  If it succeeds, the X server generates a _M_a_p_p_i_n_g_­
_N_o_t_i_f_y event, and _X_S_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g returns _M_a_p_p_i_n_g_S_u_c_c_e_s_s.
Element map[i] defines the logical button number for the
physical button i+1.  The length of the list must be the
same as _X_G_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g would return, or a _B_a_d_V_a_l_u_e error
results.  A zero element disables a button, and elements are
not restricted in value by the number of physical buttons.
However, no two elements can have the same nonzero value, or
a _B_a_d_V_a_l_u_e error results.  If any of the buttons to be
altered are logically in the down state, _X_S_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g
returns _M_a_p_p_i_n_g_B_u_s_y, and the mapping is not changed.

_X_S_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g can generate a _B_a_d_V_a_l_u_e error.


To get the pointer mapping, use _X_G_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g.
















                             338800





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XGetPointerMapping(_d_i_s_p_l_a_y, _m_a_p___r_e_t_u_r_n, _n_m_a_p)
      Display *_d_i_s_p_l_a_y;
      unsigned char _m_a_p___r_e_t_u_r_n[];
      int _n_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_m_a_p___r_e_t_u_r_n
          Returns the mapping list.

_n_m_a_p      Specifies the number of items in the mapping list.
││__

The _X_G_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g function returns the current mapping
of the pointer.  Pointer buttons are numbered starting from
one.  _X_G_e_t_P_o_i_n_t_e_r_M_a_p_p_i_n_g returns the number of physical but­
tons actually on the pointer.  The nominal mapping for a
pointer is map[i]=i+1.  The nmap argument specifies the
length of the array where the pointer mapping is returned,
and only the first nmap elements are returned in map_return.


To control the pointer’s interactive feel, use _X_C_h_a_n_g_e_P_o_i_n_t_­
_e_r_C_o_n_t_r_o_l.































                             338811





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XChangePointerControl(_d_i_s_p_l_a_y, _d_o___a_c_c_e_l, _d_o___t_h_r_e_s_h_o_l_d, _a_c_c_e_l___n_u_m_e_r_a_t_o_r,
                        _a_c_c_e_l___d_e_n_o_m_i_n_a_t_o_r, _t_h_r_e_s_h_o_l_d)
      Display *_d_i_s_p_l_a_y;
      Bool _d_o___a_c_c_e_l, _d_o___t_h_r_e_s_h_o_l_d;
      int _a_c_c_e_l___n_u_m_e_r_a_t_o_r, _a_c_c_e_l___d_e_n_o_m_i_n_a_t_o_r;
      int _t_h_r_e_s_h_o_l_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_o___a_c_c_e_l  Specifies a Boolean value that controls whether
          the values for the accel_numerator or accel_denom­
          inator are used.

_d_o___t_h_r_e_s_h_o_l_d
          Specifies a Boolean value that controls whether
          the value for the threshold is used.

_a_c_c_e_l___n_u_m_e_r_a_t_o_r
          Specifies the numerator for the acceleration mul­
          tiplier.

_a_c_c_e_l___d_e_n_o_m_i_n_a_t_o_r
          Specifies the denominator for the acceleration
          multiplier.

_t_h_r_e_s_h_o_l_d Specifies the acceleration threshold.
││__

The _X_C_h_a_n_g_e_P_o_i_n_t_e_r_C_o_n_t_r_o_l function defines how the pointing
device moves.  The acceleration, expressed as a fraction, is
a multiplier for movement.  For example, specifying 3/1
means the pointer moves three times as fast as normal.  The
fraction may be rounded arbitrarily by the X server.  Accel­
eration only takes effect if the pointer moves more than
threshold pixels at once and only applies to the amount
beyond the value in the threshold argument.  Setting a value
to −1 restores the default.  The values of the do_accel and
do_threshold arguments must be _T_r_u_e for the pointer values
to be set, or the parameters are unchanged.  Negative values
(other than −1) generate a _B_a_d_V_a_l_u_e error, as does a zero
value for the accel_denominator argument.

_X_C_h_a_n_g_e_P_o_i_n_t_e_r_C_o_n_t_r_o_l can generate a _B_a_d_V_a_l_u_e error.


To get the current pointer parameters, use _X_G_e_t_P_o_i_n_t_e_r_C_o_n_­
_t_r_o_l.








                             338822





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XGetPointerControl(_d_i_s_p_l_a_y, _a_c_c_e_l___n_u_m_e_r_a_t_o_r___r_e_t_u_r_n, _a_c_c_e_l___d_e_n_o_m_i_n_a_t_o_r___r_e_t_u_r_n,
                       _t_h_r_e_s_h_o_l_d___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int *_a_c_c_e_l___n_u_m_e_r_a_t_o_r___r_e_t_u_r_n, *_a_c_c_e_l___d_e_n_o_m_i_n_a_t_o_r___r_e_t_u_r_n;
      int *_t_h_r_e_s_h_o_l_d___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_a_c_c_e_l___n_u_m_e_r_a_t_o_r___r_e_t_u_r_n
          Returns the numerator for the acceleration multi­
          plier.

_a_c_c_e_l___d_e_n_o_m_i_n_a_t_o_r___r_e_t_u_r_n
          Returns the denominator for the acceleration mul­
          tiplier.

_t_h_r_e_s_h_o_l_d___r_e_t_u_r_n
          Returns the acceleration threshold.
││__

The _X_G_e_t_P_o_i_n_t_e_r_C_o_n_t_r_o_l function returns the pointer’s cur­
rent acceleration multiplier and acceleration threshold.

1122..77..  MMaanniippuullaattiinngg tthhee KKeeyybbooaarrdd EEnnccooddiinngg

A KeyCode represents a physical (or logical) key.  KeyCodes
lie in the inclusive range [8,255].  A KeyCode value carries
no intrinsic information, although server implementors may
attempt to encode geometry (for example, matrix) information
in some fashion so that it can be interpreted in a server‐
dependent fashion.  The mapping between keys and KeyCodes
cannot be changed.

A KeySym is an encoding of a symbol on the cap of a key.
The set of defined KeySyms includes the ISO Latin character
sets (1−4), Katakana, Arabic, Cyrillic, Greek, Technical,
Special, Publishing, APL, Hebrew, Thai, Korean and a miscel­
lany of keys found on keyboards (Return, Help, Tab, and so
on).  To the extent possible, these sets are derived from
international standards.  In areas where no standards exist,
some of these sets are derived from Digital Equipment Corpo­
ration standards.  The list of defined symbols can be found
in <_X_1_1_/_k_e_y_s_y_m_d_e_f_._h>.  Unfortunately, some C preprocessors
have limits on the number of defined symbols.  If you must
use KeySyms not in the Latin 1−4, Greek, and miscellaneous
classes, you may have to define a symbol for those sets.
Most applications usually only include <_X_1_1_/_k_e_y_s_y_m_._h>, which
defines symbols for ISO Latin 1−4, Greek, and miscellaneous.

A list of KeySyms is associated with each KeyCode.  The list
is intended to convey the set of symbols on the correspond­
ing key.  If the list (ignoring trailing _N_o_S_y_m_b_o_l entries)



                             338833





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


is a single KeySym ‘‘_K’’, then the list is treated as if it
were the list ‘‘_K NoSymbol _K NoSymbol’’.  If the list
(ignoring trailing _N_o_S_y_m_b_o_l entries) is a pair of KeySyms
‘‘_K_1 _K_2’’, then the list is treated as if it were the list
‘‘_K_1 _K_2 _K_1 _K_2’’.  If the list (ignoring trailing _N_o_S_y_m_b_o_l
entries) is a triple of KeySyms ‘‘_K_1 _K_2 _K_3’’, then the list
is treated as if it were the list ‘‘_K_1 _K_2 _K_3 NoSymbol’’.
When an explicit ‘‘void’’ element is desired in the list,
the value _V_o_i_d_S_y_m_b_o_l can be used.

The first four elements of the list are split into two
groups of KeySyms.  Group 1 contains the first and second
KeySyms; Group 2 contains the third and fourth KeySyms.
Within each group, if the second element of the group is
_N_o_S_y_m_b_o_l, then the group should be treated as if the second
element were the same as the first element, except when the
first element is an alphabetic KeySym ‘‘_K’’ for which both
lowercase and uppercase forms are defined.  In that case,
the group should be treated as if the first element were the
lowercase form of ‘‘_K’’ and the second element were the
uppercase form of ‘‘_K’’.

The standard rules for obtaining a KeySym from a _K_e_y_P_r_e_s_s
event make use of only the Group 1 and Group 2 KeySyms; no
interpretation of other KeySyms in the list is given.  Which
group to use is determined by the modifier state.  Switching
between groups is controlled by the KeySym named MODE
SWITCH, by attaching that KeySym to some KeyCode and attach­
ing that KeyCode to any one of the modifiers _M_o_d_1 through
_M_o_d_5.  This modifier is called the _g_r_o_u_p _m_o_d_i_f_i_e_r.  For any
KeyCode, Group 1 is used when the group modifier is off, and
Group 2 is used when the group modifier is on.

The _L_o_c_k modifier is interpreted as CapsLock when the KeySym
named XK_Caps_Lock is attached to some KeyCode and that Key­
Code is attached to the _L_o_c_k modifier.  The _L_o_c_k modifier is
interpreted as ShiftLock when the KeySym named XK_Shift_Lock
is attached to some KeyCode and that KeyCode is attached to
the _L_o_c_k modifier.  If the _L_o_c_k modifier could be inter­
preted as both CapsLock and ShiftLock, the CapsLock inter­
pretation is used.

The operation of keypad keys is controlled by the KeySym
named XK_Num_Lock, by attaching that KeySym to some KeyCode
and attaching that KeyCode to any one of the modifiers _M_o_d_1
through _M_o_d_5.  This modifier is called the _n_u_m_l_o_c_k _m_o_d_i_f_i_e_r.
The standard KeySyms with the prefix ‘‘XK_KP_’’ in their
name are called keypad KeySyms; these are KeySyms with
numeric value in the hexadecimal range 0xFF80 to 0xFFBD
inclusive.  In addition, vendor‐specific KeySyms in the hex­
adecimal range 0x11000000 to 0x1100FFFF are also keypad
KeySyms.





                             338844





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Within a group, the choice of KeySym is determined by apply­
ing the first rule that is satisfied from the following
list:

⋅    The numlock modifier is on and the second KeySym is a
     keypad KeySym.  In this case, if the _S_h_i_f_t modifier is
     on, or if the _L_o_c_k modifier is on and is interpreted as
     ShiftLock, then the first KeySym is used, otherwise the
     second KeySym is used.

⋅    The _S_h_i_f_t and _L_o_c_k modifiers are both off.  In this
     case, the first KeySym is used.

⋅    The _S_h_i_f_t modifier is off, and the _L_o_c_k modifier is on
     and is interpreted as CapsLock.  In this case, the
     first KeySym is used, but if that KeySym is lowercase
     alphabetic, then the corresponding uppercase KeySym is
     used instead.

⋅    The _S_h_i_f_t modifier is on, and the _L_o_c_k modifier is on
     and is interpreted as CapsLock.  In this case, the sec­
     ond KeySym is used, but if that KeySym is lowercase
     alphabetic, then the corresponding uppercase KeySym is
     used instead.

⋅    The _S_h_i_f_t modifier is on, or the _L_o_c_k modifier is on
     and is interpreted as ShiftLock, or both.  In this
     case, the second KeySym is used.

No spatial geometry of the symbols on the key is defined by
their order in the KeySym list, although a geometry might be
defined on a server‐specific basis.  The X server does not
use the mapping between KeyCodes and KeySyms.  Rather, it
merely stores it for reading and writing by clients.


To obtain the legal KeyCodes for a display, use _X_D_i_s_p_l_a_y_K_e_y_­
_c_o_d_e_s.



















                             338855





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDisplayKeycodes(_d_i_s_p_l_a_y, _m_i_n___k_e_y_c_o_d_e_s___r_e_t_u_r_n, _m_a_x___k_e_y_c_o_d_e_s___r_e_t_u_r_n)
        Display *_d_i_s_p_l_a_y;
        int *_m_i_n___k_e_y_c_o_d_e_s___r_e_t_u_r_n, *_m_a_x___k_e_y_c_o_d_e_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_m_i_n___k_e_y_c_o_d_e_s___r_e_t_u_r_n
          Returns the minimum number of KeyCodes.

_m_a_x___k_e_y_c_o_d_e_s___r_e_t_u_r_n
          Returns the maximum number of KeyCodes.
││__

The _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s function returns the min‐keycodes and
max‐keycodes supported by the specified display.  The mini­
mum number of KeyCodes returned is never less than 8, and
the maximum number of KeyCodes returned is never greater
than 255.  Not all KeyCodes in this range are required to
have corresponding keys.


To obtain the symbols for the specified KeyCodes, use
_X_G_e_t_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g.
__
││
KeySym *XGetKeyboardMapping(_d_i_s_p_l_a_y, _f_i_r_s_t___k_e_y_c_o_d_e, _k_e_y_c_o_d_e___c_o_u_n_t,
                            _k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      KeyCode _f_i_r_s_t___k_e_y_c_o_d_e;
      int _k_e_y_c_o_d_e___c_o_u_n_t;
      int *_k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_i_r_s_t___k_e_y_c_o_d_e
          Specifies the first KeyCode that is to be
          returned.

_k_e_y_c_o_d_e___c_o_u_n_t
          Specifies the number of KeyCodes that are to be
          returned.

_k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e___r_e_t_u_r_n
          Returns the number of KeySyms per KeyCode.
││__

The _X_G_e_t_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g function returns the symbols for the
specified number of KeyCodes starting with first_keycode.
The value specified in first_keycode must be greater than or
equal to min_keycode as returned by _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s, or a
_B_a_d_V_a_l_u_e error results.  In addition, the following



                             338866





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


expression must be less than or equal to max_keycode as
returned by _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s:


     first_keycode + keycode_count − 1


If this is not the case, a _B_a_d_V_a_l_u_e error results.  The num­
ber of elements in the KeySyms list is:


     keycode_count * keysyms_per_keycode_return


KeySym number N, counting from zero, for KeyCode K has the
following index in the list, counting from zero:

     (K − first_code) * keysyms_per_code_return + N


The X server arbitrarily chooses the keysyms_per_key­
code_return value to be large enough to report all requested
symbols.  A special KeySym value of _N_o_S_y_m_b_o_l is used to fill
in unused elements for individual KeyCodes.  To free the
storage returned by _X_G_e_t_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g, use _X_F_r_e_e.

_X_G_e_t_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g can generate a _B_a_d_V_a_l_u_e error.


To change the keyboard mapping, use _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g.



























                             338877





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XChangeKeyboardMapping(_d_i_s_p_l_a_y, _f_i_r_s_t___k_e_y_c_o_d_e, _k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e, _k_e_y_s_y_m_s, _n_u_m___c_o_d_e_s)
      Display *_d_i_s_p_l_a_y;
      int _f_i_r_s_t___k_e_y_c_o_d_e;
      int _k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e;
      KeySym *_k_e_y_s_y_m_s;
      int _n_u_m___c_o_d_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_i_r_s_t___k_e_y_c_o_d_e
          Specifies the first KeyCode that is to be changed.

_k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e
          Specifies the number of KeySyms per KeyCode.

_k_e_y_s_y_m_s   Specifies an array of KeySyms.

_n_u_m___c_o_d_e_s Specifies the number of KeyCodes that are to be
          changed.
││__

The _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g function defines the symbols for
the specified number of KeyCodes starting with first_key­
code.  The symbols for KeyCodes outside this range remain
unchanged.  The number of elements in keysyms must be:


     num_codes * keysyms_per_keycode


The specified first_keycode must be greater than or equal to
min_keycode returned by _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s, or a _B_a_d_V_a_l_u_e
error results.  In addition, the following expression must
be less than or equal to max_keycode as returned by _X_D_i_s_­
_p_l_a_y_K_e_y_c_o_d_e_s, or a _B_a_d_V_a_l_u_e error results:


     first_keycode + num_codes − 1


KeySym number N, counting from zero, for KeyCode K has the
following index in keysyms, counting from zero:


     (K − first_keycode) * keysyms_per_keycode + N


The specified keysyms_per_keycode can be chosen arbitrarily
by the client to be large enough to hold all desired sym­
bols.  A special KeySym value of _N_o_S_y_m_b_o_l should be used to
fill in unused elements for individual KeyCodes.  It is
legal for _N_o_S_y_m_b_o_l to appear in nontrailing positions of the



                             338888





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


effective list for a KeyCode.  _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g gener­
ates a _M_a_p_p_i_n_g_N_o_t_i_f_y event.

There is no requirement that the X server interpret this
mapping.  It is merely stored for reading and writing by
clients.

_X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e
errors.

The next six functions make use of the _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p data
structure, which contains:

__
││
typedef struct {
     int max_keypermod;  /* This server’s max number of keys per modifier */
     KeyCode *modifiermap;/* An 8 by max_keypermod array of the modifiers */
} XModifierKeymap;

││__

To create an _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure, use _X_N_e_w_M_o_d_i_f_i_e_r_m_a_p.
__
││
XModifierKeymap *XNewModifiermap(_m_a_x___k_e_y_s___p_e_r___m_o_d)
        int _m_a_x___k_e_y_s___p_e_r___m_o_d;


_m_a_x___k_e_y_s___p_e_r___m_o_d
          Specifies the number of KeyCode entries preallo­
          cated to the modifiers in the map.
││__

The _X_N_e_w_M_o_d_i_f_i_e_r_m_a_p function returns a pointer to _X_M_o_d_i_­
_f_i_e_r_K_e_y_m_a_p structure for later use.


To add a new entry to an _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure, use _X_I_n_­
_s_e_r_t_M_o_d_i_f_i_e_r_m_a_p_E_n_t_r_y.

















                             338899





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XModifierKeymap *XInsertModifiermapEntry(_m_o_d_m_a_p, _k_e_y_c_o_d_e___e_n_t_r_y, _m_o_d_i_f_i_e_r)
     XModifierKeymap *_m_o_d_m_a_p;
     KeyCode _k_e_y_c_o_d_e___e_n_t_r_y;
     int _m_o_d_i_f_i_e_r;


_m_o_d_m_a_p    Specifies the _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure.

_k_e_y_c_o_d_e___e_n_t_r_y
          Specifies the KeyCode.

_m_o_d_i_f_i_e_r  Specifies the modifier.
││__

The _X_I_n_s_e_r_t_M_o_d_i_f_i_e_r_m_a_p_E_n_t_r_y function adds the specified Key­
Code to the set that controls the specified modifier and
returns the resulting _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure (expanded as
needed).


To delete an entry from an _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure, use
_X_D_e_l_e_t_e_M_o_d_i_f_i_e_r_m_a_p_E_n_t_r_y.
__
││
XModifierKeymap *XDeleteModifiermapEntry(_m_o_d_m_a_p, _k_e_y_c_o_d_e___e_n_t_r_y, _m_o_d_i_f_i_e_r)
     XModifierKeymap *_m_o_d_m_a_p;
     KeyCode _k_e_y_c_o_d_e___e_n_t_r_y;
     int _m_o_d_i_f_i_e_r;


_m_o_d_m_a_p    Specifies the _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure.

_k_e_y_c_o_d_e___e_n_t_r_y
          Specifies the KeyCode.

_m_o_d_i_f_i_e_r  Specifies the modifier.
││__

The _X_D_e_l_e_t_e_M_o_d_i_f_i_e_r_m_a_p_E_n_t_r_y function deletes the specified
KeyCode from the set that controls the specified modifier
and returns a pointer to the resulting _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p
structure.


To destroy an _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure, use _X_F_r_e_e_M_o_d_i_­
_f_i_e_r_m_a_p.










                             339900





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XFreeModifiermap(_m_o_d_m_a_p)
        XModifierKeymap *_m_o_d_m_a_p;


_m_o_d_m_a_p    Specifies the _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure.
││__

The _X_F_r_e_e_M_o_d_i_f_i_e_r_m_a_p function frees the specified _X_M_o_d_i_­
_f_i_e_r_K_e_y_m_a_p structure.


To set the KeyCodes to be used as modifiers, use _X_S_e_t_M_o_d_i_­
_f_i_e_r_M_a_p_p_i_n_g.
__
││
int XSetModifierMapping(_d_i_s_p_l_a_y, _m_o_d_m_a_p)
        Display *_d_i_s_p_l_a_y;
        XModifierKeymap *_m_o_d_m_a_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_m_o_d_m_a_p    Specifies the _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure.
││__

The _X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g function specifies the KeyCodes of
the keys (if any) that are to be used as modifiers.  If it
succeeds, the X server generates a _M_a_p_p_i_n_g_N_o_t_i_f_y event, and
_X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g returns _M_a_p_p_i_n_g_S_u_c_c_e_s_s.  X permits at
most 8 modifier keys.  If more than 8 are specified in the
_X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure, a _B_a_d_L_e_n_g_t_h error results.

The modifiermap member of the _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure con­
tains 8 sets of max_keypermod KeyCodes, one for each modi­
fier in the order _S_h_i_f_t, _L_o_c_k, _C_o_n_t_r_o_l, _M_o_d_1, _M_o_d_2, _M_o_d_3,
_M_o_d_4, and _M_o_d_5.  Only nonzero KeyCodes have meaning in each
set, and zero KeyCodes are ignored.  In addition, all of the
nonzero KeyCodes must be in the range specified by min_key­
code and max_keycode in the _D_i_s_p_l_a_y structure, or a _B_a_d_V_a_l_u_e
error results.

An X server can impose restrictions on how modifiers can be
changed, for example, if certain keys do not generate up
transitions in hardware, if auto‐repeat cannot be disabled
on certain keys, or if multiple modifier keys are not sup­
ported.  If some such restriction is violated, the status
reply is _M_a_p_p_i_n_g_F_a_i_l_e_d, and none of the modifiers are
changed.  If the new KeyCodes specified for a modifier dif­
fer from those currently defined and any (current or new)
keys for that modifier are in the logically down state,
_X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g returns _M_a_p_p_i_n_g_B_u_s_y, and none of the
modifiers is changed.




                             339911





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e
errors.


To obtain the KeyCodes used as modifiers, use _X_G_e_t_M_o_d_i_­
_f_i_e_r_M_a_p_p_i_n_g.
__
││
XModifierKeymap *XGetModifierMapping(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;



_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_G_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g function returns a pointer to a
newly created _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure that contains the
keys being used as modifiers.  The structure should be freed
after use by calling _X_F_r_e_e_M_o_d_i_f_i_e_r_m_a_p.  If only zero values
appear in the set for any modifier, that modifier is dis­
abled.



































                             339922





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 1133

        LLooccaalleess aanndd IInntteerrnnaattiioonnaalliizzeedd TTeexxtt FFuunnccttiioonnss



An internationalized application is one that is adaptable to
the requirements of different native languages, local cus­
toms, and character string encodings.  The process of adapt­
ing the operation to a particular native language, local
custom, or string encoding is called _l_o_c_a_l_i_z_a_t_i_o_n.  A goal
of internationalization is to permit localization without
program source modifications or recompilation.

As one of the localization mechanisms, Xlib provides an X
Input Method (_X_I_M) functional interface for international­
ized text input and an X Output Method (_X_O_M) functional
interface for internationalized text output.

Internationalization in X is based on the concept of a
_l_o_c_a_l_e.  A locale defines the localized behavior of a pro­
gram at run time.  Locales affect Xlib in its:

⋅    Encoding and processing of input method text

⋅    Encoding of resource files and values

⋅    Encoding and imaging of text strings

⋅    Encoding and decoding for inter‐client text communica­
     tion

Characters from various languages are represented in a com­
puter using an encoding.  Different languages have different
encodings, and there are even different encodings for the
same characters in the same language.

This chapter defines support for localized text imaging and
text input and describes the locale mechanism that controls
all locale‐dependent Xlib functions.  Sets of functions are
provided for multibyte (char *) text as well as wide charac­
ter (wchar_t) text in the form supported by the host C lan­
guage environment.  The multibyte and wide character func­
tions are equivalent except for the form of the text argu­
ment.

The Xlib internationalization functions are not meant to
provide support for multilingual applications (mixing multi­
ple languages within a single piece of text), but they make
it possible to implement applications that work in limited
fashion with more than one language in independent contexts.




                             339933





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The remainder of this chapter discusses:

⋅    X locale management

⋅    Locale and modifier dependencies

⋅    Variable argument lists

⋅    Output methods

⋅    Input methods

⋅    String constants

1133..11..  XX LLooccaallee MMaannaaggeemmeenntt

X supports one or more of the locales defined by the host
environment.  On implementations that conform to the ANSI C
library, the locale announcement method is _s_e_t_l_o_c_a_l_e.  This
function configures the locale operation of both the host C
library and Xlib.  The operation of Xlib is governed by the
LC_CTYPE category; this is called the _c_u_r_r_e_n_t _l_o_c_a_l_e.  An
implementation is permitted to provide implementation‐depen­
dent mechanisms for announcing the locale in addition to
_s_e_t_l_o_c_a_l_e.

On implementations that do not conform to the ANSI C
library, the locale announcement method is Xlib implementa­
tion‐dependent.

The mechanism by which the semantic operation of Xlib is
defined for a specific locale is implementation‐dependent.


X is not required to support all the locales supported by
the host.  To determine if the current locale is supported
by X, use _X_S_u_p_p_o_r_t_s_L_o_c_a_l_e.
__
││
Bool XSupportsLocale()

││__

The _X_S_u_p_p_o_r_t_s_L_o_c_a_l_e function returns _T_r_u_e if Xlib functions
are capable of operating under the current locale.  If it
returns _F_a_l_s_e, Xlib locale‐dependent functions for which the
_X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d return status is defined will return
_X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d.  Other Xlib locale‐dependent routines
will operate in the ‘‘C’’ locale.

The client is responsible for selecting its locale and X
modifiers.  Clients should provide a means for the user to
override the clients’ locale selection at client invocation.
Most single‐display X clients operate in a single locale for



                             339944





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


both X and the host processing environment.  They will con­
figure the locale by calling three functions: the host
locale configuration function, _X_S_u_p_p_o_r_t_s_L_o_c_a_l_e, and _X_S_e_t_L_o_­
_c_a_l_e_M_o_d_i_f_i_e_r_s.

The semantics of certain categories of X internationaliza­
tion capabilities can be configured by setting modifiers.
Modifiers are named by implementation‐dependent and locale‐
specific strings.  The only standard use for this capability
at present is selecting one of several styles of keyboard
input method.


To configure Xlib locale modifiers for the current locale,
use _X_S_e_t_L_o_c_a_l_e_M_o_d_i_f_i_e_r_s.
__
││
char *XSetLocaleModifiers(_m_o_d_i_f_i_e_r___l_i_s_t)
      char *_m_o_d_i_f_i_e_r___l_i_s_t;


_m_o_d_i_f_i_e_r___l_i_s_t
          Specifies the modifiers.
││__

The _X_S_e_t_L_o_c_a_l_e_M_o_d_i_f_i_e_r_s function sets the X modifiers for
the current locale setting.  The modifier_list argument is a
null‐terminated string of the form ‘‘{@_c_a_t_e_g_o_r_y=_v_a_l_u_e}’’,
that is, having zero or more concatenated ‘‘@_c_a_t_e_­
_g_o_r_y=_v_a_l_u_e’’ entries, where _c_a_t_e_g_o_r_y is a category name and
_v_a_l_u_e is the (possibly empty) setting for that category.
The values are encoded in the current locale.  Category
names are restricted to the POSIX Portable Filename Charac­
ter Set.

The local host X locale modifiers announcer (on POSIX‐com­
pliant systems, the XMODIFIERS environment variable) is
appended to the modifier_list to provide default values on
the local host.  If a given category appears more than once
in the list, the first setting in the list is used.  If a
given category is not included in the full modifier list,
the category is set to an implementation‐dependent default
for the current locale.  An empty value for a category
explicitly specifies the implementation‐dependent default.

If the function is successful, it returns a pointer to a
string.  The contents of the string are such that a subse­
quent call with that string (in the same locale) will
restore the modifiers to the same settings.  If modi­
fier_list is a NULL pointer, _X_S_e_t_L_o_c_a_l_e_M_o_d_i_f_i_e_r_s also
returns a pointer to such a string, and the current locale
modifiers are not changed.





                             339955





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


If invalid values are given for one or more modifier cate­
gories supported by the locale, a NULL pointer is returned,
and none of the current modifiers are changed.

At program startup, the modifiers that are in effect are
unspecified until the first successful call to set them.
Whenever the locale is changed, the modifiers that are in
effect become unspecified until the next successful call to
set them.  Clients should always call _X_S_e_t_L_o_c_a_l_e_M_o_d_i_f_i_e_r_s
with a non‐NULL modifier_list after setting the locale
before they call any locale‐dependent Xlib routine.

The only standard modifier category currently defined is
‘‘im’’, which identifies the desired input method.  The val­
ues for input method are not standardized.  A single locale
may use multiple input methods, switching input method under
user control.  The modifier may specify the initial input
method in effect or an ordered list of input methods.  Mul­
tiple input methods may be specified in a single im value
string in an implementation‐dependent manner.

The returned modifiers string is owned by Xlib and should
not be modified or freed by the client.  It may be freed by
Xlib after the current locale or modifiers are changed.
Until freed, it will not be modified by Xlib.

The recommended procedure for clients initializing their
locale and modifiers is to obtain locale and modifier
announcers separately from one of the following prioritized
sources:

⋅    A command line option

⋅    A resource

⋅    The empty string ("")

The first of these that is defined should be used.  Note
that when a locale command line option or locale resource is
defined, the effect should be to set all categories to the
specified locale, overriding any category‐specific settings
in the local host environment.

1133..22..  LLooccaallee aanndd MMooddiiffiieerr DDeeppeennddeenncciieess

The internationalized Xlib functions operate in the current
locale configured by the host environment and X locale modi­
fiers set by _X_S_e_t_L_o_c_a_l_e_M_o_d_i_f_i_e_r_s or in the locale and modi­
fiers configured at the time some object supplied to the
function was created.  For each locale‐dependent function,
the following table describes the locale (and modifiers)
dependency:





                             339966





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


--------------------------------------------------------------------------
LLooccaallee ffrroomm    AAffffeeccttss tthhee FFuunnccttiioonn           IInn
--------------------------------------------------------------------------
               Locale Query/Configuration:
_s_e_t_l_o_c_a_l_e      _X_S_u_p_p_o_r_t_s_L_o_c_a_l_e                Locale queried
               _X_S_e_t_L_o_c_a_l_e_M_o_d_i_f_i_e_r_s            Locale modified

               Resources:
_s_e_t_l_o_c_a_l_e      _X_r_m_G_e_t_F_i_l_e_D_a_t_a_b_a_s_e             Locale of _X_r_m_D_a_t_a_b_a_s_e
               _X_r_m_G_e_t_S_t_r_i_n_g_D_a_t_a_b_a_s_e
_X_r_m_D_a_t_a_b_a_s_e    _X_r_m_P_u_t_F_i_l_e_D_a_t_a_b_a_s_e             Locale of _X_r_m_D_a_t_a_b_a_s_e
               _X_r_m_L_o_c_a_l_e_O_f_D_a_t_a_b_a_s_e

               Setting Standard Properties:
_s_e_t_l_o_c_a_l_e      _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s             Encoding of sup­
                                              plied/returned
                                              text (some WM_ property
                                              text in environment locale)
_s_e_t_l_o_c_a_l_e      _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t      Encoding of sup­
                                              plied/returned text
               _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t
               _X_m_b_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y
               _X_w_c_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y

               Text Input:
_s_e_t_l_o_c_a_l_e      _X_O_p_e_n_I_M                        XIM input method selection
               _X_R_e_g_i_s_t_e_r_I_M_I_n_s_t_a_n_t_i_a_t_e_C_a_l_l_­    XIM selection
               _b_a_c_k
               _X_U_n_r_e_g_i_s_t_e_r_I_M_I_n_s_t_a_n_t_i_a_t_e_­      XIM selection
               _C_a_l_l_b_a_c_k
_X_I_M            _X_C_r_e_a_t_e_I_C                      XIC input method configura­
                                              tion
               _X_L_o_c_a_l_e_O_f_I_M, and so on         Queried locale
_X_I_C            _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g                Keyboard layout
               _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g                Encoding of returned text

               Text Drawing:
_s_e_t_l_o_c_a_l_e      _X_O_p_e_n_O_M                        XOM output method selection
               _X_C_r_e_a_t_e_F_o_n_t_S_e_t                 Charsets of fonts in
                                              _X_F_o_n_t_S_e_t
_X_O_M            _X_C_r_e_a_t_e_O_C                      XOC output method configu­
                                              ration
               _X_L_o_c_a_l_e_O_f_O_M, and so on         Queried locale
_X_F_o_n_t_S_e_t       _X_m_b_D_r_a_w_T_e_x_t,                   Locale of supplied text
               _X_w_c_D_r_a_w_T_e_x_t, and so on         Locale of supplied text
               _X_E_x_t_e_n_t_s_O_f_F_o_n_t_S_e_t, and so on   Locale‐dependent metrics
               _X_m_b_T_e_x_t_E_x_t_e_n_t_s,
               _X_w_c_T_e_x_t_E_x_t_e_n_t_s, and so on

               Xlib Errors:
_s_e_t_l_o_c_a_l_e      _X_G_e_t_E_r_r_o_r_D_a_t_a_b_a_s_e_T_e_x_t          Locale of error message
               _X_G_e_t_E_r_r_o_r_T_e_x_t
--------------------------------------------------------------------------




                             339977





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Clients may assume that a locale‐encoded text string
returned by an X function can be passed to a C library rou­
tine, or vice versa, if the locale is the same at the two
calls.

All text strings processed by internationalized Xlib func­
tions are assumed to begin in the initial state of the
encoding of the locale, if the encoding is state‐dependent.

All Xlib functions behave as if they do not change the cur­
rent locale or X modifier setting.  (This means that if they
do change locale or call _X_S_e_t_L_o_c_a_l_e_M_o_d_i_f_i_e_r_s with a non‐NULL
argument, they must save and restore the current state on
entry and exit.)  Also, Xlib functions on implementations
that conform to the ANSI C library do not alter the global
state associated with the ANSI C functions _m_b_l_e_n, _m_b_t_o_w_c,
_w_c_t_o_m_b, and _s_t_r_t_o_k.

1133..33..  VVaarriiaabbllee AArrgguummeenntt LLiissttss

Various functions in this chapter have arguments that con­
form to the ANSI C variable argument list calling conven­
tion.  Each function denoted with an argument of the form
‘‘...’’ takes a variable‐length list of name and value
pairs, where each name is a string and each value is of type
_X_P_o_i_n_t_e_r.  A name argument that is NULL identifies the end
of the list.

A variable‐length argument list may contain a nested list.
If the name _X_N_V_a_N_e_s_t_e_d_L_i_s_t is specified in place of an argu­
ment name, then the following value is interpreted as an
_X_V_a_N_e_s_t_e_d_L_i_s_t value that specifies a list of values logi­
cally inserted into the original list at the point of decla­
ration.  A NULL identifies the end of a nested list.


To allocate a nested variable argument list dynamically, use
_X_V_a_C_r_e_a_t_e_N_e_s_t_e_d_L_i_s_t.
__
││
typedef void * XVaNestedList;

XVaNestedList XVaCreateNestedList(_d_u_m_m_y, ...)
      int _d_u_m_m_y;


_d_u_m_m_y     Specifies an unused argument (required by ANSI C).

...       Specifies the variable length argument list.
││__

The _X_V_a_C_r_e_a_t_e_N_e_s_t_e_d_L_i_s_t function allocates memory and copies
its arguments into a single list pointer, which may be used
as a value for arguments requiring a list value.  Any



                             339988





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


entries are copied as specified.  Data passed by reference
is not copied; the caller must ensure data remains valid for
the lifetime of the nested list.  The list should be freed
using _X_F_r_e_e when it is no longer needed.

1133..44..  OOuuttppuutt MMeetthhooddss

This section provides discussions of the following X Output
Method (XOM) topics:

⋅    Output method overview

⋅    Output method functions

⋅    Output method values

⋅    Output context functions

⋅    Output context values

⋅    Creating and freeing a font set

⋅    Obtaining font set metrics

⋅    Drawing text using font sets

1133..44..11..  OOuuttppuutt MMeetthhoodd OOvveerrvviieeww

Locale‐dependent text may include one or more text compo­
nents, each of which may require different fonts and charac­
ter set encodings.  In some languages, each component might
have a different drawing direction, and some components
might contain context‐dependent characters that change shape
based on relationships with neighboring characters.

When drawing such locale‐dependent text, some locale‐spe­
cific knowledge is required; for example, what fonts are
required to draw the text, how the text can be separated
into components, and which fonts are selected to draw each
component.  Further, when bidirectional text must be drawn,
the internal representation order of the text must be
changed into the visual representation order to be drawn.

An X Output Method provides a functional interface so that
clients do not have to deal directly with such locale‐depen­
dent details.  Output methods provide the following capabil­
ities:

⋅    Creating a set of fonts required to draw locale‐depen­
     dent text.

⋅    Drawing locale‐dependent text with a font set without
     the caller needing to be aware of locale dependencies.




                             339999





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    Obtaining the escapement and extents in pixels of
     locale‐dependent text.

⋅    Determining if bidirectional or context‐dependent draw­
     ing is required in a specific locale with a specific
     font set.

Two different abstractions are used in the representation of
the output method for clients.

The abstraction used to communicate with an output method is
an opaque data structure represented by the _X_O_M data type.
The abstraction for representing the state of a particular
output thread is called an _o_u_t_p_u_t _c_o_n_t_e_x_t.  The Xlib repre­
sentation of an output context is an _X_O_C, which is compati­
ble with _X_F_o_n_t_S_e_t in terms of its functional interface, but
is a broader, more generalized abstraction.

1133..44..22..  OOuuttppuutt MMeetthhoodd FFuunnccttiioonnss

To open an output method, use _X_O_p_e_n_O_M.
__
││
XOM XOpenOM(_d_i_s_p_l_a_y, _d_b, _r_e_s___n_a_m_e, _r_e_s___c_l_a_s_s)
      Display *_d_i_s_p_l_a_y;
      XrmDatabase _d_b;
      char *_r_e_s___n_a_m_e;
      char *_r_e_s___c_l_a_s_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_b        Specifies a pointer to the resource database.

_r_e_s___n_a_m_e  Specifies the full resource name of the applica­
          tion.

_r_e_s___c_l_a_s_s Specifies the full class name of the application.
││__

The _X_O_p_e_n_O_M function opens an output method matching the
current locale and modifiers specification.  The current
locale and modifiers are bound to the output method when
_X_O_p_e_n_O_M is called.  The locale associated with an output
method cannot be changed.

The specific output method to which this call will be routed
is identified on the basis of the current locale and modi­
fiers.  _X_O_p_e_n_O_M will identify a default output method corre­
sponding to the current locale.  That default can be modi­
fied using _X_S_e_t_L_o_c_a_l_e_M_o_d_i_f_i_e_r_s to set the output method mod­
ifier.





                             440000





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The db argument is the resource database to be used by the
output method for looking up resources that are private to
the output method.  It is not intended that this database be
used to look up values that can be set as OC values in an
output context.  If db is NULL, no database is passed to the
output method.

The res_name and res_class arguments specify the resource
name and class of the application.  They are intended to be
used as prefixes by the output method when looking up
resources that are common to all output contexts that may be
created for this output method.  The characters used for
resource names and classes must be in the X Portable Charac­
ter Set.  The resources looked up are not fully specified if
res_name or res_class is NULL.

The res_name and res_class arguments are not assumed to
exist beyond the call to _X_O_p_e_n_O_M.  The specified resource
database is assumed to exist for the lifetime of the output
method.

_X_O_p_e_n_O_M returns NULL if no output method could be opened.


To close an output method, use _X_C_l_o_s_e_O_M.
__
││
Status XCloseOM(_o_m)
      XOM _o_m;


_o_m        Specifies the output method.
││__

The _X_C_l_o_s_e_O_M function closes the specified output method.


To set output method attributes, use _X_S_e_t_O_M_V_a_l_u_e_s.
__
││
char * XSetOMValues(_o_m, ...)
      XOM _o_m;


_o_m        Specifies the output method.

...       Specifies the variable‐length argument list to set
          XOM values.
││__

The _X_S_e_t_O_M_V_a_l_u_e_s function presents a variable argument list
programming interface for setting properties or features of
the specified output method.  This function returns NULL if
it succeeds; otherwise, it returns the name of the first



                             440011





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


argument that could not be obtained.

No standard arguments are currently defined by Xlib.


To query an output method, use _X_G_e_t_O_M_V_a_l_u_e_s.
__
││
char * XGetOMValues(_o_m, ...)
      XOM _o_m;


_o_m        Specifies the output method.

...       Specifies the variable‐length argument list to get
          XOM values.
││__

The _X_G_e_t_O_M_V_a_l_u_e_s function presents a variable argument list
programming interface for querying properties or features of
the specified output method.  This function returns NULL if
it succeeds; otherwise, it returns the name of the first
argument that could not be obtained.

To obtain the display associated with an output method, use
_X_D_i_s_p_l_a_y_O_f_O_M.
__
││
Display * XDisplayOfOM(_o_m)
     XOM _o_m;


_o_m        Specifies the output method.
││__

The _X_D_i_s_p_l_a_y_O_f_O_M function returns the display associated
with the specified output method.


To get the locale associated with an output method, use _X_L_o_­
_c_a_l_e_O_f_O_M.
__
││
char * XLocaleOfOM(_o_m)
      XOM _o_m;


_o_m        Specifies the output method.
││__

The _X_L_o_c_a_l_e_O_f_O_M returns the locale associated with the spec­
ified output method.





                             440022





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1133..44..33..  XX OOuuttppuutt MMeetthhoodd VVaalluueess

The following table describes how XOM values are interpreted
by an output method.  The first column lists the XOM values.
The second column indicates how each of the XOM values are
treated by a particular output style.


The following key applies to this table.

-------------------------------------------------------------
KKeeyy          EExxppllaannaattiioonn
-------------------------------------------------------------
G            This value may be read using _X_G_e_t_O_M_V_a_l_u_e_s.
-------------------------------------------------------------



-----------------------------
XXOOMM VVaalluuee                KKeeyy
-----------------------------
_X_N_R_e_q_u_i_r_e_d_C_h_a_r_S_e_t         G
_X_N_Q_u_e_r_y_O_r_i_e_n_t_a_t_i_o_n        G
_X_N_D_i_r_e_c_t_i_o_n_a_l_D_e_p_e_n_­       G
_d_e_n_t_D_r_a_w_i_n_g
_X_N_C_o_n_t_e_x_t_u_a_l_D_r_a_w_i_n_g       G
-----------------------------



1133..44..33..11..  RReeqquuiirreedd CChhaarr SSeett

The _X_N_R_e_q_u_i_r_e_d_C_h_a_r_S_e_t argument returns the list of charsets
that are required for loading the fonts needed for the
locale.  The value of the argument is a pointer to a struc­
ture of type _X_O_M_C_h_a_r_S_e_t_L_i_s_t.

The _X_O_M_C_h_a_r_S_e_t_L_i_s_t structure is defined as follows:
__
││

typedef struct {
     int charset_count;
     char **charset_list;
} XOMCharSetList;

││__

The charset_list member is a list of one or more null‐termi­
nated charset names, and the charset_count member is the
number of charset names.

The required charset list is owned by Xlib and should not be
modified or freed by the client.  It will be freed by a call



                             440033





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


to _X_C_l_o_s_e_O_M with the associated _X_O_M.  Until freed, its con­
tents will not be modified by Xlib.


1133..44..33..22..  QQuueerryy OOrriieennttaattiioonn

The _X_N_Q_u_e_r_y_O_r_i_e_n_t_a_t_i_o_n argument returns the global orienta­
tion of text when drawn.  Other than _X_O_M_O_r_i_e_n_t_a_t_i_o_n___L_T_R___T_T_B,
the set of orientations supported is locale‐dependent.  The
value of the argument is a pointer to a structure of type
_X_O_M_O_r_i_e_n_t_a_t_i_o_n.  Clients are responsible for freeing the
_X_O_M_O_r_i_e_n_t_a_t_i_o_n structure by using _X_F_r_e_e; this also frees the
contents of the structure.

__
││
typedef struct {
     int num_orientation;
     XOrientation *orientation;/* Input Text description */
} XOMOrientation;

typedef enum {
     XOMOrientation_LTR_TTB,
     XOMOrientation_RTL_TTB,
     XOMOrientation_TTB_LTR,
     XOMOrientation_TTB_RTL,
     XOMOrientation_Context
} XOrientation;

││__

The possible value for XOrientation may be:

⋅    _X_O_M_O_r_i_e_n_t_a_t_i_o_n___L_T_R___T_T_B left‐to‐right, top‐to‐bottom
     global orientation

⋅    _X_O_M_O_r_i_e_n_t_a_t_i_o_n___R_T_L___T_T_B right‐to‐left, top‐to‐bottom
     global orientation

⋅    _X_O_M_O_r_i_e_n_t_a_t_i_o_n___T_T_B___L_T_R top‐to‐bottom, left‐to‐right
     global orientation

⋅    _X_O_M_O_r_i_e_n_t_a_t_i_o_n___T_T_B___R_T_L top‐to‐bottom, right‐to‐left
     global orientation

⋅    _X_O_M_O_r_i_e_n_t_a_t_i_o_n___C_o_n_t_e_x_t contextual global orientation


1133..44..33..33..  DDiirreeccttiioonnaall DDeeppeennddeenntt DDrraawwiinngg

The _X_N_D_i_r_e_c_t_i_o_n_a_l_D_e_p_e_n_d_e_n_t_D_r_a_w_i_n_g argument indicates whether
the text rendering functions implement implicit handling of
directional text.  If this value is _T_r_u_e, the output method
has knowledge of directional dependencies and reorders text



                             440044





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


as necessary when rendering text.  If this value is _F_a_l_s_e,
the output method does not implement any directional text
handling, and all character directions are assumed to be
left‐to‐right.

Regardless of the rendering order of characters, the origins
of all characters are on the primary draw direction side of
the drawing origin.

This OM value presents functionality identical to the _X_D_i_­
_r_e_c_t_i_o_n_a_l_D_e_p_e_n_d_e_n_t_D_r_a_w_i_n_g function.

1133..44..33..44..  CCoonntteexxtt DDeeppeennddeenntt DDrraawwiinngg

The _X_N_C_o_n_t_e_x_t_u_a_l_D_r_a_w_i_n_g argument indicates whether the text
rendering functions implement implicit context‐dependent
drawing.  If this value is _T_r_u_e, the output method has
knowledge of context dependencies and performs character
shape editing, combining glyphs to present a single charac­
ter as necessary.  The actual shape editing is dependent on
the locale implementation and the font set used.

This OM value presents functionality identical to the _X_C_o_n_­
_t_e_x_t_u_a_l_D_r_a_w_i_n_g function.

1133..44..44..  OOuuttppuutt CCoonntteexxtt FFuunnccttiioonnss

An output context is an abstraction that contains both the
data required by an output method and the information
required to display that data.  There can be multiple output
contexts for one output method.  The programming interfaces
for creating, reading, or modifying an output context use a
variable argument list.  The name elements of the argument
lists are referred to as XOC values.  It is intended that
output methods be controlled by these XOC values.  As new
XOC values are created, they should be registered with the X
Consortium.  An _X_O_C can be used anywhere an _X_F_o_n_t_S_e_t can be
used, and vice versa; _X_F_o_n_t_S_e_t is retained for compatibility
with previous releases.  The concepts of output methods and
output contexts include broader, more generalized abstrac­
tion than font set, supporting complex and more intelligent
text display, and dealing not only with multiple fonts but
also with context dependencies.  However, _X_F_o_n_t_S_e_t is widely
used in several interfaces, so _X_O_C is defined as an upward
compatible type of _X_F_o_n_t_S_e_t.


To create an output context, use _X_C_r_e_a_t_e_O_C.









                             440055





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XOC XCreateOC(_o_m, ...)
      XOM _o_m;


_o_m        Specifies the output method.

...       Specifies the variable‐length argument list to set
          XOC values.
││__

The _X_C_r_e_a_t_e_O_C function creates an output context within the
specified output method.

The base font names argument is mandatory at creation time,
and the output context will not be created unless it is pro­
vided.  All other output context values can be set later.

_X_C_r_e_a_t_e_O_C returns NULL if no output context could be cre­
ated.  NULL can be returned for any of the following rea­
sons:

⋅    A required argument was not set.

⋅    A read‐only argument was set.

⋅    An argument name is not recognized.

⋅    The output method encountered an output method imple­
     mentation‐dependent error.

_X_C_r_e_a_t_e_O_C can generate a _B_a_d_A_t_o_m error.


To destroy an output context, use _X_D_e_s_t_r_o_y_O_C.
__
││
void XDestroyOC(_o_c)
      XOC _o_c;


_o_c        Specifies the output context.
││__

The _X_D_e_s_t_r_o_y_O_C function destroys the specified output con­
text.


To get the output method associated with an output context,
use _X_O_M_O_f_O_C.







                             440066





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XOM XOMOfOC(_o_c)
      XOC _o_c;


_o_c        Specifies the output context.
││__

The _X_O_M_O_f_O_C function returns the output method associated
with the specified output context.


Xlib provides two functions for setting and reading output
context values, respectively, _X_S_e_t_O_C_V_a_l_u_e_s and _X_G_e_t_O_C_V_a_l_u_e_s.
Both functions have a variable‐length argument list.  In
that argument list, any XOC value’s name must be denoted
with a character string using the X Portable Character Set.


To set XOC values, use _X_S_e_t_O_C_V_a_l_u_e_s.
__
││
char * XSetOCValues(_o_c, ...)
      XOC _o_c;


_o_c        Specifies the output context.

...       Specifies the variable‐length argument list to set
          XOC values.
││__

The _X_S_e_t_O_C_V_a_l_u_e_s function returns NULL if no error occurred;
otherwise, it returns the name of the first argument that
could not be set.  An argument might not be set for any of
the following reasons:

⋅    The argument is read‐only.

⋅    The argument name is not recognized.

⋅    An implementation‐dependent error occurs.

Each value to be set must be an appropriate datum, matching
the data type imposed by the semantics of the argument.

_X_S_e_t_O_C_V_a_l_u_e_s can generate a _B_a_d_A_t_o_m error.


To obtain XOC values, use _X_G_e_t_O_C_V_a_l_u_e_s.







                             440077





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char * XGetOCValues(_o_c, ...)
      XOC _o_c;


_o_c        Specifies the output context.

...       Specifies the variable‐length argument list to get
          XOC values.
││__

The _X_G_e_t_O_C_V_a_l_u_e_s function returns NULL if no error occurred;
otherwise, it returns the name of the first argument that
could not be obtained.  An argument might not be obtained
for any of the following reasons:

⋅    The argument name is not recognized.

⋅    An implementation‐dependent error occurs.

Each argument value following a name must point to a loca­
tion where the value is to be stored.

1133..44..55..  OOuuttppuutt CCoonntteexxtt VVaalluueess

The following table describes how XOC values are interpreted
by an output method.  The first column lists the XOC values.
The second column indicates the alternative interfaces that
function identically and are provided for compatibility with
previous releases.  The third column indicates how each of
the XOC values is treated.

The following keys apply to this table.

-------------------------------------------------------------
KKeeyy          EExxppllaannaattiioonn
-------------------------------------------------------------
C            This value must be set with _X_C_r_e_a_t_e_O_C.
D            This value may be set using _X_C_r_e_a_t_e_O_C.  If it
             is not set,
             a default is provided.
G            This value may be read using _X_G_e_t_O_C_V_a_l_u_e_s.
S            This value must be set using _X_S_e_t_O_C_V_a_l_u_e_s.
-------------------------------------------------------------



-----------------------------------------------
XXOOCC VVaalluuee        AAlltteerrnnaattiivvee IInntteerrffaaccee    KKeeyy
-----------------------------------------------
BaseFontName        _X_C_r_e_a_t_e_F_o_n_t_S_e_t        C‐G
MissingCharSet      _X_C_r_e_a_t_e_F_o_n_t_S_e_t         G
DefaultString       _X_C_r_e_a_t_e_F_o_n_t_S_e_t         G




                             440088





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-----------------------------------------------
XXOOCC VVaalluuee        AAlltteerrnnaattiivvee IInntteerrffaaccee    KKeeyy
-----------------------------------------------
Orientation                −             D‐S‐G
ResourceName               −              S‐G
ResourceClass              −              S‐G
FontInfo            _X_F_o_n_t_s_O_f_F_o_n_t_S_e_t        G
OMAutomatic                −               G
-----------------------------------------------



1133..44..55..11..  BBaassee FFoonntt NNaammee

The _X_N_B_a_s_e_F_o_n_t_N_a_m_e argument is a list of base font names
that Xlib uses to load the fonts needed for the locale.  The
base font names are a comma‐separated list.  The string is
null‐terminated and is assumed to be in the Host Portable
Character Encoding; otherwise, the result is implementation‐
dependent.  White space immediately on either side of a sep­
arating comma is ignored.

Use of XLFD font names permits Xlib to obtain the fonts
needed for a variety of locales from a single locale‐inde­
pendent base font name.  The single base font name should
name a family of fonts whose members are encoded in the var­
ious charsets needed by the locales of interest.

An XLFD base font name can explicitly name a charset needed
for the locale.  This allows the user to specify an exact
font for use with a charset required by a locale, fully con­
trolling the font selection.

If a base font name is not an XLFD name, Xlib will attempt
to obtain an XLFD name from the font properties for the
font.  If Xlib is successful, the _X_G_e_t_O_C_V_a_l_u_e_s function will
return this XLFD name instead of the client‐supplied name.

This argument must be set at creation time and cannot be
changed.  If no fonts exist for any of the required
charsets, or if the locale definition in Xlib requires that
a font exist for a particular charset and a font is not
found for that charset, _X_C_r_e_a_t_e_O_C returns NULL.

When querying for the _X_N_B_a_s_e_F_o_n_t_N_a_m_e XOC value, _X_G_e_t_O_C_V_a_l_u_e_s
returns a null‐terminated string identifying the base font
names that Xlib used to load the fonts needed for the
locale.  This string is owned by Xlib and should not be mod­
ified or freed by the client.  The string will be freed by a
call to _X_D_e_s_t_r_o_y_O_C with the associated _X_O_C.  Until freed,
the string contents will not be modified by Xlib.






                             440099





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1133..44..55..22..  MMiissssiinngg CChhaarrSSeett

The _X_N_M_i_s_s_i_n_g_C_h_a_r_S_e_t argument returns the list of required
charsets that are missing from the font set.  The value of
the argument is a pointer to a structure of type _X_O_M_­
_C_h_a_r_S_e_t_L_i_s_t.

If fonts exist for all of the charsets required by the cur­
rent locale, charset_list is set to NULL and charset_count
is set to zero.  If no fonts exist for one or more of the
required charsets, charset_list is set to a list of one or
more null‐terminated charset names for which no fonts exist,
and charset_count is set to the number of missing charsets.
The charsets are from the list of the required charsets for
the encoding of the locale and do not include any charsets
to which Xlib may be able to remap a required charset.

The missing charset list is owned by Xlib and should not be
modified or freed by the client.  It will be freed by a call
to _X_D_e_s_t_r_o_y_O_C with the associated _X_O_C.  Until freed, its
contents will not be modified by Xlib.

1133..44..55..33..  DDeeffaauulltt SSttrriinngg

When a drawing or measuring function is called with an _X_O_C
that has missing charsets, some characters in the locale
will not be drawable.  The _X_N_D_e_f_a_u_l_t_S_t_r_i_n_g argument returns
a pointer to a string that represents the glyphs that are
drawn with this _X_O_C when the charsets of the available fonts
do not include all glyphs required to draw a character.  The
string does not necessarily consist of valid characters in
the current locale and is not necessarily drawn with the
fonts loaded for the font set, but the client can draw or
measure the default glyphs by including this string in a
string being drawn or measured with the _X_O_C.

If the _X_N_D_e_f_a_u_l_t_S_t_r_i_n_g argument returned the empty string
(""), no glyphs are drawn and the escapement is zero.  The
returned string is null‐terminated.  It is owned by Xlib and
should not be modified or freed by the client.  It will be
freed by a call to _X_D_e_s_t_r_o_y_O_C with the associated _X_O_C.
Until freed, its contents will not be modified by Xlib.

1133..44..55..44..  OOrriieennttaattiioonn

The _X_N_O_r_i_e_n_t_a_t_i_o_n argument specifies the current orientation
of text when drawn.  The value of this argument is one of
the values returned by the _X_G_e_t_O_M_V_a_l_u_e_s function with the
_X_N_Q_u_e_r_y_O_r_i_e_n_t_a_t_i_o_n argument specified in the _X_O_r_i_e_n_t_a_t_i_o_n
list.  The value of the argument is of type _X_O_r_i_e_n_t_a_t_i_o_n.
When _X_N_O_r_i_e_n_t_a_t_i_o_n is queried, the value specifies the cur­
rent orientation.  When _X_N_O_r_i_e_n_t_a_t_i_o_n is set, a value is
used to set the current orientation.




                             441100





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


When _X_O_M_O_r_i_e_n_t_a_t_i_o_n___C_o_n_t_e_x_t is set, the text orientation of
the text is determined according to an implementation‐
defined method (for example, ISO 6429 control sequences),
and the initial text orientation for locale‐dependent Xlib
functions is assumed to be _X_O_M_O_r_i_e_n_t_a_t_i_o_n___L_T_R___T_T_B.

The _X_N_O_r_i_e_n_t_a_t_i_o_n value does not change the prime drawing
direction for Xlib drawing functions.

1133..44..55..55..  RReessoouurrccee NNaammee aanndd CCllaassss

The _X_N_R_e_s_o_u_r_c_e_N_a_m_e and _X_N_R_e_s_o_u_r_c_e_C_l_a_s_s arguments are strings
that specify the full name and class used by the client to
obtain resources for the display of the output context.
These values should be used as prefixes for name and class
when looking up resources that may vary according to the
output context.  If these values are not set, the resources
will not be fully specified.

It is not intended that values that can be set as XOM values
be set as resources.

When querying for the _X_N_R_e_s_o_u_r_c_e_N_a_m_e or _X_N_R_e_s_o_u_r_c_e_C_l_a_s_s XOC
value, _X_G_e_t_O_C_V_a_l_u_e_s returns a null‐terminated string.  This
string is owned by Xlib and should not be modified or freed
by the client.  The string will be freed by a call to _X_D_e_­
_s_t_r_o_y_O_C with the associated _X_O_C or when the associated value
is changed via _X_S_e_t_O_C_V_a_l_u_e_s.  Until freed, the string con­
tents will not be modified by Xlib.

1133..44..55..66..  FFoonntt IInnffoo

The _X_N_F_o_n_t_I_n_f_o argument specifies a list of one or more
_X_F_o_n_t_S_t_r_u_c_t structures and font names for the fonts used for
drawing by the given output context.  The value of the argu­
ment is a pointer to a structure of type _X_O_M_F_o_n_t_I_n_f_o.

__
││
typedef struct {
     int num_font;
     XFontStruct **font_struct_list;
     char **font_name_list;
} XOMFontInfo;

││__

A list of pointers to the _X_F_o_n_t_S_t_r_u_c_t structures is returned
to font_struct_list.  A list of pointers to null‐terminated,
fully‐specified font name strings in the locale of the out­
put context is returned to font_name_list.  The
font_name_list order corresponds to the font_struct_list
order.  The number of _X_F_o_n_t_S_t_r_u_c_t structures and font names
is returned to num_font.



                             441111





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Because it is not guaranteed that a given character will be
imaged using a single font glyph, there is no provision for
mapping a character or default string to the font proper­
ties, font ID, or direction hint for the font for the char­
acter.  The client may access the _X_F_o_n_t_S_t_r_u_c_t list to obtain
these values for all the fonts currently in use.

Xlib does not guarantee that fonts are loaded from the
server at the creation of an _X_O_C.  Xlib may choose to cache
font data, loading it only as needed to draw text or compute
text dimensions.  Therefore, existence of the per_char met­
rics in the _X_F_o_n_t_S_t_r_u_c_t structures in the _X_F_o_n_t_S_t_r_u_c_t_S_e_t is
undefined.  Also, note that all properties in the
_X_F_o_n_t_S_t_r_u_c_t structures are in the STRING encoding.

The client must not free the _X_O_M_F_o_n_t_I_n_f_o struct itself; it
will be freed when the _X_O_C is closed.

1133..44..55..77..  OOMM AAuuttoommaattiicc

The _X_N_O_M_A_u_t_o_m_a_t_i_c argument returns whether the associated
output context was created by _X_C_r_e_a_t_e_F_o_n_t_S_e_t or not.
Because the _X_F_r_e_e_F_o_n_t_S_e_t function not only destroys the out­
put context but also closes the implicit output method asso­
ciated with it, _X_F_r_e_e_F_o_n_t_S_e_t should be used with any output
context created by _X_C_r_e_a_t_e_F_o_n_t_S_e_t.  However, it is possible
that a client does not know how the output context was cre­
ated.  Before a client destroys the output context, it can
query whether _X_N_O_M_A_u_t_o_m_a_t_i_c is set to determine whether
_X_F_r_e_e_F_o_n_t_S_e_t or _X_D_e_s_t_r_o_y_O_C should be used to destroy the
output context.

1133..44..66..  CCrreeaattiinngg aanndd FFrreeeeiinngg aa FFoonntt SSeett

Xlib international text drawing is done using a set of one
or more fonts, as needed for the locale of the text.  Fonts
are loaded according to a list of base font names supplied
by the client and the charsets required by the locale.  The
_X_F_o_n_t_S_e_t is an opaque type representing the state of a par­
ticular output thread and is equivalent to the type _X_O_C.


The _X_C_r_e_a_t_e_F_o_n_t_S_e_t function is a convenience function for
creating an output context using only default values.  The
returned _X_F_o_n_t_S_e_t has an implicitly created _X_O_M.  This _X_O_M
has an OM value _X_N_O_M_A_u_t_o_m_a_t_i_c automatically set to _T_r_u_e so
that the output context self indicates whether it was cre­
ated by _X_C_r_e_a_t_e_O_C or _X_C_r_e_a_t_e_F_o_n_t_S_e_t.









                             441122





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XFontSet XCreateFontSet(_d_i_s_p_l_a_y, _b_a_s_e___f_o_n_t___n_a_m_e___l_i_s_t, _m_i_s_s_i_n_g___c_h_a_r_s_e_t___l_i_s_t___r_e_t_u_r_n,
               _m_i_s_s_i_n_g___c_h_a_r_s_e_t___c_o_u_n_t___r_e_t_u_r_n, _d_e_f___s_t_r_i_n_g___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      char *_b_a_s_e___f_o_n_t___n_a_m_e___l_i_s_t;
      char ***_m_i_s_s_i_n_g___c_h_a_r_s_e_t___l_i_s_t___r_e_t_u_r_n;
      int *_m_i_s_s_i_n_g___c_h_a_r_s_e_t___c_o_u_n_t___r_e_t_u_r_n;
      char **_d_e_f___s_t_r_i_n_g___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_b_a_s_e___f_o_n_t___n_a_m_e___l_i_s_t
          Specifies the base font names.

_m_i_s_s_i_n_g___c_h_a_r_s_e_t___l_i_s_t___r_e_t_u_r_n
          Returns the missing charsets.

_m_i_s_s_i_n_g___c_h_a_r_s_e_t___c_o_u_n_t___r_e_t_u_r_n
          Returns the number of missing charsets.

_d_e_f___s_t_r_i_n_g___r_e_t_u_r_n
          Returns the string drawn for missing charsets.
││__

The _X_C_r_e_a_t_e_F_o_n_t_S_e_t function creates a font set for the spec­
ified display.  The font set is bound to the current locale
when _X_C_r_e_a_t_e_F_o_n_t_S_e_t is called.  The font set may be used in
subsequent calls to obtain font and character information
and to image text in the locale of the font set.

The base_font_name_list argument is a list of base font
names that Xlib uses to load the fonts needed for the
locale.  The base font names are a comma‐separated list.
The string is null‐terminated and is assumed to be in the
Host Portable Character Encoding; otherwise, the result is
implementation‐dependent.  White space immediately on either
side of a separating comma is ignored.

Use of XLFD font names permits Xlib to obtain the fonts
needed for a variety of locales from a single locale‐inde­
pendent base font name.  The single base font name should
name a family of fonts whose members are encoded in the var­
ious charsets needed by the locales of interest.

An XLFD base font name can explicitly name a charset needed
for the locale.  This allows the user to specify an exact
font for use with a charset required by a locale, fully con­
trolling the font selection.

If a base font name is not an XLFD name, Xlib will attempt
to obtain an XLFD name from the font properties for the
font.  If this action is successful in obtaining an XLFD
name, the _X_B_a_s_e_F_o_n_t_N_a_m_e_L_i_s_t_O_f_F_o_n_t_S_e_t function will return



                             441133





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


this XLFD name instead of the client‐supplied name.

Xlib uses the following algorithm to select the fonts that
will be used to display text with the _X_F_o_n_t_S_e_t.

For each font charset required by the locale, the base font
name list is searched for the first appearance of one of the
following cases that names a set of fonts that exist at the
server:

⋅    The first XLFD‐conforming base font name that specifies
     the required charset or a superset of the required
     charset in its _C_h_a_r_S_e_t_R_e_g_i_s_t_r_y and _C_h_a_r_S_e_t_E_n_c_o_d_i_n_g
     fields.  The implementation may use a base font name
     whose specified charset is a superset of the required
     charset, for example, an ISO8859‐1 font for an ASCII
     charset.

⋅    The first set of one or more XLFD‐conforming base font
     names that specify one or more charsets that can be
     remapped to support the required charset.  The Xlib
     implementation may recognize various mappings from a
     required charset to one or more other charsets and use
     the fonts for those charsets.  For example, JIS Roman
     is ASCII with tilde and backslash replaced by yen and
     overbar; Xlib may load an ISO8859‐1 font to support
     this character set if a JIS Roman font is not avail­
     able.

⋅    The first XLFD‐conforming font name or the first non‐
     XLFD font name for which an XLFD font name can be
     obtained, combined with the required charset (replacing
     the _C_h_a_r_S_e_t_R_e_g_i_s_t_r_y and _C_h_a_r_S_e_t_E_n_c_o_d_i_n_g fields in the
     XLFD font name).  As in case 1, the implementation may
     use a charset that is a superset of the required
     charset.

⋅    The first font name that can be mapped in some imple­
     mentation‐dependent manner to one or more fonts that
     support imaging text in the charset.

For example, assume that a locale required the charsets:


ISO8859‐1
JISX0208.1983
JISX0201.1976
GB2312‐1980.0


The user could supply a base_font_name_list that explicitly
specifies the charsets, ensuring that specific fonts are
used if they exist.  For example:




                             441144





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


"‐JIS‐Fixed‐Medium‐R‐Normal‐‐26‐180‐100‐100‐C‐240‐JISX0208.1983‐0,\
‐JIS‐Fixed‐Medium‐R‐Normal‐‐26‐180‐100‐100‐C‐120‐JISX0201.1976‐0,\
‐GB‐Fixed‐Medium‐R‐Normal‐‐26‐180‐100‐100‐C‐240‐GB2312‐1980.0,\
‐Adobe‐Courier‐Bold‐R‐Normal‐‐25‐180‐75‐75‐M‐150‐ISO8859‐1"


Alternatively, the user could supply a base_font_name_list
that omits the charsets, letting Xlib select font charsets
required for the locale.  For example:


"‐JIS‐Fixed‐Medium‐R‐Normal‐‐26‐180‐100‐100‐C‐240,\
‐JIS‐Fixed‐Medium‐R‐Normal‐‐26‐180‐100‐100‐C‐120,\
‐GB‐Fixed‐Medium‐R‐Normal‐‐26‐180‐100‐100‐C‐240,\
‐Adobe‐Courier‐Bold‐R‐Normal‐‐25‐180‐100‐100‐M‐150"


Alternatively, the user could simply supply a single base
font name that allows Xlib to select from all available
fonts that meet certain minimum XLFD property requirements.
For example:


"‐*‐*‐*‐R‐Normal‐‐*‐180‐100‐100‐*‐*"


If _X_C_r_e_a_t_e_F_o_n_t_S_e_t is unable to create the font set, either
because there is insufficient memory or because the current
locale is not supported, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns NULL, miss­
ing_charset_list_return is set to NULL, and miss­
ing_charset_count_return is set to zero.  If fonts exist for
all of the charsets required by the current locale, _X_C_r_e_a_t_e_­
_F_o_n_t_S_e_t returns a valid _X_F_o_n_t_S_e_t, miss­
ing_charset_list_return is set to NULL, and miss­
ing_charset_count_return is set to zero.

If no font exists for one or more of the required charsets,
_X_C_r_e_a_t_e_F_o_n_t_S_e_t sets missing_charset_list_return to a list of
one or more null‐terminated charset names for which no font
exists and sets missing_charset_count_return to the number
of missing fonts.  The charsets are from the list of the
required charsets for the encoding of the locale and do not
include any charsets to which Xlib may be able to remap a
required charset.

If no font exists for any of the required charsets or if the
locale definition in Xlib requires that a font exist for a
particular charset and a font is not found for that charset,
_X_C_r_e_a_t_e_F_o_n_t_S_e_t returns NULL.  Otherwise, _X_C_r_e_a_t_e_F_o_n_t_S_e_t
returns a valid _X_F_o_n_t_S_e_t to font_set.

When an Xmb/wc drawing or measuring function is called with
an _X_F_o_n_t_S_e_t that has missing charsets, some characters in
the locale will not be drawable.  If def_string_return is



                             441155





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


non‐NULL, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns a pointer to a string that
represents the glyphs that are drawn with this _X_F_o_n_t_S_e_t when
the charsets of the available fonts do not include all font
glyphs required to draw a codepoint.  The string does not
necessarily consist of valid characters in the current
locale and is not necessarily drawn with the fonts loaded
for the font set, but the client can draw and measure the
default glyphs by including this string in a string being
drawn or measured with the _X_F_o_n_t_S_e_t.

If the string returned to def_string_return is the empty
string (""), no glyphs are drawn, and the escapement is
zero.  The returned string is null‐terminated.  It is owned
by Xlib and should not be modified or freed by the client.
It will be freed by a call to _X_F_r_e_e_F_o_n_t_S_e_t with the associ­
ated _X_F_o_n_t_S_e_t.  Until freed, its contents will not be modi­
fied by Xlib.

The client is responsible for constructing an error message
from the missing charset and default string information and
may choose to continue operation in the case that some fonts
did not exist.

The returned _X_F_o_n_t_S_e_t and missing charset list should be
freed with _X_F_r_e_e_F_o_n_t_S_e_t and _X_F_r_e_e_S_t_r_i_n_g_L_i_s_t, respectively.
The client‐supplied base_font_name_list may be freed by the
client after calling _X_C_r_e_a_t_e_F_o_n_t_S_e_t.


To obtain a list of _X_F_o_n_t_S_t_r_u_c_t structures and full font
names given an _X_F_o_n_t_S_e_t, use _X_F_o_n_t_s_O_f_F_o_n_t_S_e_t.
__
││
int XFontsOfFontSet(_f_o_n_t___s_e_t, _f_o_n_t___s_t_r_u_c_t___l_i_s_t___r_e_t_u_r_n, _f_o_n_t___n_a_m_e___l_i_s_t___r_e_t_u_r_n)
       XFontSet _f_o_n_t___s_e_t;
       XFontStruct ***_f_o_n_t___s_t_r_u_c_t___l_i_s_t___r_e_t_u_r_n;
       char ***_f_o_n_t___n_a_m_e___l_i_s_t___r_e_t_u_r_n;


_f_o_n_t___s_e_t  Specifies the font set.

_f_o_n_t___s_t_r_u_c_t___l_i_s_t___r_e_t_u_r_n
          Returns the list of font structs.

_f_o_n_t___n_a_m_e___l_i_s_t___r_e_t_u_r_n
          Returns the list of font names.
││__

The _X_F_o_n_t_s_O_f_F_o_n_t_S_e_t function returns a list of one or more
_X_F_o_n_t_S_t_r_u_c_t_s and font names for the fonts used by the Xmb
and Xwc layers for the given font set.  A list of pointers
to the _X_F_o_n_t_S_t_r_u_c_t structures is returned to
font_struct_list_return.  A list of pointers to null‐termi­
nated, fully specified font name strings in the locale of



                             441166





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the font set is returned to font_name_list_return.  The
font_name_list order corresponds to the font_struct_list
order.  The number of _X_F_o_n_t_S_t_r_u_c_t structures and font names
is returned as the value of the function.

Because it is not guaranteed that a given character will be
imaged using a single font glyph, there is no provision for
mapping a character or default string to the font proper­
ties, font ID, or direction hint for the font for the char­
acter.  The client may access the _X_F_o_n_t_S_t_r_u_c_t list to obtain
these values for all the fonts currently in use.

Xlib does not guarantee that fonts are loaded from the
server at the creation of an _X_F_o_n_t_S_e_t.  Xlib may choose to
cache font data, loading it only as needed to draw text or
compute text dimensions.  Therefore, existence of the
per_char metrics in the _X_F_o_n_t_S_t_r_u_c_t structures in the
_X_F_o_n_t_S_t_r_u_c_t_S_e_t is undefined.  Also, note that all properties
in the _X_F_o_n_t_S_t_r_u_c_t structures are in the STRING encoding.

The _X_F_o_n_t_S_t_r_u_c_t and font name lists are owned by Xlib and
should not be modified or freed by the client.  They will be
freed by a call to _X_F_r_e_e_F_o_n_t_S_e_t with the associated
_X_F_o_n_t_S_e_t.  Until freed, their contents will not be modified
by Xlib.


To obtain the base font name list and the selected font name
list given an _X_F_o_n_t_S_e_t, use _X_B_a_s_e_F_o_n_t_N_a_m_e_L_i_s_t_O_f_F_o_n_t_S_e_t.
__
││
char *XBaseFontNameListOfFontSet(_f_o_n_t___s_e_t)
      XFontSet _f_o_n_t___s_e_t;


_f_o_n_t___s_e_t  Specifies the font set.
││__

The _X_B_a_s_e_F_o_n_t_N_a_m_e_L_i_s_t_O_f_F_o_n_t_S_e_t function returns the original
base font name list supplied by the client when the _X_F_o_n_t_S_e_t
was created.  A null‐terminated string containing a list of
comma‐separated font names is returned as the value of the
function.  White space may appear immediately on either side
of separating commas.

If _X_C_r_e_a_t_e_F_o_n_t_S_e_t obtained an XLFD name from the font prop­
erties for the font specified by a non‐XLFD base name, the
_X_B_a_s_e_F_o_n_t_N_a_m_e_L_i_s_t_O_f_F_o_n_t_S_e_t function will return the XLFD
name instead of the non‐XLFD base name.

The base font name list is owned by Xlib and should not be
modified or freed by the client.  It will be freed by a call
to _X_F_r_e_e_F_o_n_t_S_e_t with the associated _X_F_o_n_t_S_e_t.  Until freed,
its contents will not be modified by Xlib.



                             441177





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To obtain the locale name given an _X_F_o_n_t_S_e_t, use _X_L_o_c_a_l_e_O_f_­
_F_o_n_t_S_e_t.
__
││
char *XLocaleOfFontSet(_f_o_n_t___s_e_t)
      XFontSet _f_o_n_t___s_e_t;


_f_o_n_t___s_e_t  Specifies the font set.
││__

The _X_L_o_c_a_l_e_O_f_F_o_n_t_S_e_t function returns the name of the locale
bound to the specified _X_F_o_n_t_S_e_t, as a null‐terminated
string.

The returned locale name string is owned by Xlib and should
not be modified or freed by the client.  It may be freed by
a call to _X_F_r_e_e_F_o_n_t_S_e_t with the associated _X_F_o_n_t_S_e_t.  Until
freed, it will not be modified by Xlib.


The _X_F_r_e_e_F_o_n_t_S_e_t function is a convenience function for
freeing an output context.  _X_F_r_e_e_F_o_n_t_S_e_t also frees its
associated _X_O_M if the output context was created by _X_C_r_e_a_t_e_­
_F_o_n_t_S_e_t.
__
││
void XFreeFontSet(_d_i_s_p_l_a_y, _f_o_n_t___s_e_t)
      Display *_d_i_s_p_l_a_y;
      XFontSet _f_o_n_t___s_e_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_o_n_t___s_e_t  Specifies the font set.
││__

The _X_F_r_e_e_F_o_n_t_S_e_t function frees the specified font set.  The
associated base font name list, font name list, _X_F_o_n_t_S_t_r_u_c_t
list, and _X_F_o_n_t_S_e_t_E_x_t_e_n_t_s, if any, are freed.

1133..44..77..  OObbttaaiinniinngg FFoonntt SSeett MMeettrriiccss

Metrics for the internationalized text drawing functions are
defined in terms of a primary draw direction, which is the
default direction in which the character origin advances for
each succeeding character in the string.  The Xlib interface
is currently defined to support only a left‐to‐right primary
draw direction.  The drawing origin is the position passed
to the drawing function when the text is drawn.  The base­
line is a line drawn through the drawing origin parallel to
the primary draw direction.  Character ink is the pixels
painted in the foreground color and does not include inter­
line or intercharacter spacing or image text background



                             441188





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


pixels.

The drawing functions are allowed to implement implicit text
directionality control, reversing the order in which charac­
ters are rendered along the primary draw direction in
response to locale‐specific lexical analysis of the string.

Regardless of the character rendering order, the origins of
all characters are on the primary draw direction side of the
drawing origin.  The screen location of a particular charac­
ter image may be determined with _X_m_b_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s or
_X_w_c_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s.

The drawing functions are allowed to implement context‐
dependent rendering, where the glyphs drawn for a string are
not simply a concatenation of the glyphs that represent each
individual character.  A string of two characters drawn with
_X_m_b_D_r_a_w_S_t_r_i_n_g may render differently than if the two charac­
ters were drawn with separate calls to _X_m_b_D_r_a_w_S_t_r_i_n_g.  If
the client appends or inserts a character in a previously
drawn string, the client may need to redraw some adjacent
characters to obtain proper rendering.


To find out about direction‐dependent rendering, use _X_D_i_r_e_c_­
_t_i_o_n_a_l_D_e_p_e_n_d_e_n_t_D_r_a_w_i_n_g.
__
││
Bool XDirectionalDependentDrawing(_f_o_n_t___s_e_t)
      XFontSet _f_o_n_t___s_e_t;


_f_o_n_t___s_e_t  Specifies the font set.
││__

The _X_D_i_r_e_c_t_i_o_n_a_l_D_e_p_e_n_d_e_n_t_D_r_a_w_i_n_g function returns _T_r_u_e if
the drawing functions implement implicit text directional­
ity; otherwise, it returns _F_a_l_s_e.


To find out about context‐dependent rendering, use _X_C_o_n_t_e_x_­
_t_u_a_l_D_r_a_w_i_n_g.
__
││
Bool XContextualDrawing(_f_o_n_t___s_e_t)
      XFontSet _f_o_n_t___s_e_t;


_f_o_n_t___s_e_t  Specifies the font set.
││__

The _X_C_o_n_t_e_x_t_u_a_l_D_r_a_w_i_n_g function returns _T_r_u_e if text drawn
with the font set might include context‐dependent drawing;
otherwise, it returns _F_a_l_s_e.



                             441199





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To find out about context‐dependent or direction‐dependent
rendering, use _X_C_o_n_t_e_x_t_D_e_p_e_n_d_e_n_t_D_r_a_w_i_n_g.
__
││
Bool XContextDependentDrawing(_f_o_n_t___s_e_t)
      XFontSet _f_o_n_t___s_e_t;


_f_o_n_t___s_e_t  Specifies the font set.
││__

The _X_C_o_n_t_e_x_t_D_e_p_e_n_d_e_n_t_D_r_a_w_i_n_g function returns _T_r_u_e if the
drawing functions implement implicit text directionality or
if text drawn with the font_set might include context‐depen­
dent drawing; otherwise, it returns _F_a_l_s_e.

The drawing functions do not interpret newline, tab, or
other control characters.  The behavior when nonprinting
characters other than space are drawn is implementation‐
dependent.  It is the client’s responsibility to interpret
control characters in a text stream.

The maximum character extents for the fonts that are used by
the text drawing layers can be accessed by the _X_F_o_n_t_S_e_t_E_x_­
_t_e_n_t_s structure:


typedef struct {
     XRectangle max_ink_extent;/* over all drawable characters */
     XRectangle max_logical_extent;/* over all drawable characters */
} XFontSetExtents;


The _X_R_e_c_t_a_n_g_l_e structures used to return font set metrics
are the usual Xlib screen‐oriented rectangles with x, y giv­
ing the upper left corner, and width and height always posi­
tive.

The max_ink_extent member gives the maximum extent, over all
drawable characters, of the rectangles that bound the char­
acter glyph image drawn in the foreground color, relative to
a constant origin.  See _X_m_b_T_e_x_t_E_x_t_e_n_t_s and _X_w_c_T_e_x_t_E_x_t_e_n_t_s
for detailed semantics.

The max_logical_extent member gives the maximum extent, over
all drawable characters, of the rectangles that specify min­
imum spacing to other graphical features, relative to a con­
stant origin.  Other graphical features drawn by the client,
for example, a border surrounding the text, should not
intersect this rectangle.  The max_logical_extent member
should be used to compute minimum interline spacing and the
minimum area that must be allowed in a text field to draw a
given number of arbitrary characters.




                             442200





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Due to context‐dependent rendering, appending a given char­
acter to a string may change the string’s extent by an
amount other than that character’s individual extent.

The rectangles for a given character in a string can be
obtained from _X_m_b_P_e_r_C_h_a_r_E_x_t_e_n_t_s or _X_w_c_P_e_r_C_h_a_r_E_x_t_e_n_t_s.


To obtain the maximum extents structure given an _X_F_o_n_t_S_e_t,
use _X_E_x_t_e_n_t_s_O_f_F_o_n_t_S_e_t.
__
││
XFontSetExtents *XExtentsOfFontSet(_f_o_n_t___s_e_t)
       XFontSet _f_o_n_t___s_e_t;


_f_o_n_t___s_e_t  Specifies the font set.
││__

The _X_E_x_t_e_n_t_s_O_f_F_o_n_t_S_e_t function returns an _X_F_o_n_t_S_e_t_E_x_t_e_n_t_s
structure for the fonts used by the Xmb and Xwc layers for
the given font set.

The _X_F_o_n_t_S_e_t_E_x_t_e_n_t_s structure is owned by Xlib and should
not be modified or freed by the client.  It will be freed by
a call to _X_F_r_e_e_F_o_n_t_S_e_t with the associated _X_F_o_n_t_S_e_t.  Until
freed, its contents will not be modified by Xlib.


To obtain the escapement in pixels of the specified text as
a value, use _X_m_b_T_e_x_t_E_s_c_a_p_e_m_e_n_t or _X_w_c_T_e_x_t_E_s_c_a_p_e_m_e_n_t.


























                             442211





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XmbTextEscapement(_f_o_n_t___s_e_t, _s_t_r_i_n_g, _n_u_m___b_y_t_e_s)
      XFontSet _f_o_n_t___s_e_t;
      char *_s_t_r_i_n_g;
      int _n_u_m___b_y_t_e_s;


int XwcTextEscapement(_f_o_n_t___s_e_t, _s_t_r_i_n_g, _n_u_m___w_c_h_a_r_s)
      XFontSet _f_o_n_t___s_e_t;
      wchar_t *_s_t_r_i_n_g;
      int _n_u_m___w_c_h_a_r_s;


_f_o_n_t___s_e_t  Specifies the font set.

_s_t_r_i_n_g    Specifies the character string.

_n_u_m___b_y_t_e_s Specifies the number of bytes in the string argu­
          ment.

_n_u_m___w_c_h_a_r_s
          Specifies the number of characters in the string
          argument.
││__

The _X_m_b_T_e_x_t_E_s_c_a_p_e_m_e_n_t and _X_w_c_T_e_x_t_E_s_c_a_p_e_m_e_n_t functions return
the escapement in pixels of the specified string as a value,
using the fonts loaded for the specified font set.  The
escapement is the distance in pixels in the primary draw
direction from the drawing origin to the origin of the next
character to be drawn, assuming that the rendering of the
next character is not dependent on the supplied string.

Regardless of the character rendering order, the escapement
is always positive.


To obtain the overall_ink_return and overall_logical_return
arguments, the overall bounding box of the string’s image,
and a logical bounding box, use _X_m_b_T_e_x_t_E_x_t_e_n_t_s
 or _X_w_c_T_e_x_t_E_x_t_e_n_t_s.
















                             442222





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XmbTextExtents(_f_o_n_t___s_e_t, _s_t_r_i_n_g, _n_u_m___b_y_t_e_s, _o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n, _o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n)
      XFontSet _f_o_n_t___s_e_t;
      char *_s_t_r_i_n_g;
      int _n_u_m___b_y_t_e_s;
      XRectangle *_o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n;
      XRectangle *_o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n;


int XwcTextExtents(_f_o_n_t___s_e_t, _s_t_r_i_n_g, _n_u_m___w_c_h_a_r_s,
_o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n, _o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n)
      XFontSet _f_o_n_t___s_e_t;
      wchar_t *_s_t_r_i_n_g;
      int _n_u_m___w_c_h_a_r_s;
      XRectangle *_o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n;
      XRectangle *_o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n;


_f_o_n_t___s_e_t  Specifies the font set.

_s_t_r_i_n_g    Specifies the character string.

_n_u_m___b_y_t_e_s Specifies the number of bytes in the string argu­
          ment.

_n_u_m___w_c_h_a_r_s
          Specifies the number of characters in the string
          argument.

_o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n
          Returns the overall ink dimensions.

_o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n
          Returns the overall logical dimensions.
││__

The _X_m_b_T_e_x_t_E_x_t_e_n_t_s and _X_w_c_T_e_x_t_E_x_t_e_n_t_s functions set the com­
ponents of the specified overall_ink_return and overall_log­
ical_return arguments to the overall bounding box of the
string’s image and a logical bounding box for spacing pur­
poses, respectively.  They return the value returned by _X_m_b_­
_T_e_x_t_E_s_c_a_p_e_m_e_n_t or _X_w_c_T_e_x_t_E_s_c_a_p_e_m_e_n_t.  These metrics are rel­
ative to the drawing origin of the string, using the fonts
loaded for the specified font set.

If the overall_ink_return argument is non‐NULL, it is set to
the bounding box of the string’s character ink.  The over­
all_ink_return for a nondescending, horizontally drawn Latin
character is conventionally entirely above the baseline;
that is, overall_ink_return.height <= −overall_ink_return.y.
The overall_ink_return for a nonkerned character is entirely
at, and to the right of, the origin; that is, over­
all_ink_return.x >= 0.  A character consisting of a single
pixel at the origin would set overall_ink_return fields y =



                             442233





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


0, x = 0, width = 1, and height = 1.

If the overall_logical_return argument is non‐NULL, it is
set to the bounding box that provides minimum spacing to
other graphical features for the string.  Other graphical
features, for example, a border surrounding the text, should
not intersect this rectangle.

When the _X_F_o_n_t_S_e_t has missing charsets, metrics for each
unavailable character are taken from the default string
returned by _X_C_r_e_a_t_e_F_o_n_t_S_e_t so that the metrics represent the
text as it will actually be drawn.  The behavior for an
invalid codepoint is undefined.

To determine the effective drawing origin for a character in
a drawn string, the client should call _X_m_b_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s
on the entire string, then on the character, and subtract
the x values of the returned rectangles for the character.
This is useful to redraw portions of a line of text or to
justify words, but for context‐dependent rendering, the
client should not assume that it can redraw the character by
itself and get the same rendering.


To obtain per‐character information for a text string, use
_X_m_b_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s or _X_w_c_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s.































                             442244





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XmbTextPerCharExtents(_f_o_n_t___s_e_t, _s_t_r_i_n_g, _n_u_m___b_y_t_e_s, _i_n_k___a_r_r_a_y___r_e_t_u_r_n,
           _l_o_g_i_c_a_l___a_r_r_a_y___r_e_t_u_r_n, _a_r_r_a_y___s_i_z_e, _n_u_m___c_h_a_r_s___r_e_t_u_r_n, _o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n, _o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n)
      XFontSet _f_o_n_t___s_e_t;
      char *_s_t_r_i_n_g;
      int _n_u_m___b_y_t_e_s;
      XRectangle *_i_n_k___a_r_r_a_y___r_e_t_u_r_n;
      XRectangle *_l_o_g_i_c_a_l___a_r_r_a_y___r_e_t_u_r_n;
      int _a_r_r_a_y___s_i_z_e;
      int *_n_u_m___c_h_a_r_s___r_e_t_u_r_n;
      XRectangle *_o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n;
      XRectangle *_o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n;


Status XwcTextPerCharExtents(_f_o_n_t___s_e_t, _s_t_r_i_n_g, _n_u_m___w_c_h_a_r_s, _i_n_k___a_r_r_a_y___r_e_t_u_r_n,
          _l_o_g_i_c_a_l___a_r_r_a_y___r_e_t_u_r_n, _a_r_r_a_y___s_i_z_e, _n_u_m___c_h_a_r_s___r_e_t_u_r_n, _o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n, _o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n)
      XFontSet _f_o_n_t___s_e_t;
      wchar_t *_s_t_r_i_n_g;
      int _n_u_m___w_c_h_a_r_s;
      XRectangle *_i_n_k___a_r_r_a_y___r_e_t_u_r_n;
      XRectangle *_l_o_g_i_c_a_l___a_r_r_a_y___r_e_t_u_r_n;
      int _a_r_r_a_y___s_i_z_e;
      int *_n_u_m___c_h_a_r_s___r_e_t_u_r_n;
      XRectangle *_o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n;
      XRectangle *_o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n;


_f_o_n_t___s_e_t  Specifies the font set.

_s_t_r_i_n_g    Specifies the character string.

_n_u_m___b_y_t_e_s Specifies the number of bytes in the string argu­
          ment.

_n_u_m___w_c_h_a_r_s
          Specifies the number of characters in the string
          argument.

_i_n_k___a_r_r_a_y___r_e_t_u_r_n
          Returns the ink dimensions for each character.

_l_o_g_i_c_a_l___a_r_r_a_y___r_e_t_u_r_n
          Returns the logical dimensions for each character.

_a_r_r_a_y___s_i_z_e
          Specifies the size of ink_array_return and logi­
          cal_array_return.  The caller must pass in arrays
          of this size.

_n_u_m___c_h_a_r_s___r_e_t_u_r_n
          Returns the number of characters in the string
          argument.

_o_v_e_r_a_l_l___i_n_k___r_e_t_u_r_n



                             442255





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


          Returns the overall ink extents of the entire
          string.

_o_v_e_r_a_l_l___l_o_g_i_c_a_l___r_e_t_u_r_n
          Returns the overall logical extents of the entire
          string.
││__

The _X_m_b_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s and _X_w_c_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s func­
tions return the text dimensions of each character of the
specified text, using the fonts loaded for the specified
font set.  Each successive element of ink_array_return and
logical_array_return is set to the successive character’s
drawn metrics, relative to the drawing origin of the string
and one rectangle for each character in the supplied text
string.  The number of elements of ink_array_return and log­
ical_array_return that have been set is returned to
num_chars_return.

Each element of ink_array_return is set to the bounding box
of the corresponding character’s drawn foreground color.
Each element of logical_array_return is set to the bounding
box that provides minimum spacing to other graphical fea­
tures for the corresponding character.  Other graphical fea­
tures should not intersect any of the logical_array_return
rectangles.

Note that an _X_R_e_c_t_a_n_g_l_e represents the effective drawing
dimensions of the character, regardless of the number of
font glyphs that are used to draw the character or the
direction in which the character is drawn.  If multiple
characters map to a single character glyph, the dimensions
of all the _X_R_e_c_t_a_n_g_l_e_s of those characters are the same.

When the _X_F_o_n_t_S_e_t has missing charsets, metrics for each
unavailable character are taken from the default string
returned by _X_C_r_e_a_t_e_F_o_n_t_S_e_t so that the metrics represent the
text as it will actually be drawn.  The behavior for an
invalid codepoint is undefined.

If the array_size is too small for the number of characters
in the supplied text, the functions return zero and
num_chars_return is set to the number of rectangles
required.  Otherwise, the functions return a nonzero value.

If the overall_ink_return or overall_logical_return argument
is non‐NULL, _X_m_b_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s and _X_w_c_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s
return the maximum extent of the string’s metrics to over­
all_ink_return or overall_logical_return, as returned by
_X_m_b_T_e_x_t_E_x_t_e_n_t_s or _X_w_c_T_e_x_t_E_x_t_e_n_t_s.







                             442266





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1133..44..88..  DDrraawwiinngg TTeexxtt UUssiinngg FFoonntt SSeettss

The functions defined in this section draw text at a speci­
fied location in a drawable.  They are similar to the func­
tions _X_D_r_a_w_T_e_x_t, _X_D_r_a_w_S_t_r_i_n_g, and _X_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g except
that they work with font sets instead of single fonts and
interpret the text based on the locale of the font set
instead of treating the bytes of the string as direct font
indexes.  See section 8.6 for details of the use of Graphics
Contexts (GCs) and possible protocol errors.  If a _B_a_d_F_o_n_t
error is generated, characters prior to the offending char­
acter may have been drawn.

The text is drawn using the fonts loaded for the specified
font set; the font in the GC is ignored and may be modified
by the functions.  No validation that all fonts conform to
some width rule is performed.

The text functions _X_m_b_D_r_a_w_T_e_x_t and _X_w_c_D_r_a_w_T_e_x_t use the fol­
lowing structures:

__
││
typedef struct {
     char *chars;        /* pointer to string */
     int nchars;         /* number of bytes */
     int delta;          /* pixel delta between strings */
     XFontSet font_set;  /* fonts, None means don’t change */
} XmbTextItem;



typedef struct {
     wchar_t *chars;     /* pointer to wide char string */
     int nchars;         /* number of wide characters */
     int delta;          /* pixel delta between strings */
     XFontSet font_set;  /* fonts, None means don’t change */
} XwcTextItem;

││__


To draw text using multiple font sets in a given drawable,
use _X_m_b_D_r_a_w_T_e_x_t or _X_w_c_D_r_a_w_T_e_x_t.













                             442277





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XmbDrawText(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _i_t_e_m_s, _n_i_t_e_m_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      XmbTextItem *_i_t_e_m_s;
      int _n_i_t_e_m_s;


void XwcDrawText(_d_i_s_p_l_a_y, _d, _g_c, _x, _y, _i_t_e_m_s, _n_i_t_e_m_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      GC _g_c;
      int _x, _y;
      XwcTextItem *_i_t_e_m_s;
      int _n_i_t_e_m_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates.

_i_t_e_m_s     Specifies an array of text items.

_n_i_t_e_m_s    Specifies the number of text items in the array.
││__

The _X_m_b_D_r_a_w_T_e_x_t and _X_w_c_D_r_a_w_T_e_x_t functions allow complex
spacing and font set shifts between text strings.  Each text
item is processed in turn, with the origin of a text element
advanced in the primary draw direction by the escapement of
the previous text item.  A text item delta specifies an
additional escapement of the text item drawing origin in the
primary draw direction.  A font_set member other than _N_o_n_e
in an item causes the font set to be used for this and sub­
sequent text items in the text_items list.  Leading text
items with a font_set member set to _N_o_n_e will not be drawn.

_X_m_b_D_r_a_w_T_e_x_t and _X_w_c_D_r_a_w_T_e_x_t do not perform any context‐
dependent rendering between text segments.  Clients may com­
pute the drawing metrics by passing each text segment to
_X_m_b_T_e_x_t_E_x_t_e_n_t_s and _X_w_c_T_e_x_t_E_x_t_e_n_t_s or _X_m_b_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s
and _X_w_c_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s.  When the _X_F_o_n_t_S_e_t has missing
charsets, each unavailable character is drawn with the
default string returned by _X_C_r_e_a_t_e_F_o_n_t_S_e_t.  The behavior for
an invalid codepoint is undefined.





                             442288





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To draw text using a single font set in a given drawable,
use _X_m_b_D_r_a_w_S_t_r_i_n_g or _X_w_c_D_r_a_w_S_t_r_i_n_g.
__
││
void XmbDrawString(_d_i_s_p_l_a_y, _d, _f_o_n_t___s_e_t, _g_c, _x, _y, _s_t_r_i_n_g, _n_u_m___b_y_t_e_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      XFontSet _f_o_n_t___s_e_t;
      GC _g_c;
      int _x, _y;
      char *_s_t_r_i_n_g;
      int _n_u_m___b_y_t_e_s;


void XwcDrawString(_d_i_s_p_l_a_y, _d, _f_o_n_t___s_e_t, _g_c, _x, _y, _s_t_r_i_n_g, _n_u_m___w_c_h_a_r_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      XFontSet _f_o_n_t___s_e_t;
      GC _g_c;
      int _x, _y;
      wchar_t *_s_t_r_i_n_g;
      int _n_u_m___w_c_h_a_r_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_f_o_n_t___s_e_t  Specifies the font set.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates.

_s_t_r_i_n_g    Specifies the character string.

_n_u_m___b_y_t_e_s Specifies the number of bytes in the string argu­
          ment.

_n_u_m___w_c_h_a_r_s
          Specifies the number of characters in the string
          argument.
││__

The _X_m_b_D_r_a_w_S_t_r_i_n_g and _X_w_c_D_r_a_w_S_t_r_i_n_g functions draw the spec­
ified text with the foreground pixel.  When the _X_F_o_n_t_S_e_t has
missing charsets, each unavailable character is drawn with
the default string returned by _X_C_r_e_a_t_e_F_o_n_t_S_e_t.  The behavior
for an invalid codepoint is undefined.


To draw image text using a single font set in a given draw­
able, use _X_m_b_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g or _X_w_c_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g.



                             442299





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XmbDrawImageString(_d_i_s_p_l_a_y, _d, _f_o_n_t___s_e_t, _g_c, _x, _y, _s_t_r_i_n_g, _n_u_m___b_y_t_e_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      XFontSet _f_o_n_t___s_e_t;
      GC _g_c;
      int _x, _y;
      char *_s_t_r_i_n_g;
      int _n_u_m___b_y_t_e_s;


void XwcDrawImageString(_d_i_s_p_l_a_y, _d, _f_o_n_t___s_e_t, _g_c, _x, _y, _s_t_r_i_n_g, _n_u_m___w_c_h_a_r_s)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      XFontSet _f_o_n_t___s_e_t;
      GC _g_c;
      int _x, _y;
      wchar_t *_s_t_r_i_n_g;
      int _n_u_m___w_c_h_a_r_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_f_o_n_t___s_e_t  Specifies the font set.

_g_c        Specifies the GC.

_x
_y         Specify the x and y coordinates.

_s_t_r_i_n_g    Specifies the character string.

_n_u_m___b_y_t_e_s Specifies the number of bytes in the string argu­
          ment.

_n_u_m___w_c_h_a_r_s
          Specifies the number of characters in the string
          argument.
││__

The _X_m_b_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g and _X_w_c_D_r_a_w_I_m_a_g_e_S_t_r_i_n_g functions fill
a destination rectangle with the background pixel defined in
the GC and then paint the text with the foreground pixel.
The filled rectangle is the rectangle returned to over­
all_logical_return by _X_m_b_T_e_x_t_E_x_t_e_n_t_s or _X_w_c_T_e_x_t_E_x_t_e_n_t_s for
the same text and _X_F_o_n_t_S_e_t.

When the _X_F_o_n_t_S_e_t has missing charsets, each unavailable
character is drawn with the default string returned by _X_C_r_e_­
_a_t_e_F_o_n_t_S_e_t.  The behavior for an invalid codepoint is unde­
fined.




                             443300





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1133..55..  IInnppuutt MMeetthhooddss

This section provides discussions of the following X Input
Method (XIM) topics:

⋅    Input method overview

⋅    Input method management

⋅    Input method functions

⋅    Input method values

⋅    Input context functions

⋅    Input context values

⋅    Input method callback semantics

⋅    Event filtering

⋅    Getting keyboard input

⋅    Input method conventions

1133..55..11..  IInnppuutt MMeetthhoodd OOvveerrvviieeww

This section provides definitions for terms and concepts
used for internationalized text input and a brief overview
of the intended use of the mechanisms provided by Xlib.

A large number of languages in the world use alphabets con­
sisting of a small set of symbols (letters) to form words.
To enter text into a computer in an alphabetic language, a
user usually has a keyboard on which there exist key symbols
corresponding to the alphabet.  Sometimes, a few characters
of an alphabetic language are missing on the keyboard.  Many
computer users who speak a Latin‐alphabet‐based language
only have an English‐based keyboard.  They need to hit a
combination of keystrokes to enter a character that does not
exist directly on the keyboard.  A number of algorithms have
been developed for entering such characters.  These are
known as European input methods, compose input methods, or
dead‐key input methods.

Japanese is an example of a language with a phonetic symbol
set, where each symbol represents a specific sound.  There
are two phonetic symbol sets in Japanese:  Katakana and
Hiragana.  In general, Katakana is used for words that are
of foreign origin, and Hiragana is used for writing native
Japanese words.  Collectively, the two systems are called
Kana.  Each set consists of 48 characters.





                             443311





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Korean also has a phonetic symbol set, called Hangul.  Each
of the 24 basic phonetic symbols (14 consonants and 10 vow­
els) represents a specific sound.  A syllable is composed of
two or three parts: the initial consonants, the vowels, and
the optional last consonants.  With Hangul, syllables can be
treated as the basic units on which text processing is done.
For example, a delete operation may work on a phonetic sym­
bol or a syllable.  Korean code sets include several thou­
sands of these syllables.  A user types the phonetic symbols
that make up the syllables of the words to be entered.  The
display may change as each phonetic symbol is entered.  For
example, when the second phonetic symbol of a syllable is
entered, the first phonetic symbol may change its shape and
size.  Likewise, when the third phonetic symbol is entered,
the first two phonetic symbols may change their shape and
size.

Not all languages rely solely on alphabetic or phonetic sys­
tems.  Some languages, including Japanese and Korean, employ
an ideographic writing system.  In an ideographic system,
rather than taking a small set of symbols and combining them
in different ways to create words, each word consists of one
unique symbol (or, occasionally, several symbols).  The num­
ber of symbols can be very large: approximately 50,000 have
been identified in Hanzi, the Chinese ideographic system.

Two major aspects of ideographic systems impact their use
with computers.  First, the standard computer character sets
in Japan, China, and Korea include roughly 8,000 characters,
while sets in Taiwan have between 15,000 and 30,000 charac­
ters.  This makes it necessary to use more than one byte to
represent a character.  Second, it obviously is impractical
to have a keyboard that includes all of a given language’s
ideographic symbols.  Therefore, a mechanism is required for
entering characters so that a keyboard with a reasonable
number of keys can be used.  Those input methods are usually
based on phonetics, but there also exist methods based on
the graphical properties of characters.

In Japan, both Kana and the ideographic system Kanji are
used.  In Korea, Hangul and sometimes the ideographic system
Hanja are used.  Now consider entering ideographs in Japan,
Korea, China, and Taiwan.

In Japan, either Kana or English characters are typed and
then a region is selected (sometimes automatically) for con­
version to Kanji.  Several Kanji characters may have the
same phonetic representation.  If that is the case with the
string entered, a menu of characters is presented and the
user must choose the appropriate one.  If no choice is nec­
essary or a preference has been established, the input
method does the substitution directly.  When Latin charac­
ters are converted to Kana or Kanji, it is called a romaji
conversion.



                             443322





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


In Korea, it is usually acceptable to keep Korean text in
Hangul form, but some people may choose to write Hanja‐orig­
inated words in Hanja rather than in Hangul.  To change
Hangul to Hanja, the user selects a region for conversion
and then follows the same basic method as that described for
Japanese.

Probably because there are well‐accepted phonetic writing
systems for Japanese and Korean, computer input methods in
these countries for entering ideographs are fairly standard.
Keyboard keys have both English characters and phonetic sym­
bols engraved on them, and the user can switch between the
two sets.

The situation is different for Chinese.  While there is a
phonetic system called Pinyin promoted by authorities, there
is no consensus for entering Chinese text.  Some vendors use
a phonetic decomposition (Pinyin or another), others use
ideographic decomposition of Chinese words, with various
implementations and keyboard layouts.  There are about 16
known methods, none of which is a clear standard.

Also, there are actually two ideographic sets used: Tradi­
tional Chinese (the original written Chinese) and Simplified
Chinese.  Several years ago, the People’s Republic of China
launched a campaign to simplify some ideographic characters
and eliminate redundancies altogether.  Under the plan,
characters would be streamlined every five years.  Charac­
ters have been revised several times now, resulting in the
smaller, simpler set that makes up Simplified Chinese.

1133..55..11..11..  IInnppuutt MMeetthhoodd AArrcchhiitteeccttuurree

As shown in the previous section, there are many different
input methods in use today, each varying with language, cul­
ture, and history.  A common feature of many input methods
is that the user may type multiple keystrokes to compose a
single character (or set of characters).  The process of
composing characters from keystrokes is called _p_r_e_e_d_i_t_i_n_g.
It may require complex algorithms and large dictionaries
involving substantial computer resources.

Input methods may require one or more areas in which to show
the feedback of the actual keystrokes, to propose disam­
biguation to the user, to list dictionaries, and so on.  The
input method areas of concern are as follows:

⋅    The _s_t_a_t_u_s area is a logical extension of the LEDs that
     exist on the physical keyboard.  It is a window that is
     intended to present the internal state of the input
     method that is critical to the user.  The status area
     may consist of text data and bitmaps or some combina­
     tion.




                             443333





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    The _p_r_e_e_d_i_t area displays the intermediate text for
     those languages that are composing prior to the client
     handling the data.

⋅    The _a_u_x_i_l_i_a_r_y area is used for pop‐up menus and cus­
     tomizing dialogs that may be required for an input
     method.  There may be multiple auxiliary areas for an
     input method.  Auxiliary areas are managed by the input
     method independent of the client.  Auxiliary areas are
     assumed to be separate dialogs, which are maintained by
     the input method.

There are various user interaction styles used for preedit­
ing.  The ones supported by Xlib are as follows:

⋅    For _o_n_‐_t_h_e_‐_s_p_o_t input methods, preediting data will be
     displayed directly in the application window.  Applica­
     tion data is moved to allow preedit data to appear at
     the point of insertion.

⋅    _O_v_e_r_‐_t_h_e_‐_s_p_o_t preediting means that the data is dis­
     played in a preedit window that is placed over the
     point of insertion.

⋅    _O_f_f_‐_t_h_e_‐_s_p_o_t preediting means that the preedit window
     is inside the application window but not at the point
     of insertion.  Often, this type of window is placed at
     the bottom of the application window.

⋅    _R_o_o_t_‐_w_i_n_d_o_w preediting refers to input methods that use
     a preedit window that is the child of _R_o_o_t_W_i_n_d_o_w.

It would require a lot of computing resources if portable
applications had to include input methods for all the lan­
guages in the world.  To avoid this, a goal of the Xlib
design is to allow an application to communicate with an
input method placed in a separate process.  Such a process
is called an _i_n_p_u_t _s_e_r_v_e_r.  The server to which the applica­
tion should connect is dependent on the environment when the
application is started up, that is, the user language and
the actual encoding to be used for it.  The input method
connection is said to be _l_o_c_a_l_e_‐_d_e_p_e_n_d_e_n_t.  It is also user‐
dependent.  For a given language, the user can choose, to
some extent, the user interface style of input method (if
choice is possible among several).

Using an input server implies communication overhead, but
applications can be migrated without relinking.  Input meth­
ods can be implemented either as a stub communicating to an
input server or as a local library.

An input method may be based on a _f_r_o_n_t_‐_e_n_d or a _b_a_c_k_‐_e_n_d
architecture.  In a front‐end architecture, there are two
separate connections to the X server: keystrokes go directly



                             443344





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


from the X server to the input method on one connection and
other events to the regular client connection.  The input
method is then acting as a filter and sends composed strings
to the client.  A front‐end architecture requires synchro­
nization between the two connections to avoid lost key
events or locking issues.

In a back‐end architecture, a single X server connection is
used.  A dispatching mechanism must decide on this channel
to delegate appropriate keystrokes to the input method.  For
instance, it may retain a Help keystroke for its own pur­
pose.  In the case where the input method is a separate pro­
cess (that is, a server), there must be a special communica­
tion protocol between the back‐end client and the input
server.

A front‐end architecture introduces synchronization issues
and a filtering mechanism for noncharacter keystrokes (Func­
tion keys, Help, and so on).  A back‐end architecture some­
times implies more communication overhead and more process
switching.  If all three processes (X server, input server,
client) are running on a single workstation, there are two
process switches for each keystroke in a back‐end architec­
ture, but there is only one in a front‐end architecture.

The abstraction used by a client to communicate with an
input method is an opaque data structure represented by the
_X_I_M data type.  This data structure is returned by the
_X_O_p_e_n_I_M function, which opens an input method on a given
display.  Subsequent operations on this data structure
encapsulate all communication between client and input
method.  There is no need for an X client to use any net­
working library or natural language package to use an input
method.

A single input server may be used for one or more languages,
supporting one or more encoding schemes.  But the strings
returned from an input method will always be encoded in the
(single) locale associated with the _X_I_M object.

1133..55..11..22..  IInnppuutt CCoonntteexxttss

Xlib provides the ability to manage a multi‐threaded state
for text input.  A client may be using multiple windows,
each window with multiple text entry areas, and the user
possibly switching among them at any time.  The abstraction
for representing the state of a particular input thread is
called an _i_n_p_u_t _c_o_n_t_e_x_t.  The Xlib representation of an
input context is an _X_I_C.

An input context is the abstraction retaining the state,
properties, and semantics of communication between a client
and an input method.  An input context is a combination of
an input method, a locale specifying the encoding of the



                             443355





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


character strings to be returned, a client window, internal
state information, and various layout or appearance charac­
teristics.  The input context concept somewhat matches for
input the graphics context abstraction defined for graphics
output.

One input context belongs to exactly one input method.  Dif­
ferent input contexts may be associated with the same input
method, possibly with the same client window.  An _X_I_C is
created with the _X_C_r_e_a_t_e_I_C function, providing an _X_I_M argu­
ment and affiliating the input context to the input method
for its lifetime.  When an input method is closed with _X_C_l_o_­
_s_e_I_M, all of its affiliated input contexts should not be
used any more (and should preferably be destroyed before
closing the input method).

Considering the example of a client window with multiple
text entry areas, the application programmer could, for
example, choose to implement as follows:

⋅    As many input contexts are created as text entry areas,
     and the client will get the input accumulated on each
     context each time it looks up in that context.

⋅    A single context is created for a top‐level window in
     the application.  If such a window contains several
     text entry areas, each time the user moves to another
     text entry area, the client has to indicate changes in
     the context.

A range of choices can be made by application designers to
use either a single or multiple input contexts, according to
the needs of their application.

1133..55..11..33..  GGeettttiinngg KKeeyybbooaarrdd IInnppuutt

To obtain characters from an input method, a client must
call the function _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g with an
input context created from that input method.  Both a locale
and display are bound to an input method when it is opened,
and an input context inherits this locale and display.  Any
strings returned by _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g will
be encoded in that locale.

1133..55..11..44..  FFooccuuss MMaannaaggeemmeenntt

For each text entry area in which the _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or
_X_w_c_L_o_o_k_u_p_S_t_r_i_n_g functions are used, there will be an associ­
ated input context.

When the application focus moves to a text entry area, the
application must set the input context focus to the input
context associated with that area.  The input context focus
is set by calling _X_S_e_t_I_C_F_o_c_u_s with the appropriate input



                             443366





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


context.

Also, when the application focus moves out of a text entry
area, the application should unset the focus for the associ­
ated input context by calling _X_U_n_s_e_t_I_C_F_o_c_u_s.  As an opti­
mization, if _X_S_e_t_I_C_F_o_c_u_s is called successively on two dif­
ferent input contexts, setting the focus on the second will
automatically unset the focus on the first.

To set and unset the input context focus correctly, it is
necessary to track application‐level focus changes.  Such
focus changes do not necessarily correspond to X server
focus changes.

If a single input context is being used to do input for mul­
tiple text entry areas, it will also be necessary to set the
focus window of the input context whenever the focus window
changes (see section 13.5.6.3).

1133..55..11..55..  GGeeoommeettrryy MMaannaaggeemmeenntt

In most input method architectures (on‐the‐spot being the
notable exception), the input method will perform the dis­
play of its own data.  To provide better visual locality, it
is often desirable to have the input method areas embedded
within a client.  To do this, the client may need to allo­
cate space for an input method.  Xlib provides support that
allows the size and position of input method areas to be
provided by a client.  The input method areas that are sup­
ported for geometry management are the status area and the
preedit area.

The fundamental concept on which geometry management for
input method windows is based is the proper division of
responsibilities between the client (or toolkit) and the
input method.  The division of responsibilities is as fol­
lows:

⋅    The client is responsible for the geometry of the input
     method window.

⋅    The input method is responsible for the contents of the
     input method window.

An input method is able to suggest a size to the client, but
it cannot suggest a placement.  Also the input method can
only suggest a size.  It does not determine the size, and it
must accept the size it is given.

Before a client provides geometry management for an input
method, it must determine if geometry management is needed.
The input method indicates the need for geometry management
by setting _X_I_M_P_r_e_e_d_i_t_A_r_e_a or _X_I_M_S_t_a_t_u_s_A_r_e_a in its _X_I_M_S_t_y_l_e_s
value returned by _X_G_e_t_I_M_V_a_l_u_e_s.  When a client has decided



                             443377





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


that it will provide geometry management for an input
method, it indicates that decision by setting the _X_N_I_n_p_u_t_­
_S_t_y_l_e value in the _X_I_C.

After a client has established with the input method that it
will do geometry management, the client must negotiate the
geometry with the input method.  The geometry is negotiated
by the following steps:

⋅    The client suggests an area to the input method by set­
     ting the _X_N_A_r_e_a_N_e_e_d_e_d value for that area.  If the
     client has no constraints for the input method, it
     either will not suggest an area or will set the width
     and height to zero.  Otherwise, it will set one of the
     values.

⋅    The client will get the XIC value _X_N_A_r_e_a_N_e_e_d_e_d.  The
     input method will return its suggested size in this
     value.  The input method should pay attention to any
     constraints suggested by the client.

⋅    The client sets the XIC value _X_N_A_r_e_a to inform the
     input method of the geometry of its window.  The client
     should try to honor the geometry requested by the input
     method.  The input method must accept this geometry.

Clients doing geometry management must be aware that setting
other XIC values may affect the geometry desired by an input
method.  For example, _X_N_F_o_n_t_S_e_t and _X_N_L_i_n_e_S_p_a_c_i_n_g may change
the geometry desired by the input method.

The table of XIC values (see section 13.5.6) indicates the
values that can cause the desired geometry to change when
they are set.  It is the responsibility of the client to
renegotiate the geometry of the input method window when it
is needed.

In addition, a geometry management callback is provided by
which an input method can initiate a geometry change.

1133..55..11..66..  EEvveenntt FFiilltteerriinngg

A filtering mechanism is provided to allow input methods to
capture X events transparently to clients.  It is expected
that toolkits (or clients) using _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or
_X_w_c_L_o_o_k_u_p_S_t_r_i_n_g will call this filter at some point in the
event processing mechanism to make sure that events needed
by an input method can be filtered by that input method.

If there were no filter, a client could receive and discard
events that are necessary for the proper functioning of an
input method.  The following provides a few examples of such
events:




                             443388





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    Expose events on preedit window in local mode.

⋅    Events may be used by an input method to communicate
     with an input server.  Such input server protocol‐
     related events have to be intercepted if one does not
     want to disturb client code.

⋅    Key events can be sent to a filter before they are
     bound to translations such as those the X Toolkit
     Intrinsics library provides.

Clients are expected to get the XIC value _X_N_F_i_l_t_e_r_E_v_e_n_t_s and
augment the event mask for the client window with that event
mask.  This mask may be zero.

1133..55..11..77..  CCaallllbbaacckkss

When an on‐the‐spot input method is implemented, only the
client can insert or delete preedit data in place and possi­
bly scroll existing text.  This means that the echo of the
keystrokes has to be achieved by the client itself, tightly
coupled with the input method logic.

When the user enters a keystroke, the client calls
_X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g.  At this point, in the
on‐the‐spot case, the echo of the keystroke in the preedit
has not yet been done.  Before returning to the client logic
that handles the input characters, the look‐up function must
call the echoing logic to insert the new keystroke.  If the
keystrokes entered so far make up a character, the
keystrokes entered need to be deleted, and the composed
character will be returned.  Hence, what happens is that,
while being called by client code, the input method logic
has to call back to the client before it returns.  The
client code, that is, a callback procedure, is called from
the input method logic.

There are a number of cases where the input method logic has
to call back the client.  Each of those cases is associated
with a well‐defined callback action.  It is possible for the
client to specify, for each input context, what callback is
to be called for each action.

There are also callbacks provided for feedback of status
information and a callback to initiate a geometry request
for an input method.

1133..55..11..88..  VViissiibbllee PPoossiittiioonn FFeeeeddbbaacckk MMaasskkss

In the on‐the‐spot input style, there is a problem when
attempting to draw preedit strings that are longer than the
available space.  Once the display area is exceeded, it is
not clear how best to display the preedit string.  The visi­
ble position feedback masks of _X_I_M_T_e_x_t help resolve this



                             443399





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


problem by allowing the input method to specify hints that
indicate the essential portions of the preedit string.  For
example, such hints can help developers implement scrolling
of a long preedit string within a short preedit display
area.

1133..55..11..99..  PPrreeeeddiitt SSttrriinngg MMaannaaggeemmeenntt

As highlighted before, the input method architecture pro­
vides preediting, which supports a type of preprocessor
input composition.  In this case, composition consists of
interpreting a sequence of key events and returning a com­
mitted string via _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g.  This
provides the basics for input methods.

In addition to preediting based on key events, a general
framework is provided to give a client that desires it more
advanced preediting based on the text within the client.
This framework is called _s_t_r_i_n_g _c_o_n_v_e_r_s_i_o_n and is provided
using XIC values.  The fundamental concept of string conver­
sion is to allow the input method to manipulate the client’s
text independent of any user preediting operation.

The need for string conversion is based on language needs
and input method capabilities.  The following are some exam­
ples of string conversion:

⋅    Transliteration conversion provides language‐specific
     conversions within the input method.  In the case of
     Korean input, users wish to convert a Hangul string
     into a Hanja string while in preediting, after preedit­
     ing, or in other situations (for example, on a selected
     string).  The conversion is triggered when the user
     presses a Hangul‐to‐Hanja key sequence (which may be
     input method specific).  Sometimes the user may want to
     invoke the conversion after finishing preediting or on
     a user‐selected string.  Thus, the string to be con­
     verted is in an application buffer, not in the preedit
     area of the input method.  The string conversion ser­
     vices allow the client to request this transliteration
     conversion from the input method.  There are many other
     transliteration conversions defined for various lan­
     guages, for example, Kana‐to‐Kanji conversion in
     Japanese.

     The key to remember is that transliteration conversions
     are triggered at the request of the user and returned
     to the client immediately without affecting the preedit
     area of the input method.

⋅    Reconversion of a previously committed string or a
     selected string is supported by many input methods as a
     convenience to the user.  For example, a user tends to
     mistype the commit key while preediting.  In that case,



                             444400





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     some input methods provide a special key sequence to
     request a ‘‘reconvert’’ operation on the committed
     string, similiar to the undo facility provided by most
     text editors.  Another example is where the user is
     proofreading a document that has some misconversions
     from preediting and wants to correct the misconverted
     text.  Such reconversion is again triggered by the user
     invoking some special action, but reconversions should
     not affect the state of the preedit area.

⋅    Context‐sensitive conversion is required for some lan­
     guages and input methods that need to retrieve text
     that surrounds the current spot location (cursor posi­
     tion) of the client’s buffer.  Such text is needed when
     the preediting operation depends on some surrounding
     characters (usually preceding the spot location).  For
     example, in Thai language input, certain character
     sequences may be invalid and the input method may want
     to check whether characters constitute a valid word.
     Input methods that do such context‐dependent checking
     need to retrieve the characters surrounding the current
     cursor position to obtain complete words.

     Unlike other conversions, this conversion is not
     explicitly requested by the user.  Input methods that
     provide such context‐sensitive conversion continuously
     need to request context from the client, and any change
     in the context of the spot location may affect such
     conversions.  The client’s context would be needed if
     the user moves the cursor and starts editing again.

     For this reason, an input method supporting this type
     of conversion should take notice of when the client
     calls _X_m_b_R_e_s_e_t_I_C or _X_w_c_R_e_s_e_t_I_C, which is usually an
     indication of a context change.

Context‐sensitive conversions just need a copy of the
client’s text, while other conversions replace the client’s
text with new text to achieve the reconversion or translit­
eration.   Yet in all cases the result of a conversion,
either immediately or via preediting, is returned by the
_X_m_b_L_o_o_k_u_p_S_t_r_i_n_g and _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g functions.

String conversion support is dependent on the availability
of the _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n or _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k XIC
values.  Because the input method may not support string
conversions, clients have to query the availability of
string conversion operations by checking the supported XIC
values list by calling _X_G_e_t_I_M_V_a_l_u_e_s with the _X_N_Q_u_e_r_y_I_C_V_a_l_­
_u_e_s_L_i_s_t IM value.

The difference between these two values is whether the con­
version is invoked by the client or the input method.  The
_X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n XIC value is used by clients to request a



                             444411





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


string conversion from the input method.  The client is
responsible for determining which events are used to trigger
the string conversion and whether the string to be converted
should be copied or deleted.  The type of conversion is
determined by the input method; the client can only pass the
string to be converted.  The client is guaranteed that no
_X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k will be issued when this value is
set; thus, the client need only set one of these values.

The _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k XIC value is used by the
client to notify the input method that it will accept
requests from the input method for string conversion.  If
this value is set, it is the input method’s responsibility
to determine which events are used to trigger the string
conversion.  When such events occur, the input method issues
a call to the client‐supplied procedure to retrieve the
string to be converted.  The client’s callback procedure is
notified whether to copy or delete the string and is pro­
vided with hints as to the amount of text needed.  The _X_I_M_­
_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k_S_t_r_u_c_t specifies which text should
be passed back to the input method.

Finally, the input method may call the client’s _X_N_S_t_r_i_n_g_C_o_n_­
_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k procedure multiple times if the string
returned from the callback is not sufficient to perform a
successful conversion.   The arguments to the client’s pro­
cedure allow the input method to define a position (in char­
acter units) relative to the client’s cursor position and
the size of the text needed.  By varying the position and
size of the desired text in subsequent callbacks, the input
method can retrieve additional text.


1133..55..22..  IInnppuutt MMeetthhoodd MMaannaaggeemmeenntt

The interface to input methods might appear to be simply
creating an input method (_X_O_p_e_n_I_M) and freeing an input
method (_X_C_l_o_s_e_I_M).  However, input methods may require com­
plex communication with input method servers (IM servers),
for example:

⋅    If the X server, IM server, and X clients are started
     asynchronously, some clients may attempt to connect to
     the IM server before it is fully operational, and fail.
     Therefore, some mechanism is needed to allow clients to
     detect when an IM server has started.

It is up to clients to decide what should be done when an IM
server is not available (for example, wait, or use some
other IM server).


⋅    Some input methods may allow the underlying IM server
     to be switched.  Such customization may be desired



                             444422





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     without restarting the entire client.

To support management of input methods in these cases, the
following functions are provided:

_X_R_e_g_i_s_t_e_r_I_M_I_n_s_t_a_n_t_i_a_t_e_­    This function allows clients to
_C_a_l_l_b_a_c_k                   register a callback procedure to
                           be called when Xlib detects that
                           an IM server is up and available.
_X_O_p_e_n_I_M                    A client calls this function as a
                           result of the callback procedure
                           being called.
_X_S_e_t_I_M_V_a_l_u_e, _X_S_e_t_I_C_V_a_l_u_e   These functions use the XIM and
                           XIC values, _X_N_D_e_s_t_r_o_y_C_a_l_l_b_a_c_k, to
                           allow a client to register a
                           callback procedure to be called
                           when Xlib detects that an IM
                           server that was associated with
                           an opened input method is no
                           longer available.
                           In addition, this function can be
                           used to switch IM servers for
                           those input methods that support
                           such functionality.  The IM value
                           for switching IM servers is
                           implementation‐dependent; see the
                           description below about switching
                           IM servers.
_X_U_n_r_e_g_i_s_t_e_r_I_M_I_n_s_t_a_n_t_i_­     This function removes a callback
_a_t_e_C_a_l_l_b_a_c_k                procedure registered by the
                           client.


Input methods that support switching of IM servers may
exhibit some side‐effects:

⋅    The input method will ensure that any new IM server
     supports any of the input styles being used by input
     contexts already associated with the input method.
     However, the list of supported input styles may be dif­
     ferent.


⋅    Geometry management requests on previously created
     input contexts may be initiated by the new IM server.


1133..55..22..11..  HHoott KKeeyyss

Some clients need to guarantee which keys can be used to
escape from the input method, regardless of the input method
state; for example, the client‐specific Help key or the keys
to move the input focus.  The HotKey mechanism allows
clients to specify a set of keys for this purpose.  However,



                             444433





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the input method might not allow clients to specify hot
keys.  Therefore, clients have to query support of hot keys
by checking the supported XIC values list by calling _X_G_e_t_I_M_­
_V_a_l_u_e_s with the _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t IM value.  When the hot
keys specified conflict with the key bindings of the input
method, hot keys take precedence over the key bindings of
the input method.


1133..55..22..22..  PPrreeeeddiitt SSttaattee OOppeerraattiioonn

An input method may have several internal states, depending
on its implementation and the locale.  However, one state
that is independent of locale and implementation is whether
the input method is currently performing a preediting opera­
tion.  Xlib provides the ability for an application to man­
age the preedit state programmatically.  Two methods are
provided for retrieving the preedit state of an input con­
text.  One method is to query the state by calling _X_G_e_t_I_C_­
_V_a_l_u_e_s with the _X_N_P_r_e_e_d_i_t_S_t_a_t_e XIC value.  Another method is
to receive notification whenever the preedit state is
changed.  To receive such notification, an application needs
to register a callback by calling _X_S_e_t_I_C_V_a_l_u_e_s with the
_X_N_P_r_e_e_d_i_t_S_t_a_t_e_N_o_t_i_f_y_C_a_l_l_b_a_c_k XIC value.  In order to change
the preedit state programmatically, an application needs to
call _X_S_e_t_I_C_V_a_l_u_e_s with _X_N_P_r_e_e_d_i_t_S_t_a_t_e_.

Availability of the preedit state is input method dependent.
The input method may not provide the ability to set the
state or to retrieve the state programmatically.  Therefore,
clients have to query availability of preedit state opera­
tions by checking the supported XIC values list by calling
_X_G_e_t_I_M_V_a_l_u_e_s with the _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t IM value.

1133..55..33..  IInnppuutt MMeetthhoodd FFuunnccttiioonnss

To open a connection, use _X_O_p_e_n_I_M.




















                             444444





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XIM XOpenIM(_d_i_s_p_l_a_y, _d_b, _r_e_s___n_a_m_e, _r_e_s___c_l_a_s_s)
      Display *_d_i_s_p_l_a_y;
      XrmDatabase _d_b;
      char *_r_e_s___n_a_m_e;
      char *_r_e_s___c_l_a_s_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_b        Specifies a pointer to the resource database.

_r_e_s___n_a_m_e  Specifies the full resource name of the applica­
          tion.

_r_e_s___c_l_a_s_s Specifies the full class name of the application.
││__

The _X_O_p_e_n_I_M function opens an input method, matching the
current locale and modifiers specification.  Current locale
and modifiers are bound to the input method at opening time.
The locale associated with an input method cannot be changed
dynamically.  This implies that the strings returned by
_X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g, for any input context
affiliated with a given input method, will be encoded in the
locale current at the time the input method is opened.

The specific input method to which this call will be routed
is identified on the basis of the current locale.  _X_O_p_e_n_I_M
will identify a default input method corresponding to the
current locale.  That default can be modified using _X_S_e_t_L_o_­
_c_a_l_e_M_o_d_i_f_i_e_r_s for the input method modifier.

The db argument is the resource database to be used by the
input method for looking up resources that are private to
the input method.  It is not intended that this database be
used to look up values that can be set as IC values in an
input context.  If db is NULL, no database is passed to the
input method.

The res_name and res_class arguments specify the resource
name and class of the application.  They are intended to be
used as prefixes by the input method when looking up
resources that are common to all input contexts that may be
created for this input method.  The characters used for
resource names and classes must be in the X Portable Charac­
ter Set.  The resources looked up are not fully specified if
res_name or res_class is NULL.

The res_name and res_class arguments are not assumed to
exist beyond the call to _X_O_p_e_n_I_M.  The specified resource
database is assumed to exist for the lifetime of the input
method.




                             444455





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_O_p_e_n_I_M returns NULL if no input method could be opened.


To close a connection, use _X_C_l_o_s_e_I_M.
__
││
Status XCloseIM(_i_m)
      XIM _i_m;


_i_m        Specifies the input method.
││__

The _X_C_l_o_s_e_I_M function closes the specified input method.


To set input method attributes, use _X_S_e_t_I_M_V_a_l_u_e_s.
__
││
char * XSetIMValues(_i_m, ...)
      XIM _i_m;


_i_m        Specifies the input method.

...       Specifies the variable‐length argument list to set
          XIM values.
││__

The _X_S_e_t_I_M_V_a_l_u_e_s function presents a variable argument list
programming interface for setting attributes of the speci­
fied input method.  It returns NULL if it succeeds; other­
wise, it returns the name of the first argument that could
not be set.  Xlib does not attempt to set arguments from the
supplied list that follow the failed argument; all arguments
in the list preceding the failed argument have been set cor­
rectly.


To query an input method, use _X_G_e_t_I_M_V_a_l_u_e_s.
__
││
char * XGetIMValues(_i_m, ...)
      XIM _i_m;


_i_m        Specifies the input method.

...       Specifies the variable length argument list to get
          XIM values.
││__

The _X_G_e_t_I_M_V_a_l_u_e_s function presents a variable argument list
programming interface for querying properties or features of



                             444466





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the specified input method.  This function returns NULL if
it succeeds; otherwise, it returns the name of the first
argument that could not be obtained.

Each XIM value argument (following a name) must point to a
location where the XIM value is to be stored.  That is, if
the XIM value is of type T, the argument must be of type T*.
If T itself is a pointer type, then _X_G_e_t_I_M_V_a_l_u_e_s allocates
memory to store the actual data, and the client is responsi­
ble for freeing this data by calling _X_F_r_e_e with the returned
pointer.


To obtain the display associated with an input method, use
_X_D_i_s_p_l_a_y_O_f_I_M.
__
││
Display * XDisplayOfIM(_i_m)
     XIM _i_m;


_i_m        Specifies the input method.
││__

The _X_D_i_s_p_l_a_y_O_f_I_M function returns the display associated
with the specified input method.


To get the locale associated with an input method, use _X_L_o_­
_c_a_l_e_O_f_I_M.
__
││
char * XLocaleOfIM(_i_m)
      XIM _i_m;


_i_m        Specifies the input method.
││__

The _X_L_o_c_a_l_e_O_f_I_M function returns the locale associated with
the specified input method.


To register an input method instantiate callback, use _X_R_e_g_­
_i_s_t_e_r_I_M_I_n_s_t_a_n_t_i_a_t_e_C_a_l_l_b_a_c_k.












                             444477





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XRegisterIMInstantiateCallback(_d_i_s_p_l_a_y, _d_b, _r_e_s___n_a_m_e, _r_e_s___c_l_a_s_s, _c_a_l_l_b_a_c_k, _c_l_i_e_n_t___d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      XrmDatabase _d_b;
      char *_r_e_s___n_a_m_e;
      char *_r_e_s___c_l_a_s_s;
      XIMProc  _c_a_l_l_b_a_c_k;
      XPointer *_c_l_i_e_n_t___d_a_t_a;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_b        Specifies a pointer to the resource database.

_r_e_s___n_a_m_e  Specifies the full resource name of the applica­
          tion.

_r_e_s___c_l_a_s_s Specifies the full class name of the application.

_c_a_l_l_b_a_c_k  Specifies a pointer to the input method instanti­
          ate callback.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.
││__

The _X_R_e_g_i_s_t_e_r_I_M_I_n_s_t_a_n_t_i_a_t_e_C_a_l_l_b_a_c_k function registers a
callback to be invoked whenever a new input method becomes
available for the specified display that matches the current
locale and modifiers.

The function returns _T_r_u_e
 if it succeeds; otherwise, it returns _F_a_l_s_e.

The generic prototype is as follows:
__
││
void IMInstantiateCallback(_d_i_s_p_l_a_y, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XPointer _c_a_l_l___d_a_t_a;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Not used for this callback and always passed as
          NULL.
││__

To unregister an input method instantiation callback, use
_X_U_n_r_e_g_i_s_t_e_r_I_M_I_n_s_t_a_n_t_i_a_t_e_C_a_l_l_b_a_c_k.



                             444488





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XUnregisterIMInstantiateCallback(_d_i_s_p_l_a_y, _d_b, _r_e_s___n_a_m_e, _r_e_s___c_l_a_s_s, _c_a_l_l_b_a_c_k, _c_l_i_e_n_t___d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      XrmDatabase _d_b;
      char *_r_e_s___n_a_m_e;
      char *_r_e_s___c_l_a_s_s;
      XIMProc  _c_a_l_l_b_a_c_k;
      XPointer *_c_l_i_e_n_t___d_a_t_a;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_b        Specifies a pointer to the resource database.

_r_e_s___n_a_m_e  Specifies the full resource name of the applica­
          tion.

_r_e_s___c_l_a_s_s Specifies the full class name of the application.

_c_a_l_l_b_a_c_k  Specifies a pointer to the input method instanti­
          ate callback.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.
││__

The _X_U_n_r_e_g_i_s_t_e_r_I_M_I_n_s_t_a_n_t_i_a_t_e_C_a_l_l_b_a_c_k function removes an
input method instantiation callback previously registered.
The function returns _T_r_u_e if it succeeds; otherwise, it
returns _F_a_l_s_e.

1133..55..44..  IInnppuutt MMeetthhoodd VVaalluueess

The following table describes how XIM values are interpreted
by an input method.  The first column lists the XIM values.
The second column indicates how each of the XIM values are
treated by that input style.


The following keys apply to this table.

-------------------------------------------------------------
KKeeyy          EExxppllaannaattiioonn
-------------------------------------------------------------
D            This value may be set using _X_S_e_t_I_M_V_a_l_u_e_s.  If
             it is not set,
             a default is provided.
S            This value may be set using _X_S_e_t_I_M_V_a_l_u_e_s.
G            This value may be read using _X_G_e_t_I_M_V_a_l_u_e_s.
-------------------------------------------------------------







                             444499





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------
XXIIMM VVaalluuee                 KKeeyy
-------------------------------
_X_N_Q_u_e_r_y_I_n_p_u_t_S_t_y_l_e          G
_X_N_R_e_s_o_u_r_c_e_N_a_m_e           D‐S‐G
_X_N_R_e_s_o_u_r_c_e_C_l_a_s_s          D‐S‐G
_X_N_D_e_s_t_r_o_y_C_a_l_l_b_a_c_k        D‐S‐G
_X_N_Q_u_e_r_y_I_M_V_a_l_u_e_s_L_i_s_t        G
_X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t        G
_X_N_V_i_s_i_b_l_e_P_o_s_i_t_i_o_n          G
_X_N_R_6_P_r_e_e_d_i_t_C_a_l_l_b_a_c_k_B_e_­   D‐S‐G
_h_a_v_i_o_r
-------------------------------


_X_N_R_6_P_r_e_e_d_i_t_C_a_l_l_b_a_c_k_B_e_h_a_v_i_o_r is obsolete and its use is not
recommended (see section 13.5.4.6).


1133..55..44..11..  QQuueerryy IInnppuutt SSttyyllee

A client should always query the input method to determine
which input styles are supported.  The client should then
find an input style it is capable of supporting.

If the client cannot find an input style that it can sup­
port, it should negotiate with the user the continuation of
the program (exit, choose another input method, and so on).

The argument value must be a pointer to a location where the
returned value will be stored.  The returned value is a
pointer to a structure of type _X_I_M_S_t_y_l_e_s.  Clients are
responsible for freeing the _X_I_M_S_t_y_l_e_s structure.  To do so,
use _X_F_r_e_e.

The _X_I_M_S_t_y_l_e_s structure is defined as follows:





















                             445500





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef unsigned long XIMStyle;


#define   _X_I_M_P_r_e_e_d_i_t_A_r_e_a         0x0001L
#define   _X_I_M_P_r_e_e_d_i_t_C_a_l_l_b_a_c_k_s    0x0002L
#define   _X_I_M_P_r_e_e_d_i_t_P_o_s_i_t_i_o_n     0x0004L
#define   _X_I_M_P_r_e_e_d_i_t_N_o_t_h_i_n_g      0x0008L
#define   _X_I_M_P_r_e_e_d_i_t_N_o_n_e         0x0010L

#define   _X_I_M_S_t_a_t_u_s_A_r_e_a          0x0100L
#define   _X_I_M_S_t_a_t_u_s_C_a_l_l_b_a_c_k_s     0x0200L
#define   _X_I_M_S_t_a_t_u_s_N_o_t_h_i_n_g       0x0400L
#define   _X_I_M_S_t_a_t_u_s_N_o_n_e          0x0800L


typedef struct {
     unsigned short count_styles;
     XIMStyle * supported_styles;
} XIMStyles;

││__

An _X_I_M_S_t_y_l_e_s structure contains the number of input styles
supported in its count_styles field.  This is also the size
of the supported_styles array.

The supported styles is a list of bitmask combinations,
which indicate the combination of styles for each of the
areas supported.  These areas are described later.  Each
element in the list should select one of the bitmask values
for each area.  The list describes the complete set of com­
binations supported.  Only these combinations are supported
by the input method.

The preedit category defines what type of support is pro­
vided by the input method for preedit information.

_X_I_M_P_r_e_e_d_i_t_A_r_e_a    If chosen, the input method would require
                  the client to provide some area values for
                  it to do its preediting.  Refer to XIC
                  values _X_N_A_r_e_a and _X_N_A_r_e_a_N_e_e_d_e_d.
_X_I_M_P_r_e_e_d_i_t_P_o_s_i_­   If chosen, the input method would require
_t_i_o_n              the client to provide positional values.
                  Refer to XIC values _X_N_S_p_o_t_L_o_c_a_t_i_o_n and
                  _X_N_F_o_c_u_s_W_i_n_d_o_w.
_X_I_M_P_r_e_e_d_i_t_C_a_l_l_­   If chosen, the input method would require
_b_a_c_k_s             the client to define the set of preedit
                  callbacks.  Refer to XIC values _X_N_P_r_e_e_d_i_t_­
                  _S_t_a_r_t_C_a_l_l_b_a_c_k, _X_N_P_r_e_e_d_i_t_D_o_n_e_C_a_l_l_b_a_c_k,
                  _X_N_P_r_e_e_d_i_t_D_r_a_w_C_a_l_l_b_a_c_k, and _X_N_P_r_e_e_d_i_t_C_a_r_e_t_­
                  _C_a_l_l_b_a_c_k.





                             445511





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_I_M_P_r_e_e_d_i_t_N_o_t_h_­   If chosen, the input method can function
_i_n_g               without any preedit values.
_X_I_M_P_r_e_e_d_i_t_N_o_n_e    The input method does not provide any
                  preedit feedback.  Any preedit value is
                  ignored.  This style is mutually exclusive
                  with the other preedit styles.


The status category defines what type of support is provided
by the input method for status information.

_X_I_M_S_t_a_t_u_s_A_r_e_a     The input method requires the client to
                  provide some area values for it to do its
                  status feedback.  See _X_N_A_r_e_a and _X_N_A_r_e_a_­
                  _N_e_e_d_e_d.
_X_I_M_S_t_a_t_u_s_C_a_l_l_­    The input method requires the client to
_b_a_c_k_s             define the set of status callbacks, _X_N_S_t_a_­
                  _t_u_s_S_t_a_r_t_C_a_l_l_b_a_c_k, _X_N_S_t_a_t_u_s_D_o_n_e_C_a_l_l_b_a_c_k,
                  and _X_N_S_t_a_t_u_s_D_r_a_w_C_a_l_l_b_a_c_k.
_X_I_M_S_t_a_t_u_s_N_o_t_h_­    The input method can function without any
_i_n_g               status values.
_X_I_M_S_t_a_t_u_s_N_o_n_e     The input method does not provide any sta­
                  tus feedback.  If chosen, any status value
                  is ignored.  This style is mutually exclu­
                  sive with the other status styles.


1133..55..44..22..  RReessoouurrccee NNaammee aanndd CCllaassss

The _X_N_R_e_s_o_u_r_c_e_N_a_m_e and _X_N_R_e_s_o_u_r_c_e_C_l_a_s_s arguments are strings
that specify the full name and class used by the input
method.  These values should be used as prefixes for the
name and class when looking up resources that may vary
according to the input method.  If these values are not set,
the resources will not be fully specified.

It is not intended that values that can be set as XIM values
be set as resources.


1133..55..44..33..  DDeessttrrooyy CCaallllbbaacckk

The _X_N_D_e_s_t_r_o_y_C_a_l_l_b_a_c_k argument is a pointer to a structure
of type _X_I_M_C_a_l_l_b_a_c_k.  _X_N_D_e_s_t_r_o_y_C_a_l_l_b_a_c_k is triggered when an
input method stops its service for any reason.  After the
callback is invoked, the input method is closed and the
associated input context(s) are destroyed by Xlib.  There­
fore, the client should not call _X_C_l_o_s_e_I_M or _X_D_e_s_t_r_o_y_I_C.

The generic prototype of this callback function is as fol­
lows:






                             445522





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void DestroyCallback(_i_m, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIM _i_m;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XPointer _c_a_l_l___d_a_t_a;


_i_m        Specifies the input method.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Not used for this callback and always passed as
          NULL.
││__

A DestroyCallback is always called with a NULL call_data
argument.


1133..55..44..44..  QQuueerryy IIMM//IICC VVaalluueess LLiisstt

_X_N_Q_u_e_r_y_I_M_V_a_l_u_e_s_L_i_s_t and _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t are used to
query about XIM and XIC values supported by the input
method.

The argument value must be a pointer to a location where the
returned value will be stored.  The returned value is a
pointer to a structure of type _X_I_M_V_a_l_u_e_s_L_i_s_t.  Clients are
responsible for freeing the _X_I_M_V_a_l_u_e_s_L_i_s_t structure.  To do
so, use _X_F_r_e_e.

The _X_I_M_V_a_l_u_e_s_L_i_s_t structure is defined as follows:
__
││
typedef struct {
     unsigned short count_values;
     char **supported_values;
} XIMValuesList;

││__


1133..55..44..55..  VViissiibbllee PPoossiittiioonn

The _X_N_V_i_s_i_b_l_e_P_o_s_i_t_i_o_n argument indicates whether the visible
position masks of _X_I_M_F_e_e_d_b_a_c_k in _X_I_M_T_e_x_t are available.

The argument value must be a pointer to a location where the
returned value will be stored.  The returned value is of
type _B_o_o_l.  If the returned value is _T_r_u_e, the input method
uses the visible position masks of _X_I_M_F_e_e_d_b_a_c_k in _X_I_M_T_e_x_t;
otherwise, the input method does not use the masks.




                             445533





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Because this XIM value is optional, a client should call
_X_G_e_t_I_M_V_a_l_u_e_s with argument _X_N_Q_u_e_r_y_I_M_V_a_l_u_e_s before using this
argument.  If the _X_N_V_i_s_i_b_l_e_P_o_s_i_t_i_o_n does not exist in the IM
values list returned from _X_N_Q_u_e_r_y_I_M_V_a_l_u_e_s, the visible posi­
tion masks of _X_I_M_F_e_e_d_b_a_c_k in _X_I_M_T_e_x_t are not used to indi­
cate the visible position.


1133..55..44..66..  PPrreeeeddiitt CCaallllbbaacckk BBeehhaavviioorr

The _X_N_R_6_P_r_e_e_d_i_t_C_a_l_l_b_a_c_k_B_e_h_a_v_i_o_r argument originally included
in the X11R6 specification has been deprecated.†

The _X_N_R_6_P_r_e_e_d_i_t_C_a_l_l_b_a_c_k_B_e_h_a_v_i_o_r argument indicates whether
the behavior of preedit callbacks regarding _X_I_M_P_r_e_e_d_i_t_D_r_a_w_­
_C_a_l_l_b_a_c_k_S_t_r_u_c_t values follows Release 5 or Release 6 seman­
tics.

The value is of type _B_o_o_l.  When querying for _X_N_R_6_P_r_e_e_d_i_t_­
_C_a_l_l_b_a_c_k_B_e_h_a_v_i_o_r, if the returned value is _T_r_u_e, the input
method uses the Release 6 behavior; otherwise, it uses the
Release 5 behavior.  The default value is _F_a_l_s_e.  In order
to use Release 6 semantics, the value of _X_N_R_6_P_r_e_e_d_i_t_C_a_l_l_­
_b_a_c_k_B_e_h_a_v_i_o_r must be set to _T_r_u_e.

Because this XIM value is optional, a client should call
_X_G_e_t_I_M_V_a_l_u_e_s with argument _X_N_Q_u_e_r_y_I_M_V_a_l_u_e_s before using this
argument.  If the _X_N_R_6_P_r_e_e_d_i_t_C_a_l_l_b_a_c_k_B_e_h_a_v_i_o_r does not exist
in the IM values list returned from _X_N_Q_u_e_r_y_I_M_V_a_l_u_e_s, the
PreeditCallback behavior is Release 5 semantics.


1133..55..55..  IInnppuutt CCoonntteexxtt FFuunnccttiioonnss

An input context is an abstraction that is used to contain
both the data required (if any) by an input method and the
information required to display that data.  There may be
multiple input contexts for one input method.  The program­
ming interfaces for creating, reading, or modifying an input
context use a variable argument list.  The name elements of
the argument lists are referred to as XIC values.  It is
intended that input methods be controlled by these XIC val­
ues.  As new XIC values are created, they should be regis­
tered with the X Consortium.

-----------
  † During formulation of the X11R6 specification,
the behavior of the R6 PreeditDrawCallbacks was
going to differ significantly from that of the R5
callbacks.  Late changes to the specification con­
verged the R5 and R6 behaviors, eliminating the
need for _X_N_R_6_P_r_e_e_d_i_t_C_a_l_l_b_a_c_k_B_e_h_a_v_i_o_r.  Unfortu­
nately, this argument was not removed from the R6
specification before it was published.



                             445544





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To create an input context, use _X_C_r_e_a_t_e_I_C.
__
││
XIC XCreateIC(_i_m, ...)
      XIM _i_m;


_i_m        Specifies the input method.

...       Specifies the variable length argument list to set
          XIC values.
││__

The _X_C_r_e_a_t_e_I_C function creates a context within the speci­
fied input method.

Some of the arguments are mandatory at creation time, and
the input context will not be created if those arguments are
not provided.  The mandatory arguments are the input style
and the set of text callbacks (if the input style selected
requires callbacks).  All other input context values can be
set later.

_X_C_r_e_a_t_e_I_C returns a NULL value if no input context could be
created.  A NULL value could be returned for any of the fol­
lowing reasons:

⋅    A required argument was not set.

⋅    A read‐only argument was set (for example, _X_N_F_i_l_­
     _t_e_r_E_v_e_n_t_s).

⋅    The argument name is not recognized.

⋅    The input method encountered an input method implemen­
     tation‐dependent error.

_X_C_r_e_a_t_e_I_C can generate _B_a_d_A_t_o_m, _B_a_d_C_o_l_o_r, _B_a_d_P_i_x_m_a_p, and
_B_a_d_W_i_n_d_o_w errors.


To destroy an input context, use _X_D_e_s_t_r_o_y_I_C.
__
││
void XDestroyIC(_i_c)
      XIC _i_c;


_i_c        Specifies the input context.
││__

_X_D_e_s_t_r_o_y_I_C destroys the specified input context.





                             445555





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To communicate to and synchronize with input method for any
changes in keyboard focus from the client side, use _X_S_e_t_I_C_­
_F_o_c_u_s and _X_U_n_s_e_t_I_C_F_o_c_u_s.
__
││
void XSetICFocus(_i_c)
      XIC _i_c;


_i_c        Specifies the input context.
││__

The _X_S_e_t_I_C_F_o_c_u_s function allows a client to notify an input
method that the focus window attached to the specified input
context has received keyboard focus.  The input method
should take action to provide appropriate feedback.  Com­
plete feedback specification is a matter of user interface
policy.

Calling _X_S_e_t_I_C_F_o_c_u_s does not affect the focus window value.


__
││
void XUnsetICFocus(_i_c)
      XIC _i_c;


_i_c        Specifies the input context.
││__

The _X_U_n_s_e_t_I_C_F_o_c_u_s function allows a client to notify an
input method that the specified input context has lost the
keyboard focus and that no more input is expected on the
focus window attached to that input context.  The input
method should take action to provide appropriate feedback.
Complete feedback specification is a matter of user inter­
face policy.

Calling _X_U_n_s_e_t_I_C_F_o_c_u_s does not affect the focus window
value; the client may still receive events from the input
method that are directed to the focus window.


To reset the state of an input context to its initial state,
use _X_m_b_R_e_s_e_t_I_C or _X_w_c_R_e_s_e_t_I_C.











                             445566





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char * XmbResetIC(_i_c)
      XIC _i_c;


wchar_t * XwcResetIC(_i_c)
      XIC _i_c;


_i_c        Specifies the input context.
││__

When _X_N_R_e_s_e_t_S_t_a_t_e is set to _X_I_M_I_n_i_t_i_a_l_S_t_a_t_e, _X_m_b_R_e_s_e_t_I_C and
_X_w_c_R_e_s_e_t_I_C reset an input context to its initial state; when
_X_N_R_e_s_e_t_S_t_a_t_e is set to _X_I_M_P_r_e_s_e_r_v_e_S_t_a_t_e, the current input
context state is preserved.  In both cases, any input pend­
ing on that context is deleted.  The input method is
required to clear the preedit area, if any, and update the
status accordingly.  Calling _X_m_b_R_e_s_e_t_I_C or _X_w_c_R_e_s_e_t_I_C does
not change the focus.

The return value of _X_m_b_R_e_s_e_t_I_C is its current preedit string
as a multibyte string.  If there is any preedit text drawn
or visible to the user, then these procedures must return a
non‐NULL string.  If there is no visible preedit text, then
it is input method implementation‐dependent whether these
procedures return a non‐NULL string or NULL.

The client should free the returned string by calling _X_F_r_e_e.


To get the input method associated with an input context,
use _X_I_M_O_f_I_C.
__
││
XIM XIMOfIC(_i_c)
      XIC _i_c;


_i_c        Specifies the input context.
││__

The _X_I_M_O_f_I_C function returns the input method associated
with the specified input context.


Xlib provides two functions for setting and reading XIC val­
ues, respectively, _X_S_e_t_I_C_V_a_l_u_e_s and _X_G_e_t_I_C_V_a_l_u_e_s.  Both
functions have a variable‐length argument list.  In that
argument list, any XIC value’s name must be denoted with a
character string using the X Portable Character Set.


To set XIC values, use _X_S_e_t_I_C_V_a_l_u_e_s.



                             445577





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char * XSetICValues(_i_c, ...)
      XIC _i_c;


_i_c        Specifies the input context.

...       Specifies the variable length argument list to set
          XIC values.
││__

The _X_S_e_t_I_C_V_a_l_u_e_s function returns NULL if no error occurred;
otherwise, it returns the name of the first argument that
could not be set.  An argument might not be set for any of
the following reasons:

⋅    The argument is read‐only (for example, _X_N_F_i_l_­
     _t_e_r_E_v_e_n_t_s).

⋅    The argument name is not recognized.

⋅    An implementation‐dependent error occurs.

Each value to be set must be an appropriate datum, matching
the data type imposed by the semantics of the argument.

_X_S_e_t_I_C_V_a_l_u_e_s can generate _B_a_d_A_t_o_m, _B_a_d_C_o_l_o_r, _B_a_d_C_u_r_s_o_r, _B_a_d_­
_P_i_x_m_a_p, and _B_a_d_W_i_n_d_o_w errors.


To obtain XIC values, use _X_G_e_t_I_C_V_a_l_u_e_s.
__
││
char * XGetICValues(_i_c, ...)
      XIC _i_c;


_i_c        Specifies the input context.

...       Specifies the variable length argument list to get
          XIC values.
││__

The _X_G_e_t_I_C_V_a_l_u_e_s function returns NULL if no error occurred;
otherwise, it returns the name of the first argument that
could not be obtained.  An argument could not be obtained
for any of the following reasons:

⋅    The argument name is not recognized.

⋅    The input method encountered an implementation‐depen­
     dent error.





                             445588





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Each IC attribute value argument (following a name) must
point to a location where the IC value is to be stored.
That is, if the IC value is of type T, the argument must be
of type T*.  If T itself is a pointer type, then _X_G_e_t_I_C_V_a_l_­
_u_e_s allocates memory to store the actual data, and the
client is responsible for freeing this data by calling _X_F_r_e_e
with the returned pointer.  The exception to this rule is
for an IC value of type _X_V_a_N_e_s_t_e_d_L_i_s_t (for preedit and sta­
tus attributes).  In this case,  the argument must also be
of type _X_V_a_N_e_s_t_e_d_L_i_s_t.  Then, the rule of changing type T to
T* and freeing the allocated data applies to each element of
the nested list.

1133..55..66..  IInnppuutt CCoonntteexxtt VVaalluueess

The following tables describe how XIC values are interpreted
by an input method depending on the input style chosen by
the user.

The first column lists the XIC values.  The second column
indicates which values are involved in affecting, negotiat­
ing, and setting the geometry of the input method windows.
The subentries under the third column indicate the different
input styles that are supported.  Each of these columns
indicates how each of the XIC values are treated by that
input style.

The following keys apply to these tables.

-------------------------------------------------------------
KKeeyy          EExxppllaannaattiioonn
-------------------------------------------------------------
C            This value must be set with _X_C_r_e_a_t_e_I_C.
D            This value may be set using _X_C_r_e_a_t_e_I_C.  If it
             is not set, a default is provided.
G            This value may be read using _X_G_e_t_I_C_V_a_l_u_e_s.
GN           This value may cause geometry negotiation when
             its value is set by means of _X_C_r_e_a_t_e_I_C or _X_S_e_t_­
             _I_C_V_a_l_u_e_s.
GR           This value will be the response of the input
             method when any GN value is changed.
GS           This value will cause the geometry of the input
             method window to be set.
O            This value must be set once and only once.  It
             need not be set at create time.
S            This value may be set with _X_S_e_t_I_C_V_a_l_u_e_s.
Ignored      This value is ignored by the input method for
             the given input style.
-------------------------------------------------------------








                             445599





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-----------------------------------------------------------------------------------------------
                                                                IInnppuutt SSttyyllee
XXIICC VVaalluuee                        GGeeoommeettrryy    PPrreeeeddiitt    PPrreeeeddiitt    PPrreeeeddiitt   PPrreeeeddiitt   PPrreeeeddiitt
                                MMaannaaggeemmeenntt   CCaallllbbaacckk   PPoossiittiioonn    AArreeaa     NNootthhiinngg    NNoonnee
-----------------------------------------------------------------------------------------------
Input Style                                    C‐G        C‐G        C‐G       C‐G       C‐G
Client Window                                  O‐G        O‐G        O‐G       O‐G     Ignored
Focus Window                        GN        D‐S‐G      D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Resource Name                                Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Resource Class                               Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Geometry Callback                            Ignored    Ignored     D‐S‐G    Ignored   Ignored
Filter Events                                   G          G          G         G      Ignored
Destroy Callback                              D‐S‐G      D‐S‐G      D‐S‐G     D‐S‐G     D‐S‐G
String Conversion Callback                     S‐G        S‐G        S‐G       S‐G       S‐G
String Conversion                             D‐S‐G      D‐S‐G      D‐S‐G     D‐S‐G     D‐S‐G
Reset State                                   D‐S‐G      D‐S‐G      D‐S‐G     D‐S‐G    Ignored
HotKey                                         S‐G        S‐G        S‐G       S‐G     Ignored
HotKeyState                                   D‐S‐G      D‐S‐G      D‐S‐G     D‐S‐G    Ignored
PPrreeeeddiitt
Area                                GS       Ignored     D‐S‐G      D‐S‐G    Ignored   Ignored
Area Needed                       GN‐GR      Ignored    Ignored      S‐G     Ignored   Ignored
Spot Location                                Ignored     D‐S‐G     Ignored   Ignored   Ignored
Colormap                                     Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Foreground                                   Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Background                                   Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Background Pixmap                            Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Font Set                            GN       Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Line Spacing                        GN       Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Cursor                                       Ignored     D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Preedit State                                 D‐S‐G      D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Preedit State Notify Callback                  S‐G        S‐G        S‐G       S‐G     Ignored
Preedit Callbacks                             C‐S‐G     Ignored    Ignored   Ignored   Ignored
-----------------------------------------------------------------------------------------------



------------------------------------------------------------------------
                                              IInnppuutt SSttyyllee
XXIICC VVaalluuee            GGeeoommeettrryy     SSttaattuuss    SSttaattuuss    SSttaattuuss    SSttaattuuss
                    MMaannaaggeemmeenntt   CCaallllbbaacckk    AArreeaa     NNootthhiinngg    NNoonnee
------------------------------------------------------------------------
Input Style                        C‐G        C‐G       C‐G       C‐G
Client Window                      O‐G        O‐G       O‐G     Ignored
Focus Window            GN        D‐S‐G      D‐S‐G     D‐S‐G    Ignored
Resource Name                    Ignored     D‐S‐G     D‐S‐G    Ignored
Resource Class                   Ignored     D‐S‐G     D‐S‐G    Ignored
Geometry Callback                Ignored     D‐S‐G    Ignored   Ignored
Filter Events                       G          G         G         G
SSttaattuuss
Area                    GS       Ignored     D‐S‐G    Ignored   Ignored
Area Needed           GN‐GR      Ignored      S‐G     Ignored   Ignored
Colormap                         Ignored     D‐S‐G     D‐S‐G    Ignored
Foreground                       Ignored     D‐S‐G     D‐S‐G    Ignored




                             446600





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


------------------------------------------------------------------------
                                              IInnppuutt SSttyyllee
XXIICC VVaalluuee            GGeeoommeettrryy     SSttaattuuss    SSttaattuuss    SSttaattuuss    SSttaattuuss
                    MMaannaaggeemmeenntt   CCaallllbbaacckk    AArreeaa     NNootthhiinngg    NNoonnee
------------------------------------------------------------------------
Background                       Ignored     D‐S‐G     D‐S‐G    Ignored
Background Pixmap                Ignored     D‐S‐G     D‐S‐G    Ignored
Font Set                GN       Ignored     D‐S‐G     D‐S‐G    Ignored
Line Spacing            GN       Ignored     D‐S‐G     D‐S‐G    Ignored
Cursor                           Ignored     D‐S‐G     D‐S‐G    Ignored
Status Callbacks                  C‐S‐G     Ignored   Ignored   Ignored
------------------------------------------------------------------------


1133..55..66..11..  IInnppuutt SSttyyllee

The _X_N_I_n_p_u_t_S_t_y_l_e argument specifies the input style to be
used.  The value of this argument must be one of the values
returned by the _X_G_e_t_I_M_V_a_l_u_e_s function with the _X_N_Q_u_e_r_y_I_n_p_u_t_­
_S_t_y_l_e argument specified in the supported_styles list.

Note that this argument must be set at creation time and
cannot be changed.

1133..55..66..22..  CClliieenntt WWiinnddooww

The _X_N_C_l_i_e_n_t_W_i_n_d_o_w argument specifies to the input method
the client window in which the input method can display data
or create subwindows.  Geometry values for input method
areas are given with respect to the client window.  Dynamic
change of client window is not supported.  This argument may
be set only once and should be set before any input is done
using this input context.  If it is not set, the input
method may not operate correctly.

If an attempt is made to set this value a second time with
_X_S_e_t_I_C_V_a_l_u_e_s, the string _X_N_C_l_i_e_n_t_W_i_n_d_o_w will be returned by
_X_S_e_t_I_C_V_a_l_u_e_s, and the client window will not be changed.

If the client window is not a valid window ID on the display
attached to the input method, a _B_a_d_W_i_n_d_o_w error can be gen­
erated when this value is used by the input method.

1133..55..66..33..  FFooccuuss WWiinnddooww

The _X_N_F_o_c_u_s_W_i_n_d_o_w argument specifies the focus window.  The
primary purpose of the _X_N_F_o_c_u_s_W_i_n_d_o_w is to identify the win­
dow that will receive the key event when input is composed.
In addition, the input method may possibly affect the focus
window as follows:

⋅    Select events on it





                             446611





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    Send events to it

⋅    Modify its properties

⋅    Grab the keyboard within that window

The associated value must be of type _W_i_n_d_o_w.  If the focus
window is not a valid window ID on the display attached to
the input method, a _B_a_d_W_i_n_d_o_w error can be generated when
this value is used by the input method.

When this XIC value is left unspecified, the input method
will use the client window as the default focus window.

1133..55..66..44..  RReessoouurrccee NNaammee aanndd CCllaassss

The _X_N_R_e_s_o_u_r_c_e_N_a_m_e and _X_N_R_e_s_o_u_r_c_e_C_l_a_s_s arguments are strings
that specify the full name and class used by the client to
obtain resources for the client window.  These values should
be used as prefixes for name and class when looking up
resources that may vary according to the input context.  If
these values are not set, the resources will not be fully
specified.

It is not intended that values that can be set as XIC values
be set as resources.

1133..55..66..55..  GGeeoommeettrryy CCaallllbbaacckk

The _X_N_G_e_o_m_e_t_r_y_C_a_l_l_b_a_c_k argument is a structure of type _X_I_M_­
_C_a_l_l_b_a_c_k (see section 13.5.6.13.12).

The _X_N_G_e_o_m_e_t_r_y_C_a_l_l_b_a_c_k argument specifies the geometry call­
back that a client can set.  This callback is not required
for correct operation of either an input method or a client.
It can be set for a client whose user interface policy per­
mits an input method to request the dynamic change of that
input method’s window.  An input method that does dynamic
change will need to filter any events that it uses to initi­
ate the change.

1133..55..66..66..  FFiilltteerr EEvveennttss

The _X_N_F_i_l_t_e_r_E_v_e_n_t_s argument returns the event mask that an
input method needs to have selected for.  The client is
expected to augment its own event mask for the client window
with this one.

This argument is read‐only, is set by the input method at
create time, and is never changed.

The type of this argument is _u_n_s_i_g_n_e_d _l_o_n_g.  Setting this
value will cause an error.




                             446622





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1133..55..66..77..  DDeessttrrooyy CCaallllbbaacckk

The _X_N_D_e_s_t_r_o_y_C_a_l_l_b_a_c_k argument is a pointer to a structure
of type _X_I_M_C_a_l_l_b_a_c_k (see section 13.5.6.13.12).  This call­
back is triggered when the input method stops its service
for any reason; for example, when a connection to an IM
server is broken.  After the destroy callback is called, the
input context is destroyed and the input method is closed.
Therefore, the client should not call _X_D_e_s_t_r_o_y_I_C and _X_C_l_o_­
_s_e_I_M.


1133..55..66..88..  SSttrriinngg CCoonnvveerrssiioonn CCaallllbbaacckk

The _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k argument is a structure of
type _X_I_M_C_a_l_l_b_a_c_k (see section 13.5.6.13.12).

The _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k argument specifies a string
conversion callback.  This callback is not required for cor­
rect operation of either the input method or the client.  It
can be set by a client to support string conversions that
may be requested by the input method.  An input method that
does string conversions will filter any events that it uses
to initiate the conversion.

Because this XIC value is optional, a client should call
_X_G_e_t_I_M_V_a_l_u_e_s with argument _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t before using
this argument.


1133..55..66..99..  SSttrriinngg CCoonnvveerrssiioonn

The _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n argument is a structure of type _X_I_M_­
_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_T_e_x_t.

The _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n argument specifies the string to be
converted by an input method.  This argument is not required
for correct operation of either the input method or the
client.

String conversion facilitates the manipulation of text inde­
pendent of preediting.  It is essential for some input meth­
ods and clients to manipulate text by performing context‐
sensitive conversion, reconversion, or transliteration con­
version on it.

Because this XIC value is optional, a client should call
_X_G_e_t_I_M_V_a_l_u_e_s with argument _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t before using
this argument.

The _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_T_e_x_t structure is defined as follows:






                             446633





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││

typedef struct _XIMStringConversionText {
     unsigned short length;
     XIMStringConversionFeedback *feedback;
     Bool encoding_is_wchar;
     union {
          char *mbs;
          wchar_t *wcs;
     } string;
} XIMStringConversionText;

typedef unsigned long XIMStringConversionFeedback;

││__

The feedback member is reserved for future use.  The text to
be converted is defined by the string and length members.
The length is indicated in characters.  To prevent the
library from freeing memory pointed to by an uninitialized
pointer, the client should set the feedback element to NULL.


1133..55..66..1100..  RReesseett SSttaattee

The _X_N_R_e_s_e_t_S_t_a_t_e argument specifies the state the input con­
text will return to after calling _X_m_b_R_e_s_e_t_I_C or _X_w_c_R_e_s_e_t_I_C.

The XIC state may be set to its initial state, as specified
by the _X_N_P_r_e_e_d_i_t_S_t_a_t_e value when _X_C_r_e_a_t_e_I_C was called, or it
may be set to preserve the current state.

The valid masks for _X_I_M_R_e_s_e_t_S_t_a_t_e are as follows:

__
││

typedef unsigned long XIMResetState;


#define   _X_I_M_I_n_i_t_i_a_l_S_t_a_t_e        (1L)
#define   _X_I_M_P_r_e_s_e_r_v_e_S_t_a_t_e       (1L<<1)

││__

If _X_I_M_I_n_i_t_i_a_l_S_t_a_t_e is set, then _X_m_b_R_e_s_e_t_I_C and _X_w_c_R_e_s_e_t_I_C
will return to the initial _X_N_P_r_e_e_d_i_t_S_t_a_t_e state of the XIC.

If _X_I_M_P_r_e_s_e_r_v_e_S_t_a_t_e is set, then _X_m_b_R_e_s_e_t_I_C and _X_w_c_R_e_s_e_t_I_C
will preserve the current state of the XIC.

If _X_N_R_e_s_e_t_S_t_a_t_e is left unspecified, the default is _X_I_M_I_n_i_­
_t_i_a_l_S_t_a_t_e.




                             446644





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_I_M_R_e_s_e_t_S_t_a_t_e values other than those specified above will
default to _X_I_M_I_n_i_t_i_a_l_S_t_a_t_e.

Because this XIC value is optional, a client should call
_X_G_e_t_I_M_V_a_l_u_e_s with argument _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t before using
this argument.


1133..55..66..1111..  HHoott KKeeyyss

The _X_N_H_o_t_K_e_y argument specifies the hot key list to the XIC.
The hot key list is a pointer to the structure of type
_X_I_M_H_o_t_K_e_y_T_r_i_g_g_e_r_s, which specifies the key events that must
be received without any interruption of the input method.
For the hot key list set with this argument to be utilized,
the client must also set _X_N_H_o_t_K_e_y_S_t_a_t_e to _X_I_M_H_o_t_K_e_y_S_t_a_t_e_O_N.

Because this XIC value is optional, a client should call
_X_G_e_t_I_M_V_a_l_u_e_s with argument _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t before using
this functionality.

The value of the argument is a pointer to a structure of
type _X_I_M_H_o_t_K_e_y_T_r_i_g_g_e_r_s.

If an event for a key in the hot key list is found, then the
process will receive the event and it will be processed
inside the client.

__
││
typedef struct {
     KeySym keysym;
     unsigned int modifier;
     unsigned int modifier_mask;
} XIMHotKeyTrigger;

typedef struct {
     int num_hot_key;
     XIMHotKeyTrigger *key;
} XIMHotKeyTriggers;

││__


The combination of modifier and modifier_mask are used to
represent one of three states for each modifier: either the
modifier must be on, or the modifier must be off, or the
modifier is a ‘‘don’t care’’ − it may be on or off.  When a
modifier_mask bit is set to 0, the state of the associated
modifier is ignored when evaluating whether the key is hot
or not.






                             446655





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-----------------------------------------------------------
MMooddiiffiieerr BBiitt   MMaasskk BBiitt     MMeeaanniinngg
-----------------------------------------------------------
0              1            The modifier must be off.
1              1            The modifier must be on.
n/a            0            Do not care if the modifier is
                            on or off.
-----------------------------------------------------------


1133..55..66..1122..  HHoott KKeeyy SSttaattee

The _X_N_H_o_t_K_e_y_S_t_a_t_e argument specifies the hot key state of
the input method.  This is usually used to switch the input
method between hot key operation and normal input process­
ing.

The value of the argument is a pointer to a structure of
type XIMHotKeyState .

__
││
typedef unsigned long XIMHotKeyState;


#define   _X_I_M_H_o_t_K_e_y_S_t_a_t_e_O_N                 (0x0001L)
#define   _X_I_M_H_o_t_K_e_y_S_t_a_t_e_O_F_F                (0x0002L)

││__


If not specified, the default is _X_I_M_H_o_t_K_e_y_S_t_a_t_e_O_F_F.


1133..55..66..1133..  PPrreeeeddiitt aanndd SSttaattuuss AAttttrriibbuutteess

The _X_N_P_r_e_e_d_i_t_A_t_t_r_i_b_u_t_e_s and _X_N_S_t_a_t_u_s_A_t_t_r_i_b_u_t_e_s arguments
specify to an input method the attributes to be used for the
preedit and status areas, if any.  Those attributes are
passed to _X_S_e_t_I_C_V_a_l_u_e_s or _X_G_e_t_I_C_V_a_l_u_e_s as a nested variable‐
length list.  The names to be used in these lists are
described in the following sections.

1133..55..66..1133..11..  AArreeaa

The value of the _X_N_A_r_e_a argument must be a pointer to a
structure of type _X_R_e_c_t_a_n_g_l_e_. The interpretation of the
_X_N_A_r_e_a argument is dependent on the input method style that
has been set.

If the input method style is _X_I_M_P_r_e_e_d_i_t_P_o_s_i_t_i_o_n, _X_N_A_r_e_a
specifies the clipping region within which preediting will
take place.  If the focus window has been set, the coordi­
nates are assumed to be relative to the focus window.



                             446666





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Otherwise, the coordinates are assumed to be relative to the
client window.  If neither has been set, the results are
undefined.

If _X_N_A_r_e_a is not specified, is set to NULL, or is invalid,
the input method will default the clipping region to the
geometry of the _X_N_F_o_c_u_s_W_i_n_d_o_w.  If the area specified is
NULL or invalid, the results are undefined.

If the input style is _X_I_M_P_r_e_e_d_i_t_A_r_e_a or _X_I_M_S_t_a_t_u_s_A_r_e_a,
_X_N_A_r_e_a specifies the geometry provided by the client to the
input method.  The input method may use this area to display
its data, either preedit or status depending on the area
designated.  The input method may create a window as a child
of the client window with dimensions that fit the _X_N_A_r_e_a.
The coordinates are relative to the client window.  If the
client window has not been set yet, the input method should
save these values and apply them when the client window is
set.  If _X_N_A_r_e_a is not specified, is set to NULL, or is
invalid, the results are undefined.

1133..55..66..1133..22..  AArreeaa NNeeeeddeedd

When set, the _X_N_A_r_e_a_N_e_e_d_e_d argument specifies the geometry
suggested by the client for this area (preedit or status).
The value associated with the argument must be a pointer to
a structure of type _X_R_e_c_t_a_n_g_l_e.  Note that the x, y values
are not used and that nonzero values for width or height are
the constraints that the client wishes the input method to
respect.

When read, the _X_N_A_r_e_a_N_e_e_d_e_d argument specifies the preferred
geometry desired by the input method for the area.

This argument is only valid if the input style is _X_I_M_P_r_e_e_d_­
_i_t_A_r_e_a or _X_I_M_S_t_a_t_u_s_A_r_e_a.  It is used for geometry negotia­
tion between the client and the input method and has no
other effect on the input method (see section 13.5.1.5).

1133..55..66..1133..33..  SSppoott LLooccaattiioonn

The _X_N_S_p_o_t_L_o_c_a_t_i_o_n argument specifies to the input method
the coordinates of the spot to be used by an input method
executing with _X_N_I_n_p_u_t_S_t_y_l_e set to _X_I_M_P_r_e_e_d_i_t_P_o_s_i_t_i_o_n.  When
specified to any input method other than _X_I_M_P_r_e_e_d_i_t_P_o_s_i_t_i_o_n,
this XIC value is ignored.

The x coordinate specifies the position where the next char­
acter would be inserted.  The y coordinate is the position
of the baseline used by the current text line in the focus
window.  The x and y coordinates are relative to the focus
window, if it has been set; otherwise, they are relative to
the client window.  If neither the focus window nor the
client window has been set, the results are undefined.



                             446677





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The value of the argument is a pointer to a structure of
type _X_P_o_i_n_t.

1133..55..66..1133..44..  CCoolloorrmmaapp

Two different arguments can be used to indicate what col­
ormap the input method should use to allocate colors, a col­
ormap ID, or a standard colormap name.

The _X_N_C_o_l_o_r_m_a_p argument is used to specify a colormap ID.
The argument value is of type _C_o_l_o_r_m_a_p.  An invalid argument
may generate a _B_a_d_C_o_l_o_r error when it is used by the input
method.

The _X_N_S_t_d_C_o_l_o_r_m_a_p argument is used to indicate the name of
the standard colormap in which the input method should allo­
cate colors.  The argument value is an _A_t_o_m that should be a
valid atom for calling _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s.  An invalid argu­
ment may generate a _B_a_d_A_t_o_m error when it is used by the
input method.

If the colormap is left unspecified, the client window col­
ormap becomes the default.

1133..55..66..1133..55..  FFoorreeggrroouunndd aanndd BBaacckkggrroouunndd

The _X_N_F_o_r_e_g_r_o_u_n_d and _X_N_B_a_c_k_g_r_o_u_n_d arguments specify the
foreground and background pixel, respectively.  The argument
value is of type _u_n_s_i_g_n_e_d _l_o_n_g.  It must be a valid pixel in
the input method colormap.

If these values are left unspecified, the default is deter­
mined by the input method.

1133..55..66..1133..66..  BBaacckkggrroouunndd PPiixxmmaapp

The _X_N_B_a_c_k_g_r_o_u_n_d_P_i_x_m_a_p argument specifies a background
pixmap to be used as the background of the window.  The
value must be of type _P_i_x_m_a_p.  An invalid argument may gen­
erate a _B_a_d_P_i_x_m_a_p error when it is used by the input method.

If this value is left unspecified, the default is determined
by the input method.

1133..55..66..1133..77..  FFoonntt SSeett

The _X_N_F_o_n_t_S_e_t argument specifies to the input method what
font set is to be used.  The argument value is of type
_X_F_o_n_t_S_e_t.

If this value is left unspecified, the default is determined
by the input method.





                             446688





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1133..55..66..1133..88..  LLiinnee SSppaacciinngg

The _X_N_L_i_n_e_S_p_a_c_e argument specifies to the input method what
line spacing is to be used in the preedit window if more
than one line is to be used.  This argument is of type _i_n_t.

If this value is left unspecified, the default is determined
by the input method.

1133..55..66..1133..99..  CCuurrssoorr

The _X_N_C_u_r_s_o_r argument specifies to the input method what
cursor is to be used in the specified window.  This argument
is of type _C_u_r_s_o_r.

An invalid argument may generate a _B_a_d_C_u_r_s_o_r error when it
is used by the input method.  If this value is left unspeci­
fied, the default is determined by the input method.

1133..55..66..1133..1100..  PPrreeeeddiitt SSttaattee

The _X_N_P_r_e_e_d_i_t_S_t_a_t_e argument specifies the state of input
preediting for the input method.  Input preediting can be on
or off.

The valid mask names for _X_N_P_r_e_e_d_i_t_S_t_a_t_e are as follows:

__
││

typedef unsigned long XIMPreeditState;


#define   _X_I_M_P_r_e_e_d_i_t_U_n_k_n_o_w_n      0L
#define   _X_I_M_P_r_e_e_d_i_t_E_n_a_b_l_e       1L
#define   _X_I_M_P_r_e_e_d_i_t_D_i_s_a_b_l_e      (1L<<1)

││__

If a value of _X_I_M_P_r_e_e_d_i_t_E_n_a_b_l_e is set, then input preediting
is turned on by the input method.

If a value of _X_I_M_P_r_e_e_d_i_t_D_i_s_a_b_l_e is set, then input preedit­
ing is turned off by the input method.

If _X_N_P_r_e_e_d_i_t_S_t_a_t_e is left unspecified, then the state will
be implementation‐dependent.

When _X_N_R_e_s_e_t_S_t_a_t_e is set to _X_I_M_I_n_i_t_i_a_l_S_t_a_t_e, the _X_N_P_r_e_e_d_i_t_­
_S_t_a_t_e value specified at the creation time will be reflected
as the initial state for _X_m_b_R_e_s_e_t_I_C and _X_w_c_R_e_s_e_t_I_C.

Because this XIC value is optional, a client should call
_X_G_e_t_I_M_V_a_l_u_e_s with argument _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t before using



                             446699





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


this argument.

1133..55..66..1133..1111..  PPrreeeeddiitt SSttaattee NNoottiiffyy CCaallllbbaacckk

The preedit state notify callback is triggered by the input
method when the preediting state has changed.  The value of
the _X_N_P_r_e_e_d_i_t_S_t_a_t_e_N_o_t_i_f_y_C_a_l_l_b_a_c_k argument is a pointer to a
structure of type _X_I_M_C_a_l_l_b_a_c_k.  The generic prototype is as
follows:
__
││
void PreeditStateNotifyCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XIMPreeditStateNotifyCallbackStruct *_c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Specifies the current preedit state.
││__

The _X_I_M_P_r_e_e_d_i_t_S_t_a_t_e_N_o_t_i_f_y_C_a_l_l_b_a_c_k_S_t_r_u_c_t structure is defined
as follows:

__
││
typedef struct _XIMPreeditStateNotifyCallbackStruct {
     XIMPreeditState state;
} XIMPreeditStateNotifyCallbackStruct;

││__


Because this XIC value is optional, a client should call
_X_G_e_t_I_M_V_a_l_u_e_s with argument _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t before using
this argument.

1133..55..66..1133..1122..  PPrreeeeddiitt aanndd SSttaattuuss CCaallllbbaacckkss

A client that wants to support the input style _X_I_M_P_r_e_e_d_i_t_­
_C_a_l_l_b_a_c_k_s must provide a set of preedit callbacks to the
input method.  The set of preedit callbacks is as follows:

_X_N_P_r_e_e_d_i_t_S_t_a_r_t_­     This is called when the input method
_C_a_l_l_b_a_c_k            starts preedit.
_X_N_P_r_e_e_d_i_t_­          This is called when the input method
_D_o_n_e_C_a_l_l_b_a_c_k        stops preedit.
_X_N_P_r_e_e_d_i_t_D_r_a_w_­      This is called when a number of preedit
_C_a_l_l_b_a_c_k            keystrokes should be echoed.




                             447700





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_N_P_r_e_e_d_i_t_C_a_r_e_t_­     This is called to move the text inser­
_C_a_l_l_b_a_c_k            tion point within the preedit string.


A client that wants to support the input style _X_I_M_S_t_a_t_u_s_­
_C_a_l_l_b_a_c_k_s must provide a set of status callbacks to the
input method.  The set of status callbacks is as follows:

_X_N_S_t_a_t_u_s_S_t_a_r_t_­      This is called when the input method
_C_a_l_l_b_a_c_k            initializes the status area.
_X_N_S_t_a_t_u_s_D_o_n_e_C_a_l_l_­   This is called when the input method no
_b_a_c_k                longer needs the status area.
_X_N_S_t_a_t_u_s_D_r_a_w_C_a_l_l_­   This is called when updating of the sta­
_b_a_c_k                tus area is required.


The value of any status or preedit argument is a pointer to
a structure of type _X_I_M_C_a_l_l_b_a_c_k.
__
││

typedef void (*XIMProc)();

typedef struct {
     XPointer client_data;
     XIMProc callback;
} XIMCallback;

││__

Each callback has some particular semantics and will carry
the data that expresses the environment necessary to the
client into a specific data structure.  This paragraph only
describes the arguments to be used to set the callback.

Setting any of these values while doing preedit may cause
unexpected results.

1133..55..77..  IInnppuutt MMeetthhoodd CCaallllbbaacckk SSeemmaannttiiccss

XIM callbacks are procedures defined by clients or text
drawing packages that are to be called from the input method
when selected events occur.  Most clients will use a text
editing package or a toolkit and, hence, will not need to
define such callbacks.  This section defines the callback
semantics, when they are triggered, and what their arguments
are.  This information is mostly useful for X toolkit imple­
mentors.

Callbacks are mostly provided so that clients (or text edit­
ing packages) can implement on‐the‐spot preediting in their
own window.  In that case, the input method needs to commu­
nicate and synchronize with the client.  The input method
needs to communicate changes in the preedit window when it



                             447711





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


is under control of the client.  Those callbacks allow the
client to initialize the preedit area, display a new preedit
string, move the text insertion point during preedit, termi­
nate preedit, or update the status area.

All callback procedures follow the generic prototype:
__
││
void CallbackPrototype(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      SomeType _c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Specifies data specific to the callback.
││__

The call_data argument is a structure that expresses the
arguments needed to achieve the semantics; that is, it is a
specific data structure appropriate to the callback.  In
cases where no data is needed in the callback, this
call_data argument is NULL.  The client_data argument is a
closure that has been initially specified by the client when
specifying the callback and passed back.  It may serve, for
example, to inherit application context in the callback.

The following paragraphs describe the programming semantics
and specific data structure associated with the different
reasons.

1133..55..77..11..  GGeeoommeettrryy CCaallllbbaacckk

The geometry callback is triggered by the input method to
indicate that it wants the client to negotiate geometry.
The generic prototype is as follows:

















                             447722





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void GeometryCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XPointer _c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Not used for this callback and always passed as
          NULL.
││__

The callback is called with a NULL call_data argument.

1133..55..77..22..  DDeessttrrooyy CCaallllbbaacckk

The destroy callback is triggered by the input method when
it stops service for any reason.  After the callback is
invoked, the input context will be freed by Xlib.  The
generic prototype is as follows:
__
││
void DestroyCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XPointer _c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Not used for this callback and always passed as
          NULL.
││__

The callback is called with a NULL call_data argument.

1133..55..77..33..  SSttrriinngg CCoonnvveerrssiioonn CCaallllbbaacckk

The string conversion callback is triggered by the input
method to request the client to return the string to be con­
verted.  The returned string may be either a multibyte or
wide character string, with an encoding matching the locale
bound to the input context.  The callback prototype is as
follows:






                             447733





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void StringConversionCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XIMStringConversionCallbackStruct *_c_a_l_l___d_a_t_a;


_i_c        Specifies the input method.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Specifies the amount of the string to be con­
          verted.
││__

The callback is passed an _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k_S_t_r_u_c_t
structure in the call_data argument.  The text member is an
_X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_T_e_x_t structure (see section 13.5.6.9) to
be filled in by the client and describes the text to be sent
to the input method.  The data pointed to by the string and
feedback elements of the _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_T_e_x_t structure
will be freed using _X_F_r_e_e by the input method after the
callback returns.  So the client should not point to inter­
nal buffers that are critical to the client.  Similarly,
because the feedback element is currently reserved for
future use, the client should set feedback to NULL to pre­
vent the library from freeing memory at some random location
due to an uninitialized pointer.

The _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k_S_t_r_u_c_t structure is defined
as follows:

























                             447744





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││

typedef struct _XIMStringConversionCallbackStruct {
     XIMStringConversionPosition position;
     XIMCaretDirection direction;
     short factor;
     XIMStringConversionOperation operation;
     XIMStringConversionText *text;
} XIMStringConversionCallbackStruct;

typedef short XIMStringConversionPosition;

typedef unsigned short XIMStringConversionOperation;




#define   _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_S_u_b_s_t_i_t_u_­     (0x0001)
          _t_i_o_n
#define   _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_R_e_t_r_i_e_v_a_l     (0x0002)

││__

_X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_P_o_s_i_t_i_o_n specifies the starting position
of the string to be returned in the _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_T_e_x_t
structure.  The value identifies a position, in units of
characters, relative to the client’s cursor position in the
client’s buffer.

The ending position of the text buffer is determined by the
direction and factor members.  Specifically, it is the char­
acter position relative to the starting point as defined by
the _X_I_M_C_a_r_e_t_D_i_r_e_c_t_i_o_n.  The factor member of _X_I_M_S_t_r_i_n_g_C_o_n_­
_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k_S_t_r_u_c_t specifies the number of _X_I_M_C_a_r_e_t_D_i_r_e_c_­
_t_i_o_n positions to be applied.  For example, if the direction
specifies _X_I_M_L_i_n_e_E_n_d and factor is 1, then all characters
from the starting position to the end of the current display
line are returned.  If the direction specifies _X_I_M_F_o_r_w_a_r_d_­
_C_h_a_r or _X_I_M_B_a_c_k_w_a_r_d_C_h_a_r, then the factor specifies a rela­
tive position, indicated in characters, from the starting
position.

_X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_O_p_e_r_a_t_i_o_n specifies whether the string to
be converted should be deleted (substitution) or copied
(retrieval) from the client’s buffer.  When the _X_I_M_S_t_r_i_n_g_­
_C_o_n_v_e_r_s_i_o_n_O_p_e_r_a_t_i_o_n is _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_S_u_b_s_t_i_t_u_t_i_o_n, the
client must delete the string to be converted from its own
buffer.  When the _X_I_M_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_O_p_e_r_a_t_i_o_n is _X_I_M_S_t_r_i_n_g_­
_C_o_n_v_e_r_s_i_o_n_R_e_t_r_i_e_v_a_l, the client must not delete the string
to be converted from its buffer.  The substitute operation
is typically used for reconversion and transliteration con­
version, while the retrieval operation is typically used for
context‐sensitive conversion.




                             447755





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1133..55..77..44..  PPrreeeeddiitt SSttaattee CCaallllbbaacckkss

When the input method turns preediting on or off, a _P_r_e_e_d_i_t_­
_S_t_a_r_t_C_a_l_l_b_a_c_k or _P_r_e_e_d_i_t_D_o_n_e_C_a_l_l_b_a_c_k callback is triggered
to let the toolkit do the setup or the cleanup for the
preedit region.
__
││
int PreeditStartCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XPointer _c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Not used for this callback and always passed as
          NULL.
││__

When preedit starts on the specified input context, the
callback is called with a NULL call_data argument.  _P_r_e_e_d_i_t_­
_S_t_a_r_t_C_a_l_l_b_a_c_k will return the maximum size of the preedit
string.  A positive number indicates the maximum number of
bytes allowed in the preedit string, and a value of −1 indi­
cates there is no limit.
__
││
void PreeditDoneCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XPointer _c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Not used for this callback and always passed as
          NULL.
││__

When preedit stops on the specified input context, the call­
back is called with a NULL call_data argument.  The client
can release the data allocated by _P_r_e_e_d_i_t_S_t_a_r_t_C_a_l_l_b_a_c_k.

_P_r_e_e_d_i_t_S_t_a_r_t_C_a_l_l_b_a_c_k should initialize appropriate data
needed for displaying preedit information and for handling
further _P_r_e_e_d_i_t_D_r_a_w_C_a_l_l_b_a_c_k calls.  Once _P_r_e_e_d_i_t_S_t_a_r_t_C_a_l_l_­
_b_a_c_k is called, it will not be called again before



                             447766





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_P_r_e_e_d_i_t_D_o_n_e_C_a_l_l_b_a_c_k has been called.

1133..55..77..55..  PPrreeeeddiitt DDrraaww CCaallllbbaacckk

This callback is triggered to draw and insert, delete or
replace, preedit text in the preedit region.  The preedit
text may include unconverted input text such as Japanese
Kana, converted text such as Japanese Kanji characters, or
characters of both kinds.  That string is either a multibyte
or wide character string, whose encoding matches the locale
bound to the input context.  The callback prototype is as
follows:
__
││
void PreeditDrawCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XIMPreeditDrawCallbackStruct *_c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Specifies the preedit drawing information.
││__

The callback is passed an _X_I_M_P_r_e_e_d_i_t_D_r_a_w_C_a_l_l_b_a_c_k_S_t_r_u_c_t
structure in the call_data argument.  The text member of
this structure contains the text to be drawn.  After the
string has been drawn, the caret should be moved to the
specified location.

The _X_I_M_P_r_e_e_d_i_t_D_r_a_w_C_a_l_l_b_a_c_k_S_t_r_u_c_t structure is defined as
follows:

__
││
typedef struct _XIMPreeditDrawCallbackStruct {
     int caret;          /* Cursor offset within preedit string */
     int chg_first;      /* Starting change position */
     int chg_length;     /* Length of the change in character count */
     XIMText *text;
} XIMPreeditDrawCallbackStruct;

││__

The client must keep updating a buffer of the preedit text
and the callback arguments referring to indexes in that
buffer.  The call_data fields have specific meanings accord­
ing to the operation, as follows:





                             447777





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


⋅    To indicate text deletion, the call_data member speci­
     fies a NULL text field.  The text to be deleted is then
     the current text in the buffer from position chg_first
     (starting at zero) on a character length of chg_length.

⋅    When text is non‐NULL, it indicates insertion or
     replacement of text in the buffer.

     The chg_length member identifies the number of charac­
     ters in the current preedit buffer that are affected by
     this call.  A positive chg_length indicates that
     chg_length number of characters, starting at chg_first,
     must be deleted or must be replaced by text, whose
     length is specified in the _X_I_M_T_e_x_t structure.

     A chg_length value of zero indicates that text must be
     inserted right at the position specified by chg_first.
     A value of zero for chg_first specifies the first char­
     acter in the buffer.

     chg_length and chg_first combine to identify the modi­
     fication required to the preedit buffer; beginning at
     chg_first, replace chg_length number of characters with
     the text in the supplied _X_I_M_T_e_x_t structure. For exam­
     ple, suppose the preedit buffer contains the string
     "ABCDE".


          Text:      A B C D E
                    ^ ^ ^ ^ ^ ^
          CharPos:  0 1 2 3 4 5


     The CharPos in the diagram shows the location of the
     character position relative to the character.

     If the value of chg_first is 1 and the value of
     chg_length is 3, this says to replace 3 characters
     beginning at character position 1 with the string in
     the _X_I_M_T_e_x_t structure.  Hence, BCD would be replaced by
     the value in the structure.

     Though chg_length and chg_first are both signed inte­
     gers they will never have a negative value.

⋅    The caret member identifies the character position
     before which the cursor should be placed − after modi­
     fication to the preedit buffer has been completed.  For
     example, if caret is zero, the cursor is at the begin­
     ning of the buffer.  If the caret is one, the cursor is
     between the first and second character.






                             447788





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
     typedef struct _XIMText {
          unsigned short length;
          XIMFeedback * feedback;
          Bool encoding_is_wchar;
          union {
               char * multi_byte;
               wchar_t * wide_char;
          } string;
     } XIMText;

││__

The text string passed is actually a structure specifying as
follows:

⋅    The length member is the text length in characters.

⋅    The encoding_is_wchar member is a value that indicates
     if the text string is encoded in wide character or
     multibyte format.  The text string may be passed either
     as multibyte or as wide character; the input method
     controls in which form data is passed.  The client’s
     callback routine must be able to handle data passed in
     either form.

⋅    The string member is the text string.

⋅    The feedback member indicates rendering type for each
     character in the string member.  If string is NULL
     (indicating that only highlighting of the existing
     preedit buffer should be updated), feedback points to
     length highlight elements that should be applied to the
     existing preedit buffer, beginning at chg_first.

The feedback member expresses the types of rendering feed­
back the callback should apply when drawing text.  Rendering
of the text to be drawn is specified either in generic ways
(for example, primary, secondary) or in specific ways
(reverse, underline).  When generic indications are given,
the client is free to choose the rendering style.  It is
necessary, however, that primary and secondary be mapped to
two distinct rendering styles.

If an input method wants to control display of the preedit
string, an input method can indicate the visibility hints
using feedbacks in a specific way.  The _X_I_M_V_i_s_i_b_l_e_T_o_F_o_r_w_a_r_d,
_X_I_M_V_i_s_i_b_l_e_T_o_B_a_c_k_w_a_r_d, and _X_I_M_V_i_s_i_b_l_e_C_e_n_t_e_r masks are exclu­
sively used for these visibility hints.  The _X_I_M_V_i_s_i_b_l_e_T_o_­
_F_o_r_w_a_r_d mask indicates that the preedit text is preferably
displayed in the primary draw direction from the caret posi­
tion in the preedit area forward.  The _X_I_M_V_i_s_i_b_l_e_T_o_B_a_c_k_w_a_r_d
mask indicates that the preedit text is preferably displayed
from the caret position in the preedit area backward,



                             447799





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


relative to the primary draw direction.  The _X_I_M_V_i_s_i_b_l_e_C_e_n_­
_t_e_r mask indicates that the preedit text is preferably dis­
played with the caret position in the preedit area centered.

The insertion point of the preedit string could exist out­
side of the visible area when visibility hints are used.
Only one of the masks is valid for the entire preedit
string, and only one character can hold one of these feed­
backs for a given input context at one time.  This feedback
may be OR’ed together with another highlight (such as _X_I_M_R_e_­
_v_e_r_s_e).  Only the most recently set feedback is valid, and
any previous feedback is automatically canceled.  This is a
hint to the client, and the client is free to choose how to
display the preedit string.

The feedback member also specifies how rendering of the text
argument should be performed.  If the feedback is NULL, the
callback should apply the same feedback as is used for the
surrounding characters in the preedit buffer; if chg_first
is at a highlight boundary, the client can choose which of
the two highlights to use.  If feedback is not NULL, feed­
back specifies an array defining the rendering for each
character of the string, and the length of the array is thus
length.

If an input method wants to indicate that it is only updat­
ing the feedback of the preedit text without changing the
content of it, the _X_I_M_T_e_x_t structure will contain a NULL
value for the string field, the number of characters
affected (relative to chg_first) will be in the length
field, and the feedback field will point to an array of _X_I_M_­
_F_e_e_d_b_a_c_k.

Each element in the feedback array is a bitmask represented
by a value of type _X_I_M_F_e_e_d_b_a_c_k.  The valid mask names are as
follows:





















                             448800





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││

typedef unsigned long XIMFeedback;


#define   _X_I_M_R_e_v_e_r_s_e             1L
#define   _X_I_M_U_n_d_e_r_l_i_n_e           (1L<<1)
#define   _X_I_M_H_i_g_h_l_i_g_h_t           (1L<<2)
#define   _X_I_M_P_r_i_m_a_r_y             (1L<<5)†
#define   _X_I_M_S_e_c_o_n_d_a_r_y           (1L<<6)†
#define   _X_I_M_T_e_r_t_i_a_r_y            (1L<<7)†
#define   _X_I_M_V_i_s_i_b_l_e_T_o_F_o_r_w_a_r_d    (1L<<8)
#define   _X_I_M_V_i_s_i_b_l_e_T_o_B_a_c_k_w_a_r_d   (1L<<9)
#define   _X_I_M_V_i_s_i_b_l_e_C_e_n_t_e_r       (1L<<10)

││__


Characters drawn with the _X_I_M_R_e_v_e_r_s_e highlight should be
drawn by swapping the foreground and background colors used
to draw normal, unhighlighted characters.  Characters drawn
with the _X_I_M_U_n_d_e_r_l_i_n_e highlight should be underlined.  Char­
acters drawn with the _X_I_M_H_i_g_h_l_i_g_h_t, _X_I_M_P_r_i_m_a_r_y, _X_I_M_S_e_c_­
_o_n_d_a_r_y, and _X_I_M_T_e_r_t_i_a_r_y highlights should be drawn in some
unique manner that must be different from _X_I_M_R_e_v_e_r_s_e and
_X_I_M_U_n_d_e_r_l_i_n_e.

1133..55..77..66..  PPrreeeeddiitt CCaarreett CCaallllbbaacckk

An input method may have its own navigation keys to allow
the user to move the text insertion point in the preedit
area (for example, to move backward or forward).  Conse­
quently, input method needs to indicate to the client that
it should move the text insertion point.  It then calls the
PreeditCaretCallback.










-----------
  † The values for _X_I_M_P_r_i_m_a_r_y, _X_I_M_S_e_c_o_n_d_a_r_y, and
_X_I_M_T_e_r_t_i_a_r_y were incorrectly defined in the R5
specification.  The X Consortium’s X11R5 implemen­
tation correctly implemented the values for these
highlights.  The value of these highlights has
been corrected in this specification to agree with
the values in the Consortium’s X11R5 and X11R6
implementations.



                             448811





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void PreeditCaretCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XIMPreeditCaretCallbackStruct *_c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Specifies the preedit caret information.
││__

The input method will trigger PreeditCaretCallback to move
the text insertion point during preedit.  The call_data
argument contains a pointer to an _X_I_M_P_r_e_e_d_i_t_C_a_r_e_t_C_a_l_l_b_a_c_k_­
_S_t_r_u_c_t structure, which indicates where the caret should be
moved.  The callback must move the insertion point to its
new location and return, in field position, the new offset
value from the initial position.

The _X_I_M_P_r_e_e_d_i_t_C_a_r_e_t_C_a_l_l_b_a_c_k_S_t_r_u_c_t structure is defined as
follows:

__
││
typedef struct _XIMPreeditCaretCallbackStruct {
     int position;       /* Caret offset within preedit string */
     XIMCaretDirection direction;/* Caret moves direction */
     XIMCaretStyle style;/* Feedback of the caret */
} XIMPreeditCaretCallbackStruct;

││__

The _X_I_M_C_a_r_e_t_S_t_y_l_e structure is defined as follows:

__
││
typedef enum {
     XIMIsInvisible,     /* Disable caret feedback */
     XIMIsPrimary,       /* UI defined caret feedback */
     XIMIsSecondary,     /* UI defined caret feedback */
} XIMCaretStyle;

││__

The _X_I_M_C_a_r_e_t_D_i_r_e_c_t_i_o_n structure is defined as follows:








                             448822





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef enum {
     XIMForwardChar, XIMBackwardChar,
     XIMForwardWord, XIMBackwardWord,
     XIMCaretUp, XIMCaretDown,
     XIMNextLine, XIMPreviousLine,
     XIMLineStart, XIMLineEnd,
     XIMAbsolutePosition,
     XIMDontChange,
 } XIMCaretDirection;

││__

These values are defined as follows:

_X_I_M_F_o_r_w_a_r_d_C_h_a_r    Move the caret forward one character posi­
                  tion.
_X_I_M_B_a_c_k_w_a_r_d_C_h_a_r   Move the caret backward one character
                  position.
_X_I_M_F_o_r_w_a_r_d_W_o_r_d    Move the caret forward one word.
_X_I_M_B_a_c_k_w_a_r_d_W_o_r_d   Move the caret backward one word.
_X_I_M_C_a_r_e_t_U_p        Move the caret up one line keeping the
                  current horizontal offset.
_X_I_M_C_a_r_e_t_D_o_w_n      Move the caret down one line keeping the
                  current horizontal offset.
_X_I_M_P_r_e_v_i_o_u_s_L_i_n_e   Move the caret to the beginning of the
                  previous line.
_X_I_M_N_e_x_t_L_i_n_e       Move the caret to the beginning of the
                  next line.
_X_I_M_L_i_n_e_S_t_a_r_t      Move the caret to the beginning of the
                  current display line that contains the
                  caret.
_X_I_M_L_i_n_e_E_n_d        Move the caret to the end of the current
                  display line that contains the caret.
_X_I_M_A_b_s_o_l_u_t_e_P_o_­    The callback must move to the location
_s_i_t_i_o_n            specified by the position field of the
                  callback data, indicated in characters,
                  starting from the beginning of the preedit
                  text.  Hence, a value of zero means move
                  back to the beginning of the preedit text.
_X_I_M_D_o_n_t_C_h_a_n_g_e     The caret position does not change.


1133..55..77..77..  SSttaattuuss CCaallllbbaacckkss

An input method may communicate changes in the status of an
input context (for example, created, destroyed, or focus
changes) with three status callbacks:  StatusStartCallback,
StatusDoneCallback, and StatusDrawCallback.


When the input context is created or gains focus, the input
method calls the StatusStartCallback callback.




                             448833





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void StatusStartCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XPointer _c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Not used for this callback and always passed as
          NULL.
││__

The callback should initialize appropriate data for display­
ing status and for responding to StatusDrawCallback calls.
Once StatusStartCallback is called, it will not be called
again before StatusDoneCallback has been called.


When an input context is destroyed or when it loses focus,
the input method calls StatusDoneCallback.
__
││
void StatusDoneCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XPointer _c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Not used for this callback and always passed as
          NULL.
││__

The callback may release any data allocated on _S_t_a_t_u_s_S_t_a_r_t.


When an input context status has to be updated, the input
method calls StatusDrawCallback.











                             448844





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void StatusDrawCallback(_i_c, _c_l_i_e_n_t___d_a_t_a, _c_a_l_l___d_a_t_a)
      XIC _i_c;
      XPointer _c_l_i_e_n_t___d_a_t_a;
      XIMStatusDrawCallbackStruct *_c_a_l_l___d_a_t_a;


_i_c        Specifies the input context.

_c_l_i_e_n_t___d_a_t_a
          Specifies the additional client data.

_c_a_l_l___d_a_t_a Specifies the status drawing information.
││__

The callback should update the status area by either drawing
a string or imaging a bitmap in the status area.

The _X_I_M_S_t_a_t_u_s_D_a_t_a_T_y_p_e and _X_I_M_S_t_a_t_u_s_D_r_a_w_C_a_l_l_b_a_c_k_S_t_r_u_c_t struc­
tures are defined as follows:

__
││
typedef enum {
     XIMTextType,
     XIMBitmapType,
} XIMStatusDataType;

typedef struct _XIMStatusDrawCallbackStruct {
     XIMStatusDataType type;
     union {
          XIMText *text;
          Pixmap  bitmap;
     } data;
} XIMStatusDrawCallbackStruct;

││__


The feedback styles _X_I_M_V_i_s_i_b_l_e_T_o_F_o_r_w_a_r_d, _X_I_M_V_i_s_i_b_l_e_T_o_B_a_c_k_­
_w_a_r_d, and _X_I_M_V_i_s_i_b_l_e_T_o_C_e_n_t_e_r are not relevant and will not
appear in the _X_I_M_F_e_e_d_b_a_c_k element of the _X_I_M_T_e_x_t structure.


1133..55..88..  EEvveenntt FFiilltteerriinngg

Xlib provides the ability for an input method to register a
filter internal to Xlib.  This filter is called by a client
(or toolkit) by calling _X_F_i_l_t_e_r_E_v_e_n_t after calling _X_N_e_x_­
_t_E_v_e_n_t.  Any client that uses the _X_I_M interface should call
_X_F_i_l_t_e_r_E_v_e_n_t to allow input methods to process their events
without knowledge of the client’s dispatching mechanism.  A
client’s user interface policy may determine the priority of
event filters with respect to other event‐handling



                             448855





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


mechanisms (for example, modal grabs).

Clients may not know how many filters there are, if any, and
what they do.  They may only know if an event has been fil­
tered on return of _X_F_i_l_t_e_r_E_v_e_n_t.  Clients should discard
filtered events.


To filter an event, use _X_F_i_l_t_e_r_E_v_e_n_t.
__
││
Bool XFilterEvent(_e_v_e_n_t, _w)
      XEvent *_e_v_e_n_t;
      Window _w;


_e_v_e_n_t     Specifies the event to filter.

_w         Specifies the window for which the filter is to be
          applied.
││__

If the window argument is _N_o_n_e, _X_F_i_l_t_e_r_E_v_e_n_t applies the
filter to the window specified in the _X_E_v_e_n_t structure.  The
window argument is provided so that layers above Xlib that
do event redirection can indicate to which window an event
has been redirected.

If _X_F_i_l_t_e_r_E_v_e_n_t returns _T_r_u_e, then some input method has
filtered the event, and the client should discard the event.
If _X_F_i_l_t_e_r_E_v_e_n_t returns _F_a_l_s_e, then the client should con­
tinue processing the event.

If a grab has occurred in the client and _X_F_i_l_t_e_r_E_v_e_n_t
returns _T_r_u_e, the client should ungrab the keyboard.

1133..55..99..  GGeettttiinngg KKeeyybbooaarrdd IInnppuutt

To get composed input from an input method, use _X_m_b_L_o_o_k_u_p_­
_S_t_r_i_n_g or _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g.

















                             448866





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XmbLookupString(_i_c, _e_v_e_n_t, _b_u_f_f_e_r___r_e_t_u_r_n, _b_y_t_e_s___b_u_f_f_e_r, _k_e_y_s_y_m___r_e_t_u_r_n, _s_t_a_t_u_s___r_e_t_u_r_n)
      XIC _i_c;
      XKeyPressedEvent *_e_v_e_n_t;
      char *_b_u_f_f_e_r___r_e_t_u_r_n;
      int _b_y_t_e_s___b_u_f_f_e_r;
      KeySym *_k_e_y_s_y_m___r_e_t_u_r_n;
      Status *_s_t_a_t_u_s___r_e_t_u_r_n;


int XwcLookupString(_i_c, _e_v_e_n_t, _b_u_f_f_e_r___r_e_t_u_r_n, _b_y_t_e_s___b_u_f_f_e_r, _k_e_y_s_y_m___r_e_t_u_r_n, _s_t_a_t_u_s___r_e_t_u_r_n)
      XIC _i_c;
      XKeyPressedEvent *_e_v_e_n_t;
      wchar_t *_b_u_f_f_e_r___r_e_t_u_r_n;
      int _w_c_h_a_r_s___b_u_f_f_e_r;
      KeySym *_k_e_y_s_y_m___r_e_t_u_r_n;
      Status *_s_t_a_t_u_s___r_e_t_u_r_n;


_i_c        Specifies the input context.

_e_v_e_n_t     Specifies the key event to be used.

_b_u_f_f_e_r___r_e_t_u_r_n
          Returns a multibyte string or wide character
          string (if any) from the input method.

_b_y_t_e_s___b_u_f_f_e_r
_w_c_h_a_r_s___b_u_f_f_e_r
          Specifies space available in the return buffer.

_k_e_y_s_y_m___r_e_t_u_r_n
          Returns the KeySym computed from the event if this
          argument is not NULL.

_s_t_a_t_u_s___r_e_t_u_r_n
          Returns a value indicating what kind of data is
          returned.
││__

The _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g and _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g functions return the
string from the input method specified in the buffer_return
argument.  If no string is returned, the buffer_return argu­
ment is unchanged.

The KeySym into which the KeyCode from the event was mapped
is returned in the keysym_return argument if it is non‐NULL
and the status_return argument indicates that a KeySym was
returned.  If both a string and a KeySym are returned, the
KeySym value does not necessarily correspond to the string
returned.

_X_m_b_L_o_o_k_u_p_S_t_r_i_n_g returns the length of the string in bytes,
and _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g returns the length of the string in



                             448877





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


characters.  Both _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g and _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g return
text in the encoding of the locale bound to the input method
of the specified input context.

Each string returned by _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g and _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g
begins in the initial state of the encoding of the locale
(if the encoding of the locale is state‐dependent).

                            Note

     To insure proper input processing, it is essential
     that the client pass only _K_e_y_P_r_e_s_s events to
     _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g and _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g.  Their behav­
     ior when a client passes a _K_e_y_R_e_l_e_a_s_e event is
     undefined.


Clients should check the status_return argument before using
the other returned values.  These two functions both return
a value to status_return that indicates what has been
returned in the other arguments.  The possible values
returned are:

_X_B_u_f_f_e_r_O_v_e_r_f_l_o_w   The input string to be returned is too
                  large for the supplied buffer_return.  The
                  required size (_X_m_b_L_o_o_k_u_p_S_t_r_i_n_g in bytes;
                  _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g in characters) is returned
                  as the value of the function, and the con­
                  tents of buffer_return and keysym_return
                  are not modified.  The client should recall
                  the function with the same event and a
                  buffer of adequate size to obtain the
                  string.
_X_L_o_o_k_u_p_N_o_n_e       No consistent input has been composed so
                  far.  The contents of buffer_return and
                  keysym_return are not modified, and the
                  function returns zero.
_X_L_o_o_k_u_p_C_h_a_r_s      Some input characters have been composed.
                  They are placed in the buffer_return argu­
                  ment, and the string length is returned as
                  the value of the function.  The string is
                  encoded in the locale bound to the input
                  context.  The content of the keysym_return
                  argument is not modified.
_X_L_o_o_k_u_p_K_e_y_S_y_m     A KeySym has been returned instead of a
                  string and is returned in keysym_return.
                  The content of the buffer_return argument
                  is not modified, and the function returns
                  zero.
_X_L_o_o_k_u_p_B_o_t_h       Both a KeySym and a string are returned;
                  _X_L_o_o_k_u_p_C_h_a_r_s and _X_L_o_o_k_u_p_K_e_y_S_y_m occur simul­
                  taneously.





                             448888





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


It does not make any difference if the input context passed
as an argument to _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g and _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g is the
one currently in possession of the focus or not.  Input may
have been composed within an input context before it lost
the focus, and that input may be returned on subsequent
calls to _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g even though it
does not have any more keyboard focus.

1133..55..1100..  IInnppuutt MMeetthhoodd CCoonnvveennttiioonnss

The input method architecture is transparent to the client.
However, clients should respect a number of conventions in
order to work properly.  Clients must also be aware of pos­
sible effects of synchronization between input method and
library in the case of a remote input server.

1133..55..1100..11..  CClliieenntt CCoonnvveennttiioonnss

A well‐behaved client (or toolkit) should first query the
input method style.  If the client cannot satisfy the
requirements of the supported styles (in terms of geometry
management or callbacks), it should negotiate with the user
continuation of the program or raise an exception or error
of some sort.

1133..55..1100..22..  SSyynncchhrroonniizzaattiioonn CCoonnvveennttiioonnss

A _K_e_y_P_r_e_s_s event with a KeyCode of zero is used exclusively
as a signal that an input method has composed input that can
be returned by _X_m_b_L_o_o_k_u_p_S_t_r_i_n_g or _X_w_c_L_o_o_k_u_p_S_t_r_i_n_g.  No other
use is made of a _K_e_y_P_r_e_s_s event with KeyCode of zero.

Such an event may be generated by either a front‐end or a
back‐end input method in an implementation‐dependent manner.
Some possible ways to generate this event include:

⋅    A synthetic event sent by an input method server

⋅    An artificial event created by a input method filter
     and pushed onto a client’s event queue

⋅    A _K_e_y_P_r_e_s_s event whose KeyCode value is modified by an
     input method filter

When callback support is specified by the client, input
methods will not take action unless they explicitly called
back the client and obtained no response (the callback is
not specified or returned invalid data).

1133..66..  SSttrriinngg CCoonnssttaannttss

The following symbols for string constants are defined in
<_X_1_1_/_X_l_i_b_._h>.  Although they are shown here with particular
macro definitions, they may be implemented as macros, as



                             448899





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


global symbols, or as a mixture of the two.  The string
pointer value itself is not significant; clients must not
assume that inequality of two values implies inequality of
the actual string data.

#define   _X_N_V_a_N_e_s_t_e_d_L_i_s_t                "XNVaNestedList"
#define   _X_N_S_e_p_a_r_a_t_o_r_o_f_N_e_s_t_e_d_L_i_s_t       "separatorofNestedList"
#define   _X_N_Q_u_e_r_y_I_n_p_u_t_S_t_y_l_e             "queryInputStyle"
#define   _X_N_C_l_i_e_n_t_W_i_n_d_o_w                "clientWindow"
#define   _X_N_I_n_p_u_t_S_t_y_l_e                  "inputStyle"
#define   _X_N_F_o_c_u_s_W_i_n_d_o_w                 "focusWindow"
#define   _X_N_R_e_s_o_u_r_c_e_N_a_m_e                "resourceName"
#define   _X_N_R_e_s_o_u_r_c_e_C_l_a_s_s               "resourceClass"
#define   _X_N_G_e_o_m_e_t_r_y_C_a_l_l_b_a_c_k            "geometryCallback"
#define   _X_N_D_e_s_t_r_o_y_C_a_l_l_b_a_c_k             "destroyCallback"
#define   _X_N_F_i_l_t_e_r_E_v_e_n_t_s                "filterEvents"
#define   _X_N_P_r_e_e_d_i_t_S_t_a_r_t_C_a_l_l_b_a_c_k        "preeditStartCallback"
#define   _X_N_P_r_e_e_d_i_t_D_o_n_e_C_a_l_l_b_a_c_k         "preeditDoneCallback"
#define   _X_N_P_r_e_e_d_i_t_D_r_a_w_C_a_l_l_b_a_c_k         "preeditDrawCallback"
#define   _X_N_P_r_e_e_d_i_t_C_a_r_e_t_C_a_l_l_b_a_c_k        "preeditCaretCallback"
#define   _X_N_P_r_e_e_d_i_t_S_t_a_t_e_N_o_t_i_f_y_C_a_l_l_­     "preeditStateNotifyCall­
          _b_a_c_k                          back"
#define   _X_N_P_r_e_e_d_i_t_A_t_t_r_i_b_u_t_e_s           "preeditAttributes"

#define   _X_N_S_t_a_t_u_s_S_t_a_r_t_C_a_l_l_b_a_c_k         "statusStartCallback"
#define   _X_N_S_t_a_t_u_s_D_o_n_e_C_a_l_l_b_a_c_k          "statusDoneCallback"
#define   _X_N_S_t_a_t_u_s_D_r_a_w_C_a_l_l_b_a_c_k          "statusDrawCallback"
#define   _X_N_S_t_a_t_u_s_A_t_t_r_i_b_u_t_e_s            "statusAttributes"
#define   _X_N_A_r_e_a                        "area"
#define   _X_N_A_r_e_a_N_e_e_d_e_d                  "areaNeeded"
#define   _X_N_S_p_o_t_L_o_c_a_t_i_o_n                "spotLocation"
#define   _X_N_C_o_l_o_r_m_a_p                    "colorMap"
#define   _X_N_S_t_d_C_o_l_o_r_m_a_p                 "stdColorMap"
#define   _X_N_F_o_r_e_g_r_o_u_n_d                  "foreground"
#define   _X_N_B_a_c_k_g_r_o_u_n_d                  "background"
#define   _X_N_B_a_c_k_g_r_o_u_n_d_P_i_x_m_a_p            "backgroundPixmap"
#define   _X_N_F_o_n_t_S_e_t                     "fontSet"
#define   _X_N_L_i_n_e_S_p_a_c_e                   "lineSpace"
#define   _X_N_C_u_r_s_o_r                      "cursor"

#define   _X_N_Q_u_e_r_y_I_M_V_a_l_u_e_s_L_i_s_t           "queryIMValuesList"
#define   _X_N_Q_u_e_r_y_I_C_V_a_l_u_e_s_L_i_s_t           "queryICValuesList"
#define   _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n_C_a_l_l_b_a_c_k    "stringConversionCall­
                                        back"
#define   _X_N_S_t_r_i_n_g_C_o_n_v_e_r_s_i_o_n            "stringConversion"
#define   _X_N_R_e_s_e_t_S_t_a_t_e                  "resetState"
#define   _X_N_H_o_t_K_e_y                      "hotkey"
#define   _X_N_H_o_t_K_e_y_S_t_a_t_e                 "hotkeyState"
#define   _X_N_P_r_e_e_d_i_t_S_t_a_t_e                "preeditState"
#define   _X_N_V_i_s_i_b_l_e_P_o_s_i_t_i_o_n             "visiblePosition"
#define   _X_N_R_6_P_r_e_e_d_i_t_C_a_l_l_b_a_c_k_B_e_h_a_v_i_o_r   "r6PreeditCallback"

#define   _X_N_R_e_q_u_i_r_e_d_C_h_a_r_S_e_t             "requiredCharSet"




                             449900





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


#define   _X_N_Q_u_e_r_y_O_r_i_e_n_t_a_t_i_o_n            "queryOrientation"
#define   _X_N_D_i_r_e_c_t_i_o_n_a_l_D_e_p_e_n_d_e_n_t_D_r_a_w_­   "directionalDependent­
          _i_n_g                           Drawing"
#define   _X_N_C_o_n_t_e_x_t_u_a_l_D_r_a_w_i_n_g           "contextualDrawing"
#define   _X_N_B_a_s_e_F_o_n_t_N_a_m_e                "baseFontName"
#define   _X_N_M_i_s_s_i_n_g_C_h_a_r_S_e_t              "missingCharSet"
#define   _X_N_D_e_f_a_u_l_t_S_t_r_i_n_g               "defaultString"
#define   _X_N_O_r_i_e_n_t_a_t_i_o_n                 "orientation"
#define   _X_N_F_o_n_t_I_n_f_o                    "fontInfo"
#define   _X_N_O_M_A_u_t_o_m_a_t_i_c                 "omAutomatic"















































                             449911





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 1144

            IInntteerr‐‐CClliieenntt CCoommmmuunniiccaattiioonn FFuunnccttiioonnss



The _I_n_t_e_r_‐_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l, hereafter
referred to as the ICCCM, details the X Consortium approved
conventions that govern inter‐client communications.  These
conventions ensure peer‐to‐peer client cooperation in the
use of selections, cut buffers, and shared resources as well
as client cooperation with window and session managers.  For
further information, see the _I_n_t_e_r_‐_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_­
_v_e_n_t_i_o_n_s _M_a_n_u_a_l.

Xlib provides a number of standard properties and program­
ming interfaces that are ICCCM compliant.  The predefined
atoms for some of these properties are defined in the
<_X_1_1_/_X_a_t_o_m_._h> header file, where to avoid name conflicts
with user symbols their _#_d_e_f_i_n_e name has an XA_ prefix.  For
further information about atoms and properties, see section
4.3.

Xlib’s selection and cut buffer mechanisms provide the pri­
mary programming interfaces by which peer client applica­
tions communicate with each other (see sections 4.5 and
16.6).  The functions discussed in this chapter provide the
primary programming interfaces by which client applications
communicate with their window and session managers as well
as share standard colormaps.

The standard properties that are of special interest for
communicating with window and session managers are:

-----------------------------------------------------------------------
NNaammee                   TTyyppee            FFoorrmmaatt   DDeessccrriippttiioonn
-----------------------------------------------------------------------
WM_CLASS               STRING            8      Set by application
                                                programs to allow win­
                                                dow and session man­
                                                agers to obtain the
                                                application’s
                                                resources from the
                                                resource database.
WM_CLIENT_MACHINE      TEXT                     The string name of the
                                                machine on which the
                                                client application is
                                                running.







                             449922





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-----------------------------------------------------------------------
NNaammee                   TTyyppee            FFoorrmmaatt   DDeessccrriippttiioonn
-----------------------------------------------------------------------
WM_COLORMAP_WINDOWS    WINDOW            32     The list of window IDs
                                                that may need a dif­
                                                ferent colormap from
                                                that of their top‐
                                                level window.
WM_COMMAND             TEXT                     The command and argu­
                                                ments, null‐separated,
                                                used to invoke the
                                                application.
WM_HINTS               WM_HINTS          32     Additional hints set
                                                by the client for use
                                                by the window manager.
                                                The C type of this
                                                property is _X_W_M_H_i_n_t_s.
WM_ICON_NAME           TEXT                     The name to be used in
                                                an icon.
WM_ICON_SIZE           WM_ICON_SIZE      32     The window manager may
                                                set this property on
                                                the root window to
                                                specify the icon sizes
                                                it supports.  The C
                                                type of this property
                                                is _X_I_c_o_n_S_i_z_e.
WM_NAME                TEXT                     The name of the appli­
                                                cation.
WM_NORMAL_HINTS        WM_SIZE_HINTS     32     Size hints for a win­
                                                dow in its normal
                                                state.  The C type of
                                                this property is
                                                _X_S_i_z_e_H_i_n_t_s.
WM_PROTOCOLS           ATOM              32     List of atoms that
                                                identify the communi­
                                                cations protocols
                                                between the client and
                                                window manager in
                                                which the client is
                                                willing to partici­
                                                pate.
WM_STATE               WM_STATE          32     Intended for communi­
                                                cation between window
                                                and session managers
                                                only.
WM_TRANSIENT_FOR       WINDOW            32     Set by application
                                                programs to indicate
                                                to the window manager
                                                that a transient top‐
                                                level window, such as
                                                a dialog box.
-----------------------------------------------------------------------





                             449933





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The remainder of this chapter discusses:

⋅    Client to window manager communication

⋅    Client to session manager communication

⋅    Standard colormaps

1144..11..  CClliieenntt ttoo WWiinnddooww MMaannaaggeerr CCoommmmuunniiccaattiioonn

This section discusses how to:

⋅    Manipulate top‐level windows

⋅    Convert string lists

⋅    Set and read text properties

⋅    Set and read the WM_NAME property

⋅    Set and read the WM_ICON_NAME property

⋅    Set and read the WM_HINTS property

⋅    Set and read the WM_NORMAL_HINTS property

⋅    Set and read the WM_CLASS property

⋅    Set and read the WM_TRANSIENT_FOR property

⋅    Set and read the WM_PROTOCOLS property

⋅    Set and read the WM_COLORMAP_WINDOWS property

⋅    Set and read the WM_ICON_SIZE property

⋅    Use window manager convenience functions

1144..11..11..  MMaanniippuullaattiinngg TToopp‐‐LLeevveell WWiinnddoowwss

Xlib provides functions that you can use to change the visi­
bility or size of top‐level windows (that is, those that
were created as children of the root window).  Note that the
subwindows that you create are ignored by window managers.
Therefore, you should use the basic window functions
described in chapter 3 to manipulate your application’s sub­
windows.

To request that a top‐level window be iconified, use _X_I_c_o_n_i_­
_f_y_W_i_n_d_o_w.







                             449944





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XIconifyWindow(_d_i_s_p_l_a_y, _w, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

The _X_I_c_o_n_i_f_y_W_i_n_d_o_w function sends a WM_CHANGE_STATE
_C_l_i_e_n_t_M_e_s_s_a_g_e event with a format of 32 and a first data
element of _I_c_o_n_i_c_S_t_a_t_e (as described in section 4.1.4 of the
_I_n_t_e_r_‐_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l) and a window
of w to the root window of the specified screen with an
event mask set to _S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y_M_a_s_k| _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_­
_r_e_c_t_M_a_s_k.  Window managers may elect to receive this message
and if the window is in its normal state, may treat it as a
request to change the window’s state from normal to iconic.
If the WM_CHANGE_STATE property cannot be interned, _X_I_c_o_n_i_­
_f_y_W_i_n_d_o_w does not send a message and returns a zero status.
It returns a nonzero status if the client message is sent
successfully; otherwise, it returns a zero status.


To request that a top‐level window be withdrawn, use _X_W_i_t_h_­
_d_r_a_w_W_i_n_d_o_w.
__
││
Status XWithdrawWindow(_d_i_s_p_l_a_y, _w, _s_c_r_e_e_n___n_u_m_b_e_r)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _s_c_r_e_e_n___n_u_m_b_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.
││__

The _X_W_i_t_h_d_r_a_w_W_i_n_d_o_w function unmaps the specified window and
sends a synthetic _U_n_m_a_p_N_o_t_i_f_y event to the root window of
the specified screen.  Window managers may elect to receive
this message and may treat it as a request to change the



                             449955





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


window’s state to withdrawn.  When a window is in the with­
drawn state, neither its normal nor its iconic representa­
tions is visible.  It returns a nonzero status if the _U_n_m_a_p_­
_N_o_t_i_f_y event is successfully sent; otherwise, it returns a
zero status.

_X_W_i_t_h_d_r_a_w_W_i_n_d_o_w can generate a _B_a_d_W_i_n_d_o_w error.


To request that a top‐level window be reconfigured, use _X_R_e_­
_c_o_n_f_i_g_u_r_e_W_M_W_i_n_d_o_w.
__
││
Status XReconfigureWMWindow(_d_i_s_p_l_a_y, _w, _s_c_r_e_e_n___n_u_m_b_e_r, _v_a_l_u_e___m_a_s_k, _v_a_l_u_e_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      int _s_c_r_e_e_n___n_u_m_b_e_r;
      unsigned int _v_a_l_u_e___m_a_s_k;
      XWindowChanges *_v_a_l_u_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_s_c_r_e_e_n___n_u_m_b_e_r
          Specifies the appropriate screen number on the
          host server.

_v_a_l_u_e___m_a_s_k
          Specifies which values are to be set using infor­
          mation in the values structure.  This mask is the
          bitwise inclusive OR of the valid configure window
          values bits.

_v_a_l_u_e_s    Specifies the _X_W_i_n_d_o_w_C_h_a_n_g_e_s structure.
││__

The _X_R_e_c_o_n_f_i_g_u_r_e_W_M_W_i_n_d_o_w function issues a _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w
request on the specified top‐level window.  If the stacking
mode is changed and the request fails with a _B_a_d_M_a_t_c_h error,
the error is trapped by Xlib and a synthetic _C_o_n_f_i_g_u_r_­
_e_R_e_q_u_e_s_t_E_v_e_n_t containing the same configuration parameters
is sent to the root of the specified window.  Window man­
agers may elect to receive this event and treat it as a
request to reconfigure the indicated window.  It returns a
nonzero status if the request or event is successfully sent;
otherwise, it returns a zero status.

_X_R_e_c_o_n_f_i_g_u_r_e_W_M_W_i_n_d_o_w can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w
errors.






                             449966





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1144..11..22..  CCoonnvveerrttiinngg SSttrriinngg LLiissttss

Many of the text properties allow a variety of types and
formats.  Because the data stored in these properties are
not simple null‐terminated strings, an _X_T_e_x_t_P_r_o_p_e_r_t_y struc­
ture is used to describe the encoding, type, and length of
the text as well as its value.  The _X_T_e_x_t_P_r_o_p_e_r_t_y structure
contains:
__
││
typedef struct {
     unsigned char *value;/* property data */
     Atom encoding;      /* type of property */
     int format;         /* 8, 16, or 32 */
     unsigned long nitems;/* number of items in value */
} XTextProperty;

││__

Xlib provides functions to convert localized text to or from
encodings that support the inter‐client communication con­
ventions for text.  In addition, functions are provided for
converting between lists of pointers to character strings
and text properties in the STRING encoding.

The functions for localized text return a signed integer
error status that encodes _S_u_c_c_e_s_s as zero, specific error
conditions as negative numbers, and partial conversion as a
count of unconvertible characters.

__
││
#define   _X_N_o_M_e_m_o_r_y              −1
#define   _X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d    −2
#define   _X_C_o_n_v_e_r_t_e_r_N_o_t_F_o_u_n_d     −3


typedef enum {
     XStringStyle,       /* STRING */
     XCompoundTextStyle, /* COMPOUND_TEXT */
     XTextStyle,         /* text in owner’s encoding (current locale) */
     XStdICCTextStyle    /* STRING, else COMPOUND_TEXT */
} XICCEncodingStyle;

││__



To convert a list of text strings to an _X_T_e_x_t_P_r_o_p_e_r_t_y struc­
ture, use _X_m_b_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y or _X_w_c_T_e_x_t_L_i_s_t_T_o_­
_T_e_x_t_P_r_o_p_e_r_t_y.






                             449977





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XmbTextListToTextProperty(_d_i_s_p_l_a_y, _l_i_s_t, _c_o_u_n_t, _s_t_y_l_e, _t_e_x_t___p_r_o_p___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      char **_l_i_s_t;
      int _c_o_u_n_t;
      XICCEncodingStyle _s_t_y_l_e;
      XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n;


int XwcTextListToTextProperty(_d_i_s_p_l_a_y, _l_i_s_t, _c_o_u_n_t, _s_t_y_l_e, _t_e_x_t___p_r_o_p___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      wchar_t **_l_i_s_t;
      int _c_o_u_n_t;
      XICCEncodingStyle _s_t_y_l_e;
      XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_l_i_s_t      Specifies a list of null‐terminated character
          strings.

_c_o_u_n_t     Specifies the number of strings specified.

_s_t_y_l_e     Specifies the manner in which the property is
          encoded.

_t_e_x_t___p_r_o_p___r_e_t_u_r_n
          Returns the _X_T_e_x_t_P_r_o_p_e_r_t_y structure.
││__

The _X_m_b_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y and _X_w_c_T_e_x_t_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y
functions set the specified _X_T_e_x_t_P_r_o_p_e_r_t_y value to a set of
null‐separated elements representing the concatenation of
the specified list of null‐terminated text strings.  A final
terminating null is stored at the end of the value field of
text_prop_return but is not included in the nitems member.

The functions set the encoding field of text_prop_return to
an _A_t_o_m for the specified display naming the encoding deter­
mined by the specified style and convert the specified text
list to this encoding for storage in the text_prop_return
value field.  If the style _X_S_t_r_i_n_g_S_t_y_l_e or _X_C_o_m_p_o_u_n_d_­
_T_e_x_t_S_t_y_l_e is specified, this encoding is ‘‘STRING’’ or
‘‘COMPOUND_TEXT’’, respectively.  If the style _X_T_e_x_t_S_t_y_l_e is
specified, this encoding is the encoding of the current
locale.  If the style _X_S_t_d_I_C_C_T_e_x_t_S_t_y_l_e is specified, this
encoding is ‘‘STRING’’ if the text is fully convertible to
STRING, else ‘‘COMPOUND_TEXT’’.

If insufficient memory is available for the new value
string, the functions return _X_N_o_M_e_m_o_r_y.  If the current
locale is not supported, the functions return _X_L_o_c_a_l_e_N_o_t_S_u_p_­
_p_o_r_t_e_d.  In both of these error cases, the functions do not



                             449988





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


set text_prop_return.

To determine if the functions are guaranteed not to return
_X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d, use _X_S_u_p_p_o_r_t_s_L_o_c_a_l_e.

If the supplied text is not fully convertible to the speci­
fied encoding, the functions return the number of unconvert­
ible characters.  Each unconvertible character is converted
to an implementation‐defined and encoding‐specific default
string.  Otherwise, the functions return _S_u_c_c_e_s_s.  Note that
full convertibility to all styles except _X_S_t_r_i_n_g_S_t_y_l_e is
guaranteed.

To free the storage for the value field, use _X_F_r_e_e.


To obtain a list of text strings from an _X_T_e_x_t_P_r_o_p_e_r_t_y
structure, use _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t or _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_­
_T_o_T_e_x_t_L_i_s_t.
__
││
int XmbTextPropertyToTextList(_d_i_s_p_l_a_y, _t_e_x_t___p_r_o_p, _l_i_s_t___r_e_t_u_r_n, _c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      XTextProperty *_t_e_x_t___p_r_o_p;
      char ***_l_i_s_t___r_e_t_u_r_n;
      int *_c_o_u_n_t___r_e_t_u_r_n;


int XwcTextPropertyToTextList(_d_i_s_p_l_a_y, _t_e_x_t___p_r_o_p, _l_i_s_t___r_e_t_u_r_n, _c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      XTextProperty *_t_e_x_t___p_r_o_p;
      wchar_t ***_l_i_s_t___r_e_t_u_r_n;
      int *_c_o_u_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_t_e_x_t___p_r_o_p Specifies the _X_T_e_x_t_P_r_o_p_e_r_t_y structure to be used.

_l_i_s_t___r_e_t_u_r_n
          Returns a list of null‐terminated character
          strings.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of strings.
││__

The _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t
functions return a list of text strings in the current
locale representing the null‐separated elements of the spec­
ified _X_T_e_x_t_P_r_o_p_e_r_t_y structure.  The data in text_prop must
be format 8.





                             449999





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Multiple elements of the property (for example, the strings
in a disjoint text selection) are separated by a null byte.
The contents of the property are not required to be null‐
terminated; any terminating null should not be included in
text_prop.nitems.

If insufficient memory is available for the list and its
elements, _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_­
_T_e_x_t_L_i_s_t return _X_N_o_M_e_m_o_r_y.  If the current locale is not
supported, the functions return _X_L_o_c_a_l_e_N_o_t_S_u_p_p_o_r_t_e_d.  Other­
wise, if the encoding field of text_prop is not convertible
to the encoding of the current locale, the functions return
_X_C_o_n_v_e_r_t_e_r_N_o_t_F_o_u_n_d.  For supported locales, existence of a
converter from COMPOUND_TEXT, STRING or the encoding of the
current locale is guaranteed if _X_S_u_p_p_o_r_t_s_L_o_c_a_l_e returns _T_r_u_e
for the current locale (but the actual text may contain
unconvertible characters).  Conversion of other encodings is
implementation‐dependent.  In all of these error cases, the
functions do not set any return values.

Otherwise, _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_­
_T_e_x_t_L_i_s_t return the list of null‐terminated text strings to
list_return and the number of text strings to count_return.

If the value field of text_prop is not fully convertible to
the encoding of the current locale, the functions return the
number of unconvertible characters.  Each unconvertible
character is converted to a string in the current locale
that is specific to the current locale.  To obtain the value
of this string, use _X_D_e_f_a_u_l_t_S_t_r_i_n_g.  Otherwise, _X_m_b_T_e_x_t_P_r_o_p_­
_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t return _S_u_c_c_e_s_s.

To free the storage for the list and its contents returned
by _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t, use _X_F_r_e_e_S_t_r_i_n_g_L_i_s_t.  To free
the storage for the list and its contents returned by _X_w_c_­
_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t, use _X_w_c_F_r_e_e_S_t_r_i_n_g_L_i_s_t.


To free the in‐memory data associated with the specified
wide character string list, use _X_w_c_F_r_e_e_S_t_r_i_n_g_L_i_s_t.
__
││
void XwcFreeStringList(_l_i_s_t)
      wchar_t **_l_i_s_t;


_l_i_s_t      Specifies the list of strings to be freed.
││__

The _X_w_c_F_r_e_e_S_t_r_i_n_g_L_i_s_t function frees memory allocated by
_X_w_c_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t.






                             550000





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To obtain the default string for text conversion in the cur­
rent locale, use _X_D_e_f_a_u_l_t_S_t_r_i_n_g.
__
││
char *XDefaultString()

││__

The _X_D_e_f_a_u_l_t_S_t_r_i_n_g function returns the default string used
by Xlib for text conversion (for example, in _X_m_b_T_e_x_t_P_r_o_p_e_r_­
_t_y_T_o_T_e_x_t_L_i_s_t).  The default string is the string in the cur­
rent locale that is output when an unconvertible character
is found during text conversion.  If the string returned by
_X_D_e_f_a_u_l_t_S_t_r_i_n_g is the empty string (""), no character is
output in the converted text.  _X_D_e_f_a_u_l_t_S_t_r_i_n_g does not
return NULL.

The string returned by _X_D_e_f_a_u_l_t_S_t_r_i_n_g is independent of the
default string for text drawing; see _X_C_r_e_a_t_e_F_o_n_t_S_e_t to
obtain the default string for an _X_F_o_n_t_S_e_t.

The behavior when an invalid codepoint is supplied to any
Xlib function is undefined.

The returned string is null‐terminated.  It is owned by Xlib
and should not be modified or freed by the client.  It may
be freed after the current locale is changed.  Until freed,
it will not be modified by Xlib.


To set the specified list of strings in the STRING encoding
to a _X_T_e_x_t_P_r_o_p_e_r_t_y structure, use _X_S_t_r_i_n_g_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y.
__
││
Status XStringListToTextProperty(_l_i_s_t, _c_o_u_n_t, _t_e_x_t___p_r_o_p___r_e_t_u_r_n)
      char **_l_i_s_t;
      int _c_o_u_n_t;
      XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n;


_l_i_s_t      Specifies a list of null‐terminated character
          strings.

_c_o_u_n_t     Specifies the number of strings.

_t_e_x_t___p_r_o_p___r_e_t_u_r_n
          Returns the _X_T_e_x_t_P_r_o_p_e_r_t_y structure.
││__

The _X_S_t_r_i_n_g_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y function sets the specified
_X_T_e_x_t_P_r_o_p_e_r_t_y to be of type STRING (format 8) with a value
representing the concatenation of the specified list of
null‐separated character strings.  An extra null byte (which
is not included in the nitems member) is stored at the end



                             550011





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


of the value field of text_prop_return.  The strings are
assumed (without verification) to be in the STRING encoding.
If insufficient memory is available for the new value
string, _X_S_t_r_i_n_g_L_i_s_t_T_o_T_e_x_t_P_r_o_p_e_r_t_y does not set any fields in
the _X_T_e_x_t_P_r_o_p_e_r_t_y structure and returns a zero status.  Oth­
erwise, it returns a nonzero status.  To free the storage
for the value field, use _X_F_r_e_e.


To obtain a list of strings from a specified _X_T_e_x_t_P_r_o_p_e_r_t_y
structure in the STRING encoding, use _X_T_e_x_t_P_r_o_p_e_r_t_y_­
_T_o_S_t_r_i_n_g_L_i_s_t.
__
││
Status XTextPropertyToStringList(_t_e_x_t___p_r_o_p, _l_i_s_t___r_e_t_u_r_n, _c_o_u_n_t___r_e_t_u_r_n)
       XTextProperty *_t_e_x_t___p_r_o_p;
       char ***_l_i_s_t___r_e_t_u_r_n;
       int *_c_o_u_n_t___r_e_t_u_r_n;


_t_e_x_t___p_r_o_p Specifies the _X_T_e_x_t_P_r_o_p_e_r_t_y structure to be used.

_l_i_s_t___r_e_t_u_r_n
          Returns a list of null‐terminated character
          strings.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of strings.
││__

The _X_T_e_x_t_P_r_o_p_e_r_t_y_T_o_S_t_r_i_n_g_L_i_s_t function returns a list of
strings representing the null‐separated elements of the
specified _X_T_e_x_t_P_r_o_p_e_r_t_y structure.  The data in text_prop
must be of type STRING and format 8.  Multiple elements of
the property (for example, the strings in a disjoint text
selection) are separated by NULL (encoding 0).  The contents
of the property are not null‐terminated.  If insufficient
memory is available for the list and its elements,
_X_T_e_x_t_P_r_o_p_e_r_t_y_T_o_S_t_r_i_n_g_L_i_s_t sets no return values and returns
a zero status.  Otherwise, it returns a nonzero status.  To
free the storage for the list and its contents, use
_X_F_r_e_e_S_t_r_i_n_g_L_i_s_t.


To free the in‐memory data associated with the specified
string list, use _X_F_r_e_e_S_t_r_i_n_g_L_i_s_t.











                             550022





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XFreeStringList(_l_i_s_t)
      char **_l_i_s_t;


_l_i_s_t      Specifies the list of strings to be freed.
││__

The _X_F_r_e_e_S_t_r_i_n_g_L_i_s_t function releases memory allocated by
_X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t and _X_T_e_x_t_P_r_o_p_e_r_t_y_T_o_S_t_r_i_n_g_L_i_s_t and
the missing charset list allocated by _X_C_r_e_a_t_e_F_o_n_t_S_e_t.

1144..11..33..  SSeettttiinngg aanndd RReeaaddiinngg TTeexxtt PPrrooppeerrttiieess

Xlib provides two functions that you can use to set and read
the text properties for a given window.  You can use these
functions to set and read those properties of type TEXT
(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE).
In addition, Xlib provides separate convenience functions
that you can use to set each of these properties.  For fur­
ther information about these convenience functions, see sec­
tions 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.


To set one of a window’s text properties, use _X_S_e_t_T_e_x_t_P_r_o_p_­
_e_r_t_y.
__
││
void XSetTextProperty(_d_i_s_p_l_a_y, _w, _t_e_x_t___p_r_o_p, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XTextProperty *_t_e_x_t___p_r_o_p;
      Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_t_e_x_t___p_r_o_p Specifies the _X_T_e_x_t_P_r_o_p_e_r_t_y structure to be used.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_S_e_t_T_e_x_t_P_r_o_p_e_r_t_y function replaces the existing speci­
fied property for the named window with the data, type, for­
mat, and number of items determined by the value field, the
encoding field, the format field, and the nitems field,
respectively, of the specified _X_T_e_x_t_P_r_o_p_e_r_t_y structure.  If
the property does not already exist, _X_S_e_t_T_e_x_t_P_r_o_p_e_r_t_y sets
it for the specified window.

_X_S_e_t_T_e_x_t_P_r_o_p_e_r_t_y can generate _B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, _B_a_d_V_a_l_u_e,
and _B_a_d_W_i_n_d_o_w errors.



                             550033





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To read one of a window’s text properties, use _X_G_e_t_T_e_x_t_P_r_o_p_­
_e_r_t_y.
__
││
Status XGetTextProperty(_d_i_s_p_l_a_y, _w, _t_e_x_t___p_r_o_p___r_e_t_u_r_n, _p_r_o_p_e_r_t_y)
       Display *_d_i_s_p_l_a_y;
       Window _w;
       XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n;
       Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_t_e_x_t___p_r_o_p___r_e_t_u_r_n
          Returns the _X_T_e_x_t_P_r_o_p_e_r_t_y structure.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_G_e_t_T_e_x_t_P_r_o_p_e_r_t_y function reads the specified property
from the window and stores the data in the returned
_X_T_e_x_t_P_r_o_p_e_r_t_y structure.  It stores the data in the value
field, the type of the data in the encoding field, the for­
mat of the data in the format field, and the number of items
of data in the nitems field.  An extra byte containing null
(which is not included in the nitems member) is stored at
the end of the value field of text_prop_return.  The partic­
ular interpretation of the property’s encoding and data as
text is left to the calling application.  If the specified
property does not exist on the window, _X_G_e_t_T_e_x_t_P_r_o_p_e_r_t_y sets
the value field to NULL, the encoding field to _N_o_n_e, the
format field to zero, and the nitems field to zero.

If it was able to read and store the data in the _X_T_e_x_t_P_r_o_p_­
_e_r_t_y structure, _X_G_e_t_T_e_x_t_P_r_o_p_e_r_t_y returns a nonzero status;
otherwise, it returns a zero status.

_X_G_e_t_T_e_x_t_P_r_o_p_e_r_t_y can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w errors.

1144..11..44..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__NNAAMMEE PPrrooppeerrttyy

Xlib provides convenience functions that you can use to set
and read the WM_NAME property for a given window.


To set a window’s WM_NAME property with the supplied conve­
nience function, use _X_S_e_t_W_M_N_a_m_e.








                             550044





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XSetWMName(_d_i_s_p_l_a_y, _w, _t_e_x_t___p_r_o_p)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XTextProperty *_t_e_x_t___p_r_o_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_t_e_x_t___p_r_o_p Specifies the _X_T_e_x_t_P_r_o_p_e_r_t_y structure to be used.
││__

The _X_S_e_t_W_M_N_a_m_e convenience function calls _X_S_e_t_T_e_x_t_P_r_o_p_e_r_t_y
to set the WM_NAME property.


To read a window’s WM_NAME property with the supplied conve­
nience function, use _X_G_e_t_W_M_N_a_m_e.
__
││
Status XGetWMName(_d_i_s_p_l_a_y, _w, _t_e_x_t___p_r_o_p___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_t_e_x_t___p_r_o_p___r_e_t_u_r_n
          Returns the _X_T_e_x_t_P_r_o_p_e_r_t_y structure.
││__

The _X_G_e_t_W_M_N_a_m_e convenience function calls _X_G_e_t_T_e_x_t_P_r_o_p_e_r_t_y
to obtain the WM_NAME property.  It returns a nonzero status
on success; otherwise, it returns a zero status.

The following two functions have been superseded by _X_S_e_t_W_M_­
_N_a_m_e and _X_G_e_t_W_M_N_a_m_e, respectively.  You can use these addi­
tional convenience functions for window names that are
encoded as STRING properties.


To assign a name to a window, use _X_S_t_o_r_e_N_a_m_e.










                             550055





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XStoreName(_d_i_s_p_l_a_y, _w, _w_i_n_d_o_w___n_a_m_e)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      char *_w_i_n_d_o_w___n_a_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_w_i_n_d_o_w___n_a_m_e
          Specifies the window name, which should be a null‐
          terminated string.
││__

The _X_S_t_o_r_e_N_a_m_e function assigns the name passed to win­
dow_name to the specified window.  A window manager can dis­
play the window name in some prominent place, such as the
title bar, to allow users to identify windows easily.  Some
window managers may display a window’s name in the window’s
icon, although they are encouraged to use the window’s icon
name if one is provided by the application.  If the string
is not in the Host Portable Character Encoding, the result
is implementation‐dependent.

_X_S_t_o_r_e_N_a_m_e can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To get the name of a window, use _X_F_e_t_c_h_N_a_m_e.
__
││
Status XFetchName(_d_i_s_p_l_a_y, _w, _w_i_n_d_o_w___n_a_m_e___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      char **_w_i_n_d_o_w___n_a_m_e___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_w_i_n_d_o_w___n_a_m_e___r_e_t_u_r_n
          Returns the window name, which is a null‐termi­
          nated string.
││__

The _X_F_e_t_c_h_N_a_m_e function returns the name of the specified
window.  If it succeeds, it returns a nonzero status; other­
wise, no name has been set for the window, and it returns
zero.  If the WM_NAME property has not been set for this
window, _X_F_e_t_c_h_N_a_m_e sets window_name_return to NULL.  If the
data returned by the server is in the Latin Portable Charac­
ter Encoding, then the returned string is in the Host



                             550066





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Portable Character Encoding.  Otherwise, the result is
implementation‐dependent.  When finished with it, a client
must free the window name string using _X_F_r_e_e.

_X_F_e_t_c_h_N_a_m_e can generate a _B_a_d_W_i_n_d_o_w error.

1144..11..55..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__IICCOONN__NNAAMMEE PPrrooppeerrttyy

Xlib provides convenience functions that you can use to set
and read the WM_ICON_NAME property for a given window.


To set a window’s WM_ICON_NAME property, use _X_S_e_t_W_M_I_c_o_n_N_a_m_e.
__
││
void XSetWMIconName(_d_i_s_p_l_a_y, _w, _t_e_x_t___p_r_o_p)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XTextProperty *_t_e_x_t___p_r_o_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_t_e_x_t___p_r_o_p Specifies the _X_T_e_x_t_P_r_o_p_e_r_t_y structure to be used.
││__

The _X_S_e_t_W_M_I_c_o_n_N_a_m_e convenience function calls _X_S_e_t_T_e_x_t_P_r_o_p_­
_e_r_t_y to set the WM_ICON_NAME property.


To read a window’s WM_ICON_NAME property, use _X_G_e_t_W_M_I_c_o_n_­
_N_a_m_e.
__
││
Status XGetWMIconName(_d_i_s_p_l_a_y, _w, _t_e_x_t___p_r_o_p___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_t_e_x_t___p_r_o_p___r_e_t_u_r_n
          Returns the _X_T_e_x_t_P_r_o_p_e_r_t_y structure.
││__

The _X_G_e_t_W_M_I_c_o_n_N_a_m_e convenience function calls _X_G_e_t_T_e_x_t_P_r_o_p_­
_e_r_t_y to obtain the WM_ICON_NAME property.  It returns a
nonzero status on success; otherwise, it returns a zero sta­
tus.



                             550077





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The next two functions have been superseded by _X_S_e_t_W_M_I_c_o_n_­
_N_a_m_e and _X_G_e_t_W_M_I_c_o_n_N_a_m_e, respectively.  You can use these
additional convenience functions for window names that are
encoded as STRING properties.



To set the name to be displayed in a window’s icon, use
_X_S_e_t_I_c_o_n_N_a_m_e.
__
││
XSetIconName(_d_i_s_p_l_a_y, _w, _i_c_o_n___n_a_m_e)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      char *_i_c_o_n___n_a_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_i_c_o_n___n_a_m_e Specifies the icon name, which should be a null‐
          terminated string.
││__

If the string is not in the Host Portable Character Encod­
ing, the result is implementation‐dependent.  _X_S_e_t_I_c_o_n_N_a_m_e
can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To get the name a window wants displayed in its icon, use
_X_G_e_t_I_c_o_n_N_a_m_e.
__
││
Status XGetIconName(_d_i_s_p_l_a_y, _w, _i_c_o_n___n_a_m_e___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      char **_i_c_o_n___n_a_m_e___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_i_c_o_n___n_a_m_e___r_e_t_u_r_n
          Returns the window’s icon name, which is a null‐
          terminated string.
││__

The _X_G_e_t_I_c_o_n_N_a_m_e function returns the name to be displayed
in the specified window’s icon.  If it succeeds, it returns
a nonzero status; otherwise, if no icon name has been set
for the window, it returns zero.  If you never assigned a
name to the window, _X_G_e_t_I_c_o_n_N_a_m_e sets icon_name_return to



                             550088





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


NULL.  If the data returned by the server is in the Latin
Portable Character Encoding, then the returned string is in
the Host Portable Character Encoding.  Otherwise, the result
is implementation‐dependent.  When finished with it, a
client must free the icon name string using _X_F_r_e_e.

_X_G_e_t_I_c_o_n_N_a_m_e can generate a _B_a_d_W_i_n_d_o_w error.

1144..11..66..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__HHIINNTTSS PPrrooppeerrttyy

Xlib provides functions that you can use to set and read the
WM_HINTS property for a given window.  These functions use
the flags and the _X_W_M_H_i_n_t_s structure, as defined in the
<_X_1_1_/_X_u_t_i_l_._h> header file.


To allocate an _X_W_M_H_i_n_t_s structure, use _X_A_l_l_o_c_W_M_H_i_n_t_s.
__
││
XWMHints *XAllocWMHints()

││__

The _X_A_l_l_o_c_W_M_H_i_n_t_s function allocates and returns a pointer
to an _X_W_M_H_i_n_t_s structure.  Note that all fields in the
_X_W_M_H_i_n_t_s structure are initially set to zero.  If insuffi­
cient memory is available, _X_A_l_l_o_c_W_M_H_i_n_t_s returns NULL.  To
free the memory allocated to this structure, use _X_F_r_e_e.

The _X_W_M_H_i_n_t_s structure contains:



























                             550099





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││    /* Window manager hints mask bits */

#define   _I_n_p_u_t_H_i_n_t                   (1L << 0)
#define   _S_t_a_t_e_H_i_n_t                   (1L << 1)
#define   _I_c_o_n_P_i_x_m_a_p_H_i_n_t              (1L << 2)
#define   _I_c_o_n_W_i_n_d_o_w_H_i_n_t              (1L << 3)
#define   _I_c_o_n_P_o_s_i_t_i_o_n_H_i_n_t            (1L << 4)
#define   _I_c_o_n_M_a_s_k_H_i_n_t                (1L << 5)
#define   _W_i_n_d_o_w_G_r_o_u_p_H_i_n_t             (1L << 6)
#define   _U_r_g_e_n_c_y_H_i_n_t                 (1L << 8)
#define   _A_l_l_H_i_n_t_s                    (InputHint|State­
                                      Hint|IconPixmapHint|
                                      IconWindowHint|IconPosi­
                                      tionHint|
                                      IconMaskHint|Window­
                                      GroupHint)


/* Values */

typedef struct {
     long flags;         /* marks which fields in this structure are defined */
     Bool input;         /* does this application rely on the window manager to
                         get keyboard input? */
     int initial_state;  /* see below */
     Pixmap icon_pixmap; /* pixmap to be used as icon */
     Window icon_window; /* window to be used as icon */
     int icon_x, icon_y; /* initial position of icon */
     Pixmap icon_mask;   /* pixmap to be used as mask for icon_pixmap */
     XID window_group;   /* id of related window group */
     /* this structure may be extended in the future */
} XWMHints;

││__

The input member is used to communicate to the window man­
ager the input focus model used by the application.  Appli­
cations that expect input but never explicitly set focus to
any of their subwindows (that is, use the push model of
focus management), such as X Version 10 style applications
that use real‐estate driven focus, should set this member to
_T_r_u_e.  Similarly, applications that set input focus to their
subwindows only when it is given to their top‐level window
by a window manager should also set this member to _T_r_u_e.
Applications that manage their own input focus by explicitly
setting focus to one of their subwindows whenever they want
keyboard input (that is, use the pull model of focus manage­
ment) should set this member to _F_a_l_s_e.  Applications that
never expect any keyboard input also should set this member
to _F_a_l_s_e.

Pull model window managers should make it possible for push
model applications to get input by setting input focus to
the top‐level windows of applications whose input member is



                             551100





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_T_r_u_e.  Push model window managers should make sure that pull
model applications do not break them by resetting input
focus to _P_o_i_n_t_e_r_R_o_o_t when it is appropriate (for example,
whenever an application whose input member is _F_a_l_s_e sets
input focus to one of its subwindows).

The definitions for the initial_state flag are:

#define   _W_i_t_h_d_r_a_w_n_S_t_a_t_e         0
#define   _N_o_r_m_a_l_S_t_a_t_e            1    /* most applications start
                                      this way */
#define   _I_c_o_n_i_c_S_t_a_t_e            3    /* application wants to
                                      start as an icon */

The icon_mask specifies which pixels of the icon_pixmap
should be used as the icon.  This allows for nonrectangular
icons.  Both icon_pixmap and icon_mask must be bitmaps.  The
icon_window lets an application provide a window for use as
an icon for window managers that support such use.  The win­
dow_group lets you specify that this window belongs to a
group of other windows.  For example, if a single applica­
tion manipulates multiple top‐level windows, this allows you
to provide enough information that a window manager can
iconify all of the windows rather than just the one window.

The _U_r_g_e_n_c_y_H_i_n_t flag, if set in the flags field, indicates
that the client deems the window contents to be urgent,
requiring the timely response of the user.  The window man­
ager will make some effort to draw the user’s attention to
this window while this flag is set.  The client must provide
some means by which the user can cause the urgency flag to
be cleared (either mitigating the condition that made the
window urgent or merely shutting off the alarm) or the win­
dow to be withdrawn.


To set a window’s WM_HINTS property, use _X_S_e_t_W_M_H_i_n_t_s.
__
││
XSetWMHints(_d_i_s_p_l_a_y, _w, _w_m_h_i_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XWMHints *_w_m_h_i_n_t_s;



_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_w_m_h_i_n_t_s   Specifies the _X_W_M_H_i_n_t_s structure to be used.
││__

The _X_S_e_t_W_M_H_i_n_t_s function sets the window manager hints that



                             551111





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


include icon information and location, the initial state of
the window, and whether the application relies on the window
manager to get keyboard input.

_X_S_e_t_W_M_H_i_n_t_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To read a window’s WM_HINTS property, use _X_G_e_t_W_M_H_i_n_t_s.
__
││
XWMHints *XGetWMHints(_d_i_s_p_l_a_y, _w)
      Display *_d_i_s_p_l_a_y;
      Window _w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.
││__

The _X_G_e_t_W_M_H_i_n_t_s function reads the window manager hints and
returns NULL if no WM_HINTS property was set on the window
or returns a pointer to an _X_W_M_H_i_n_t_s structure if it suc­
ceeds.  When finished with the data, free the space used for
it by calling _X_F_r_e_e.

_X_G_e_t_W_M_H_i_n_t_s can generate a _B_a_d_W_i_n_d_o_w error.

1144..11..77..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__NNOORRMMAALL__HHIINNTTSS PPrrooppeerrttyy

Xlib provides functions that you can use to set or read the
WM_NORMAL_HINTS property for a given window.  The functions
use the flags and the _X_S_i_z_e_H_i_n_t_s structure, as defined in
the <_X_1_1_/_X_u_t_i_l_._h> header file.

The size of the _X_S_i_z_e_H_i_n_t_s structure may grow in future
releases, as new components are added to support new ICCCM
features.  Passing statically allocated instances of this
structure into Xlib may result in memory corruption when
running against a future release of the library.  As such,
it is recommended that only dynamically allocated instances
of the structure be used.


To allocate an _X_S_i_z_e_H_i_n_t_s structure, use _X_A_l_l_o_c_S_i_z_e_H_i_n_t_s.
__
││
XSizeHints *XAllocSizeHints()

││__

The _X_A_l_l_o_c_S_i_z_e_H_i_n_t_s function allocates and returns a pointer
to an _X_S_i_z_e_H_i_n_t_s structure.  Note that all fields in the
_X_S_i_z_e_H_i_n_t_s structure are initially set to zero.  If



                             551122





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


insufficient memory is available, _X_A_l_l_o_c_S_i_z_e_H_i_n_t_s returns
NULL.  To free the memory allocated to this structure, use
_X_F_r_e_e.

The _X_S_i_z_e_H_i_n_t_s structure contains:

__
││    /* Size hints mask bits */

#define   _U_S_P_o_s_i_t_i_o_n    (1L << 0)          /* user specified x, y */
#define   _U_S_S_i_z_e        (1L << 1)          /* user specified width, height
                                           */
#define   _P_P_o_s_i_t_i_o_n     (1L << 2)          /* program specified position
                                           */
#define   _P_S_i_z_e         (1L << 3)          /* program specified size */
#define   _P_M_i_n_S_i_z_e      (1L << 4)          /* program specified minimum
                                           size */
#define   _P_M_a_x_S_i_z_e      (1L << 5)          /* program specified maximum
                                           size */
#define   _P_R_e_s_i_z_e_I_n_c    (1L << 6)          /* program specified resize
                                           increments */
#define   _P_A_s_p_e_c_t       (1L << 7)          /* program specified min and
                                           max aspect ratios */
#define   _P_B_a_s_e_S_i_z_e     (1L << 8)
#define   _P_W_i_n_G_r_a_v_i_t_y   (1L << 9)
#define   _P_A_l_l_H_i_n_t_s     (PPosi­
                        tion|PSize|
                        PMinSize|PMax­
                        Size|
                        PRe­
                        sizeInc|PAspect)


/* Values */

typedef struct {
     long flags;         /* marks which fields in this structure are defined */
     int x, y;           /* Obsolete */
     int width, height;  /* Obsolete */
     int min_width, min_height;
     int max_width, max_height;
     int width_inc, height_inc;
     struct {
            int x;       /* numerator */
            int y;       /* denominator */
     } min_aspect, max_aspect;
     int base_width, base_height;
     int win_gravity;
     /* this structure may be extended in the future */
} XSizeHints;

││__

The x, y, width, and height members are now obsolete and are



                             551133





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


left solely for compatibility reasons.  The min_width and
min_height members specify the minimum window size that
still allows the application to be useful.  The max_width
and max_height members specify the maximum window size.  The
width_inc and height_inc members define an arithmetic pro­
gression of sizes (minimum to maximum) into which the window
prefers to be resized.  The min_aspect and max_aspect mem­
bers are expressed as ratios of x and y, and they allow an
application to specify the range of aspect ratios it
prefers.  The base_width and base_height members define the
desired size of the window.  The window manager will inter­
pret the position of the window and its border width to
position the point of the outer rectangle of the overall
window specified by the win_gravity member.  The outer rect­
angle of the window includes any borders or decorations sup­
plied by the window manager.  In other words, if the window
manager decides to place the window where the client asked,
the position on the parent window’s border named by the
win_gravity will be placed where the client window would
have been placed in the absence of a window manager.

Note that use of the _P_A_l_l_H_i_n_t_s macro is highly discouraged.


To set a window’s WM_NORMAL_HINTS property, use _X_S_e_t_W_M_N_o_r_­
_m_a_l_H_i_n_t_s.
__
││
void XSetWMNormalHints(_d_i_s_p_l_a_y, _w, _h_i_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_h_i_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_h_i_n_t_s     Specifies the size hints for the window in its
          normal state.
││__

The _X_S_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s function replaces the size hints for
the WM_NORMAL_HINTS property on the specified window.  If
the property does not already exist, _X_S_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s sets
the size hints for the WM_NORMAL_HINTS property on the spec­
ified window.  The property is stored with a type of
WM_SIZE_HINTS and a format of 32.

_X_S_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w
errors.






                             551144





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To read a window’s WM_NORMAL_HINTS property, use _X_G_e_t_W_M_N_o_r_­
_m_a_l_H_i_n_t_s.
__
││
Status XGetWMNormalHints(_d_i_s_p_l_a_y, _w, _h_i_n_t_s___r_e_t_u_r_n, _s_u_p_p_l_i_e_d___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_h_i_n_t_s___r_e_t_u_r_n;
      long *_s_u_p_p_l_i_e_d___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_h_i_n_t_s___r_e_t_u_r_n
          Returns the size hints for the window in its
          normal state.

_s_u_p_p_l_i_e_d___r_e_t_u_r_n
          Returns the hints that were supplied by the user.
││__

The _X_G_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s function returns the size hints stored
in the WM_NORMAL_HINTS property on the specified window.  If
the property is of type WM_SIZE_HINTS, is of format 32, and
is long enough to contain either an old (pre‐ICCCM) or new
size hints structure, _X_G_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s sets the various
fields of the _X_S_i_z_e_H_i_n_t_s structure, sets the supplied_return
argument to the list of fields that were supplied by the
user (whether or not they contained defined values), and
returns a nonzero status.  Otherwise, it returns a zero sta­
tus.

If _X_G_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s returns successfully and a pre‐ICCCM
size hints property is read, the supplied_return argument
will contain the following bits:


     (USPosition|USSize|PPosition|PSize|PMinSize|
      PMaxSize|PResizeInc|PAspect)


If the property is large enough to contain the base size and
window gravity fields as well, the supplied_return argument
will also contain the following bits:


     PBaseSize|PWinGravity


_X_G_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s can generate a _B_a_d_W_i_n_d_o_w error.





                             551155





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To set a window’s WM_SIZE_HINTS property, use _X_S_e_t_W_M_S_i_z_e_­
_H_i_n_t_s.
__
││
void XSetWMSizeHints(_d_i_s_p_l_a_y, _w, _h_i_n_t_s, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_h_i_n_t_s;
      Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_h_i_n_t_s     Specifies the _X_S_i_z_e_H_i_n_t_s structure to be used.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_S_e_t_W_M_S_i_z_e_H_i_n_t_s function replaces the size hints for the
specified property on the named window.  If the specified
property does not already exist, _X_S_e_t_W_M_S_i_z_e_H_i_n_t_s sets the
size hints for the specified property on the named window.
The property is stored with a type of WM_SIZE_HINTS and a
format of 32.  To set a window’s normal size hints, you can
use the _X_S_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s function.

_X_S_e_t_W_M_S_i_z_e_H_i_n_t_s can generate _B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, and _B_a_d_W_i_n_­
_d_o_w errors.


To read a window’s WM_SIZE_HINTS property, use _X_G_e_t_W_M_S_i_z_e_­
_H_i_n_t_s.























                             551166





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetWMSizeHints(_d_i_s_p_l_a_y, _w, _h_i_n_t_s___r_e_t_u_r_n, _s_u_p_p_l_i_e_d___r_e_t_u_r_n, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_h_i_n_t_s___r_e_t_u_r_n;
      long *_s_u_p_p_l_i_e_d___r_e_t_u_r_n;
      Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_h_i_n_t_s___r_e_t_u_r_n
          Returns the _X_S_i_z_e_H_i_n_t_s structure.

_s_u_p_p_l_i_e_d___r_e_t_u_r_n
          Returns the hints that were supplied by the user.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_G_e_t_W_M_S_i_z_e_H_i_n_t_s function returns the size hints stored
in the specified property on the named window.  If the prop­
erty is of type WM_SIZE_HINTS, is of format 32, and is long
enough to contain either an old (pre‐ICCCM) or new size
hints structure, _X_G_e_t_W_M_S_i_z_e_H_i_n_t_s sets the various fields of
the _X_S_i_z_e_H_i_n_t_s structure, sets the supplied_return argument
to the list of fields that were supplied by the user
(whether or not they contained defined values), and returns
a nonzero status.  Otherwise, it returns a zero status.  To
get a window’s normal size hints, you can use the _X_G_e_t_W_M_N_o_r_­
_m_a_l_H_i_n_t_s function.

If _X_G_e_t_W_M_S_i_z_e_H_i_n_t_s returns successfully and a pre‐ICCCM size
hints property is read, the supplied_return argument will
contain the following bits:


     (USPosition|USSize|PPosition|PSize|PMinSize|
      PMaxSize|PResizeInc|PAspect)


If the property is large enough to contain the base size and
window gravity fields as well, the supplied_return argument
will also contain the following bits:


     PBaseSize|PWinGravity


_X_G_e_t_W_M_S_i_z_e_H_i_n_t_s can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w errors.





                             551177





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1144..11..88..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__CCLLAASSSS PPrrooppeerrttyy

Xlib provides functions that you can use to set and get the
WM_CLASS property for a given window.  These functions use
the _X_C_l_a_s_s_H_i_n_t structure, which is defined in the
<_X_1_1_/_X_u_t_i_l_._h> header file.


To allocate an _X_C_l_a_s_s_H_i_n_t structure, use _X_A_l_l_o_c_C_l_a_s_s_H_i_n_t.
__
││
XClassHint *XAllocClassHint()

││__

The _X_A_l_l_o_c_C_l_a_s_s_H_i_n_t function allocates and returns a pointer
to an _X_C_l_a_s_s_H_i_n_t structure.  Note that the pointer fields in
the _X_C_l_a_s_s_H_i_n_t structure are initially set to NULL.  If
insufficient memory is available, _X_A_l_l_o_c_C_l_a_s_s_H_i_n_t returns
NULL.  To free the memory allocated to this structure, use
_X_F_r_e_e.

The _X_C_l_a_s_s_H_i_n_t contains:

__
││
typedef struct {
     char *res_name;
     char *res_class;
} XClassHint;

││__

The res_name member contains the application name, and the
res_class member contains the application class.  Note that
the name set in this property may differ from the name set
as WM_NAME.  That is, WM_NAME specifies what should be dis­
played in the title bar and, therefore, can contain temporal
information (for example, the name of a file currently in an
editor’s buffer).  On the other hand, the name specified as
part of WM_CLASS is the formal name of the application that
should be used when retrieving the application’s resources
from the resource database.


To set a window’s WM_CLASS property, use _X_S_e_t_C_l_a_s_s_H_i_n_t.











                             551188





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetClassHint(_d_i_s_p_l_a_y, _w, _c_l_a_s_s___h_i_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XClassHint *_c_l_a_s_s___h_i_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_c_l_a_s_s___h_i_n_t_s
          Specifies the _X_C_l_a_s_s_H_i_n_t structure that is to be
          used.
││__

The _X_S_e_t_C_l_a_s_s_H_i_n_t function sets the class hint for the spec­
ified window.  If the strings are not in the Host Portable
Character Encoding, the result is implementation‐dependent.

_X_S_e_t_C_l_a_s_s_H_i_n_t can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To read a window’s WM_CLASS property, use _X_G_e_t_C_l_a_s_s_H_i_n_t.
__
││
Status XGetClassHint(_d_i_s_p_l_a_y, _w, _c_l_a_s_s___h_i_n_t_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XClassHint *_c_l_a_s_s___h_i_n_t_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_c_l_a_s_s___h_i_n_t_s___r_e_t_u_r_n
          Returns the _X_C_l_a_s_s_H_i_n_t structure.
││__

The _X_G_e_t_C_l_a_s_s_H_i_n_t function returns the class hint of the
specified window to the members of the supplied structure.
If the data returned by the server is in the Latin Portable
Character Encoding, then the returned strings are in the
Host Portable Character Encoding.  Otherwise, the result is
implementation‐dependent.  It returns a nonzero status on
success; otherwise, it returns a zero status.  To free
res_name and res_class when finished with the strings, use
_X_F_r_e_e on each individually.

_X_G_e_t_C_l_a_s_s_H_i_n_t can generate a _B_a_d_W_i_n_d_o_w error.






                             551199





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1144..11..99..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__TTRRAANNSSIIEENNTT__FFOORR PPrrooppeerrttyy

Xlib provides functions that you can use to set and read the
WM_TRANSIENT_FOR property for a given window.


To set a window’s WM_TRANSIENT_FOR property, use _X_S_e_t_T_r_a_n_­
_s_i_e_n_t_F_o_r_H_i_n_t.
__
││
XSetTransientForHint(_d_i_s_p_l_a_y, _w, _p_r_o_p___w_i_n_d_o_w)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Window _p_r_o_p___w_i_n_d_o_w;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_p_r_o_p___w_i_n_d_o_w
          Specifies the window that the WM_TRANSIENT_FOR
          property is to be set to.
││__

The _X_S_e_t_T_r_a_n_s_i_e_n_t_F_o_r_H_i_n_t function sets the WM_TRANSIENT_FOR
property of the specified window to the specified prop_win­
dow.

_X_S_e_t_T_r_a_n_s_i_e_n_t_F_o_r_H_i_n_t can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w
errors.


To read a window’s WM_TRANSIENT_FOR property, use _X_G_e_t_T_r_a_n_­
_s_i_e_n_t_F_o_r_H_i_n_t.
__
││
Status XGetTransientForHint(_d_i_s_p_l_a_y, _w, _p_r_o_p___w_i_n_d_o_w___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Window *_p_r_o_p___w_i_n_d_o_w___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_p_r_o_p___w_i_n_d_o_w___r_e_t_u_r_n
          Returns the WM_TRANSIENT_FOR property of the spec­
          ified window.
││__

The _X_G_e_t_T_r_a_n_s_i_e_n_t_F_o_r_H_i_n_t function returns the WM_TRAN­
SIENT_FOR property for the specified window.  It returns a



                             552200





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


nonzero status on success; otherwise, it returns a zero sta­
tus.

_X_G_e_t_T_r_a_n_s_i_e_n_t_F_o_r_H_i_n_t can generate a _B_a_d_W_i_n_d_o_w error.

1144..11..1100..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__PPRROOTTOOCCOOLLSS PPrrooppeerrttyy

Xlib provides functions that you can use to set and read the
WM_PROTOCOLS property for a given window.


To set a window’s WM_PROTOCOLS property, use _X_S_e_t_W_M_P_r_o_t_o_­
_c_o_l_s.
__
││
Status XSetWMProtocols(_d_i_s_p_l_a_y, _w, _p_r_o_t_o_c_o_l_s, _c_o_u_n_t)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Atom *_p_r_o_t_o_c_o_l_s;
      int _c_o_u_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_p_r_o_t_o_c_o_l_s Specifies the list of protocols.

_c_o_u_n_t     Specifies the number of protocols in the list.
││__

The _X_S_e_t_W_M_P_r_o_t_o_c_o_l_s function replaces the WM_PROTOCOLS prop­
erty on the specified window with the list of atoms speci­
fied by the protocols argument.  If the property does not
already exist, _X_S_e_t_W_M_P_r_o_t_o_c_o_l_s sets the WM_PROTOCOLS prop­
erty on the specified window to the list of atoms specified
by the protocols argument.  The property is stored with a
type of ATOM and a format of 32.  If it cannot intern the
WM_PROTOCOLS atom, _X_S_e_t_W_M_P_r_o_t_o_c_o_l_s returns a zero status.
Otherwise, it returns a nonzero status.

_X_S_e_t_W_M_P_r_o_t_o_c_o_l_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To read a window’s WM_PROTOCOLS property, use _X_G_e_t_W_M_P_r_o_t_o_­
_c_o_l_s.











                             552211





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetWMProtocols(_d_i_s_p_l_a_y, _w, _p_r_o_t_o_c_o_l_s___r_e_t_u_r_n, _c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Atom **_p_r_o_t_o_c_o_l_s___r_e_t_u_r_n;
      int *_c_o_u_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_p_r_o_t_o_c_o_l_s___r_e_t_u_r_n
          Returns the list of protocols.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of protocols in the list.
││__

The _X_G_e_t_W_M_P_r_o_t_o_c_o_l_s function returns the list of atoms
stored in the WM_PROTOCOLS property on the specified window.
These atoms describe window manager protocols in which the
owner of this window is willing to participate.  If the
property exists, is of type ATOM, is of format 32, and the
atom WM_PROTOCOLS can be interned, _X_G_e_t_W_M_P_r_o_t_o_c_o_l_s sets the
protocols_return argument to a list of atoms, sets the
count_return argument to the number of elements in the list,
and returns a nonzero status.  Otherwise, it sets neither of
the return arguments and returns a zero status.  To release
the list of atoms, use _X_F_r_e_e.

_X_G_e_t_W_M_P_r_o_t_o_c_o_l_s can generate a _B_a_d_W_i_n_d_o_w error.

1144..11..1111..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__CCOOLLOORRMMAAPP__WWIINNDDOOWWSS PPrroopp­­
eerrttyy

Xlib provides functions that you can use to set and read the
WM_COLORMAP_WINDOWS property for a given window.


To set a window’s WM_COLORMAP_WINDOWS property, use _X_S_e_t_W_M_­
_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s.















                             552222





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XSetWMColormapWindows(_d_i_s_p_l_a_y, _w, _c_o_l_o_r_m_a_p___w_i_n_d_o_w_s, _c_o_u_n_t)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Window *_c_o_l_o_r_m_a_p___w_i_n_d_o_w_s;
      int _c_o_u_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_c_o_l_o_r_m_a_p___w_i_n_d_o_w_s
          Specifies the list of windows.

_c_o_u_n_t     Specifies the number of windows in the list.
││__

The _X_S_e_t_W_M_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s function replaces the WM_COL­
ORMAP_WINDOWS property on the specified window with the list
of windows specified by the colormap_windows argument.  If
the property does not already exist, _X_S_e_t_W_M_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s
sets the WM_COLORMAP_WINDOWS property on the specified win­
dow to the list of windows specified by the colormap_windows
argument.  The property is stored with a type of WINDOW and
a format of 32.  If it cannot intern the WM_COLORMAP_WINDOWS
atom, _X_S_e_t_W_M_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s returns a zero status.  Other­
wise, it returns a nonzero status.

_X_S_e_t_W_M_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w
errors.


To read a window’s WM_COLORMAP_WINDOWS property, use _X_G_e_t_W_M_­
_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s.






















                             552233





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetWMColormapWindows(_d_i_s_p_l_a_y, _w, _c_o_l_o_r_m_a_p___w_i_n_d_o_w_s___r_e_t_u_r_n, _c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      Window **_c_o_l_o_r_m_a_p___w_i_n_d_o_w_s___r_e_t_u_r_n;
      int *_c_o_u_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_c_o_l_o_r_m_a_p___w_i_n_d_o_w_s___r_e_t_u_r_n
          Returns the list of windows.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of windows in the list.
││__

The _X_G_e_t_W_M_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s function returns the list of win­
dow identifiers stored in the WM_COLORMAP_WINDOWS property
on the specified window.  These identifiers indicate the
colormaps that the window manager may need to install for
this window.  If the property exists, is of type WINDOW, is
of format 32, and the atom WM_COLORMAP_WINDOWS can be
interned, _X_G_e_t_W_M_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s sets the windows_return
argument to a list of window identifiers, sets the
count_return argument to the number of elements in the list,
and returns a nonzero status.  Otherwise, it sets neither of
the return arguments and returns a zero status.  To release
the list of window identifiers, use _X_F_r_e_e.

_X_G_e_t_W_M_C_o_l_o_r_m_a_p_W_i_n_d_o_w_s can generate a _B_a_d_W_i_n_d_o_w error.

1144..11..1122..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__IICCOONN__SSIIZZEE PPrrooppeerrttyy

Xlib provides functions that you can use to set and read the
WM_ICON_SIZE property for a given window.  These functions
use the _X_I_c_o_n_S_i_z_e structure, which is defined in the
<_X_1_1_/_X_u_t_i_l_._h> header file.


To allocate an _X_I_c_o_n_S_i_z_e structure, use _X_A_l_l_o_c_I_c_o_n_S_i_z_e.
__
││
XIconSize *XAllocIconSize()

││__

The _X_A_l_l_o_c_I_c_o_n_S_i_z_e function allocates and returns a pointer
to an _X_I_c_o_n_S_i_z_e structure.  Note that all fields in the
_X_I_c_o_n_S_i_z_e structure are initially set to zero.  If insuffi­
cient memory is available, _X_A_l_l_o_c_I_c_o_n_S_i_z_e returns NULL.  To
free the memory allocated to this structure, use _X_F_r_e_e.



                             552244





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The _X_I_c_o_n_S_i_z_e structure contains:

__
││
typedef struct {
     int min_width, min_height;
     int max_width, max_height;
     int width_inc, height_inc;
} XIconSize;

││__

The width_inc and height_inc members define an arithmetic
progression of sizes (minimum to maximum) that represent the
supported icon sizes.


To set a window’s WM_ICON_SIZE property, use _X_S_e_t_I_c_o_n_S_i_z_e_s.
__
││
XSetIconSizes(_d_i_s_p_l_a_y, _w, _s_i_z_e___l_i_s_t, _c_o_u_n_t)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XIconSize *_s_i_z_e___l_i_s_t;
      int _c_o_u_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_s_i_z_e___l_i_s_t Specifies the size list.

_c_o_u_n_t     Specifies the number of items in the size list.
││__

The _X_S_e_t_I_c_o_n_S_i_z_e_s function is used only by window managers
to set the supported icon sizes.

_X_S_e_t_I_c_o_n_S_i_z_e_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To read a window’s WM_ICON_SIZE property, use _X_G_e_t_I_c_o_n_S_i_z_e_s.














                             552255





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetIconSizes(_d_i_s_p_l_a_y, _w, _s_i_z_e___l_i_s_t___r_e_t_u_r_n, _c_o_u_n_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XIconSize **_s_i_z_e___l_i_s_t___r_e_t_u_r_n;
      int *_c_o_u_n_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_s_i_z_e___l_i_s_t___r_e_t_u_r_n
          Returns the size list.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of items in the size list.
││__

The _X_G_e_t_I_c_o_n_S_i_z_e_s function returns zero if a window manager
has not set icon sizes; otherwise, it returns nonzero.
_X_G_e_t_I_c_o_n_S_i_z_e_s should be called by an application that wants
to find out what icon sizes would be most appreciated by the
window manager under which the application is running.  The
application should then use _X_S_e_t_W_M_H_i_n_t_s to supply the window
manager with an icon pixmap or window in one of the sup­
ported sizes.  To free the data allocated in
size_list_return, use _X_F_r_e_e.

_X_G_e_t_I_c_o_n_S_i_z_e_s can generate a _B_a_d_W_i_n_d_o_w error.

1144..11..1133..  UUssiinngg WWiinnddooww MMaannaaggeerr CCoonnvveenniieennccee FFuunnccttiioonnss

The _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s function stores the standard set of
window manager properties, with text properties in standard
encodings for internationalized text communication.  The
standard window manager properties for a given window are
WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME.


















                             552266





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XmbSetWMProperties(_d_i_s_p_l_a_y, _w, _w_i_n_d_o_w___n_a_m_e, _i_c_o_n___n_a_m_e, _a_r_g_v, _a_r_g_c,
                      _n_o_r_m_a_l___h_i_n_t_s, _w_m___h_i_n_t_s, _c_l_a_s_s___h_i_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      char *_w_i_n_d_o_w___n_a_m_e;
      char *_i_c_o_n___n_a_m_e;
      char *_a_r_g_v[];
      int _a_r_g_c;
      XSizeHints *_n_o_r_m_a_l___h_i_n_t_s;
      XWMHints *_w_m___h_i_n_t_s;
      XClassHint *_c_l_a_s_s___h_i_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_w_i_n_d_o_w___n_a_m_e
          Specifies the window name, which should be a null‐
          terminated string.

_i_c_o_n___n_a_m_e Specifies the icon name, which should be a null‐
          terminated string.

_a_r_g_v      Specifies the application’s argument list.

_a_r_g_c      Specifies the number of arguments.

_h_i_n_t_s     Specifies the size hints for the window in its
          normal state.

_w_m___h_i_n_t_s  Specifies the _X_W_M_H_i_n_t_s structure to be used.

_c_l_a_s_s___h_i_n_t_s
          Specifies the _X_C_l_a_s_s_H_i_n_t structure to be used.
││__

The _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s convenience function provides a sim­
ple programming interface for setting those essential window
properties that are used for communicating with other
clients (particularly window and session managers).

If the window_name argument is non‐NULL, _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s
sets the WM_NAME property.  If the icon_name argument is
non‐NULL, _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s sets the WM_ICON_NAME property.
The window_name and icon_name arguments are null‐terminated
strings in the encoding of the current locale.  If the argu­
ments can be fully converted to the STRING encoding, the
properties are created with type ‘‘STRING’’; otherwise, the
arguments are converted to Compound Text, and the properties
are created with type ‘‘COMPOUND_TEXT’’.





                             552277





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


If the normal_hints argument is non‐NULL, _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s
calls _X_S_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s, which sets the WM_NORMAL_HINTS
property (see section 14.1.7).  If the wm_hints argument is
non‐NULL, _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s calls _X_S_e_t_W_M_H_i_n_t_s, which sets
the WM_HINTS property (see section 14.1.6).

If the argv argument is non‐NULL, _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s sets
the WM_COMMAND property from argv and argc.  An argc of zero
indicates a zero‐length command.

The hostname of the machine is stored using _X_S_e_t_W_M_C_l_i_e_n_t_M_a_­
_c_h_i_n_e (see section 14.2.2).

If the class_hints argument is non‐NULL, _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s
sets the WM_CLASS property.  If the res_name member in the
_X_C_l_a_s_s_H_i_n_t structure is set to the NULL pointer and the
RESOURCE_NAME environment variable is set, the value of the
environment variable is substituted for res_name.  If the
res_name member is NULL, the environment variable is not
set, and argv and argv[0] are set, then the value of
argv[0], stripped of any directory prefixes, is substituted
for res_name.

It is assumed that the supplied class_hints.res_name and
argv, the RESOURCE_NAME environment variable, and the host­
name of the machine are in the encoding of the locale
announced for the LC_CTYPE category (on POSIX‐compliant sys­
tems, the LC_CTYPE, else LANG environment variable).  The
corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE
properties are typed according to the local host locale
announcer.  No encoding conversion is performed prior to
storage in the properties.

For clients that need to process the property text in a
locale, _X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s sets the WM_LOCALE_NAME property
to be the name of the current locale.  The name is assumed
to be in the Host Portable Character Encoding and is con­
verted to STRING for storage in the property.

_X_m_b_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w
errors.


To set a window’s standard window manager properties with
strings in client‐specified encodings, use _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s.
The standard window manager properties for a given window
are WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS,
WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE.









                             552288





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XSetWMProperties(_d_i_s_p_l_a_y, _w, _w_i_n_d_o_w___n_a_m_e, _i_c_o_n___n_a_m_e, _a_r_g_v, _a_r_g_c, _n_o_r_m_a_l___h_i_n_t_s, _w_m___h_i_n_t_s, _c_l_a_s_s___h_i_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XTextProperty *_w_i_n_d_o_w___n_a_m_e;
      XTextProperty *_i_c_o_n___n_a_m_e;
      char **_a_r_g_v;
      int _a_r_g_c;
      XSizeHints *_n_o_r_m_a_l___h_i_n_t_s;
      XWMHints *_w_m___h_i_n_t_s;
      XClassHint *_c_l_a_s_s___h_i_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_w_i_n_d_o_w___n_a_m_e
          Specifies the window name, which should be a null‐
          terminated string.

_i_c_o_n___n_a_m_e Specifies the icon name, which should be a null‐
          terminated string.

_a_r_g_v      Specifies the application’s argument list.

_a_r_g_c      Specifies the number of arguments.

_n_o_r_m_a_l___h_i_n_t_s
          Specifies the size hints for the window in its
          normal state.

_w_m___h_i_n_t_s  Specifies the _X_W_M_H_i_n_t_s structure to be used.

_c_l_a_s_s___h_i_n_t_s
          Specifies the _X_C_l_a_s_s_H_i_n_t structure to be used.
││__

The _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s convenience function provides a single
programming interface for setting those essential window
properties that are used for communicating with other
clients (particularly window and session managers).

If the window_name argument is non‐NULL, _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s
calls _X_S_e_t_W_M_N_a_m_e, which, in turn, sets the WM_NAME property
(see section 14.1.4).  If the icon_name argument is non‐
NULL, _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s calls _X_S_e_t_W_M_I_c_o_n_N_a_m_e, which sets the
WM_ICON_NAME property (see section 14.1.5).  If the argv
argument is non‐NULL, _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s calls _X_S_e_t_C_o_m_m_a_n_d,
which sets the WM_COMMAND property (see section 14.2.1).
Note that an argc of zero is allowed to indicate a zero‐
length command.  Note also that the hostname of this machine
is stored using _X_S_e_t_W_M_C_l_i_e_n_t_M_a_c_h_i_n_e (see section 14.2.2).




                             552299





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


If the normal_hints argument is non‐NULL, _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s
calls _X_S_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s, which sets the WM_NORMAL_HINTS
property (see section 14.1.7).  If the wm_hints argument is
non‐NULL, _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s calls _X_S_e_t_W_M_H_i_n_t_s, which sets the
WM_HINTS property (see section 14.1.6).

If the class_hints argument is non‐NULL, _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s
calls _X_S_e_t_C_l_a_s_s_H_i_n_t, which sets the WM_CLASS property (see
section 14.1.8).  If the res_name member in the _X_C_l_a_s_s_H_i_n_t
structure is set to the NULL pointer and the RESOURCE_NAME
environment variable is set, then the value of the environ­
ment variable is substituted for res_name.  If the res_name
member is NULL, the environment variable is not set, and
argv and argv[0] are set, then the value of argv[0],
stripped of any directory prefixes, is substituted for
res_name.

_X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.

1144..22..  CClliieenntt ttoo SSeessssiioonn MMaannaaggeerr CCoommmmuunniiccaattiioonn

This section discusses how to:

⋅    Set and read the WM_COMMAND property

⋅    Set and read the WM_CLIENT_MACHINE property

1144..22..11..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__CCOOMMMMAANNDD PPrrooppeerrttyy

Xlib provides functions that you can use to set and read the
WM_COMMAND property for a given window.


To set a window’s WM_COMMAND property, use _X_S_e_t_C_o_m_m_a_n_d.
__
││
XSetCommand(_d_i_s_p_l_a_y, _w, _a_r_g_v, _a_r_g_c)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      char **_a_r_g_v;
      int _a_r_g_c;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_a_r_g_v      Specifies the application’s argument list.

_a_r_g_c      Specifies the number of arguments.
││__

The _X_S_e_t_C_o_m_m_a_n_d function sets the command and arguments used
to invoke the application.  (Typically, argv is the argv



                             553300





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


array of your main program.)  If the strings are not in the
Host Portable Character Encoding, the result is implementa­
tion‐dependent.

_X_S_e_t_C_o_m_m_a_n_d can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To read a window’s WM_COMMAND property, use _X_G_e_t_C_o_m_m_a_n_d.
__
││
Status XGetCommand(_d_i_s_p_l_a_y, _w, _a_r_g_v___r_e_t_u_r_n, _a_r_g_c___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      char ***_a_r_g_v___r_e_t_u_r_n;
      int *_a_r_g_c___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_a_r_g_v___r_e_t_u_r_n
          Returns the application’s argument list.

_a_r_g_c___r_e_t_u_r_n
          Returns the number of arguments returned.
││__

The _X_G_e_t_C_o_m_m_a_n_d function reads the WM_COMMAND property from
the specified window and returns a string list.  If the
WM_COMMAND property exists, it is of type STRING and format
8.  If sufficient memory can be allocated to contain the
string list, _X_G_e_t_C_o_m_m_a_n_d fills in the argv_return and
argc_return arguments and returns a nonzero status.  Other­
wise, it returns a zero status.  If the data returned by the
server is in the Latin Portable Character Encoding, then the
returned strings are in the Host Portable Character Encod­
ing.  Otherwise, the result is implementation‐dependent.  To
free the memory allocated to the string list, use
_X_F_r_e_e_S_t_r_i_n_g_L_i_s_t.

1144..22..22..  SSeettttiinngg aanndd RReeaaddiinngg tthhee WWMM__CCLLIIEENNTT__MMAACCHHIINNEE PPrrooppeerrttyy

Xlib provides functions that you can use to set and read the
WM_CLIENT_MACHINE property for a given window.


To set a window’s WM_CLIENT_MACHINE property, use _X_S_e_t_W_M_­
_C_l_i_e_n_t_M_a_c_h_i_n_e.








                             553311





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XSetWMClientMachine(_d_i_s_p_l_a_y, _w, _t_e_x_t___p_r_o_p)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XTextProperty *_t_e_x_t___p_r_o_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_t_e_x_t___p_r_o_p Specifies the _X_T_e_x_t_P_r_o_p_e_r_t_y structure to be used.
││__

The _X_S_e_t_W_M_C_l_i_e_n_t_M_a_c_h_i_n_e convenience function calls _X_S_e_t_­
_T_e_x_t_P_r_o_p_e_r_t_y to set the WM_CLIENT_MACHINE property.


To read a window’s WM_CLIENT_MACHINE property, use _X_G_e_t_W_M_­
_C_l_i_e_n_t_M_a_c_h_i_n_e.
__
││
Status XGetWMClientMachine(_d_i_s_p_l_a_y, _w, _t_e_x_t___p_r_o_p___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XTextProperty *_t_e_x_t___p_r_o_p___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_t_e_x_t___p_r_o_p___r_e_t_u_r_n
          Returns the _X_T_e_x_t_P_r_o_p_e_r_t_y structure.
││__

The _X_G_e_t_W_M_C_l_i_e_n_t_M_a_c_h_i_n_e convenience function performs an
_X_G_e_t_T_e_x_t_P_r_o_p_e_r_t_y on the WM_CLIENT_MACHINE property.  It
returns a nonzero status on success; otherwise, it returns a
zero status.

1144..33..  SSttaannddaarrdd CCoolloorrmmaappss

Applications with color palettes, smooth‐shaded drawings, or
digitized images demand large numbers of colors.  In addi­
tion, these applications often require an efficient mapping
from color triples to pixel values that display the appro­
priate colors.

As an example, consider a three‐dimensional display program
that wants to draw a smoothly shaded sphere.  At each pixel
in the image of the sphere, the program computes the inten­
sity and color of light reflected back to the viewer.  The
result of each computation is a triple of red, green, and



                             553322





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


blue (RGB) coefficients in the range 0.0 to 1.0.  To draw
the sphere, the program needs a colormap that provides a
large range of uniformly distributed colors.  The colormap
should be arranged so that the program can convert its RGB
triples into pixel values very quickly, because drawing the
entire sphere requires many such conversions.

On many current workstations, the display is limited to 256
or fewer colors.  Applications must allocate colors care­
fully, not only to make sure they cover the entire range
they need but also to make use of as many of the available
colors as possible.  On a typical X display, many applica­
tions are active at once.  Most workstations have only one
hardware look‐up table for colors, so only one application
colormap can be installed at a given time.  The application
using the installed colormap is displayed correctly, and the
other applications go technicolor and are displayed with
false colors.

As another example, consider a user who is running an image
processing program to display earth‐resources data.  The
image processing program needs a colormap set up with 8
reds, 8 greens, and 4 blues, for a total of 256 colors.
Because some colors are already in use in the default col­
ormap, the image processing program allocates and installs a
new colormap.

The user decides to alter some of the colors in the image by
invoking a color palette program to mix and choose colors.
The color palette program also needs a colormap with eight
reds, eight greens, and four blues, so just like the image
processing program, it must allocate and install a new col­
ormap.

Because only one colormap can be installed at a time, the
color palette may be displayed incorrectly whenever the
image processing program is active.  Conversely, whenever
the palette program is active, the image may be displayed
incorrectly.  The user can never match or compare colors in
the palette and image.  Contention for colormap resources
can be reduced if applications with similar color needs
share colormaps.

The image processing program and the color palette program
could share the same colormap if there existed a convention
that described how the colormap was set up.  Whenever either
program was active, both would be displayed correctly.

The standard colormap properties define a set of commonly
used colormaps.  Applications that share these colormaps and
conventions display true colors more often and provide a
better interface to the user.





                             553333





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Standard colormaps allow applications to share commonly used
color resources.  This allows many applications to be dis­
played in true colors simultaneously, even when each appli­
cation needs an entirely filled colormap.

Several standard colormaps are described in this section.
Usually, a window manager creates these colormaps.  Applica­
tions should use the standard colormaps if they already
exist.


To allocate an _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure, use _X_A_l_l_o_c_S_t_a_n_­
_d_a_r_d_C_o_l_o_r_m_a_p.
__
││
XStandardColormap *XAllocStandardColormap()

││__

The _X_A_l_l_o_c_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p function allocates and returns a
pointer to an _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure.  Note that all
fields in the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure are initially set
to zero.  If insufficient memory is available, _X_A_l_l_o_c_S_t_a_n_­
_d_a_r_d_C_o_l_o_r_m_a_p returns NULL.  To free the memory allocated to
this structure, use _X_F_r_e_e.

The _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure contains:

__
││    /* Hints */

#define   _R_e_l_e_a_s_e_B_y_F_r_e_e_i_n_g_C_o_l_­   ( (XID)
          _o_r_m_a_p                  1L)

/* Values */

typedef struct {
     Colormap colormap;
     unsigned long red_max;
     unsigned long red_mult;
     unsigned long green_max;
     unsigned long green_mult;
     unsigned long blue_max;
     unsigned long blue_mult;
     unsigned long base_pixel;
     VisualID visualid;
     XID killid;
} XStandardColormap;

││__

The colormap member is the colormap created by the _X_C_r_e_a_t_e_­
_C_o_l_o_r_m_a_p function.  The red_max, green_max, and blue_max
members give the maximum red, green, and blue values,



                             553344





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


respectively.  Each color coefficient ranges from zero to
its max, inclusive.  For example, a common colormap alloca­
tion is 3/3/2 (3 planes for red, 3 planes for green, and 2
planes for blue).  This colormap would have red_max = 7,
green_max = 7, and blue_max = 3.  An alternate allocation
that uses only 216 colors is red_max = 5, green_max = 5, and
blue_max = 5.

The red_mult, green_mult, and blue_mult members give the
scale factors used to compose a full pixel value.  (See the
discussion of the base_pixel members for further informa­
tion.)  For a 3/3/2 allocation, red_mult might be 32,
green_mult might be 4, and blue_mult might be 1.  For a
6‐colors‐each allocation, red_mult might be 36, green_mult
might be 6, and blue_mult might be 1.

The base_pixel member gives the base pixel value used to
compose a full pixel value.  Usually, the base_pixel is
obtained from a call to the _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s function.
Given integer red, green, and blue coefficients in their
appropriate ranges, one then can compute a corresponding
pixel value by using the following expression:


     (r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF


For _G_r_a_y_S_c_a_l_e colormaps, only the colormap, red_max,
red_mult, and base_pixel members are defined.  The other
members are ignored.  To compute a _G_r_a_y_S_c_a_l_e pixel value,
use the following expression:


     (gray * red_mult + base_pixel) & 0xFFFFFFFF


Negative multipliers can be represented by converting the
2’s complement representation of the multiplier into an
unsigned long and storing the result in the appropriate
_mult field.  The step of masking by 0xFFFFFFFF effectively
converts the resulting positive multiplier into a negative
one.  The masking step will take place automatically on many
machine architectures, depending on the size of the integer
type used to do the computation.

The visualid member gives the ID number of the visual from
which the colormap was created.  The killid member gives a
resource ID that indicates whether the cells held by this
standard colormap are to be released by freeing the colormap
ID or by calling the _X_K_i_l_l_C_l_i_e_n_t function on the indicated
resource.  (Note that this method is necessary for allocat­
ing out of an existing colormap.)





                             553355





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The properties containing the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p information
have the type RGB_COLOR_MAP.

The remainder of this section discusses standard colormap
properties and atoms as well as how to manipulate standard
colormaps.

1144..33..11..  SSttaannddaarrdd CCoolloorrmmaapp PPrrooppeerrttiieess aanndd AAttoommss

Several standard colormaps are available.  Each standard
colormap is defined by a property, and each such property is
identified by an atom.  The following list names the atoms
and describes the colormap associated with each one.  The
<_X_1_1_/_X_a_t_o_m_._h> header file contains the definitions for each
of the following atoms, which are prefixed with XA_.

RGB_DEFAULT_MAP
     This atom names a property.  The value of the property
     is an array of _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structures.  Each
     entry in the array describes an RGB subset of the
     default color map for the Visual specified by
     visual_id.

     Some applications only need a few RGB colors and may be
     able to allocate them from the system default colormap.
     This is the ideal situation because the fewer colormaps
     that are active in the system the more applications are
     displayed with correct colors at all times.

     A typical allocation for the RGB_DEFAULT_MAP on 8‐plane
     displays is 6 reds, 6 greens, and 6 blues.  This gives
     216 uniformly distributed colors (6 intensities of 36
     different hues) and still leaves 40 elements of a
     256‐element colormap available for special‐purpose col­
     ors for text, borders, and so on.

RGB_BEST_MAP
     This atom names a property.  The value of the property
     is an _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p.

     The property defines the best RGB colormap available on
     the screen.  (Of course, this is a subjective evalua­
     tion.)  Many image processing and three‐dimensional
     applications need to use all available colormap cells
     and to distribute as many perceptually distinct colors
     as possible over those cells.  This implies that there
     may be more green values available than red, as well as
     more green or red than blue.

     For an 8‐plane _P_s_e_u_d_o_C_o_l_o_r visual, RGB_BEST_MAP is
     likely to be a 3/3/2 allocation.  For a 24‐plane
     _D_i_r_e_c_t_C_o_l_o_r visual, RGB_BEST_MAP is normally an 8/8/8
     allocation.




                             553366





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


RGB_RED_MAP
RGB_GREEN_MAP
RGB_BLUE_MAP
     These atoms name properties.  The value of each prop­
     erty is an _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p.

     The properties define all‐red, all‐green, and all‐blue
     colormaps, respectively.  These maps are used by appli­
     cations that want to make color‐separated images.  For
     example, a user might generate a full‐color image on an
     8‐plane display both by rendering an image three times
     (once with high color resolution in red, once with
     green, and once with blue) and by multiply exposing a
     single frame in a camera.

RGB_GRAY_MAP
     This atom names a property.  The value of the property
     is an _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p.

     The property describes the best _G_r_a_y_S_c_a_l_e colormap
     available on the screen.  As previously mentioned, only
     the colormap, red_max, red_mult, and base_pixel members
     of the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure are used for
     _G_r_a_y_S_c_a_l_e colormaps.

1144..33..22..  SSeettttiinngg aanndd OObbttaaiinniinngg SSttaannddaarrdd CCoolloorrmmaappss

Xlib provides functions that you can use to set and obtain
an _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure.


To set an _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure, use _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s.

























                             553377





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XSetRGBColormaps(_d_i_s_p_l_a_y, _w, _s_t_d___c_o_l_o_r_m_a_p, _c_o_u_n_t, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XStandardColormap *_s_t_d___c_o_l_o_r_m_a_p;
      int _c_o_u_n_t;
      Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_s_t_d___c_o_l_o_r_m_a_p
          Specifies the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure to be
          used.

_c_o_u_n_t     Specifies the number of colormaps.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s function replaces the RGB colormap def­
inition in the specified property on the named window.  If
the property does not already exist, _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s sets
the RGB colormap definition in the specified property on the
named window.  The property is stored with a type of
RGB_COLOR_MAP and a format of 32.  Note that it is the
caller’s responsibility to honor the ICCCM restriction that
only RGB_DEFAULT_MAP contain more than one definition.

The _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s function usually is only used by window
or session managers.  To create a standard colormap, follow
this procedure:

1.   Open a new connection to the same server.

2.   Grab the server.

3.   See if the property is on the property list of the root
     window for the screen.

4.   If the desired property is not present:

     ⋅    Create a colormap (unless you are using the
          default colormap of the screen).

     ⋅    Determine the color characteristics of the visual.

     ⋅    Allocate cells in the colormap (or create it with
          _A_l_l_o_c_A_l_l).

     ⋅    Call _X_S_t_o_r_e_C_o_l_o_r_s to store appropriate color val­
          ues in the colormap.



                             553388





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


     ⋅    Fill in the descriptive members in the _X_S_t_a_n_d_a_r_d_­
          _C_o_l_o_r_m_a_p structure.

     ⋅    Attach the property to the root window.

     ⋅    Use _X_S_e_t_C_l_o_s_e_D_o_w_n_M_o_d_e to make the resource perma­
          nent.

5.   Ungrab the server.

_X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s can generate _B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, and _B_a_d_W_i_n_­
_d_o_w errors.


To obtain the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure associated with
the specified property, use _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s.
__
││
Status XGetRGBColormaps(_d_i_s_p_l_a_y, _w, _s_t_d___c_o_l_o_r_m_a_p___r_e_t_u_r_n, _c_o_u_n_t___r_e_t_u_r_n, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XStandardColormap **_s_t_d___c_o_l_o_r_m_a_p___r_e_t_u_r_n;
      int *_c_o_u_n_t___r_e_t_u_r_n;
      Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_s_t_d___c_o_l_o_r_m_a_p___r_e_t_u_r_n
          Returns the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure.

_c_o_u_n_t___r_e_t_u_r_n
          Returns the number of colormaps.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s function returns the RGB colormap defi­
nitions stored in the specified property on the named win­
dow.  If the property exists, is of type RGB_COLOR_MAP, is
of format 32, and is long enough to contain a colormap defi­
nition, _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s allocates and fills in space for
the returned colormaps and returns a nonzero status.  If the
visualid is not present, _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s assumes the
default visual for the screen on which the window is
located; if the killid is not present, _N_o_n_e is assumed,
which indicates that the resources cannot be released.  Oth­
erwise, none of the fields are set, and _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s
returns a zero status.  Note that it is the caller’s respon­
sibility to honor the ICCCM restriction that only
RGB_DEFAULT_MAP contain more than one definition.




                             553399





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w errors.
























































                             554400





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 1155

                 RReessoouurrccee MMaannaaggeerr FFuunnccttiioonnss



A program often needs a variety of options in the X environ­
ment (for example, fonts, colors, icons, and cursors).
Specifying all of these options on the command line is awk­
ward because users may want to customize many aspects of the
program and need a convenient way to establish these cus­
tomizations as the default settings.  The resource manager
is provided for this purpose.  Resource specifications are
usually stored in human‐readable files and in server proper­
ties.

The resource manager is a database manager with a twist.  In
most database systems, you perform a query using an impre­
cise specification, and you get back a set of records.  The
resource manager, however, allows you to specify a large set
of values with an imprecise specification, to query the
database with a precise specification, and to get back only
a single value.  This should be used by applications that
need to know what the user prefers for colors, fonts, and
other resources.  It is this use as a database for dealing
with X resources that inspired the name ‘‘Resource Man­
ager,’’ although the resource manager can be and is used in
other ways.

For example, a user of your application may want to specify
that all windows should have a blue background but that all
mail‐reading windows should have a red background.  With
well‐engineered and coordinated applications, a user can
define this information using only two lines of specifica­
tions.

As an example of how the resource manager works, consider a
mail‐reading application called xmh.  Assume that it is
designed so that it uses a complex window hierarchy all the
way down to individual command buttons, which may be actual
small subwindows in some toolkits.  These are often called
objects or widgets.  In such toolkit systems, each user
interface object can be composed of other objects and can be
assigned a name and a class.  Fully qualified names or
classes can have arbitrary numbers of component names, but a
fully qualified name always has the same number of component
names as a fully qualified class.  This generally reflects
the structure of the application as composed of these
objects, starting with the application itself.

For example, the xmh mail program has a name ‘‘xmh’’ and is
one of a class of ‘‘Mail’’ programs.  By convention, the



                             554411





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


first character of class components is capitalized, and the
first letter of name components is in lowercase.  Each name
and class finally has an attribute (for example, ‘‘fore­
ground’’ or ‘‘font’’).  If each window is properly assigned
a name and class, it is easy for the user to specify
attributes of any portion of the application.

At the top level, the application might consist of a paned
window (that is, a window divided into several sections)
named ‘‘toc’’.  One pane of the paned window is a button box
window named ‘‘buttons’’ and is filled with command buttons.
One of these command buttons is used to incorporate new mail
and has the name ‘‘incorporate’’.  This window has a fully
qualified name, ‘‘xmh.toc.buttons.incorporate’’, and a fully
qualified class, ‘‘Xmh.Paned.Box.Command’’.  Its fully qual­
ified name is the name of its parent, ‘‘xmh.toc.buttons’’,
followed by its name, ‘‘incorporate’’.  Its class is the
class of its parent, ‘‘Xmh.Paned.Box’’, followed by its par­
ticular class, ‘‘Command’’.  The fully qualified name of a
resource is the attribute’s name appended to the object’s
fully qualified name, and the fully qualified class is its
class appended to the object’s class.

The incorporate button might need the following resources:
Title string, Font, Foreground color for its inactive state,
Background color for its inactive state, Foreground color
for its active state, and Background color for its active
state.  Each resource is considered to be an attribute of
the button and, as such, has a name and a class.  For exam­
ple, the foreground color for the button in its active state
might be named ‘‘activeForeground’’, and its class might be
‘‘Foreground’’.

When an application looks up a resource (for example, a
color), it passes the complete name and complete class of
the resource to a look‐up routine.  The resource manager
compares this complete specification against the incomplete
specifications of entries in the resource database, finds
the best match, and returns the corresponding value for that
entry.

The definitions for the resource manager are contained in
<_X_1_1_/_X_r_e_s_o_u_r_c_e_._h>.

1155..11..  RReessoouurrccee FFiillee SSyynnttaaxx

The syntax of a resource file is a sequence of resource
lines terminated by newline characters or the end of the
file.  The syntax of an individual resource line is:


ResourceLine   = Comment | IncludeFile | ResourceSpec | <empty line>
Comment        = "!" {<any character except null or newline>}
IncludeFile    = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace



                             554422





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


FileName       = <valid filename for operating system>
ResourceSpec   = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
ResourceName   = [Binding] {Component Binding} ComponentName
Binding        = "." | "*"
WhiteSpace     = {<space> | <horizontal tab>}
Component      = "?" | ComponentName
ComponentName  = NameChar {NameChar}
NameChar       = "a"−"z" | "A"−"Z" | "0"−"9" | "_" | "‐"
Value          = {<any character except null or unescaped newline>}


Elements separated by vertical bar (|) are alternatives.
Curly braces ({...}) indicate zero or more repetitions of
the enclosed elements.  Square brackets ([...]) indicate
that the enclosed element is optional.  Quotes ("...") are
used around literal characters.

IncludeFile lines are interpreted by replacing the line with
the contents of the specified file.  The word ‘‘include’’
must be in lowercase.  The file name is interpreted relative
to the directory of the file in which the line occurs (for
example, if the file name contains no directory or contains
a relative directory specification).

If a ResourceName contains a contiguous sequence of two or
more Binding characters, the sequence will be replaced with
a single ‘‘.’’ character if the sequence contains only ‘‘.’’
characters; otherwise, the sequence will be replaced with a
single ‘‘*’’ character.

A resource database never contains more than one entry for a
given ResourceName.  If a resource file contains multiple
lines with the same ResourceName, the last line in the file
is used.

Any white space characters before or after the name or colon
in a ResourceSpec are ignored.  To allow a Value to begin
with white space, the two‐character sequence ‘‘\_s_p_a_c_e’’
(backslash followed by space) is recognized and replaced by
a space character, and the two‐character sequence ‘‘\_t_a_b’’
(backslash followed by horizontal tab) is recognized and
replaced by a horizontal tab character.  To allow a Value to
contain embedded newline characters, the two‐character
sequence ‘‘\n’’ is recognized and replaced by a newline
character.  To allow a Value to be broken across multiple
lines in a text file, the two‐character sequence ‘‘\_n_e_w_­
_l_i_n_e’’ (backslash followed by newline) is recognized and
removed from the value.  To allow a Value to contain arbi­
trary character codes, the four‐character sequence ‘‘\_n_n_n’’,
where each _n is a digit character in the range of
‘‘0’’−‘‘7’’, is recognized and replaced with a single byte
that contains the octal value specified by the sequence.
Finally, the two‐character sequence ‘‘\\’’ is recognized and
replaced with a single backslash.



                             554433





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


As an example of these sequences, the following resource
line contains a value consisting of four characters: a back­
slash, a null, a ‘‘z’’, and a newline:

     magic.values: \\\000\
     z\n


1155..22..  RReessoouurrccee MMaannaaggeerr MMaattcchhiinngg RRuulleess

The algorithm for determining which resource database entry
matches a given query is the heart of the resource manager.
All queries must fully specify the name and class of the
desired resource (use of the characters ‘‘*’’ and ‘‘?’’ is
not permitted).  The library supports up to 100 components
in a full name or class.  Resources are stored in the
database with only partially specified names and classes,
using pattern matching constructs.  An asterisk (*) is a
loose binding and is used to represent any number of inter­
vening components, including none.  A period (.) is a tight
binding and is used to separate immediately adjacent compo­
nents.  A question mark (?) is used to match any single com­
ponent name or class.  A database entry cannot end in a
loose binding; the final component (which cannot be the
character ‘‘?’’) must be specified.  The lookup algorithm
searches the database for the entry that most closely
matches (is most specific for) the full name and class being
queried.  When more than one database entry matches the full
name and class, precedence rules are used to select just
one.

The full name and class are scanned from left to right (from
highest level in the hierarchy to lowest), one component at
a time.  At each level, the corresponding component and/or
binding of each matching entry is determined, and these
matching components and bindings are compared according to
precedence rules.  Each of the rules is applied at each
level before moving to the next level, until a rule selects
a single entry over all others.  The rules, in order of
precedence, are:

1.   An entry that contains a matching component (whether
     name, class, or the character ‘‘?’’)  takes precedence
     over entries that elide the level (that is, entries
     that match the level in a loose binding).

2.   An entry with a matching name takes precedence over
     both entries with a matching class and entries that
     match using the character ‘‘?’’.  An entry with a
     matching class takes precedence over entries that match
     using the character ‘‘?’’.

3.   An entry preceded by a tight binding takes precedence
     over entries preceded by a loose binding.



                             554444





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To illustrate these rules, consider the following resource
database entries:

     xmh*Paned*activeForeground:        red_(_e_n_t_r_y _A_)
     *incorporate.Foreground: blue      _(_e_n_t_r_y _B_)
     xmh.toc*Command*activeForeground:  green_(_e_n_t_r_y _C_)
     xmh.toc*?.Foreground:    white     _(_e_n_t_r_y _D_)
     xmh.toc*Command.activeForeground:  black_(_e_n_t_r_y _E_)


Consider a query for the resource:


     xmh.toc.messagefunctions.incorporate.activeForeground_(_n_a_m_e_)
     Xmh.Paned.Box.Command.Foreground   _(_c_l_a_s_s_)


At the first level (xmh, Xmh), rule 1 eliminates entry B.
At the second level (toc, Paned), rule 2 eliminates entry A.
At the third level (messagefunctions, Box), no entries are
eliminated.  At the fourth level (incorporate, Command),
rule 2 eliminates entry D.  At the fifth level (activeFore­
ground, Foreground), rule 3 eliminates entry C.

1155..33..  QQuuaarrkkss

Most uses of the resource manager involve defining names,
classes, and representation types as string constants.  How­
ever, always referring to strings in the resource manager
can be slow, because it is so heavily used in some toolkits.
To solve this problem, a shorthand for a string is used in
place of the string in many of the resource manager func­
tions.  Simple comparisons can be performed rather than
string comparisons.  The shorthand name for a string is
called a quark and is the type _X_r_m_Q_u_a_r_k.  On some occasions,
you may want to allocate a quark that has no string equiva­
lent.

A quark is to a string what an atom is to a string in the
server, but its use is entirely local to your application.


To allocate a new quark, use _X_r_m_U_n_i_q_u_e_Q_u_a_r_k.
__
││
XrmQuark XrmUniqueQuark()

││__

The _X_r_m_U_n_i_q_u_e_Q_u_a_r_k function allocates a quark that is guar­
anteed not to represent any string that is known to the
resource manager.





                             554455





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Each name, class, and representation type is typedef’d as an
_X_r_m_Q_u_a_r_k.

__
││
typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuark XrmName;
typedef XrmQuark XrmClass;
typedef XrmQuark XrmRepresentation;
#define NULLQUARK ((XrmQuark) 0)

││__

Lists are represented as null‐terminated arrays of quarks.
The size of the array must be large enough for the number of
components used.

__
││
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;

││__


To convert a string to a quark, use _X_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k or _X_r_m_­
_P_e_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k.
__
││
#define XrmStringToName(string) XrmStringToQuark(string)
#define XrmStringToClass(string) XrmStringToQuark(string)
#define XrmStringToRepresentation(string) XrmStringToQuark(string)

XrmQuark XrmStringToQuark(_s_t_r_i_n_g)
     char *_s_t_r_i_n_g;

XrmQuark XrmPermStringToQuark(_s_t_r_i_n_g)
     char *_s_t_r_i_n_g;


_s_t_r_i_n_g    Specifies the string for which a quark is to be
          allocated.
││__

These functions can be used to convert from string to quark
representation.  If the string is not in the Host Portable
Character Encoding, the conversion is implementation‐depen­
dent.  The string argument to _X_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k need not be
permanently allocated storage.  _X_r_m_P_e_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k is just
like _X_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k, except that Xlib is permitted to
assume the string argument is permanently allocated, and,
hence, that it can be used as the value to be returned by
_X_r_m_Q_u_a_r_k_T_o_S_t_r_i_n_g.




                             554466





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


For any given quark, if _X_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k returns a non‐NULL
value, all future calls will return the same value (identi­
cal address).


To convert a quark to a string, use _X_r_m_Q_u_a_r_k_T_o_S_t_r_i_n_g.
__
││
#define XrmNameToString(name) XrmQuarkToString(name)
#define XrmClassToString(class) XrmQuarkToString(class)
#define XrmRepresentationToString(type) XrmQuarkToString(type)

char *XrmQuarkToString(_q_u_a_r_k)
     XrmQuark _q_u_a_r_k;


_q_u_a_r_k     Specifies the quark for which the equivalent
          string is desired.
││__

These functions can be used to convert from quark represen­
tation to string.  The string pointed to by the return value
must not be modified or freed.  The returned string is byte‐
for‐byte equal to the original string passed to one of the
string‐to‐quark routines.  If no string exists for that
quark, _X_r_m_Q_u_a_r_k_T_o_S_t_r_i_n_g returns NULL.  For any given quark,
if _X_r_m_Q_u_a_r_k_T_o_S_t_r_i_n_g returns a non‐NULL value, all future
calls will return the same value (identical address).


To convert a string with one or more components to a quark
list, use _X_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k_L_i_s_t.
__
││
#define XrmStringToNameList(str, name)  XrmStringToQuarkList((str), (name))
#define XrmStringToClassList(str, class) XrmStringToQuarkList((str), (class))

void XrmStringToQuarkList(_s_t_r_i_n_g, _q_u_a_r_k_s___r_e_t_u_r_n)
     char *_s_t_r_i_n_g;
     XrmQuarkList _q_u_a_r_k_s___r_e_t_u_r_n;


_s_t_r_i_n_g    Specifies the string for which a quark list is to
          be allocated.

_q_u_a_r_k_s___r_e_t_u_r_n
          Returns the list of quarks.  The caller must allo­
          cate sufficient space for the quarks list before
          calling _X_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k_L_i_s_t.
││__

The _X_r_m_S_t_r_i_n_g_T_o_Q_u_a_r_k_L_i_s_t function converts the null‐termi­
nated string (generally a fully qualified name) to a list of
quarks.  Note that the string must be in the valid



                             554477





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


ResourceName format (see section 15.1).  If the string is
not in the Host Portable Character Encoding, the conversion
is implementation‐dependent.

A binding list is a list of type _X_r_m_B_i_n_d_i_n_g_L_i_s_t and indi­
cates if components of name or class lists are bound tightly
or loosely (that is, if wildcarding of intermediate compo­
nents is specified).


typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;


_X_r_m_B_i_n_d_T_i_g_h_t_l_y indicates that a period separates the compo­
nents, and _X_r_m_B_i_n_d_L_o_o_s_e_l_y indicates that an asterisk sepa­
rates the components.


To convert a string with one or more components to a binding
list and a quark list, use _X_r_m_S_t_r_i_n_g_T_o_B_i_n_d_i_n_g_Q_u_a_r_k_L_i_s_t.
__
││
XrmStringToBindingQuarkList(_s_t_r_i_n_g, _b_i_n_d_i_n_g_s___r_e_t_u_r_n, _q_u_a_r_k_s___r_e_t_u_r_n)
     char *_s_t_r_i_n_g;
     XrmBindingList _b_i_n_d_i_n_g_s___r_e_t_u_r_n;
     XrmQuarkList _q_u_a_r_k_s___r_e_t_u_r_n;


_s_t_r_i_n_g    Specifies the string for which a quark list is to
          be allocated.

_b_i_n_d_i_n_g_s___r_e_t_u_r_n
          Returns the binding list.  The caller must allo­
          cate sufficient space for the binding list before
          calling _X_r_m_S_t_r_i_n_g_T_o_B_i_n_d_i_n_g_Q_u_a_r_k_L_i_s_t.

_q_u_a_r_k_s___r_e_t_u_r_n
          Returns the list of quarks.  The caller must allo­
          cate sufficient space for the quarks list before
          calling _X_r_m_S_t_r_i_n_g_T_o_B_i_n_d_i_n_g_Q_u_a_r_k_L_i_s_t.
││__

Component names in the list are separated by a period or an
asterisk character.  The string must be in the format of a
valid ResourceName (see section 15.1).  If the string does
not start with a period or an asterisk, a tight binding is
assumed.  For example, the string ‘‘*a.b*c’’ becomes:


quarks:        a      bc
bindings:      loose  tightloose






                             554488





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


1155..44..  CCrreeaattiinngg aanndd SSttoorriinngg DDaattaabbaasseess

A resource database is an opaque type, _X_r_m_D_a_t_a_b_a_s_e.  Each
database value is stored in an _X_r_m_V_a_l_u_e structure.  This
structure consists of a size, an address, and a representa­
tion type.  The size is specified in bytes.  The representa­
tion type is a way for you to store data tagged by some
application‐defined type (for example, the strings ‘‘font’’
or ‘‘color’’).  It has nothing to do with the C data type or
with its class.  The _X_r_m_V_a_l_u_e structure is defined as:

__
││
typedef struct {
     unsigned int size;
     XPointer addr;
} XrmValue, *XrmValuePtr;

││__


To initialize the resource manager, use _X_r_m_I_n_i_t_i_a_l_i_z_e.
__
││
void XrmInitialize();

││__

To retrieve a database from disk, use _X_r_m_G_e_t_F_i_l_e_D_a_t_a_b_a_s_e.
__
││
XrmDatabase XrmGetFileDatabase(_f_i_l_e_n_a_m_e)
     char *_f_i_l_e_n_a_m_e;


_f_i_l_e_n_a_m_e  Specifies the resource database file name.
││__

The _X_r_m_G_e_t_F_i_l_e_D_a_t_a_b_a_s_e function opens the specified file,
creates a new resource database, and loads it with the spec­
ifications read in from the specified file.  The specified
file should contain a sequence of entries in valid Resource­
Line format (see section 15.1); the database that results
from reading a file with incorrect syntax is implementation‐
dependent.  The file is parsed in the current locale, and
the database is created in the current locale.  If it cannot
open the specified file, _X_r_m_G_e_t_F_i_l_e_D_a_t_a_b_a_s_e returns NULL.


To store a copy of a database to disk, use _X_r_m_P_u_t_F_i_l_e_­
_D_a_t_a_b_a_s_e.






                             554499





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XrmPutFileDatabase(_d_a_t_a_b_a_s_e, _s_t_o_r_e_d___d_b)
     XrmDatabase _d_a_t_a_b_a_s_e;
     char *_s_t_o_r_e_d___d_b;


_d_a_t_a_b_a_s_e  Specifies the database that is to be used.

_s_t_o_r_e_d___d_b Specifies the file name for the stored database.
││__

The _X_r_m_P_u_t_F_i_l_e_D_a_t_a_b_a_s_e function stores a copy of the speci­
fied database in the specified file.  Text is written to the
file as a sequence of entries in valid ResourceLine format
(see section 15.1).  The file is written in the locale of
the database.  Entries containing resource names that are
not in the Host Portable Character Encoding or containing
values that are not in the encoding of the database locale,
are written in an implementation‐dependent manner.  The
order in which entries are written is implementation‐depen­
dent.  Entries with representation types other than
‘‘String’’ are ignored.


To obtain a pointer to the screen‐independent resources of a
display, use _X_R_e_s_o_u_r_c_e_M_a_n_a_g_e_r_S_t_r_i_n_g.
__
││
char *XResourceManagerString(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_R_e_s_o_u_r_c_e_M_a_n_a_g_e_r_S_t_r_i_n_g function returns the
RESOURCE_MANAGER property from the server’s root window of
screen zero, which was returned when the connection was
opened using _X_O_p_e_n_D_i_s_p_l_a_y.  The property is converted from
type STRING to the current locale.  The conversion is iden­
tical to that produced by _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t for a
single element STRING property.  The returned string is
owned by Xlib and should not be freed by the client.  The
property value must be in a format that is acceptable to
_X_r_m_G_e_t_S_t_r_i_n_g_D_a_t_a_b_a_s_e.  If no property exists, NULL is
returned.


To obtain a pointer to the screen‐specific resources of a
screen, use _X_S_c_r_e_e_n_R_e_s_o_u_r_c_e_S_t_r_i_n_g.







                             555500





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char *XScreenResourceString(_s_c_r_e_e_n)
      Screen *_s_c_r_e_e_n;


_s_c_r_e_e_n    Specifies the screen.
││__

The _X_S_c_r_e_e_n_R_e_s_o_u_r_c_e_S_t_r_i_n_g function returns the
SCREEN_RESOURCES property from the root window of the speci­
fied screen.  The property is converted from type STRING to
the current locale.  The conversion is identical to that
produced by _X_m_b_T_e_x_t_P_r_o_p_e_r_t_y_T_o_T_e_x_t_L_i_s_t for a single element
STRING property.  The property value must be in a format
that is acceptable to _X_r_m_G_e_t_S_t_r_i_n_g_D_a_t_a_b_a_s_e.  If no property
exists, NULL is returned.  The caller is responsible for
freeing the returned string by using _X_F_r_e_e.


To create a database from a string, use _X_r_m_G_e_t_S_t_r_i_n_g_­
_D_a_t_a_b_a_s_e.
__
││
XrmDatabase XrmGetStringDatabase(_d_a_t_a)
     char *_d_a_t_a;


_d_a_t_a      Specifies the database contents using a string.
││__

The _X_r_m_G_e_t_S_t_r_i_n_g_D_a_t_a_b_a_s_e function creates a new database and
stores the resources specified in the specified null‐termi­
nated string.  _X_r_m_G_e_t_S_t_r_i_n_g_D_a_t_a_b_a_s_e is similar to _X_r_m_G_e_t_­
_F_i_l_e_D_a_t_a_b_a_s_e except that it reads the information out of a
string instead of out of a file.  The string should contain
a sequence of entries in valid ResourceLine format (see sec­
tion 15.1) terminated by a null character; the database that
results from using a string with incorrect syntax is imple­
mentation‐dependent.  The string is parsed in the current
locale, and the database is created in the current locale.


To obtain the locale name of a database, use _X_r_m_L_o_c_a_l_e_O_f_­
_D_a_t_a_b_a_s_e.
__
││
char *XrmLocaleOfDatabase(_d_a_t_a_b_a_s_e)
      XrmDatabase _d_a_t_a_b_a_s_e;


_d_a_t_a_b_a_s_e  Specifies the resource database.
││__

The _X_r_m_L_o_c_a_l_e_O_f_D_a_t_a_b_a_s_e function returns the name of the



                             555511





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


locale bound to the specified database, as a null‐terminated
string.  The returned locale name string is owned by Xlib
and should not be modified or freed by the client.  Xlib is
not permitted to free the string until the database is
destroyed.  Until the string is freed, it will not be modi­
fied by Xlib.


To destroy a resource database and free its allocated mem­
ory, use _X_r_m_D_e_s_t_r_o_y_D_a_t_a_b_a_s_e.
__
││
void XrmDestroyDatabase(_d_a_t_a_b_a_s_e)
      XrmDatabase _d_a_t_a_b_a_s_e;


_d_a_t_a_b_a_s_e  Specifies the resource database.
││__

If database is NULL, _X_r_m_D_e_s_t_r_o_y_D_a_t_a_b_a_s_e returns immediately.


To associate a resource database with a display, use _X_r_m_S_e_t_­
_D_a_t_a_b_a_s_e.
__
││
void XrmSetDatabase(_d_i_s_p_l_a_y, _d_a_t_a_b_a_s_e)
      Display *_d_i_s_p_l_a_y;
      XrmDatabase _d_a_t_a_b_a_s_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_a_t_a_b_a_s_e  Specifies the resource database.
││__

The _X_r_m_S_e_t_D_a_t_a_b_a_s_e function associates the specified
resource database (or NULL) with the specified display.  The
database previously associated with the display (if any) is
not destroyed.  A client or toolkit may find this function
convenient for retaining a database once it is constructed.


To get the resource database associated with a display, use
_X_r_m_G_e_t_D_a_t_a_b_a_s_e.












                             555522





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XrmDatabase XrmGetDatabase(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

The _X_r_m_G_e_t_D_a_t_a_b_a_s_e function returns the database associated
with the specified display.  It returns NULL if a database
has not yet been set.

1155..55..  MMeerrggiinngg RReessoouurrccee DDaattaabbaasseess

To merge the contents of a resource file into a database,
use _X_r_m_C_o_m_b_i_n_e_F_i_l_e_D_a_t_a_b_a_s_e.
__
││
Status XrmCombineFileDatabase(_f_i_l_e_n_a_m_e, _t_a_r_g_e_t___d_b, _o_v_e_r_r_i_d_e)
      char *_f_i_l_e_n_a_m_e;
      XrmDatabase *_t_a_r_g_e_t___d_b;
      Bool _o_v_e_r_r_i_d_e;


_f_i_l_e_n_a_m_e  Specifies the resource database file name.

_t_a_r_g_e_t___d_b Specifies the resource database into which the
          source database is to be merged.

_o_v_e_r_r_i_d_e  Specifies whether source entries override target
          ones.
││__

The _X_r_m_C_o_m_b_i_n_e_F_i_l_e_D_a_t_a_b_a_s_e function merges the contents of a
resource file into a database.  If the same specifier is
used for an entry in both the file and the database, the
entry in the file will replace the entry in the database if
override is _T_r_u_e; otherwise, the entry in the file is dis­
carded.  The file is parsed in the current locale.  If the
file cannot be read, a zero status is returned; otherwise, a
nonzero status is returned.  If target_db contains NULL,
_X_r_m_C_o_m_b_i_n_e_F_i_l_e_D_a_t_a_b_a_s_e creates and returns a new database to
it.  Otherwise, the database pointed to by target_db is not
destroyed by the merge.  The database entries are merged
without changing values or types, regardless of the locale
of the database.  The locale of the target database is not
modified.


To merge the contents of one database into another database,
use _X_r_m_C_o_m_b_i_n_e_D_a_t_a_b_a_s_e.






                             555533





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XrmCombineDatabase(_s_o_u_r_c_e___d_b, _t_a_r_g_e_t___d_b, _o_v_e_r_r_i_d_e)
      XrmDatabase _s_o_u_r_c_e___d_b, *_t_a_r_g_e_t___d_b;
      Bool _o_v_e_r_r_i_d_e;


_s_o_u_r_c_e___d_b Specifies the resource database that is to be
          merged into the target database.

_t_a_r_g_e_t___d_b Specifies the resource database into which the
          source database is to be merged.

_o_v_e_r_r_i_d_e  Specifies whether source entries override target
          ones.
││__

The _X_r_m_C_o_m_b_i_n_e_D_a_t_a_b_a_s_e function merges the contents of one
database into another.  If the same specifier is used for an
entry in both databases, the entry in the source_db will
replace the entry in the target_db if override is _T_r_u_e; oth­
erwise, the entry in source_db is discarded.  If target_db
contains NULL, _X_r_m_C_o_m_b_i_n_e_D_a_t_a_b_a_s_e simply stores source_db in
it.  Otherwise, source_db is destroyed by the merge, but the
database pointed to by target_db is not destroyed.  The
database entries are merged without changing values or
types, regardless of the locales of the databases.  The
locale of the target database is not modified.


To merge the contents of one database into another database
with override semantics, use _X_r_m_M_e_r_g_e_D_a_t_a_b_a_s_e_s.
__
││
void XrmMergeDatabases(_s_o_u_r_c_e___d_b, _t_a_r_g_e_t___d_b)
      XrmDatabase _s_o_u_r_c_e___d_b, *_t_a_r_g_e_t___d_b;


_s_o_u_r_c_e___d_b Specifies the resource database that is to be
          merged into the target database.

_t_a_r_g_e_t___d_b Specifies the resource database into which the
          source database is to be merged.
││__

Calling the _X_r_m_M_e_r_g_e_D_a_t_a_b_a_s_e_s function is equivalent to
calling the _X_r_m_C_o_m_b_i_n_e_D_a_t_a_b_a_s_e function with an override
argument of _T_r_u_e.

1155..66..  LLooookkiinngg UUpp RReessoouurrcceess

To retrieve a resource from a resource database, use _X_r_m_G_e_­
_t_R_e_s_o_u_r_c_e, _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e, or _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e.





                             555544





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XrmGetResource(_d_a_t_a_b_a_s_e, _s_t_r___n_a_m_e, _s_t_r___c_l_a_s_s, _s_t_r___t_y_p_e___r_e_t_u_r_n, _v_a_l_u_e___r_e_t_u_r_n)
     XrmDatabase _d_a_t_a_b_a_s_e;
     char *_s_t_r___n_a_m_e;
     char *_s_t_r___c_l_a_s_s;
     char **_s_t_r___t_y_p_e___r_e_t_u_r_n;
     XrmValue *_v_a_l_u_e___r_e_t_u_r_n;


_d_a_t_a_b_a_s_e  Specifies the database that is to be used.

_s_t_r___n_a_m_e  Specifies the fully qualified name of the value
          being retrieved (as a string).

_s_t_r___c_l_a_s_s Specifies the fully qualified class of the value
          being retrieved (as a string).

_s_t_r___t_y_p_e___r_e_t_u_r_n
          Returns the representation type of the destination
          (as a string).

_v_a_l_u_e___r_e_t_u_r_n
          Returns the value in the database.
││__

































                             555555





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XrmQGetResource(_d_a_t_a_b_a_s_e, _q_u_a_r_k___n_a_m_e, _q_u_a_r_k___c_l_a_s_s, _q_u_a_r_k___t_y_p_e___r_e_t_u_r_n, _v_a_l_u_e___r_e_t_u_r_n)
     XrmDatabase _d_a_t_a_b_a_s_e;
     XrmNameList _q_u_a_r_k___n_a_m_e;
     XrmClassList _q_u_a_r_k___c_l_a_s_s;
     XrmRepresentation *_q_u_a_r_k___t_y_p_e___r_e_t_u_r_n;
     XrmValue *_v_a_l_u_e___r_e_t_u_r_n;


_d_a_t_a_b_a_s_e  Specifies the database that is to be used.

_q_u_a_r_k___n_a_m_e
          Specifies the fully qualified name of the value
          being retrieved (as a quark).

_q_u_a_r_k___c_l_a_s_s
          Specifies the fully qualified class of the value
          being retrieved (as a quark).

_q_u_a_r_k___t_y_p_e___r_e_t_u_r_n
          Returns the representation type of the destination
          (as a quark).

_v_a_l_u_e___r_e_t_u_r_n
          Returns the value in the database.
││__

The _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e functions retrieve a
resource from the specified database.  Both take a fully
qualified name/class pair, a destination resource represen­
tation, and the address of a value (size/address pair).  The
value and returned type point into database memory; there­
fore, you must not modify the data.

The database only frees or overwrites entries on _X_r_m_P_u_t_R_e_­
_s_o_u_r_c_e, _X_r_m_Q_P_u_t_R_e_s_o_u_r_c_e, or _X_r_m_M_e_r_g_e_D_a_t_a_b_a_s_e_s.  A client
that is not storing new values into the database or is not
merging the database should be safe using the address passed
back at any time until it exits.  If a resource was found,
both _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e return _T_r_u_e; other­
wise, they return _F_a_l_s_e.


Most applications and toolkits do not make random probes
into a resource database to fetch resources.  The X toolkit
access pattern for a resource database is quite stylized.  A
series of from 1 to 20 probes is made with only the last
name/class differing in each probe.  The _X_r_m_G_e_t_R_e_s_o_u_r_c_e
function is at worst a 2_n algorithm, where _n is the length
of the name/class list.  This can be improved upon by the
application programmer by prefetching a list of database
levels that might match the first part of a name/class list.





                             555566





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To obtain a list of database levels, use _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.
__
││
typedef XrmHashTable *XrmSearchList;

Bool XrmQGetSearchList(_d_a_t_a_b_a_s_e, _n_a_m_e_s, _c_l_a_s_s_e_s, _l_i_s_t___r_e_t_u_r_n, _l_i_s_t___l_e_n_g_t_h)
     XrmDatabase _d_a_t_a_b_a_s_e;
     XrmNameList _n_a_m_e_s;
     XrmClassList _c_l_a_s_s_e_s;
     XrmSearchList _l_i_s_t___r_e_t_u_r_n;
     int _l_i_s_t___l_e_n_g_t_h;


_d_a_t_a_b_a_s_e  Specifies the database that is to be used.

_n_a_m_e_s     Specifies a list of resource names.

_c_l_a_s_s_e_s   Specifies a list of resource classes.

_l_i_s_t___r_e_t_u_r_n
          Returns a search list for further use.  The caller
          must allocate sufficient space for the list before
          calling _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.

_l_i_s_t___l_e_n_g_t_h
          Specifies the number of entries (not the byte
          size) allocated for list_return.
││__

The _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t function takes a list of names and
classes and returns a list of database levels where a match
might occur.  The returned list is in best‐to‐worst order
and uses the same algorithm as _X_r_m_G_e_t_R_e_s_o_u_r_c_e for determin­
ing precedence.  If list_return was large enough for the
search list, _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t returns _T_r_u_e; otherwise, it
returns _F_a_l_s_e.

The size of the search list that the caller must allocate is
dependent upon the number of levels and wildcards in the
resource specifiers that are stored in the database.  The
worst case length is 3_n, where _n is the number of name or
class components in names or classes.

When using _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t followed by multiple probes for
resources with a common name and class prefix, only the com­
mon prefix should be specified in the name and class list to
_X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.


To search resource database levels for a given resource, use
_X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e.






                             555577





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XrmQGetSearchResource(_l_i_s_t, _n_a_m_e, _c_l_a_s_s, _t_y_p_e___r_e_t_u_r_n, _v_a_l_u_e___r_e_t_u_r_n)
     XrmSearchList _l_i_s_t;
     XrmName _n_a_m_e;
     XrmClass _c_l_a_s_s;
     XrmRepresentation *_t_y_p_e___r_e_t_u_r_n;
     XrmValue *_v_a_l_u_e___r_e_t_u_r_n;


_l_i_s_t      Specifies the search list returned by _X_r_m_Q_G_e_t_­
          _S_e_a_r_c_h_L_i_s_t.

_n_a_m_e      Specifies the resource name.

_c_l_a_s_s     Specifies the resource class.

_t_y_p_e___r_e_t_u_r_n
          Returns data representation type.

_v_a_l_u_e___r_e_t_u_r_n
          Returns the value in the database.
││__

The _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e function searches the specified
database levels for the resource that is fully identified by
the specified name and class.  The search stops with the
first match.  _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e returns _T_r_u_e if the
resource was found; otherwise, it returns _F_a_l_s_e.

A call to _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t with a name and class list con­
taining all but the last component of a resource name fol­
lowed by a call to _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e with the last com­
ponent name and class returns the same database entry as
_X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e with the fully qualified
name and class.

1155..77..  SSttoorriinngg iinnttoo aa RReessoouurrccee DDaattaabbaassee

To store resources into the database, use _X_r_m_P_u_t_R_e_s_o_u_r_c_e or
_X_r_m_Q_P_u_t_R_e_s_o_u_r_c_e.  Both functions take a partial resource
specification, a representation type, and a value.  This
value is copied into the specified database.















                             555588





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XrmPutResource(_d_a_t_a_b_a_s_e, _s_p_e_c_i_f_i_e_r, _t_y_p_e, _v_a_l_u_e)
     XrmDatabase *_d_a_t_a_b_a_s_e;
     char *_s_p_e_c_i_f_i_e_r;
     char *_t_y_p_e;
     XrmValue *_v_a_l_u_e;


_d_a_t_a_b_a_s_e  Specifies the resource database.

_s_p_e_c_i_f_i_e_r Specifies a complete or partial specification of
          the resource.

_t_y_p_e      Specifies the type of the resource.

_v_a_l_u_e     Specifies the value of the resource, which is
          specified as a string.
││__

If database contains NULL, _X_r_m_P_u_t_R_e_s_o_u_r_c_e creates a new
database and returns a pointer to it.  _X_r_m_P_u_t_R_e_s_o_u_r_c_e is a
convenience function that calls _X_r_m_S_t_r_i_n_g_T_o_B_i_n_d_i_n_g_Q_u_a_r_k_L_i_s_t
followed by:


     XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)

If the specifier and type are not in the Host Portable Char­
acter Encoding, the result is implementation‐dependent.  The
value is stored in the database without modification.



























                             555599





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XrmQPutResource(_d_a_t_a_b_a_s_e, _b_i_n_d_i_n_g_s, _q_u_a_r_k_s, _t_y_p_e, _v_a_l_u_e)
     XrmDatabase *_d_a_t_a_b_a_s_e;
     XrmBindingList _b_i_n_d_i_n_g_s;
     XrmQuarkList _q_u_a_r_k_s;
     XrmRepresentation _t_y_p_e;
     XrmValue *_v_a_l_u_e;


_d_a_t_a_b_a_s_e  Specifies the resource database.

_b_i_n_d_i_n_g_s  Specifies a list of bindings.

_q_u_a_r_k_s    Specifies the complete or partial name or the
          class list of the resource.

_t_y_p_e      Specifies the type of the resource.

_v_a_l_u_e     Specifies the value of the resource, which is
          specified as a string.
││__

If database contains NULL, _X_r_m_Q_P_u_t_R_e_s_o_u_r_c_e creates a new
database and returns a pointer to it.  If a resource entry
with the identical bindings and quarks already exists in the
database, the previous type and value are replaced by the
new specified type and value.  The value is stored in the
database without modification.


To add a resource that is specified as a string, use _X_r_m_P_u_t_­
_S_t_r_i_n_g_R_e_s_o_u_r_c_e.
__
││
void XrmPutStringResource(_d_a_t_a_b_a_s_e, _s_p_e_c_i_f_i_e_r, _v_a_l_u_e)
     XrmDatabase *_d_a_t_a_b_a_s_e;
     char *_s_p_e_c_i_f_i_e_r;
     char *_v_a_l_u_e;


_d_a_t_a_b_a_s_e  Specifies the resource database.

_s_p_e_c_i_f_i_e_r Specifies a complete or partial specification of
          the resource.

_v_a_l_u_e     Specifies the value of the resource, which is
          specified as a string.
││__

If database contains NULL, _X_r_m_P_u_t_S_t_r_i_n_g_R_e_s_o_u_r_c_e creates a
new database and returns a pointer to it.  _X_r_m_P_u_t_S_t_r_i_n_g_R_e_­
_s_o_u_r_c_e adds a resource with the specified value to the spec­
ified database.  _X_r_m_P_u_t_S_t_r_i_n_g_R_e_s_o_u_r_c_e is a convenience func­
tion that first calls _X_r_m_S_t_r_i_n_g_T_o_B_i_n_d_i_n_g_Q_u_a_r_k_L_i_s_t on the



                             556600





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


specifier and then calls _X_r_m_Q_P_u_t_R_e_s_o_u_r_c_e, using a ‘‘String’’
representation type.  If the specifier is not in the Host
Portable Character Encoding, the result is implementation‐
dependent.  The value is stored in the database without mod­
ification.


To add a string resource using quarks as a specification,
use _X_r_m_Q_P_u_t_S_t_r_i_n_g_R_e_s_o_u_r_c_e.
__
││
void XrmQPutStringResource(_d_a_t_a_b_a_s_e, _b_i_n_d_i_n_g_s, _q_u_a_r_k_s, _v_a_l_u_e)
     XrmDatabase *_d_a_t_a_b_a_s_e;
     XrmBindingList _b_i_n_d_i_n_g_s;
     XrmQuarkList _q_u_a_r_k_s;
     char *_v_a_l_u_e;


_d_a_t_a_b_a_s_e  Specifies the resource database.

_b_i_n_d_i_n_g_s  Specifies a list of bindings.

_q_u_a_r_k_s    Specifies the complete or partial name or the
          class list of the resource.

_v_a_l_u_e     Specifies the value of the resource, which is
          specified as a string.
││__

If database contains NULL, _X_r_m_Q_P_u_t_S_t_r_i_n_g_R_e_s_o_u_r_c_e creates a
new database and returns a pointer to it.  _X_r_m_Q_P_u_t_S_t_r_i_n_g_R_e_­
_s_o_u_r_c_e is a convenience routine that constructs an _X_r_m_V_a_l_u_e
for the value string (by calling _s_t_r_l_e_n to compute the size)
and then calls _X_r_m_Q_P_u_t_R_e_s_o_u_r_c_e, using a ‘‘String’’ represen­
tation type.  The value is stored in the database without
modification.


To add a single resource entry that is specified as a string
that contains both a name and a value, use _X_r_m_P_u_t_L_i_n_e_R_e_­
_s_o_u_r_c_e.
















                             556611





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XrmPutLineResource(_d_a_t_a_b_a_s_e, _l_i_n_e)
     XrmDatabase *_d_a_t_a_b_a_s_e;
     char *_l_i_n_e;


_d_a_t_a_b_a_s_e  Specifies the resource database.

_l_i_n_e      Specifies the resource name and value pair as a
          single string.
││__

If database contains NULL, _X_r_m_P_u_t_L_i_n_e_R_e_s_o_u_r_c_e creates a new
database and returns a pointer to it.  _X_r_m_P_u_t_L_i_n_e_R_e_s_o_u_r_c_e
adds a single resource entry to the specified database.  The
line should be in valid ResourceLine format (see section
15.1) terminated by a newline or null character; the
database that results from using a string with incorrect
syntax is implementation‐dependent.  The string is parsed in
the locale of the database.  If the _R_e_s_o_u_r_c_e_N_a_m_e is not in
the Host Portable Character Encoding, the result is imple­
mentation‐dependent.  Note that comment lines are not
stored.

1155..88..  EEnnuummeerraattiinngg DDaattaabbaassee EEnnttrriieess

To enumerate the entries of a database, use _X_r_m_E_n_u_m_e_r_a_t_e_­
_D_a_t_a_b_a_s_e.





























                             556622





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
#define   _X_r_m_E_n_u_m_A_l_l_L_e_v_e_l_s       0
#define   _X_r_m_E_n_u_m_O_n_e_L_e_v_e_l        1


Bool XrmEnumerateDatabase(_d_a_t_a_b_a_s_e, _n_a_m_e___p_r_e_f_i_x, _c_l_a_s_s___p_r_e_f_i_x, _m_o_d_e, _p_r_o_c, _a_r_g)
      XrmDatabase _d_a_t_a_b_a_s_e;
      XrmNameList _n_a_m_e___p_r_e_f_i_x;
      XrmClassList _c_l_a_s_s___p_r_e_f_i_x;
      int _m_o_d_e;
      Bool (*_p_r_o_c)();
      XPointer _a_r_g;


_d_a_t_a_b_a_s_e  Specifies the resource database.

_n_a_m_e___p_r_e_f_i_x
          Specifies the resource name prefix.

_c_l_a_s_s___p_r_e_f_i_x
          Specifies the resource class prefix.

_m_o_d_e      Specifies the number of levels to enumerate.

_p_r_o_c      Specifies the procedure that is to be called for
          each matching entry.

_a_r_g       Specifies the user‐supplied argument that will be
          passed to the procedure.
││__

The _X_r_m_E_n_u_m_e_r_a_t_e_D_a_t_a_b_a_s_e function calls the specified proce­
dure for each resource in the database that would match some
completion of the given name/class resource prefix.  The
order in which resources are found is implementation‐depen­
dent.  If mode is _X_r_m_E_n_u_m_O_n_e_L_e_v_e_l, a resource must match the
given name/class prefix with just a single name and class
appended.  If mode is _X_r_m_E_n_u_m_A_l_l_L_e_v_e_l_s, the resource must
match the given name/class prefix with one or more names and
classes appended.  If the procedure returns _T_r_u_e, the enu­
meration terminates and the function returns _T_r_u_e.  If the
procedure always returns _F_a_l_s_e, all matching resources are
enumerated and the function returns _F_a_l_s_e.

The procedure is called with the following arguments:


(*_p_r_o_c)(_d_a_t_a_b_a_s_e, _b_i_n_d_i_n_g_s, _q_u_a_r_k_s, _t_y_p_e, _v_a_l_u_e, _a_r_g)
     XrmDatabase *_d_a_t_a_b_a_s_e;
     XrmBindingList _b_i_n_d_i_n_g_s;
     XrmQuarkList _q_u_a_r_k_s;
     XrmRepresentation *_t_y_p_e;
     XrmValue *_v_a_l_u_e;
     XPointer _a_r_g;



                             556633





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The bindings and quarks lists are terminated by _N_U_L_L_Q_U_A_R_K.
Note that pointers to the database and type are passed, but
these values should not be modified.

The procedure must not modify the database.  If Xlib has
been initialized for threads, the procedure is called with
the database locked and the result of a call by the proce­
dure to any Xlib function using the same database is not
defined.

1155..99..  PPaarrssiinngg CCoommmmaanndd LLiinnee OOppttiioonnss

The _X_r_m_P_a_r_s_e_C_o_m_m_a_n_d function can be used to parse the com­
mand line arguments to a program and modify a resource
database with selected entries from the command line.

__
││
typedef enum {
     XrmoptionNoArg,     /* Value is specified in XrmOptionDescRec.value */
     XrmoptionIsArg,     /* Value is the option string itself */
     XrmoptionStickyArg, /* Value is characters immediately following option */
     XrmoptionSepArg,    /* Value is next argument in argv */
     XrmoptionResArg,    /* Resource and value in next argument in argv */
     XrmoptionSkipArg,   /* Ignore this option and the next argument in argv */
     XrmoptionSkipLine,  /* Ignore this option and the rest of argv */
     XrmoptionSkipNArgs  /* Ignore this option and the next
                            XrmOptionDescRec.value arguments in argv */
} XrmOptionKind;

││__

Note that _X_r_m_o_p_t_i_o_n_S_k_i_p_A_r_g is equivalent to _X_r_m_o_p_t_i_o_n_S_k_i_p_­
_N_A_r_g_s with the _X_r_m_O_p_t_i_o_n_D_e_s_c_R_e_c_._v_a_l_u_e field containing the
value one.  Note also that the value zero for _X_r_m_o_p_t_i_o_n_S_k_i_p_­
_N_A_r_g_s indicates that only the option itself is to be
skipped.

__
││
typedef struct {
     char *option;       /* Option specification string in argv    */
     char *specifier;    /* Binding and resource name (sans application name)    */
     XrmOptionKind argKind;/* Which style of option it is    */
     XPointer value;     /* Value to provide if XrmoptionNoArg or
                            XrmoptionSkipNArgs   */
} XrmOptionDescRec, *XrmOptionDescList;

││__


To load a resource database from a C command line, use _X_r_m_­
_P_a_r_s_e_C_o_m_m_a_n_d.




                             556644





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XrmParseCommand(_d_a_t_a_b_a_s_e, _t_a_b_l_e, _t_a_b_l_e___c_o_u_n_t, _n_a_m_e, _a_r_g_c___i_n___o_u_t, _a_r_g_v___i_n___o_u_t)
      XrmDatabase *_d_a_t_a_b_a_s_e;
      XrmOptionDescList _t_a_b_l_e;
      int _t_a_b_l_e___c_o_u_n_t;
      char *_n_a_m_e;
      int *_a_r_g_c___i_n___o_u_t;
      char **_a_r_g_v___i_n___o_u_t;


_d_a_t_a_b_a_s_e  Specifies the resource database.

_t_a_b_l_e     Specifies the table of command line arguments to
          be parsed.

_t_a_b_l_e___c_o_u_n_t
          Specifies the number of entries in the table.

_n_a_m_e      Specifies the application name.

_a_r_g_c___i_n___o_u_t
          Specifies the number of arguments and returns the
          number of remaining arguments.

_a_r_g_v___i_n___o_u_t
          Specifies the command line arguments and returns
          the remaining arguments.
││__

The _X_r_m_P_a_r_s_e_C_o_m_m_a_n_d function parses an (argc, argv) pair
according to the specified option table, loads recognized
options into the specified database with type ‘‘String,’’
and modifies the (argc, argv) pair to remove all recognized
options.  If database contains NULL, _X_r_m_P_a_r_s_e_C_o_m_m_a_n_d creates
a new database and returns a pointer to it.  Otherwise,
entries are added to the database specified.  If a database
is created, it is created in the current locale.

The specified table is used to parse the command line.  Rec­
ognized options in the table are removed from argv, and
entries are added to the specified resource database in the
order they occur in argv.  The table entries contain infor­
mation on the option string, the option name, the style of
option, and a value to provide if the option kind is _X_r_m_o_p_­
_t_i_o_n_N_o_A_r_g.  The option names are compared byte‐for‐byte to
arguments in argv, independent of any locale.  The resource
values given in the table are stored in the resource
database without modification.  All resource database
entries are created using a ‘‘String’’ representation type.
The argc argument specifies the number of arguments in argv
and is set on return to the remaining number of arguments
that were not parsed.  The name argument should be the name
of your application for use in building the database entry.
The name argument is prefixed to the resourceName in the



                             556655





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


option table before storing a database entry.  The name
argument is treated as a single component, even if it has
embedded periods.  No separating (binding) character is
inserted, so the table must contain either a period (.) or
an asterisk (*) as the first character in each resourceName
entry.  To specify a more completely qualified resource
name, the resourceName entry can contain multiple compo­
nents.  If the name argument and the resourceNames are not
in the Host Portable Character Encoding, the result is
implementation‐dependent.

The following provides a sample option table:


static XrmOptionDescRec opTable[] = {
{"−background",                 "*background", XrmoptionSepArg,(XPointer) NULL},
{"−bd",     "*borderColor",     XrmoptionSepArg,(XPointer) NULL},
{"−bg",     "*background",      XrmoptionSepArg,(XPointer) NULL},
{"−borderwidth",                "*TopLevelShell.borderWidth",XrmoptionSepArg,(XPointer) NULL},
{"−bordercolor",                "*borderColor",XrmoptionSepArg,(XPointer) NULL},
{"−bw",     "*TopLevelShell.borderWidth",      XrmoptionSepArg,(XPointer) NULL},
{"−display",                    ".display",    XrmoptionSepArg,(XPointer) NULL},
{"−fg",     "*foreground",      XrmoptionSepArg,(XPointer) NULL},
{"−fn",     "*font",            XrmoptionSepArg,(XPointer) NULL},
{"−font",   "*font",            XrmoptionSepArg,(XPointer) NULL},
{"−foreground",                 "*foreground", XrmoptionSepArg,(XPointer) NULL},
{"−geometry",                   ".TopLevelShell.geometry",XrmoptionSepArg,(XPointer) NULL},
{"−iconic", ".TopLevelShell.iconic",           XrmoptionNoArg,(XPointer) "on"},
{"−name",   ".name",            XrmoptionSepArg,(XPointer) NULL},
{"−reverse",                    "*reverseVideo",XrmoptionNoArg,(XPointer) "on"},
{"−rv",     "*reverseVideo",    XrmoptionNoArg,(XPointer) "on"},
{"−synchronous",                "*synchronous",XrmoptionNoArg,(XPointer) "on"},
{"−title",  ".TopLevelShell.title",            XrmoptionSepArg,(XPointer) NULL},
{"−xrm",    NULL,               XrmoptionResArg,(XPointer) NULL},
};


In this table, if the −background (or −bg) option is used to
set background colors, the stored resource specifier matches
all resources of attribute background.  If the −borderwidth
option is used, the stored resource specifier applies only
to border width attributes of class TopLevelShell (that is,
outer‐most windows, including pop‐up windows).  If the
−title option is used to set a window name, only the topmost
application windows receive the resource.

When parsing the command line, any unique unambiguous abbre­
viation for an option name in the table is considered a
match for the option.  Note that uppercase and lowercase
matter.







                             556666





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         CChhaapptteerr 1166

               AApppplliiccaattiioonn UUttiilliittyy FFuunnccttiioonnss



Once you have initialized the X system, you can use the Xlib
utility functions to:

⋅    Use keyboard utility functions

⋅    Use Latin‐1 keyboard event functions

⋅    Allocate permanent storage

⋅    Parse the window geometry

⋅    Manipulate regions

⋅    Use cut buffers

⋅    Determine the appropriate visual type

⋅    Manipulate images

⋅    Manipulate bitmaps

⋅    Use the context manager

As a group, the functions discussed in this chapter provide
the functionality that is frequently needed and that spans
toolkits.  Many of these functions do not generate actual
protocol requests to the server.

1166..11..  UUssiinngg KKeeyybbooaarrdd UUttiilliittyy FFuunnccttiioonnss

This section discusses mapping between KeyCodes and KeySyms,
classifying KeySyms, and mapping between KeySyms and string
names.  The first three functions in this section operate on
a cached copy of the server keyboard mapping.  The first
four KeySyms for each KeyCode are modified according to the
rules given in section 12.7.  To obtain the untransformed
KeySyms defined for a key, use the functions described in
section 12.7.


To obtain a KeySym for the KeyCode of an event, use _X_L_o_o_k_u_p_­
_K_e_y_s_y_m.







                             556677





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
KeySym XLookupKeysym(_k_e_y___e_v_e_n_t, _i_n_d_e_x)
      XKeyEvent *_k_e_y___e_v_e_n_t;
      int _i_n_d_e_x;


_k_e_y___e_v_e_n_t Specifies the _K_e_y_P_r_e_s_s or _K_e_y_R_e_l_e_a_s_e event.

_i_n_d_e_x     Specifies the index into the KeySyms list for the
          event’s KeyCode.
││__

The _X_L_o_o_k_u_p_K_e_y_s_y_m function uses a given keyboard event and
the index you specified to return the KeySym from the list
that corresponds to the KeyCode member in the _X_K_e_y_P_r_e_s_s_e_d_E_­
_v_e_n_t or _X_K_e_y_R_e_l_e_a_s_e_d_E_v_e_n_t structure.  If no KeySym is
defined for the KeyCode of the event, _X_L_o_o_k_u_p_K_e_y_s_y_m returns
_N_o_S_y_m_b_o_l.


To obtain a KeySym for a specific KeyCode, use _X_K_e_y_­
_c_o_d_e_T_o_K_e_y_s_y_m.
__
││
KeySym XKeycodeToKeysym(_d_i_s_p_l_a_y, _k_e_y_c_o_d_e, _i_n_d_e_x)
      Display *_d_i_s_p_l_a_y;
      KeyCode _k_e_y_c_o_d_e;
      int _i_n_d_e_x;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_k_e_y_c_o_d_e   Specifies the KeyCode.

_i_n_d_e_x     Specifies the element of KeyCode vector.
││__

The _X_K_e_y_c_o_d_e_T_o_K_e_y_s_y_m function uses internal Xlib tables and
returns the KeySym defined for the specified KeyCode and the
element of the KeyCode vector.  If no symbol is defined,
_X_K_e_y_c_o_d_e_T_o_K_e_y_s_y_m returns _N_o_S_y_m_b_o_l.


To obtain a KeyCode for a key having a specific KeySym, use
_X_K_e_y_s_y_m_T_o_K_e_y_c_o_d_e.












                             556688





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
KeyCode XKeysymToKeycode(_d_i_s_p_l_a_y, _k_e_y_s_y_m)
      Display *_d_i_s_p_l_a_y;
      KeySym _k_e_y_s_y_m;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_k_e_y_s_y_m    Specifies the KeySym that is to be searched for.
││__

If the specified KeySym is not defined for any KeyCode,
_X_K_e_y_s_y_m_T_o_K_e_y_c_o_d_e returns zero.


The mapping between KeyCodes and KeySyms is cached internal
to Xlib.  When this information is changed at the server, an
Xlib function must be called to refresh the cache.  To
refresh the stored modifier and keymap information, use _X_R_e_­
_f_r_e_s_h_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g.
__
││
XRefreshKeyboardMapping(_e_v_e_n_t___m_a_p)
      XMappingEvent *_e_v_e_n_t___m_a_p;


_e_v_e_n_t___m_a_p Specifies the mapping event that is to be used.
││__

The _X_R_e_f_r_e_s_h_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g function refreshes the stored
modifier and keymap information.  You usually call this
function when a _M_a_p_p_i_n_g_N_o_t_i_f_y event with a request member of
_M_a_p_p_i_n_g_K_e_y_b_o_a_r_d or _M_a_p_p_i_n_g_M_o_d_i_f_i_e_r occurs.  The result is to
update Xlib’s knowledge of the keyboard.


To obtain the uppercase and lowercase forms of a KeySym, use
_X_C_o_n_v_e_r_t_C_a_s_e.



















                             556699





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
void XConvertCase(_k_e_y_s_y_m, _l_o_w_e_r___r_e_t_u_r_n, _u_p_p_e_r___r_e_t_u_r_n)
      KeySym _k_e_y_s_y_m;
      KeySym *_l_o_w_e_r___r_e_t_u_r_n;
      KeySym *_u_p_p_e_r___r_e_t_u_r_n;


_k_e_y_s_y_m    Specifies the KeySym that is to be converted.

_l_o_w_e_r___r_e_t_u_r_n
          Returns the lowercase form of keysym, or keysym.

_u_p_p_e_r___r_e_t_u_r_n
          Returns the uppercase form of keysym, or keysym.
││__

The _X_C_o_n_v_e_r_t_C_a_s_e function returns the uppercase and lower­
case forms of the specified Keysym, if the KeySym is subject
to case conversion; otherwise, the specified KeySym is
returned to both lower_return and upper_return.  Support for
conversion of other than Latin and Cyrillic KeySyms is
implementation‐dependent.


KeySyms have string names as well as numeric codes.  To con­
vert the name of the KeySym to the KeySym code, use _X_S_t_r_i_n_g_­
_T_o_K_e_y_s_y_m.
__
││
KeySym XStringToKeysym(_s_t_r_i_n_g)
      char *_s_t_r_i_n_g;


_s_t_r_i_n_g    Specifies the name of the KeySym that is to be
          converted.
││__

Standard KeySym names are obtained from <_X_1_1_/_k_e_y_s_y_m_d_e_f_._h> by
removing the XK_ prefix from each name.  KeySyms that are
not part of the Xlib standard also may be obtained with this
function.  The set of KeySyms that are available in this
manner and the mechanisms by which Xlib obtains them is
implementation‐dependent.

If the KeySym name is not in the Host Portable Character
Encoding, the result is implementation‐dependent.  If the
specified string does not match a valid KeySym, _X_S_t_r_i_n_g_­
_T_o_K_e_y_s_y_m returns _N_o_S_y_m_b_o_l.


To convert a KeySym code to the name of the KeySym, use
_X_K_e_y_s_y_m_T_o_S_t_r_i_n_g.





                             557700





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char *XKeysymToString(_k_e_y_s_y_m)
      KeySym _k_e_y_s_y_m;


_k_e_y_s_y_m    Specifies the KeySym that is to be converted.
││__

The returned string is in a static area and must not be mod­
ified.  The returned string is in the Host Portable Charac­
ter Encoding.  If the specified KeySym is not defined,
_X_K_e_y_s_y_m_T_o_S_t_r_i_n_g returns a NULL.

1166..11..11..  KKeeyySSyymm CCllaassssiiffiiccaattiioonn MMaaccrrooss

You may want to test if a KeySym is, for example, on the
keypad or on one of the function keys.  You can use KeySym
macros to perform the following tests.


__
││
IsCursorKey(_k_e_y_s_y_m)


_k_e_y_s_y_m    Specifies the KeySym that is to be tested.
││__

Returns _T_r_u_e if the specified KeySym is a cursor key.


__
││
IsFunctionKey(_k_e_y_s_y_m)


_k_e_y_s_y_m    Specifies the KeySym that is to be tested.
││__

Returns _T_r_u_e if the specified KeySym is a function key.


__
││
IsKeypadKey(_k_e_y_s_y_m)


_k_e_y_s_y_m    Specifies the KeySym that is to be tested.
││__

Returns _T_r_u_e if the specified KeySym is a standard keypad
key.





                             557711





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
IsPrivateKeypadKey(_k_e_y_s_y_m)


_k_e_y_s_y_m    Specifies the KeySym that is to be tested.
││__

Returns _T_r_u_e if the specified KeySym is a vendor‐private
keypad key.


__
││
IsMiscFunctionKey(_k_e_y_s_y_m)


_k_e_y_s_y_m    Specifies the KeySym that is to be tested.
││__

Returns _T_r_u_e if the specified KeySym is a miscellaneous
function key.


__
││
IsModifierKey(_k_e_y_s_y_m)


_k_e_y_s_y_m    Specifies the KeySym that is to be tested.
││__

Returns _T_r_u_e if the specified KeySym is a modifier key.


__
││
IsPFKey(_k_e_y_s_y_m)


_k_e_y_s_y_m    Specifies the KeySym that is to be tested.
││__

Returns _T_r_u_e if the specified KeySym is a PF key.

1166..22..  UUssiinngg LLaattiinn‐‐11 KKeeyybbooaarrdd EEvveenntt FFuunnccttiioonnss

Chapter 13 describes internationalized text input facili­
ties, but sometimes it is expedient to write an application
that only deals with Latin‐1 characters and ASCII controls,
so Xlib provides a simple function for that purpose.
_X_L_o_o_k_u_p_S_t_r_i_n_g handles the standard modifier semantics
described in section 12.7.  This function does not use any
of the input method facilities described in chapter 13 and
does not depend on the current locale.



                             557722





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To map a key event to an ISO Latin‐1 string, use _X_L_o_o_k_u_p_­
_S_t_r_i_n_g.
__
││
int XLookupString(_e_v_e_n_t___s_t_r_u_c_t, _b_u_f_f_e_r___r_e_t_u_r_n, _b_y_t_e_s___b_u_f_f_e_r, _k_e_y_s_y_m___r_e_t_u_r_n, _s_t_a_t_u_s___i_n___o_u_t)
      XKeyEvent *_e_v_e_n_t___s_t_r_u_c_t;
      char *_b_u_f_f_e_r___r_e_t_u_r_n;
      int _b_y_t_e_s___b_u_f_f_e_r;
      KeySym *_k_e_y_s_y_m___r_e_t_u_r_n;
      XComposeStatus *_s_t_a_t_u_s___i_n___o_u_t;


_e_v_e_n_t___s_t_r_u_c_t
          Specifies the key event structure to be used.  You
          can pass _X_K_e_y_P_r_e_s_s_e_d_E_v_e_n_t or _X_K_e_y_R_e_l_e_a_s_e_d_E_v_e_n_t.

_b_u_f_f_e_r___r_e_t_u_r_n
          Returns the translated characters.

_b_y_t_e_s___b_u_f_f_e_r
          Specifies the length of the buffer.  No more than
          bytes_buffer of translation are returned.

_k_e_y_s_y_m___r_e_t_u_r_n
          Returns the KeySym computed from the event if this
          argument is not NULL.

_s_t_a_t_u_s___i_n___o_u_t
          Specifies or returns the _X_C_o_m_p_o_s_e_S_t_a_t_u_s structure
          or NULL.
││__

The _X_L_o_o_k_u_p_S_t_r_i_n_g function translates a key event to a
KeySym and a string.  The KeySym is obtained by using the
standard interpretation of the _S_h_i_f_t, _L_o_c_k, group, and num­
lock modifiers as defined in the X Protocol specification.
If the KeySym has been rebound (see _X_R_e_b_i_n_d_K_e_y_s_y_m), the
bound string will be stored in the buffer.  Otherwise, the
KeySym is mapped, if possible, to an ISO Latin‐1 character
or (if the Control modifier is on) to an ASCII control char­
acter, and that character is stored in the buffer.  _X_L_o_o_k_u_p_­
_S_t_r_i_n_g returns the number of characters that are stored in
the buffer.

If present (non‐NULL), the _X_C_o_m_p_o_s_e_S_t_a_t_u_s structure records
the state, which is private to Xlib, that needs preservation
across calls to _X_L_o_o_k_u_p_S_t_r_i_n_g to implement compose process­
ing.  The creation of _X_C_o_m_p_o_s_e_S_t_a_t_u_s structures is implemen­
tation‐dependent; a portable program must pass NULL for this
argument.

_X_L_o_o_k_u_p_S_t_r_i_n_g depends on the cached keyboard information
mentioned in the previous section, so it is necessary to use
_X_R_e_f_r_e_s_h_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g to keep this information up‐to‐date.



                             557733





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To rebind the meaning of a KeySym for _X_L_o_o_k_u_p_S_t_r_i_n_g, use
_X_R_e_b_i_n_d_K_e_y_s_y_m.
__
││
XRebindKeysym(_d_i_s_p_l_a_y, _k_e_y_s_y_m, _l_i_s_t, _m_o_d___c_o_u_n_t, _s_t_r_i_n_g, _n_u_m___b_y_t_e_s)
      Display *_d_i_s_p_l_a_y;
      KeySym _k_e_y_s_y_m;
      KeySym _l_i_s_t[];
      int _m_o_d___c_o_u_n_t;
      unsigned char *_s_t_r_i_n_g;
      int _n_u_m___b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_k_e_y_s_y_m    Specifies the KeySym that is to be rebound.

_l_i_s_t      Specifies the KeySyms to be used as modifiers.

_m_o_d___c_o_u_n_t Specifies the number of modifiers in the modifier
          list.

_s_t_r_i_n_g    Specifies the string that is copied and will be
          returned by _X_L_o_o_k_u_p_S_t_r_i_n_g.

_n_u_m___b_y_t_e_s Specifies the number of bytes in the string argu­
          ment.
││__

The _X_R_e_b_i_n_d_K_e_y_s_y_m function can be used to rebind the meaning
of a KeySym for the client.  It does not redefine any key in
the X server but merely provides an easy way for long
strings to be attached to keys.  _X_L_o_o_k_u_p_S_t_r_i_n_g returns this
string when the appropriate set of modifier keys are pressed
and when the KeySym would have been used for the transla­
tion.  No text conversions are performed; the client is
responsible for supplying appropriately encoded strings.
Note that you can rebind a KeySym that may not exist.

1166..33..  AAllllooccaattiinngg PPeerrmmaanneenntt SSttoorraaggee

To allocate some memory you will never give back, use
_X_p_e_r_m_a_l_l_o_c.
__
││
char *Xpermalloc(_s_i_z_e)
     unsigned int _s_i_z_e;

││__

The _X_p_e_r_m_a_l_l_o_c function allocates storage that can never be
freed for the life of the program.  The memory is allocated
with alignment for the C type double.  This function may
provide some performance and space savings over the standard



                             557744





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


operating system memory allocator.

1166..44..  PPaarrssiinngg tthhee WWiinnddooww GGeeoommeettrryy

To parse standard window geometry strings, use _X_P_a_r_s_e_G_e_o_m_e_­
_t_r_y.

__
││
int XParseGeometry(_p_a_r_s_e_s_t_r_i_n_g, _x___r_e_t_u_r_n, _y___r_e_t_u_r_n, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n)
      char *_p_a_r_s_e_s_t_r_i_n_g;
      int *_x___r_e_t_u_r_n, *_y___r_e_t_u_r_n;
      unsigned int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;


_p_a_r_s_e_s_t_r_i_n_g
          Specifies the string you want to parse.

_x___r_e_t_u_r_n
_y___r_e_t_u_r_n  Return the x and y offsets.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the width and height determined.
││__

By convention, X applications use a standard string to indi­
cate window size and placement.  _X_P_a_r_s_e_G_e_o_m_e_t_r_y makes it
easier to conform to this standard because it allows you to
parse the standard window geometry.  Specifically, this
function lets you parse strings of the form:


     [=][<_w_i_d_t_h>{xX}<_h_e_i_g_h_t>][{+‐}<_x_o_f_f_s_e_t>{+‐}<_y_o_f_f_s_e_t>]


The fields map into the arguments associated with this func­
tion.  (Items enclosed in <> are integers, items in [] are
optional, and items enclosed in {} indicate ‘‘choose one
of.’’  Note that the brackets should not appear in the
actual string.)  If the string is not in the Host Portable
Character Encoding, the result is implementation‐dependent.

The _X_P_a_r_s_e_G_e_o_m_e_t_r_y function returns a bitmask that indicates
which of the four values (width, height, xoffset, and yoff­
set) were actually found in the string and whether the x and
y values are negative.  By convention, −0 is not equal to
+0, because the user needs to be able to say ‘‘position the
window relative to the right or bottom edge.’’  For each
value found, the corresponding argument is updated.  For
each value not found, the argument is left unchanged.  The
bits are represented by _X_V_a_l_u_e, _Y_V_a_l_u_e, _W_i_d_t_h_V_a_l_u_e, _H_e_i_g_h_t_­
_V_a_l_u_e, _X_N_e_g_a_t_i_v_e, or _Y_N_e_g_a_t_i_v_e and are defined in
<_X_1_1_/_X_u_t_i_l_._h>.  They will be set whenever one of the values



                             557755





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


is defined or one of the signs is set.

If the function returns either the _X_V_a_l_u_e or _Y_V_a_l_u_e flag,
you should place the window at the requested position.


To construct a window’s geometry information, use _X_W_M_G_e_o_m_e_­
_t_r_y.
__
││
int XWMGeometry(_d_i_s_p_l_a_y, _s_c_r_e_e_n, _u_s_e_r___g_e_o_m, _d_e_f___g_e_o_m, _b_w_i_d_t_h, _h_i_n_t_s, _x___r_e_t_u_r_n, _y___r_e_t_u_r_n,
                _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n, _g_r_a_v_i_t_y___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n;
      char *_u_s_e_r___g_e_o_m;
      char *_d_e_f___g_e_o_m;
      unsigned int _b_w_i_d_t_h;
      XSizeHints *_h_i_n_t_s;
      int *_x___r_e_t_u_r_n, *_y___r_e_t_u_r_n;
      int *_w_i_d_t_h___r_e_t_u_r_n;
      int *_h_e_i_g_h_t___r_e_t_u_r_n;
      int *_g_r_a_v_i_t_y___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n    Specifies the screen.

_u_s_e_r___g_e_o_m Specifies the user‐specified geometry or NULL.

_d_e_f___g_e_o_m  Specifies the application’s default geometry or
          NULL.

_b_w_i_d_t_h    Specifies the border width.

_h_i_n_t_s     Specifies the size hints for the window in its
          normal state.

_x___r_e_t_u_r_n
_y___r_e_t_u_r_n  Return the x and y offsets.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the width and height determined.

_g_r_a_v_i_t_y___r_e_t_u_r_n
          Returns the window gravity.
││__

The _X_W_M_G_e_o_m_e_t_r_y function combines any geometry information
(given in the format used by _X_P_a_r_s_e_G_e_o_m_e_t_r_y) specified by
the user and by the calling program with size hints (usually
the ones to be stored in WM_NORMAL_HINTS) and returns the
position, size, and gravity (_N_o_r_t_h_W_e_s_t_G_r_a_v_i_t_y,



                             557766





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_N_o_r_t_h_E_a_s_t_G_r_a_v_i_t_y, _S_o_u_t_h_E_a_s_t_G_r_a_v_i_t_y, or _S_o_u_t_h_W_e_s_t_G_r_a_v_i_t_y)
that describe the window.  If the base size is not set in
the _X_S_i_z_e_H_i_n_t_s structure, the minimum size is used if set.
Otherwise, a base size of zero is assumed.  If no minimum
size is set in the hints structure, the base size is used.
A mask (in the form returned by _X_P_a_r_s_e_G_e_o_m_e_t_r_y) that
describes which values came from the user specification and
whether or not the position coordinates are relative to the
right and bottom edges is returned.  Note that these coordi­
nates will have already been accounted for in the x_return
and y_return values.

Note that invalid geometry specifications can cause a width
or height of zero to be returned.  The caller may pass the
address of the hints win_gravity field as gravity_return to
update the hints directly.

1166..55..  MMaanniippuullaattiinngg RReeggiioonnss

Regions are arbitrary sets of pixel locations.  Xlib pro­
vides functions for manipulating regions.  The opaque type
_R_e_g_i_o_n is defined in <_X_1_1_/_X_u_t_i_l_._h>.  Xlib provides functions
that you can use to manipulate regions.  This section dis­
cusses how to:

⋅    Create, copy, or destroy regions

⋅    Move or shrink regions

⋅    Compute with regions

⋅    Determine if regions are empty or equal

⋅    Locate a point or rectangle in a region

1166..55..11..  CCrreeaattiinngg,, CCooppyyiinngg,, oorr DDeessttrrooyyiinngg RReeggiioonnss

To create a new empty region, use _X_C_r_e_a_t_e_R_e_g_i_o_n.
__
││
Region XCreateRegion()

││__


To generate a region from a polygon, use _X_P_o_l_y_g_o_n_R_e_g_i_o_n.











                             557777





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Region XPolygonRegion(_p_o_i_n_t_s, _n, _f_i_l_l___r_u_l_e)
      XPoint _p_o_i_n_t_s_[_];
      int _n;
      int _f_i_l_l___r_u_l_e;


_p_o_i_n_t_s    Specifies an array of points.

_n         Specifies the number of points in the polygon.

_f_i_l_l___r_u_l_e Specifies the fill‐rule you want to set for the
          specified GC.  You can pass _E_v_e_n_O_d_d_R_u_l_e or _W_i_n_d_i_n_­
          _g_R_u_l_e.
││__

The _X_P_o_l_y_g_o_n_R_e_g_i_o_n function returns a region for the polygon
defined by the points array.  For an explanation of
fill_rule, see _X_C_r_e_a_t_e_G_C.


To set the clip‐mask of a GC to a region, use _X_S_e_t_R_e_g_i_o_n.
__
││
XSetRegion(_d_i_s_p_l_a_y, _g_c, _r)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;
      Region _r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.

_r         Specifies the region.
││__

The _X_S_e_t_R_e_g_i_o_n function sets the clip‐mask in the GC to the
specified region.  The region is specified relative to the
drawable’s origin.  The resulting GC clip origin is imple­
mentation‐dependent.  Once it is set in the GC, the region
can be destroyed.


To deallocate the storage associated with a specified
region, use _X_D_e_s_t_r_o_y_R_e_g_i_o_n.











                             557788





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDestroyRegion(_r)
      Region _r;


_r         Specifies the region.
││__


1166..55..22..  MMoovviinngg oorr SShhrriinnkkiinngg RReeggiioonnss

To move a region by a specified amount, use _X_O_f_f_s_e_t_R_e_g_i_o_n.
__
││
XOffsetRegion(_r, _d_x, _d_y)
      Region _r;
      int _d_x, _d_y;


_r         Specifies the region.

_d_x
_d_y        Specify the x and y coordinates, which define the
          amount you want to move the specified region.
││__


To reduce a region by a specified amount, use _X_S_h_r_i_n_k_R_e_g_i_o_n.
__
││
XShrinkRegion(_r, _d_x, _d_y)
      Region _r;
      int _d_x, _d_y;


_r         Specifies the region.

_d_x
_d_y        Specify the x and y coordinates, which define the
          amount you want to shrink the specified region.
││__

Positive values shrink the size of the region, and negative
values expand the region.

1166..55..33..  CCoommppuuttiinngg wwiitthh RReeggiioonnss


To generate the smallest rectangle enclosing a region, use
_X_C_l_i_p_B_o_x.







                             557799





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XClipBox(_r, _r_e_c_t___r_e_t_u_r_n)
      Region _r;
      XRectangle *_r_e_c_t___r_e_t_u_r_n;


_r         Specifies the region.

_r_e_c_t___r_e_t_u_r_n
          Returns the smallest enclosing rectangle.
││__

The _X_C_l_i_p_B_o_x function returns the smallest rectangle enclos­
ing the specified region.


To compute the intersection of two regions, use _X_I_n_t_e_r_s_e_c_­
_t_R_e_g_i_o_n.
__
││
XIntersectRegion(_s_r_a, _s_r_b, _d_r___r_e_t_u_r_n)
      Region _s_r_a, _s_r_b, _d_r___r_e_t_u_r_n;


_s_r_a
_s_r_b       Specify the two regions with which you want to
          perform the computation.

_d_r___r_e_t_u_r_n Returns the result of the computation.
││__


To compute the union of two regions, use _X_U_n_i_o_n_R_e_g_i_o_n.
__
││
XUnionRegion(_s_r_a, _s_r_b, _d_r___r_e_t_u_r_n)
      Region _s_r_a, _s_r_b, _d_r___r_e_t_u_r_n;


_s_r_a
_s_r_b       Specify the two regions with which you want to
          perform the computation.

_d_r___r_e_t_u_r_n Returns the result of the computation.
││__


To create a union of a source region and a rectangle, use
_X_U_n_i_o_n_R_e_c_t_W_i_t_h_R_e_g_i_o_n.








                             558800





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XUnionRectWithRegion(_r_e_c_t_a_n_g_l_e, _s_r_c___r_e_g_i_o_n, _d_e_s_t___r_e_g_i_o_n___r_e_t_u_r_n)
     XRectangle *_r_e_c_t_a_n_g_l_e;
     Region _s_r_c___r_e_g_i_o_n;
     Region _d_e_s_t___r_e_g_i_o_n___r_e_t_u_r_n;


_r_e_c_t_a_n_g_l_e Specifies the rectangle.

_s_r_c___r_e_g_i_o_n
          Specifies the source region to be used.

_d_e_s_t___r_e_g_i_o_n___r_e_t_u_r_n
          Returns the destination region.
││__

The _X_U_n_i_o_n_R_e_c_t_W_i_t_h_R_e_g_i_o_n function updates the destination
region from a union of the specified rectangle and the spec­
ified source region.


To subtract two regions, use _X_S_u_b_t_r_a_c_t_R_e_g_i_o_n.
__
││
XSubtractRegion(_s_r_a, _s_r_b, _d_r___r_e_t_u_r_n)
      Region _s_r_a, _s_r_b, _d_r___r_e_t_u_r_n;


_s_r_a
_s_r_b       Specify the two regions with which you want to
          perform the computation.

_d_r___r_e_t_u_r_n Returns the result of the computation.
││__

The _X_S_u_b_t_r_a_c_t_R_e_g_i_o_n function subtracts srb from sra and
stores the results in dr_return.


To calculate the difference between the union and intersec­
tion of two regions, use _X_X_o_r_R_e_g_i_o_n.
















                             558811





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XXorRegion(_s_r_a, _s_r_b, _d_r___r_e_t_u_r_n)
      Region _s_r_a, _s_r_b, _d_r___r_e_t_u_r_n;


_s_r_a
_s_r_b       Specify the two regions with which you want to
          perform the computation.

_d_r___r_e_t_u_r_n Returns the result of the computation.
││__


1166..55..44..  DDeetteerrmmiinniinngg iiff RReeggiioonnss AArree EEmmppttyy oorr EEqquuaall

To determine if the specified region is empty, use _X_E_m_p_t_y_R_e_­
_g_i_o_n.
__
││
Bool XEmptyRegion(_r)
      Region _r;


_r         Specifies the region.
││__

The _X_E_m_p_t_y_R_e_g_i_o_n function returns _T_r_u_e if the region is
empty.


To determine if two regions have the same offset, size, and
shape, use _X_E_q_u_a_l_R_e_g_i_o_n.
__
││
Bool XEqualRegion(_r_1, _r_2)
      Region _r_1, _r_2;


_r_1
_r_2        Specify the two regions.
││__

The _X_E_q_u_a_l_R_e_g_i_o_n function returns _T_r_u_e if the two regions
have the same offset, size, and shape.

1166..55..55..  LLooccaattiinngg aa PPooiinntt oorr aa RReeccttaannggllee iinn aa RReeggiioonn

To determine if a specified point resides in a specified
region, use _X_P_o_i_n_t_I_n_R_e_g_i_o_n.








                             558822





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XPointInRegion(_r, _x, _y)
      Region _r;
      int _x, _y;


_r         Specifies the region.

_x
_y         Specify the x and y coordinates, which define the
          point.
││__

The _X_P_o_i_n_t_I_n_R_e_g_i_o_n function returns _T_r_u_e if the point (x, y)
is contained in the region r.


To determine if a specified rectangle is inside a region,
use _X_R_e_c_t_I_n_R_e_g_i_o_n.
__
││
int XRectInRegion(_r, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t)
      Region _r;
      int _x, _y;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;


_r         Specifies the region.

_x
_y         Specify the x and y coordinates, which define the
          coordinates of the upper‐left corner of the rect­
          angle.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height, which define the
          rectangle.
││__

The _X_R_e_c_t_I_n_R_e_g_i_o_n function returns _R_e_c_t_a_n_g_l_e_I_n if the rect­
angle is entirely in the specified region, _R_e_c_t_a_n_g_l_e_O_u_t if
the rectangle is entirely out of the specified region, and
_R_e_c_t_a_n_g_l_e_P_a_r_t if the rectangle is partially in the specified
region.

1166..66..  UUssiinngg CCuutt BBuuffffeerrss

Xlib provides functions to manipulate cut buffers, a very
simple form of cut‐and‐paste inter‐client communication.
Selections are a much more powerful and useful mechanism for
interchanging data between clients (see section 4.5) and
generally should be used instead of cut buffers.





                             558833





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Cut buffers are implemented as properties on the first root
window of the display.  The buffers can only contain text,
in the STRING encoding.  The text encoding is not changed by
Xlib when fetching or storing.  Eight buffers are provided
and can be accessed as a ring or as explicit buffers (num­
bered 0 through 7).


To store data in cut buffer 0, use _X_S_t_o_r_e_B_y_t_e_s.
__
││
XStoreBytes(_d_i_s_p_l_a_y, _b_y_t_e_s, _n_b_y_t_e_s)
      Display *_d_i_s_p_l_a_y;
      char *_b_y_t_e_s;
      int _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_b_y_t_e_s     Specifies the bytes, which are not necessarily
          ASCII or null‐terminated.

_n_b_y_t_e_s    Specifies the number of bytes to be stored.
││__

The data can have embedded null characters and need not be
null‐terminated.  The cut buffer’s contents can be retrieved
later by any client calling _X_F_e_t_c_h_B_y_t_e_s.

_X_S_t_o_r_e_B_y_t_e_s can generate a _B_a_d_A_l_l_o_c error.


To store data in a specified cut buffer, use _X_S_t_o_r_e_B_u_f_f_e_r.
__
││
XStoreBuffer(_d_i_s_p_l_a_y, _b_y_t_e_s, _n_b_y_t_e_s, _b_u_f_f_e_r)
      Display *_d_i_s_p_l_a_y;
      char *_b_y_t_e_s;
      int _n_b_y_t_e_s;
      int _b_u_f_f_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_b_y_t_e_s     Specifies the bytes, which are not necessarily
          ASCII or null‐terminated.

_n_b_y_t_e_s    Specifies the number of bytes to be stored.

_b_u_f_f_e_r    Specifies the buffer in which you want to store
          the bytes.
││__

If an invalid buffer is specified, the call has no effect.



                             558844





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The data can have embedded null characters and need not be
null‐terminated.

_X_S_t_o_r_e_B_u_f_f_e_r can generate a _B_a_d_A_l_l_o_c error.


To return data from cut buffer 0, use _X_F_e_t_c_h_B_y_t_e_s.
__
││
char *XFetchBytes(_d_i_s_p_l_a_y, _n_b_y_t_e_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int *_n_b_y_t_e_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_b_y_t_e_s___r_e_t_u_r_n
          Returns the number of bytes in the buffer.
││__

The _X_F_e_t_c_h_B_y_t_e_s function returns the number of bytes in the
nbytes_return argument, if the buffer contains data.  Other­
wise, the function returns NULL and sets nbytes to 0.  The
appropriate amount of storage is allocated and the pointer
returned.  The client must free this storage when finished
with it by calling _X_F_r_e_e.


To return data from a specified cut buffer, use _X_F_e_t_c_h_­
_B_u_f_f_e_r.
__
││
char *XFetchBuffer(_d_i_s_p_l_a_y, _n_b_y_t_e_s___r_e_t_u_r_n, _b_u_f_f_e_r)
      Display *_d_i_s_p_l_a_y;
      int *_n_b_y_t_e_s___r_e_t_u_r_n;
      int _b_u_f_f_e_r;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_b_y_t_e_s___r_e_t_u_r_n
          Returns the number of bytes in the buffer.

_b_u_f_f_e_r    Specifies the buffer from which you want the
          stored data returned.
││__

The _X_F_e_t_c_h_B_u_f_f_e_r function returns zero to the nbytes_return
argument if there is no data in the buffer or if an invalid
buffer is specified.


To rotate the cut buffers, use _X_R_o_t_a_t_e_B_u_f_f_e_r_s.




                             558855





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XRotateBuffers(_d_i_s_p_l_a_y, _r_o_t_a_t_e)
      Display *_d_i_s_p_l_a_y;
      int _r_o_t_a_t_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_r_o_t_a_t_e    Specifies how much to rotate the cut buffers.
││__

The _X_R_o_t_a_t_e_B_u_f_f_e_r_s function rotates the cut buffers, such
that buffer 0 becomes buffer n, buffer 1 becomes n + 1 mod
8, and so on.  This cut buffer numbering is global to the
display.  Note that _X_R_o_t_a_t_e_B_u_f_f_e_r_s generates _B_a_d_M_a_t_c_h errors
if any of the eight buffers have not been created.

1166..77..  DDeetteerrmmiinniinngg tthhee AApppprroopprriiaattee VViissuuaall TTyyppee

A single display can support multiple screens.  Each screen
can have several different visual types supported at differ­
ent depths.  You can use the functions described in this
section to determine which visual to use for your applica­
tion.

The functions in this section use the visual information
masks and the _X_V_i_s_u_a_l_I_n_f_o structure, which is defined in
<_X_1_1_/_X_u_t_i_l_._h> and contains:





























                             558866





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
/* Visual information mask bits */

#define   _V_i_s_u_a_l_N_o_M_a_s_k                0x0
#define   _V_i_s_u_a_l_I_D_M_a_s_k                0x1
#define   _V_i_s_u_a_l_S_c_r_e_e_n_M_a_s_k            0x2
#define   _V_i_s_u_a_l_D_e_p_t_h_M_a_s_k             0x4
#define   _V_i_s_u_a_l_C_l_a_s_s_M_a_s_k             0x8
#define   _V_i_s_u_a_l_R_e_d_M_a_s_k_M_a_s_k           0x10
#define   _V_i_s_u_a_l_G_r_e_e_n_M_a_s_k_M_a_s_k         0x20
#define   _V_i_s_u_a_l_B_l_u_e_M_a_s_k_M_a_s_k          0x40
#define   _V_i_s_u_a_l_C_o_l_o_r_m_a_p_S_i_z_e_M_a_s_k      0x80
#define   _V_i_s_u_a_l_B_i_t_s_P_e_r_R_G_B_M_a_s_k        0x100
#define   _V_i_s_u_a_l_A_l_l_M_a_s_k               0x1FF


/* Values */

typedef struct {
     Visual *visual;
     VisualID visualid;
     int screen;
     unsigned int depth;
     int class;
     unsigned long red_mask;
     unsigned long green_mask;
     unsigned long blue_mask;
     int colormap_size;
     int bits_per_rgb;
} XVisualInfo;

││__

To obtain a list of visual information structures that match
a specified template, use _X_G_e_t_V_i_s_u_a_l_I_n_f_o.






















                             558877





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XVisualInfo *XGetVisualInfo(_d_i_s_p_l_a_y, _v_i_n_f_o___m_a_s_k, _v_i_n_f_o___t_e_m_p_l_a_t_e, _n_i_t_e_m_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      long _v_i_n_f_o___m_a_s_k;
      XVisualInfo *_v_i_n_f_o___t_e_m_p_l_a_t_e;
      int *_n_i_t_e_m_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_v_i_n_f_o___m_a_s_k
          Specifies the visual mask value.

_v_i_n_f_o___t_e_m_p_l_a_t_e
          Specifies the visual attributes that are to be
          used in matching the visual structures.

_n_i_t_e_m_s___r_e_t_u_r_n
          Returns the number of matching visual structures.
││__

The _X_G_e_t_V_i_s_u_a_l_I_n_f_o function returns a list of visual struc­
tures that have attributes equal to the attributes specified
by vinfo_template.  If no visual structures match the tem­
plate using the specified vinfo_mask, _X_G_e_t_V_i_s_u_a_l_I_n_f_o returns
a NULL.  To free the data returned by this function, use
_X_F_r_e_e.


To obtain the visual information that matches the specified
depth and class of the screen, use _X_M_a_t_c_h_V_i_s_u_a_l_I_n_f_o.
__
││
Status XMatchVisualInfo(_d_i_s_p_l_a_y, _s_c_r_e_e_n, _d_e_p_t_h, _c_l_a_s_s, _v_i_n_f_o___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n;
      int _d_e_p_t_h;
      int _c_l_a_s_s;
      XVisualInfo *_v_i_n_f_o___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n    Specifies the screen.

_d_e_p_t_h     Specifies the depth of the screen.

_c_l_a_s_s     Specifies the class of the screen.

_v_i_n_f_o___r_e_t_u_r_n
          Returns the matched visual information.
││__

The _X_M_a_t_c_h_V_i_s_u_a_l_I_n_f_o function returns the visual information



                             558888





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


for a visual that matches the specified depth and class for
a screen.  Because multiple visuals that match the specified
depth and class can exist, the exact visual chosen is unde­
fined.  If a visual is found, _X_M_a_t_c_h_V_i_s_u_a_l_I_n_f_o returns
nonzero and the information on the visual to vinfo_return.
Otherwise, when a visual is not found, _X_M_a_t_c_h_V_i_s_u_a_l_I_n_f_o
returns zero.

1166..88..  MMaanniippuullaattiinngg IImmaaggeess

Xlib provides several functions that perform basic opera­
tions on images.  All operations on images are defined using
an _X_I_m_a_g_e structure, as defined in <_X_1_1_/_X_l_i_b_._h>.  Because
the number of different types of image formats can be very
large, this hides details of image storage properly from
applications.

This section describes the functions for generic operations
on images.  Manufacturers can provide very fast implementa­
tions of these for the formats frequently encountered on
their hardware.  These functions are neither sufficient nor
desirable to use for general image processing.  Rather, they
are here to provide minimal functions on screen format
images.  The basic operations for getting and putting images
are _X_G_e_t_I_m_a_g_e and _X_P_u_t_I_m_a_g_e.

Note that no functions have been defined, as yet, to read
and write images to and from disk files.

The _X_I_m_a_g_e structure describes an image as it exists in the
client’s memory.  The user can request that some of the mem­
bers such as height, width, and xoffset be changed when the
image is sent to the server.  Note that bytes_per_line in
concert with offset can be used to extract a subset of the
image.  Other members (for example, byte order, bitmap_unit,
and so forth) are characteristics of both the image and the
server.  If these members differ between the image and the
server, _X_P_u_t_I_m_a_g_e makes the appropriate conversions.  The
first byte of the first line of plane n must be located at
the address (data + (n * height * bytes_per_line)).  For a
description of the _X_I_m_a_g_e structure, see section 8.7.


To allocate an _X_I_m_a_g_e structure and initialize it with image
format values from a display, use _X_C_r_e_a_t_e_I_m_a_g_e.












                             558899





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XImage *XCreateImage(_d_i_s_p_l_a_y, _v_i_s_u_a_l, _d_e_p_t_h, _f_o_r_m_a_t, _o_f_f_s_e_t, _d_a_t_a, _w_i_d_t_h, _h_e_i_g_h_t, _b_i_t_m_a_p___p_a_d,
                        _b_y_t_e_s___p_e_r___l_i_n_e)
      Display *_d_i_s_p_l_a_y;
      Visual *_v_i_s_u_a_l;
      unsigned int _d_e_p_t_h;
      int _f_o_r_m_a_t;
      int _o_f_f_s_e_t;
      char *_d_a_t_a;
      unsigned int _w_i_d_t_h;
      unsigned int _h_e_i_g_h_t;
      int _b_i_t_m_a_p___p_a_d;
      int _b_y_t_e_s___p_e_r___l_i_n_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_v_i_s_u_a_l    Specifies the _V_i_s_u_a_l structure.

_d_e_p_t_h     Specifies the depth of the image.

_f_o_r_m_a_t    Specifies the format for the image.  You can pass
          _X_Y_B_i_t_m_a_p, _X_Y_P_i_x_m_a_p, or _Z_P_i_x_m_a_p.

_o_f_f_s_e_t    Specifies the number of pixels to ignore at the
          beginning of the scanline.

_d_a_t_a      Specifies the image data.

_w_i_d_t_h     Specifies the width of the image, in pixels.

_h_e_i_g_h_t    Specifies the height of the image, in pixels.

_b_i_t_m_a_p___p_a_d
          Specifies the quantum of a scanline (8, 16, or
          32).  In other words, the start of one scanline is
          separated in client memory from the start of the
          next scanline by an integer multiple of this many
          bits.

_b_y_t_e_s___p_e_r___l_i_n_e
          Specifies the number of bytes in the client image
          between the start of one scanline and the start of
          the next.
││__

The _X_C_r_e_a_t_e_I_m_a_g_e function allocates the memory needed for an
_X_I_m_a_g_e structure for the specified display but does not
allocate space for the image itself.  Rather, it initializes
the structure byte‐order, bit‐order, and bitmap‐unit values
from the display and returns a pointer to the _X_I_m_a_g_e struc­
ture.  The red, green, and blue mask values are defined for
Z format images only and are derived from the _V_i_s_u_a_l struc­
ture passed in.  Other values also are passed in.  The



                             559900





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


offset permits the rapid displaying of the image without
requiring each scanline to be shifted into position.  If you
pass a zero value in bytes_per_line, Xlib assumes that the
scanlines are contiguous in memory and calculates the value
of bytes_per_line itself.

Note that when the image is created using _X_C_r_e_a_t_e_I_m_a_g_e, _X_G_e_­
_t_I_m_a_g_e, or _X_S_u_b_I_m_a_g_e, the destroy procedure that the _X_D_e_­
_s_t_r_o_y_I_m_a_g_e function calls frees both the image structure and
the data pointed to by the image structure.

The basic functions used to get a pixel, set a pixel, create
a subimage, and add a constant value to an image are defined
in the image object.  The functions in this section are
really macro invocations of the functions in the image
object and are defined in <_X_1_1_/_X_u_t_i_l_._h>.


To obtain a pixel value in an image, use _X_G_e_t_P_i_x_e_l.
__
││
unsigned long XGetPixel(_x_i_m_a_g_e, _x, _y)
      XImage *_x_i_m_a_g_e;
      int _x;
      int _y;


_x_i_m_a_g_e    Specifies the image.

_x
_y         Specify the x and y coordinates.
││__

The _X_G_e_t_P_i_x_e_l function returns the specified pixel from the
named image.  The pixel value is returned in normalized for­
mat (that is, the least significant byte of the long is the
least significant byte of the pixel).  The image must con­
tain the x and y coordinates.


To set a pixel value in an image, use _X_P_u_t_P_i_x_e_l.
















                             559911





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XPutPixel(_x_i_m_a_g_e, _x, _y, _p_i_x_e_l)
      XImage *_x_i_m_a_g_e;
      int _x;
      int _y;
      unsigned long _p_i_x_e_l;


_x_i_m_a_g_e    Specifies the image.

_x
_y         Specify the x and y coordinates.

_p_i_x_e_l     Specifies the new pixel value.
││__

The _X_P_u_t_P_i_x_e_l function overwrites the pixel in the named
image with the specified pixel value.  The input pixel value
must be in normalized format (that is, the least significant
byte of the long is the least significant byte of the
pixel).  The image must contain the x and y coordinates.


To create a subimage, use _X_S_u_b_I_m_a_g_e.
__
││
XImage *XSubImage(_x_i_m_a_g_e, _x, _y, _s_u_b_i_m_a_g_e___w_i_d_t_h, _s_u_b_i_m_a_g_e___h_e_i_g_h_t)
      XImage *_x_i_m_a_g_e;
      int _x;
      int _y;
      unsigned int _s_u_b_i_m_a_g_e___w_i_d_t_h;
      unsigned int _s_u_b_i_m_a_g_e___h_e_i_g_h_t;


_x_i_m_a_g_e    Specifies the image.

_x
_y         Specify the x and y coordinates.

_s_u_b_i_m_a_g_e___w_i_d_t_h
          Specifies the width of the new subimage, in pix­
          els.

_s_u_b_i_m_a_g_e___h_e_i_g_h_t
          Specifies the height of the new subimage, in pix­
          els.
││__

The _X_S_u_b_I_m_a_g_e function creates a new image that is a subsec­
tion of an existing one.  It allocates the memory necessary
for the new _X_I_m_a_g_e structure and returns a pointer to the
new image.  The data is copied from the source image, and
the image must contain the rectangle defined by x, y, subim­
age_width, and subimage_height.



                             559922





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


To increment each pixel in an image by a constant value, use
_X_A_d_d_P_i_x_e_l.
__
││
XAddPixel(_x_i_m_a_g_e, _v_a_l_u_e)
      XImage *_x_i_m_a_g_e;
      long _v_a_l_u_e;


_x_i_m_a_g_e    Specifies the image.

_v_a_l_u_e     Specifies the constant value that is to be added.
││__

The _X_A_d_d_P_i_x_e_l function adds a constant value to every pixel
in an image.  It is useful when you have a base pixel value
from allocating color resources and need to manipulate the
image to that form.


To deallocate the memory allocated in a previous call to
_X_C_r_e_a_t_e_I_m_a_g_e, use _X_D_e_s_t_r_o_y_I_m_a_g_e.
__
││
XDestroyImage(_x_i_m_a_g_e)
        XImage *_x_i_m_a_g_e;


_x_i_m_a_g_e    Specifies the image.
││__

The _X_D_e_s_t_r_o_y_I_m_a_g_e function deallocates the memory associated
with the _X_I_m_a_g_e structure.

Note that when the image is created using _X_C_r_e_a_t_e_I_m_a_g_e, _X_G_e_­
_t_I_m_a_g_e, or _X_S_u_b_I_m_a_g_e, the destroy procedure that this macro
calls frees both the image structure and the data pointed to
by the image structure.

1166..99..  MMaanniippuullaattiinngg BBiittmmaappss

Xlib provides functions that you can use to read a bitmap
from a file, save a bitmap to a file, or create a bitmap.
This section describes those functions that transfer bitmaps
to and from the client’s file system, thus allowing their
reuse in a later connection (for example, from an entirely
different client or to a different display or server).

The X version 11 bitmap file format is:








                             559933





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
#define _n_a_m_e_width _w_i_d_t_h
#define _n_a_m_e_height _h_e_i_g_h_t
#define _n_a_m_e_x_hot _x
#define _n_a_m_e_y_hot _y
static unsigned char _n_a_m_e_bits[] = { 0x_N_N,... }

││__

The lines for the variables ending with _x_hot and _y_hot
suffixes are optional because they are present only if a
hotspot has been defined for this bitmap.  The lines for the
other variables are required.  The word ‘‘unsigned’’ is
optional; that is, the type of the _bits array can be
‘‘char’’ or ‘‘unsigned char’’.  The _bits array must be
large enough to contain the size bitmap.  The bitmap unit is
8.


To read a bitmap from a file and store it in a pixmap, use
_X_R_e_a_d_B_i_t_m_a_p_F_i_l_e.
__
││
int XReadBitmapFile(_d_i_s_p_l_a_y, _d, _f_i_l_e_n_a_m_e, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n, _b_i_t_m_a_p___r_e_t_u_r_n, _x___h_o_t___r_e_t_u_r_n,
                       _y___h_o_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      char *_f_i_l_e_n_a_m_e;
      unsigned int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;
      Pixmap *_b_i_t_m_a_p___r_e_t_u_r_n;
      int *_x___h_o_t___r_e_t_u_r_n, *_y___h_o_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable that indicates the screen.

_f_i_l_e_n_a_m_e  Specifies the file name to use.  The format of the
          file name is operating‐system dependent.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the width and height values of the read in
          bitmap file.

_b_i_t_m_a_p___r_e_t_u_r_n
          Returns the bitmap that is created.

_x___h_o_t___r_e_t_u_r_n
_y___h_o_t___r_e_t_u_r_n
          Return the hotspot coordinates.
││__

The _X_R_e_a_d_B_i_t_m_a_p_F_i_l_e function reads in a file containing a



                             559944





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


bitmap.  The file is parsed in the encoding of the current
locale.  The ability to read other than the standard format
is implementation‐dependent.  If the file cannot be opened,
_X_R_e_a_d_B_i_t_m_a_p_F_i_l_e returns _B_i_t_m_a_p_O_p_e_n_F_a_i_l_e_d.  If the file can
be opened but does not contain valid bitmap data, it returns
_B_i_t_m_a_p_F_i_l_e_I_n_v_a_l_i_d.  If insufficient working storage is allo­
cated, it returns _B_i_t_m_a_p_N_o_M_e_m_o_r_y.  If the file is readable
and valid, it returns _B_i_t_m_a_p_S_u_c_c_e_s_s.

_X_R_e_a_d_B_i_t_m_a_p_F_i_l_e returns the bitmap’s height and width, as
read from the file, to width_return and height_return.  It
then creates a pixmap of the appropriate size, reads the
bitmap data from the file into the pixmap, and assigns the
pixmap to the caller’s variable bitmap.  The caller must
free the bitmap using _X_F_r_e_e_P_i_x_m_a_p when finished.  If
_n_a_m_e_x_hot and _n_a_m_e_y_hot exist, _X_R_e_a_d_B_i_t_m_a_p_F_i_l_e returns
them to x_hot_return and y_hot_return; otherwise, it returns
−1,−1.

_X_R_e_a_d_B_i_t_m_a_p_F_i_l_e can generate _B_a_d_A_l_l_o_c, _B_a_d_D_r_a_w_a_b_l_e, and
_B_a_d_G_C errors.


To read a bitmap from a file and return it as data, use
_X_R_e_a_d_B_i_t_m_a_p_F_i_l_e_D_a_t_a.
__
││
int XReadBitmapFileData(_f_i_l_e_n_a_m_e, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n, _d_a_t_a___r_e_t_u_r_n, _x___h_o_t___r_e_t_u_r_n, _y___h_o_t___r_e_t_u_r_n)
      char *_f_i_l_e_n_a_m_e;
      unsigned int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;
      unsigned char *_d_a_t_a___r_e_t_u_r_n;
      int *_x___h_o_t___r_e_t_u_r_n, *_y___h_o_t___r_e_t_u_r_n;


_f_i_l_e_n_a_m_e  Specifies the file name to use.  The format of the
          file name is operating‐system dependent.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the width and height values of the read in
          bitmap file.

_d_a_t_a___r_e_t_u_r_n
          Returns the bitmap data.

_x___h_o_t___r_e_t_u_r_n
_y___h_o_t___r_e_t_u_r_n
          Return the hotspot coordinates.
││__

The _X_R_e_a_d_B_i_t_m_a_p_F_i_l_e_D_a_t_a function reads in a file containing
a bitmap, in the same manner as _X_R_e_a_d_B_i_t_m_a_p_F_i_l_e, but returns
the data directly rather than creating a pixmap in the
server.  The bitmap data is returned in data_return; the



                             559955





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


client must free this storage when finished with it by call­
ing _X_F_r_e_e.  The status and other return values are the same
as for _X_R_e_a_d_B_i_t_m_a_p_F_i_l_e.


To write out a bitmap from a pixmap to a file, use
_X_W_r_i_t_e_B_i_t_m_a_p_F_i_l_e.
__
││
int XWriteBitmapFile(_d_i_s_p_l_a_y, _f_i_l_e_n_a_m_e, _b_i_t_m_a_p, _w_i_d_t_h, _h_e_i_g_h_t, _x___h_o_t, _y___h_o_t)
      Display *_d_i_s_p_l_a_y;
      char *_f_i_l_e_n_a_m_e;
      Pixmap _b_i_t_m_a_p;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
      int _x___h_o_t, _y___h_o_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_f_i_l_e_n_a_m_e  Specifies the file name to use.  The format of the
          file name is operating‐system dependent.

_b_i_t_m_a_p    Specifies the bitmap.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height.

_x___h_o_t
_y___h_o_t     Specify where to place the hotspot coordinates (or
          −1,−1 if none are present) in the file.
││__

The _X_W_r_i_t_e_B_i_t_m_a_p_F_i_l_e function writes a bitmap out to a file
in the X Version 11 format.  The name used in the output
file is derived from the file name by deleting the directory
prefix.  The file is written in the encoding of the current
locale.  If the file cannot be opened for writing, it
returns _B_i_t_m_a_p_O_p_e_n_F_a_i_l_e_d.  If insufficient memory is allo­
cated, _X_W_r_i_t_e_B_i_t_m_a_p_F_i_l_e returns _B_i_t_m_a_p_N_o_M_e_m_o_r_y; otherwise,
on no error, it returns _B_i_t_m_a_p_S_u_c_c_e_s_s.  If x_hot and y_hot
are not −1, −1, _X_W_r_i_t_e_B_i_t_m_a_p_F_i_l_e writes them out as the
hotspot coordinates for the bitmap.

_X_W_r_i_t_e_B_i_t_m_a_p_F_i_l_e can generate _B_a_d_D_r_a_w_a_b_l_e and _B_a_d_M_a_t_c_h
errors.


To create a pixmap and then store bitmap‐format data into
it, use _X_C_r_e_a_t_e_P_i_x_m_a_p_F_r_o_m_B_i_t_m_a_p_D_a_t_a.








                             559966





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Pixmap XCreatePixmapFromBitmapData(_d_i_s_p_l_a_y, _d, _d_a_t_a, _w_i_d_t_h, _h_e_i_g_h_t, _f_g, _b_g, _d_e_p_t_h)
     Display *_d_i_s_p_l_a_y;
     Drawable _d;
     char *_d_a_t_a;
     unsigned int _w_i_d_t_h, _h_e_i_g_h_t;
     unsigned long _f_g, _b_g;
     unsigned int _d_e_p_t_h;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable that indicates the screen.

_d_a_t_a      Specifies the data in bitmap format.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height.

_f_g
_b_g        Specify the foreground and background pixel values
          to use.

_d_e_p_t_h     Specifies the depth of the pixmap.
││__

The _X_C_r_e_a_t_e_P_i_x_m_a_p_F_r_o_m_B_i_t_m_a_p_D_a_t_a function creates a pixmap of
the given depth and then does a bitmap‐format _X_P_u_t_I_m_a_g_e of
the data into it.  The depth must be supported by the screen
of the specified drawable, or a _B_a_d_M_a_t_c_h error results.

_X_C_r_e_a_t_e_P_i_x_m_a_p_F_r_o_m_B_i_t_m_a_p_D_a_t_a can generate _B_a_d_A_l_l_o_c, _B_a_d_D_r_a_w_­
_a_b_l_e, _B_a_d_G_C, and _B_a_d_V_a_l_u_e errors.


To include a bitmap written out by _X_W_r_i_t_e_B_i_t_m_a_p_F_i_l_e in a
program directly, as opposed to reading it in every time at
run time, use _X_C_r_e_a_t_e_B_i_t_m_a_p_F_r_o_m_D_a_t_a.



















                             559977





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Pixmap XCreateBitmapFromData(_d_i_s_p_l_a_y, _d, _d_a_t_a, _w_i_d_t_h, _h_e_i_g_h_t)
      Display *_d_i_s_p_l_a_y;
      Drawable _d;
      char *_d_a_t_a;
      unsigned int _w_i_d_t_h, _h_e_i_g_h_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable that indicates the screen.

_d_a_t_a      Specifies the location of the bitmap data.

_w_i_d_t_h
_h_e_i_g_h_t    Specify the width and height.
││__

The _X_C_r_e_a_t_e_B_i_t_m_a_p_F_r_o_m_D_a_t_a function allows you to include in
your C program (using _#_i_n_c_l_u_d_e) a bitmap file that was writ­
ten out by _X_W_r_i_t_e_B_i_t_m_a_p_F_i_l_e (X version 11 format only) with­
out reading in the bitmap file.  The following example cre­
ates a gray bitmap:


#include "gray.bitmap"
Pixmap bitmap;
bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);


If insufficient working storage was allocated, _X_C_r_e_­
_a_t_e_B_i_t_m_a_p_F_r_o_m_D_a_t_a returns _N_o_n_e.  It is your responsibility
to free the bitmap using _X_F_r_e_e_P_i_x_m_a_p when finished.

_X_C_r_e_a_t_e_B_i_t_m_a_p_F_r_o_m_D_a_t_a can generate _B_a_d_A_l_l_o_c and _B_a_d_G_C
errors.

1166..1100..  UUssiinngg tthhee CCoonntteexxtt MMaannaaggeerr

The context manager provides a way of associating data with
an X resource ID (mostly typically a window) in your pro­
gram.  Note that this is local to your program; the data is
not stored in the server on a property list.  Any amount of
data in any number of pieces can be associated with a
resource ID, and each piece of data has a type associated
with it.  The context manager requires knowledge of the
resource ID and type to store or retrieve data.

Essentially, the context manager can be viewed as a two‐
dimensional, sparse array:  one dimension is subscripted by
the X resource ID and the other by a context type field.
Each entry in the array contains a pointer to the data.
Xlib provides context management functions with which you
can save data values, get data values, delete entries, and



                             559988





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


create a unique context type.  The symbols used are in
<_X_1_1_/_X_u_t_i_l_._h>.


To save a data value that corresponds to a resource ID and
context type, use _X_S_a_v_e_C_o_n_t_e_x_t.
__
││
int XSaveContext(_d_i_s_p_l_a_y, _r_i_d, _c_o_n_t_e_x_t, _d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      XID _r_i_d;
      XContext _c_o_n_t_e_x_t;
      XPointer _d_a_t_a;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_r_i_d       Specifies the resource ID with which the data is
          associated.

_c_o_n_t_e_x_t   Specifies the context type to which the data
          belongs.

_d_a_t_a      Specifies the data to be associated with the win­
          dow and type.
││__

If an entry with the specified resource ID and type already
exists, _X_S_a_v_e_C_o_n_t_e_x_t overrides it with the specified con­
text.  The _X_S_a_v_e_C_o_n_t_e_x_t function returns a nonzero error
code if an error has occurred and zero otherwise.  Possible
errors are _X_C_N_O_M_E_M (out of memory).


To get the data associated with a resource ID and type, use
_X_F_i_n_d_C_o_n_t_e_x_t.





















                             559999





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XFindContext(_d_i_s_p_l_a_y, _r_i_d, _c_o_n_t_e_x_t, _d_a_t_a___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      XID _r_i_d;
      XContext _c_o_n_t_e_x_t;
      XPointer *_d_a_t_a___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_r_i_d       Specifies the resource ID with which the data is
          associated.

_c_o_n_t_e_x_t   Specifies the context type to which the data
          belongs.

_d_a_t_a___r_e_t_u_r_n
          Returns the data.
││__

Because it is a return value, the data is a pointer.  The
_X_F_i_n_d_C_o_n_t_e_x_t function returns a nonzero error code if an
error has occurred and zero otherwise.  Possible errors are
_X_C_N_O_E_N_T (context‐not‐found).


To delete an entry for a given resource ID and type, use
_X_D_e_l_e_t_e_C_o_n_t_e_x_t.
__
││
int XDeleteContext(_d_i_s_p_l_a_y, _r_i_d, _c_o_n_t_e_x_t)
      Display *_d_i_s_p_l_a_y;
      XID _r_i_d;
      XContext _c_o_n_t_e_x_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_r_i_d       Specifies the resource ID with which the data is
          associated.

_c_o_n_t_e_x_t   Specifies the context type to which the data
          belongs.
││__

The _X_D_e_l_e_t_e_C_o_n_t_e_x_t function deletes the entry for the given
resource ID and type from the data structure.  This function
returns the same error codes that _X_F_i_n_d_C_o_n_t_e_x_t returns if
called with the same arguments.  _X_D_e_l_e_t_e_C_o_n_t_e_x_t does not
free the data whose address was saved.


To create a unique context type that may be used in subse­
quent calls to _X_S_a_v_e_C_o_n_t_e_x_t and _X_F_i_n_d_C_o_n_t_e_x_t, use



                             660000





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_U_n_i_q_u_e_C_o_n_t_e_x_t.
__
││
XContext XUniqueContext()

││__



















































                             660011





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         AAppppeennddiixx AA

            XXlliibb FFuunnccttiioonnss aanndd PPrroottooccooll RReeqquueessttss



This appendix provides two tables that relate to Xlib func­
tions and the X protocol.  The following table lists each
Xlib function (in alphabetical order) and the corresponding
protocol request that it generates.


-------------------------------------------------------
XXlliibb FFuunnccttiioonn                PPrroottooccooll RReeqquueesstt
-------------------------------------------------------
XActivateScreenSaver         ForceScreenSaver
XAddHost                     ChangeHosts
XAddHosts                    ChangeHosts
XAddToSaveSet                ChangeSaveSet
XAllocColor                  AllocColor
XAllocColorCells             AllocColorCells
XAllocColorPlanes            AllocColorPlanes
XAllocNamedColor             AllocNamedColor
XAllowEvents                 AllowEvents
XAutoRepeatOff               ChangeKeyboardControl
XAutoRepeatOn                ChangeKeyboardControl
XBell                        Bell
XChangeActivePointerGrab     ChangeActivePointerGrab
XChangeGC                    ChangeGC
XChangeKeyboardControl       ChangeKeyboardControl
XChangeKeyboardMapping       ChangeKeyboardMapping
XChangePointerControl        ChangePointerControl
XChangeProperty              ChangeProperty
XChangeSaveSet               ChangeSaveSet
XChangeWindowAttributes      ChangeWindowAttributes
XCirculateSubwindows         CirculateWindow
XCirculateSubwindowsDown     CirculateWindow
XCirculateSubwindowsUp       CirculateWindow
XClearArea                   ClearArea
XClearWindow                 ClearArea
XConfigureWindow             ConfigureWindow
XConvertSelection            ConvertSelection
XCopyArea                    CopyArea
XCopyColormapAndFree         CopyColormapAndFree
XCopyGC                      CopyGC
XCopyPlane                   CopyPlane
XCreateBitmapFromData        CreateGC
                             CreatePixmap
                             FreeGC
                             PutImage
XCreateColormap              CreateColormap




                             660022





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
XXlliibb FFuunnccttiioonn                PPrroottooccooll RReeqquueesstt
-------------------------------------------------------
XCreateFontCursor            CreateGlyphCursor
XCreateGC                    CreateGC
XCreateGlyphCursor           CreateGlyphCursor
XCreatePixmap                CreatePixmap
XCreatePixmapCursor          CreateCursor
XCreatePixmapFromData        CreateGC
                             CreatePixmap
                             FreeGC
                             PutImage
XCreateSimpleWindow          CreateWindow
XCreateWindow                CreateWindow
XDefineCursor                ChangeWindowAttributes
XDeleteProperty              DeleteProperty
XDestroySubwindows           DestroySubwindows
XDestroyWindow               DestroyWindow
XDisableAccessControl        SetAccessControl
XDrawArc                     PolyArc
XDrawArcs                    PolyArc
XDrawImageString             ImageText8
XDrawImageString16           ImageText16
XDrawLine                    PolySegment
XDrawLines                   PolyLine
XDrawPoint                   PolyPoint
XDrawPoints                  PolyPoint
XDrawRectangle               PolyRectangle
XDrawRectangles              PolyRectangle
XDrawSegments                PolySegment
XDrawString                  PolyText8
XDrawString16                PolyText16
XDrawText                    PolyText8
XDrawText16                  PolyText16
XEnableAccessControl         SetAccessControl
XFetchBytes                  GetProperty
XFetchName                   GetProperty
XFillArc                     PolyFillArc
XFillArcs                    PolyFillArc
XFillPolygon                 FillPoly
XFillRectangle               PolyFillRectangle
XFillRectangles              PolyFillRectangle
XForceScreenSaver            ForceScreenSaver
XFreeColormap                FreeColormap
XFreeColors                  FreeColors
XFreeCursor                  FreeCursor
XFreeFont                    CloseFont
XFreeGC                      FreeGC
XFreePixmap                  FreePixmap
XGetAtomName                 GetAtomName
XGetClassHint                GetProperty
XGetFontPath                 GetFontPath
XGetGeometry                 GetGeometry




                             660033





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
XXlliibb FFuunnccttiioonn                PPrroottooccooll RReeqquueesstt
-------------------------------------------------------
XGetIconName                 GetProperty
XGetIconSizes                GetProperty
XGetImage                    GetImage
XGetInputFocus               GetInputFocus
XGetKeyboardControl          GetKeyboardControl
XGetKeyboardMapping          GetKeyboardMapping
XGetModifierMapping          GetModifierMapping
XGetMotionEvents             GetMotionEvents
XGetNormalHints              GetProperty
XGetPointerControl           GetPointerControl
XGetPointerMapping           GetPointerMapping
XGetRGBColormaps             GetProperty
XGetScreenSaver              GetScreenSaver
XGetSelectionOwner           GetSelectionOwner
XGetSizeHints                GetProperty
XGetTextProperty             GetProperty
XGetTransientForHint         GetProperty
XGetWMClientMachine          GetProperty
XGetWMColormapWindows        GetProperty
                             InternAtom
XGetWMHints                  GetProperty
XGetWMIconName               GetProperty
XGetWMName                   GetProperty
XGetWMNormalHints            GetProperty
XGetWMProtocols              GetProperty
                             InternAtom
XGetWMSizeHints              GetProperty
XGetWindowAttributes         GetWindowAttributes
                             GetGeometry
XGetWindowProperty           GetProperty
XGetZoomHints                GetProperty
XGrabButton                  GrabButton
XGrabKey                     GrabKey
XGrabKeyboard                GrabKeyboard
XGrabPointer                 GrabPointer
XGrabServer                  GrabServer
XIconifyWindow               InternAtom
                             SendEvent
XInitExtension               QueryExtension
XInstallColormap             InstallColormap
XInternAtom                  InternAtom
XKillClient                  KillClient
XListExtensions              ListExtensions
XListFonts                   ListFonts
XListFontsWithInfo           ListFontsWithInfo
XListHosts                   ListHosts
XListInstalledColormaps      ListInstalledColormaps
XListProperties              ListProperties
XLoadFont                    OpenFont
XLoadQueryFont               OpenFont




                             660044





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
XXlliibb FFuunnccttiioonn                PPrroottooccooll RReeqquueesstt
-------------------------------------------------------
                             QueryFont
XLookupColor                 LookupColor
XLowerWindow                 ConfigureWindow
XMapRaised                   ConfigureWindow
                             MapWindow
XMapSubwindows               MapSubwindows
XMapWindow                   MapWindow
XMoveResizeWindow            ConfigureWindow
XMoveWindow                  ConfigureWindow
XNoOp                        NoOperation
XOpenDisplay                 CreateGC
XParseColor                  LookupColor
XPutImage                    PutImage
XQueryBestCursor             QueryBestSize
XQueryBestSize               QueryBestSize
XQueryBestStipple            QueryBestSize
XQueryBestTile               QueryBestSize
XQueryColor                  QueryColors
XQueryColors                 QueryColors
XQueryExtension              QueryExtension
XQueryFont                   QueryFont
XQueryKeymap                 QueryKeymap
XQueryPointer                QueryPointer
XQueryTextExtents            QueryTextExtents
XQueryTextExtents16          QueryTextExtents
XQueryTree                   QueryTree
XRaiseWindow                 ConfigureWindow
XReadBitmapFile              CreateGC
                             CreatePixmap
                             FreeGC
                             PutImage
XRecolorCursor               RecolorCursor
XReconfigureWMWindow         ConfigureWindow
                             SendEvent
XRemoveFromSaveSet           ChangeSaveSet
XRemoveHost                  ChangeHosts
XRemoveHosts                 ChangeHosts
XReparentWindow              ReparentWindow
XResetScreenSaver            ForceScreenSaver
XResizeWindow                ConfigureWindow
XRestackWindows              ConfigureWindow
XRotateBuffers               RotateProperties
XRotateWindowProperties      RotateProperties
XSelectInput                 ChangeWindowAttributes
XSendEvent                   SendEvent
XSetAccessControl            SetAccessControl
XSetArcMode                  ChangeGC
XSetBackground               ChangeGC
XSetClassHint                ChangeProperty
XSetClipMask                 ChangeGC




                             660055





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
XXlliibb FFuunnccttiioonn                PPrroottooccooll RReeqquueesstt
-------------------------------------------------------
XSetClipOrigin               ChangeGC
XSetClipRectangles           SetClipRectangles
XSetCloseDownMode            SetCloseDownMode
XSetCommand                  ChangeProperty
XSetDashes                   SetDashes
XSetFillRule                 ChangeGC
XSetFillStyle                ChangeGC
XSetFont                     ChangeGC
XSetFontPath                 SetFontPath
XSetForeground               ChangeGC
XSetFunction                 ChangeGC
XSetGraphicsExposures        ChangeGC
XSetIconName                 ChangeProperty
XSetIconSizes                ChangeProperty
XSetInputFocus               SetInputFocus
XSetLineAttributes           ChangeGC
XSetModifierMapping          SetModifierMapping
XSetNormalHints              ChangeProperty
XSetPlaneMask                ChangeGC
XSetPointerMapping           SetPointerMapping
XSetRGBColormaps             ChangeProperty
XSetScreenSaver              SetScreenSaver
XSetSelectionOwner           SetSelectionOwner
XSetSizeHints                ChangeProperty
XSetStandardProperties       ChangeProperty
XSetState                    ChangeGC
XSetStipple                  ChangeGC
XSetSubwindowMode            ChangeGC
XSetTextProperty             ChangeProperty
XSetTile                     ChangeGC
XSetTransientForHint         ChangeProperty
XSetTSOrigin                 ChangeGC
XSetWMClientMachine          ChangeProperty
XSetWMColormapWindows        ChangeProperty
                             InternAtom
XSetWMHints                  ChangeProperty
XSetWMIconName               ChangeProperty
XSetWMName                   ChangeProperty
XSetWMNormalHints            ChangeProperty
XSetWMProperties             ChangeProperty
XSetWMProtocols              ChangeProperty
                             InternAtom
XSetWMSizeHints              ChangeProperty
XSetWindowBackground         ChangeWindowAttributes
XSetWindowBackgroundPixmap   ChangeWindowAttributes
XSetWindowBorder             ChangeWindowAttributes
XSetWindowBorderPixmap       ChangeWindowAttributes
XSetWindowBorderWidth        ConfigureWindow
XSetWindowColormap           ChangeWindowAttributes
XSetZoomHints                ChangeProperty




                             660066





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
XXlliibb FFuunnccttiioonn                PPrroottooccooll RReeqquueesstt
-------------------------------------------------------
XStoreBuffer                 ChangeProperty
XStoreBytes                  ChangeProperty
XStoreColor                  StoreColors
XStoreColors                 StoreColors
XStoreName                   ChangeProperty
XStoreNamedColor             StoreNamedColor
XSync                        GetInputFocus
XSynchronize                 GetInputFocus
XTranslateCoordinates        TranslateCoordinates
XUndefineCursor              ChangeWindowAttributes
XUngrabButton                UngrabButton
XUngrabKey                   UngrabKey
XUngrabKeyboard              UngrabKeyboard
XUngrabPointer               UngrabPointer
XUngrabServer                UngrabServer
XUninstallColormap           UninstallColormap
XUnloadFont                  CloseFont
XUnmapSubwindows             UnmapSubwindows
XUnmapWindow                 UnmapWindow
XWarpPointer                 WarpPointer
XWithdrawWindow              SendEvent
                             UnmapWindow
































                             660077





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The following table lists each X protocol request (in alpha­
betical order) and the Xlib functions that reference it.

-------------------------------------------------------
PPrroottooccooll RReeqquueesstt            XXlliibb FFuunnccttiioonn
-------------------------------------------------------
AllocColor                  XAllocColor
AllocColorCells             XAllocColorCells
AllocColorPlanes            XAllocColorPlanes
AllocNamedColor             XAllocNamedColor
AllowEvents                 XAllowEvents
Bell                        XBell
ChangeActivePointerGrab     XChangeActivePointerGrab
ChangeGC                    XChangeGC
                            XSetArcMode
                            XSetBackground
                            XSetClipMask
                            XSetClipOrigin
                            XSetFillRule
                            XSetFillStyle
                            XSetFont
                            XSetForeground
                            XSetFunction
                            XSetGraphicsExposures
                            XSetLineAttributes
                            XSetPlaneMask
                            XSetState
                            XSetStipple
                            XSetSubwindowMode
                            XSetTile
                            XSetTSOrigin
ChangeHosts                 XAddHost
                            XAddHosts
                            XRemoveHost
                            XRemoveHosts
ChangeKeyboardControl       XAutoRepeatOff
                            XAutoRepeatOn
                            XChangeKeyboardControl
ChangeKeyboardMapping       XChangeKeyboardMapping
ChangePointerControl        XChangePointerControl
ChangeProperty              XChangeProperty
                            XSetClassHint
                            XSetCommand
                            XSetIconName
                            XSetIconSizes
                            XSetNormalHints
                            XSetRGBColormaps
                            XSetSizeHints
                            XSetStandardProperties
                            XSetTextProperty
                            XSetTransientForHint
                            XSetWMClientMachine
                            XSetWMColormapWindows




                             660088





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
PPrroottooccooll RReeqquueesstt            XXlliibb FFuunnccttiioonn
-------------------------------------------------------
                            XSetWMHints
                            XSetWMIconName
                            XSetWMName
                            XSetWMNormalHints
                            XSetWMProperties
                            XSetWMProtocols
                            XSetWMSizeHints
                            XSetZoomHints
                            XStoreBuffer
                            XStoreBytes
                            XStoreName
ChangeSaveSet               XAddToSaveSet
                            XChangeSaveSet
                            XRemoveFromSaveSet
ChangeWindowAttributes      XChangeWindowAttributes
                            XDefineCursor
                            XSelectInput
                            XSetWindowBackground
                            XSetWindowBackgroundPixmap
                            XSetWindowBorder
                            XSetWindowBorderPixmap
                            XSetWindowColormap
                            XUndefineCursor
CirculateWindow             XCirculateSubwindowsDown
                            XCirculateSubwindowsUp
                            XCirculateSubwindows
ClearArea                   XClearArea
                            XClearWindow
CloseFont                   XFreeFont
                            XUnloadFont
ConfigureWindow             XConfigureWindow
                            XLowerWindow
                            XMapRaised
                            XMoveResizeWindow
                            XMoveWindow
                            XRaiseWindow
                            XReconfigureWMWindow
                            XResizeWindow
                            XRestackWindows
                            XSetWindowBorderWidth
ConvertSelection            XConvertSelection
CopyArea                    XCopyArea
CopyColormapAndFree         XCopyColormapAndFree
CopyGC                      XCopyGC
CopyPlane                   XCopyPlane
CreateColormap              XCreateColormap
CreateCursor                XCreatePixmapCursor
CreateGC                    XCreateGC
                            XCreateBitmapFromData
                            XCreatePixmapFromData




                             660099





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
PPrroottooccooll RReeqquueesstt            XXlliibb FFuunnccttiioonn
-------------------------------------------------------
                            XOpenDisplay
                            XReadBitmapFile
CreateGlyphCursor           XCreateFontCursor
                            XCreateGlyphCursor
CreatePixmap                XCreatePixmap
                            XCreateBitmapFromData
                            XCreatePixmapFromData
                            XReadBitmapFile
CreateWindow                XCreateSimpleWindow
                            XCreateWindow
DeleteProperty              XDeleteProperty
DestroySubwindows           XDestroySubwindows
DestroyWindow               XDestroyWindow
FillPoly                    XFillPolygon
ForceScreenSaver            XActivateScreenSaver
                            XForceScreenSaver
                            XResetScreenSaver
FreeColormap                XFreeColormap
FreeColors                  XFreeColors
FreeCursor                  XFreeCursor
FreeGC                      XFreeGC
                            XCreateBitmapFromData
                            XCreatePixmapFromData
                            XReadBitmapFile
FreePixmap                  XFreePixmap
GetAtomName                 XGetAtomName
GetFontPath                 XGetFontPath
GetGeometry                 XGetGeometry
                            XGetWindowAttributes
GetImage                    XGetImage
GetInputFocus               XGetInputFocus
                            XSync
                            XSynchronize
GetKeyboardControl          XGetKeyboardControl
GetKeyboardMapping          XGetKeyboardMapping
GetModifierMapping          XGetModifierMapping
GetMotionEvents             XGetMotionEvents
GetPointerControl           XGetPointerControl
GetPointerMapping           XGetPointerMapping
GetProperty                 XFetchBytes
                            XFetchName
                            XGetClassHint
                            XGetIconName
                            XGetIconSizes
                            XGetNormalHints
                            XGetRGBColormaps
                            XGetSizeHints
                            XGetTextProperty
                            XGetTransientForHint
                            XGetWMClientMachine




                             661100





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
PPrroottooccooll RReeqquueesstt            XXlliibb FFuunnccttiioonn
-------------------------------------------------------
                            XGetWMColormapWindows
                            XGetWMHints
                            XGetWMIconName
                            XGetWMName
                            XGetWMNormalHints
                            XGetWMProtocols
                            XGetWMSizeHints
                            XGetWindowProperty
                            XGetZoomHints
GetSelectionOwner           XGetSelectionOwner
GetWindowAttributes         XGetWindowAttributes
GrabButton                  XGrabButton
GrabKey                     XGrabKey
GrabKeyboard                XGrabKeyboard
GrabPointer                 XGrabPointer
GrabServer                  XGrabServer
ImageText8                  XDrawImageString
ImageText16                 XDrawImageString16
InstallColormap             XInstallColormap
InternAtom                  XGetWMColormapWindows
                            XGetWMProtocols
                            XIconifyWindow
                            XInternAtom
                            XSetWMColormapWindows
                            XSetWMProtocols
KillClient                  XKillClient
ListExtensions              XListExtensions
ListFonts                   XListFonts
ListFontsWithInfo           XListFontsWithInfo
ListHosts                   XListHosts
ListInstalledColormaps      XListInstalledColormaps
ListProperties              XListProperties
LookupColor                 XLookupColor
                            XParseColor
MapSubwindows               XMapSubwindows
MapWindow                   XMapRaised
                            XMapWindow
NoOperation                 XNoOp
OpenFont                    XLoadFont
                            XLoadQueryFont
PolyArc                     XDrawArc
                            XDrawArcs
PolyFillArc                 XFillArc
                            XFillArcs
PolyFillRectangle           XFillRectangle
                            XFillRectangles
PolyLine                    XDrawLines
PolyPoint                   XDrawPoint
                            XDrawPoints
PolyRectangle               XDrawRectangle




                             661111





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
PPrroottooccooll RReeqquueesstt            XXlliibb FFuunnccttiioonn
-------------------------------------------------------
                            XDrawRectangles
PolySegment                 XDrawLine
                            XDrawSegments
PolyText8                   XDrawString
                            XDrawText
PolyText16                  XDrawString16
                            XDrawText16
PutImage                    XPutImage
                            XCreateBitmapFromData
                            XCreatePixmapFromData
                            XReadBitmapFile
QueryBestSize               XQueryBestCursor
                            XQueryBestSize
                            XQueryBestStipple
                            XQueryBestTile
QueryColors                 XQueryColor
                            XQueryColors
QueryExtension              XInitExtension
                            XQueryExtension
QueryFont                   XLoadQueryFont
                            XQueryFont
QueryKeymap                 XQueryKeymap
QueryPointer                XQueryPointer
QueryTextExtents            XQueryTextExtents
                            XQueryTextExtents16
QueryTree                   XQueryTree
RecolorCursor               XRecolorCursor
ReparentWindow              XReparentWindow
RotateProperties            XRotateBuffers
                            XRotateWindowProperties
SendEvent                   XIconifyWindow
                            XReconfigureWMWindow
                            XSendEvent
                            XWithdrawWindow
SetAccessControl            XDisableAccessControl
                            XEnableAccessControl
                            XSetAccessControl
SetClipRectangles           XSetClipRectangles
SetCloseDownMode            XSetCloseDownMode
SetDashes                   XSetDashes
SetFontPath                 XSetFontPath
SetInputFocus               XSetInputFocus
SetModifierMapping          XSetModifierMapping
SetPointerMapping           XSetPointerMapping
SetScreenSaver              XGetScreenSaver
                            XSetScreenSaver
SetSelectionOwner           XSetSelectionOwner
StoreColors                 XStoreColor
                            XStoreColors
StoreNamedColor             XStoreNamedColor




                             661122





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


-------------------------------------------------------
PPrroottooccooll RReeqquueesstt            XXlliibb FFuunnccttiioonn
-------------------------------------------------------
TranslateCoordinates        XTranslateCoordinates
UngrabButton                XUngrabButton
UngrabKey                   XUngrabKey
UngrabKeyboard              XUngrabKeyboard
UngrabPointer               XUngrabPointer
UngrabServer                XUngrabServer
UninstallColormap           XUninstallColormap
UnmapSubwindows             XUnmapSubWindows
UnmapWindow                 XUnmapWindow
                            XWithdrawWindow
WarpPointer                 XWarpPointer











































                             661133





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         AAppppeennddiixx BB

                       XX FFoonntt CCuurrssoorrss



The following are the available cursors that can be used
with _X_C_r_e_a_t_e_F_o_n_t_C_u_r_s_o_r.


#define XC_X_cursor 0         #define XC_ll_angle 76
#define XC_arrow 2            #define XC_lr_angle 78
#define XC_based_arrow_down 4 #define XC_man 80
#define XC_based_arrow_up 6   #define XC_middlebutton 82
#define XC_boat 8             #define XC_mouse 84
#define XC_bogosity 10        #define XC_pencil 86
#define XC_bottom_left_corner 12#define XC_pirate 88
#define XC_bottom_right_corner 14#define XC_plus 90
#define XC_bottom_side 16     #define XC_question_arrow 92
#define XC_bottom_tee 18      #define XC_right_ptr 94
#define XC_box_spiral 20      #define XC_right_side 96
#define XC_center_ptr 22      #define XC_right_tee 98
#define XC_circle 24          #define XC_rightbutton 100
#define XC_clock 26           #define XC_rtl_logo 102
#define XC_coffee_mug 28      #define XC_sailboat 104
#define XC_cross 30           #define XC_sb_down_arrow 106
#define XC_cross_reverse 32   #define XC_sb_h_double_arrow 108
#define XC_crosshair 34       #define XC_sb_left_arrow 110
#define XC_diamond_cross 36   #define XC_sb_right_arrow 112
#define XC_dot 38             #define XC_sb_up_arrow 114
#define XC_dot_box_mask 40    #define XC_sb_v_double_arrow 116
#define XC_double_arrow 42    #define XC_shuttle 118
#define XC_draft_large 44     #define XC_sizing 120
#define XC_draft_small 46     #define XC_spider 122
#define XC_draped_box 48      #define XC_spraycan 124
#define XC_exchange 50        #define XC_star 126
#define XC_fleur 52           #define XC_target 128
#define XC_gobbler 54         #define XC_tcross 130
#define XC_gumby 56           #define XC_top_left_arrow 132
#define XC_hand1 58           #define XC_top_left_corner 134
#define XC_hand2 60           #define XC_top_right_corner 136
#define XC_heart 62           #define XC_top_side 138
#define XC_icon 64            #define XC_top_tee 140
#define XC_iron_cross 66      #define XC_trek 142
#define XC_left_ptr 68        #define XC_ul_angle 144
#define XC_left_side 70       #define XC_umbrella 146
#define XC_left_tee 72        #define XC_ur_angle 148
#define XC_leftbutton 74      #define XC_watch 150
                              #define XC_xterm 152






                             661144





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                         AAppppeennddiixx CC

                         EExxtteennssiioonnss



Because X can evolve by extensions to the core protocol, it
is important that extensions not be perceived as second‐
class citizens.  At some point, your favorite extensions may
be adopted as additional parts of the X Standard.

Therefore, there should be little to distinguish the use of
an extension from that of the core protocol.  To avoid hav­
ing to initialize extensions explicitly in application pro­
grams, it is also important that extensions perform lazy
evaluations, automatically initializing themselves when
called for the first time.

This appendix describes techniques for writing extensions to
Xlib that will run at essentially the same performance as
the core protocol requests.

                            Note

     It is expected that a given extension to X con­
     sists of multiple requests.  Defining 10 new fea­
     tures as 10 separate extensions is a bad practice.
     Rather, they should be packaged into a single
     extension and should use minor opcodes to distin­
     guish the requests.


The symbols and macros used for writing stubs to Xlib are
listed in <_X_1_1_/_X_l_i_b_i_n_t_._h>.

BBaassiicc PPrroottooccooll SSuuppppoorrtt RRoouuttiinneess

The basic protocol requests for extensions are _X_Q_u_e_r_y_E_x_t_e_n_­
_s_i_o_n and _X_L_i_s_t_E_x_t_e_n_s_i_o_n_s.
















                             661155





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Bool XQueryExtension(_d_i_s_p_l_a_y, _n_a_m_e, _m_a_j_o_r___o_p_c_o_d_e___r_e_t_u_r_n, _f_i_r_s_t___e_v_e_n_t___r_e_t_u_r_n, _f_i_r_s_t___e_r_r_o_r___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      char *_n_a_m_e_;
      int *_m_a_j_o_r___o_p_c_o_d_e___r_e_t_u_r_n;
      int *_f_i_r_s_t___e_v_e_n_t___r_e_t_u_r_n;
      int *_f_i_r_s_t___e_r_r_o_r___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_a_m_e      Specifies the extension name.

_m_a_j_o_r___o_p_c_o_d_e___r_e_t_u_r_n
          Returns the major opcode.

_f_i_r_s_t___e_v_e_n_t___r_e_t_u_r_n
          Returns the first event code, if any.

_f_i_r_s_t___e_r_r_o_r___r_e_t_u_r_n
          Returns the first error code, if any.
││__

The _X_Q_u_e_r_y_E_x_t_e_n_s_i_o_n function determines if the named exten­
sion is present.  If the extension is not present, _X_Q_u_e_r_y_E_x_­
_t_e_n_s_i_o_n returns _F_a_l_s_e; otherwise, it returns _T_r_u_e.  If the
extension is present, _X_Q_u_e_r_y_E_x_t_e_n_s_i_o_n returns the major
opcode for the extension to major_opcode_return; otherwise,
it returns zero.  Any minor opcode and the request formats
are specific to the extension.  If the extension involves
additional event types, _X_Q_u_e_r_y_E_x_t_e_n_s_i_o_n returns the base
event type code to first_event_return; otherwise, it returns
zero.  The format of the events is specific to the exten­
sion.  If the extension involves additional error codes,
_X_Q_u_e_r_y_E_x_t_e_n_s_i_o_n returns the base error code to
first_error_return; otherwise, it returns zero.  The format
of additional data in the errors is specific to the exten­
sion.

If the extension name is not in the Host Portable Character
Encoding the result is implementation‐dependent.  Uppercase
and lowercase matter; the strings ‘‘thing’’, ‘‘Thing’’, and
‘‘thinG’’ are all considered different names.














                             661166





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char **XListExtensions(_d_i_s_p_l_a_y, _n_e_x_t_e_n_s_i_o_n_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int *_n_e_x_t_e_n_s_i_o_n_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_e_x_t_e_n_s_i_o_n_s___r_e_t_u_r_n
          Returns the number of extensions listed.
││__

The _X_L_i_s_t_E_x_t_e_n_s_i_o_n_s function returns a list of all exten­
sions supported by the server.  If the data returned by the
server is in the Latin Portable Character Encoding, then the
returned strings are in the Host Portable Character Encod­
ing.  Otherwise, the result is implementation‐dependent.
__
││
XFreeExtensionList(_l_i_s_t)
      char **_l_i_s_t;


_l_i_s_t      Specifies the list of extension names.
││__

The _X_F_r_e_e_E_x_t_e_n_s_i_o_n_L_i_s_t function frees the memory allocated
by _X_L_i_s_t_E_x_t_e_n_s_i_o_n_s.

HHooookkiinngg iinnttoo XXlliibb

These functions allow you to hook into the library.  They
are not normally used by application programmers but are
used by people who need to extend the core X protocol and
the X library interface.  The functions, which generate pro­
tocol requests for X, are typically called stubs.

In extensions, stubs first should check to see if they have
initialized themselves on a connection.  If they have not,
they then should call _X_I_n_i_t_E_x_t_e_n_s_i_o_n to attempt to initial­
ize themselves on the connection.

If the extension needs to be informed of GC/font allocation
or deallocation or if the extension defines new event types,
the functions described here allow the extension to be
called when these events occur.

The _X_E_x_t_C_o_d_e_s structure returns the information from _X_I_n_i_­
_t_E_x_t_e_n_s_i_o_n and is defined in <_X_1_1_/_X_l_i_b_._h>:








                             661177





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct _XExtCodes {   /* public to extension, cannot be changed */
     int extension;           /* extension number */
     int major_opcode;        /* major op‐code assigned by server */
     int first_event;         /* first event number for the extension */
     int first_error;         /* first error number for the extension */
} XExtCodes;

││__

__
││
XExtCodes *XInitExtension(_d_i_s_p_l_a_y, _n_a_m_e)
      Display *_d_i_s_p_l_a_y;
      char *_n_a_m_e;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_a_m_e      Specifies the extension name.
││__

The _X_I_n_i_t_E_x_t_e_n_s_i_o_n function determines if the named exten­
sion exists.  Then, it allocates storage for maintaining the
information about the extension on the connection, chains
this onto the extension list for the connection, and returns
the information the stub implementor will need to access the
extension.  If the extension does not exist, _X_I_n_i_t_E_x_t_e_n_s_i_o_n
returns NULL.

If the extension name is not in the Host Portable Character
Encoding, the result is implementation‐dependent.  Uppercase
and lowercase matter; the strings ‘‘thing’’, ‘‘Thing’’, and
‘‘thinG’’ are all considered different names.

The extension number in the _X_E_x_t_C_o_d_e_s structure is needed in
the other calls that follow.  This extension number is
unique only to a single connection.

__
││
XExtCodes *XAddExtension(_d_i_s_p_l_a_y)
        Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

For local Xlib extensions, the _X_A_d_d_E_x_t_e_n_s_i_o_n function allo­
cates the _X_E_x_t_C_o_d_e_s structure, bumps the extension number
count, and chains the extension onto the extension list.
(This permits extensions to Xlib without requiring server
extensions.)




                             661188





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


HHooookkss iinnttoo tthhee LLiibbrraarryy

These functions allow you to define procedures that are to
be called when various circumstances occur.  The procedures
include the creation of a new GC for a connection, the copy­
ing of a GC, the freeing of a GC, the creating and freeing
of fonts, the conversion of events defined by extensions to
and from wire format, and the handling of errors.

All of these functions return the previous procedure defined
for this extension.
__
││
int (*XESetCloseDisplay(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when the display
          is closed.
││__

The _X_E_S_e_t_C_l_o_s_e_D_i_s_p_l_a_y function defines a procedure to be
called whenever _X_C_l_o_s_e_D_i_s_p_l_a_y is called.  It returns any
previously defined procedure, usually NULL.

When _X_C_l_o_s_e_D_i_s_p_l_a_y is called, your procedure is called with
these arguments:

__
││
(*_p_r_o_c)(_d_i_s_p_l_a_y, _c_o_d_e_s)
     Display *_d_i_s_p_l_a_y;
     XExtCodes *_c_o_d_e_s;

││__
















                             661199





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int (*XESetCreateGC(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when a GC is
          closed.
││__

The _X_E_S_e_t_C_r_e_a_t_e_G_C function defines a procedure to be called
whenever a new GC is created.  It returns any previously
defined procedure, usually NULL.

When a GC is created, your procedure is called with these
arguments:

__
││
(*_p_r_o_c)(_d_i_s_p_l_a_y, _g_c, _c_o_d_e_s)
     Display *_d_i_s_p_l_a_y;
     GC _g_c;
     XExtCodes *_c_o_d_e_s;

││__

__
││
int (*XESetCopyGC(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when GC components
          are copied.
││__

The _X_E_S_e_t_C_o_p_y_G_C function defines a procedure to be called
whenever a GC is copied.  It returns any previously defined
procedure, usually NULL.

When a GC is copied, your procedure is called with these
arguments:




                             662200





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
(*_p_r_o_c)(_d_i_s_p_l_a_y, _g_c, _c_o_d_e_s)
     Display *_d_i_s_p_l_a_y;
     GC _g_c;
     XExtCodes *_c_o_d_e_s;

││__

__
││
int (*XESetFreeGC(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c_))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when a GC is
          freed.
││__

The _X_E_S_e_t_F_r_e_e_G_C function defines a procedure to be called
whenever a GC is freed.  It returns any previously defined
procedure, usually NULL.

When a GC is freed, your procedure is called with these
arguments:

__
││
(*_p_r_o_c)(_d_i_s_p_l_a_y, _g_c, _c_o_d_e_s)
     Display *_d_i_s_p_l_a_y;
     GC _g_c;
     XExtCodes *_c_o_d_e_s;

││__


















                             662211





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int (*XESetCreateFont(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when a font is
          created.
││__

The _X_E_S_e_t_C_r_e_a_t_e_F_o_n_t function defines a procedure to be
called whenever _X_L_o_a_d_Q_u_e_r_y_F_o_n_t and _X_Q_u_e_r_y_F_o_n_t are called.
It returns any previously defined procedure, usually NULL.

When _X_L_o_a_d_Q_u_e_r_y_F_o_n_t or _X_Q_u_e_r_y_F_o_n_t is called, your procedure
is called with these arguments:

__
││
(*_p_r_o_c)(_d_i_s_p_l_a_y, _f_s, _c_o_d_e_s)
     Display *_d_i_s_p_l_a_y;
     XFontStruct *_f_s;
     XExtCodes *_c_o_d_e_s;

││__

__
││
int (*XESetFreeFont(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when a font is
          freed.
││__

The _X_E_S_e_t_F_r_e_e_F_o_n_t function defines a procedure to be called
whenever _X_F_r_e_e_F_o_n_t is called.  It returns any previously
defined procedure, usually NULL.

When _X_F_r_e_e_F_o_n_t is called, your procedure is called with
these arguments:




                             662222





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
(*_p_r_o_c)(_d_i_s_p_l_a_y, _f_s, _c_o_d_e_s)
     Display *_d_i_s_p_l_a_y;
     XFontStruct *_f_s;
     XExtCodes *_c_o_d_e_s;

││__

The _X_E_S_e_t_W_i_r_e_T_o_E_v_e_n_t and _X_E_S_e_t_E_v_e_n_t_T_o_W_i_r_e functions allow
you to define new events to the library.  An _X_E_v_e_n_t struc­
ture always has a type code (type _i_n_t) as the first compo­
nent.  This uniquely identifies what kind of event it is.
The second component is always the serial number (type
_u_n_s_i_g_n_e_d _l_o_n_g) of the last request processed by the server.
The third component is always a Boolean (type _B_o_o_l) indicat­
ing whether the event came from a _S_e_n_d_E_v_e_n_t protocol
request.  The fourth component is always a pointer to the
display the event was read from.  The fifth component is
always a resource ID of one kind or another, usually a win­
dow, carefully selected to be useful to toolkit dispatchers.
The fifth component should always exist, even if the event
does not have a natural destination; if there is no value
from the protocol to put in this component, initialize it to
zero.

                            Note

     There is an implementation limit such that your
     host event structure size cannot be bigger than
     the size of the _X_E_v_e_n_t union of structures.  There
     also is no way to guarantee that more than 24 ele­
     ments or 96 characters in the structure will be
     fully portable between machines.

__
││
int (*XESetWireToEvent(_d_i_s_p_l_a_y, _e_v_e_n_t___n_u_m_b_e_r, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_v_e_n_t___n_u_m_b_e_r;
      Status (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___n_u_m_b_e_r
          Specifies the event code.

_p_r_o_c      Specifies the procedure to call when converting an
          event.
││__

The _X_E_S_e_t_W_i_r_e_T_o_E_v_e_n_t function defines a procedure to be
called when an event needs to be converted from wire format
(_x_E_v_e_n_t) to host format (_X_E_v_e_n_t).  The event number defines



                             662233





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


which protocol event number to install a conversion proce­
dure for.  _X_E_S_e_t_W_i_r_e_T_o_E_v_e_n_t returns any previously defined
procedure.

                            Note

     You can replace a core event conversion function
     with one of your own, although this is not encour­
     aged.  It would, however, allow you to intercept a
     core event and modify it before being placed in
     the queue or otherwise examined.

When Xlib needs to convert an event from wire format to host
format, your procedure is called with these arguments:

__
││
Status (*_p_r_o_c)(_d_i_s_p_l_a_y, _r_e, _e_v_e_n_t)
     Display *_d_i_s_p_l_a_y;
     XEvent *_r_e;
     xEvent *_e_v_e_n_t;

││__

Your procedure must return status to indicate if the conver­
sion succeeded.  The re argument is a pointer to where the
host format event should be stored, and the event argument
is the 32‐byte wire event structure.  In the _X_E_v_e_n_t struc­
ture you are creating, you must fill in the five required
members of the event structure.  You should fill in the type
member with the type specified for the _x_E_v_e_n_t structure.
You should copy all other members from the _x_E_v_e_n_t structure
(wire format) to the _X_E_v_e_n_t structure (host format).  Your
conversion procedure should return _T_r_u_e if the event should
be placed in the queue or _F_a_l_s_e if it should not be placed
in the queue.

To initialize the serial number component of the event, call
___X_S_e_t_L_a_s_t_R_e_q_u_e_s_t_R_e_a_d with the event and use the return
value.

__
││
unsigned long _XSetLastRequestRead(_d_i_s_p_l_a_y, _r_e_p)
      Display *_d_i_s_p_l_a_y;
      xGenericReply *_r_e_p;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_r_e_p       Specifies the wire event structure.
││__

The ___X_S_e_t_L_a_s_t_R_e_q_u_e_s_t_R_e_a_d function computes and returns a



                             662244





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


complete serial number from the partial serial number in the
event.


__
││
Status (*XESetEventToWire(_d_i_s_p_l_a_y, _e_v_e_n_t___n_u_m_b_e_r, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_v_e_n_t___n_u_m_b_e_r;
      int (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_v_e_n_t___n_u_m_b_e_r
          Specifies the event code.

_p_r_o_c      Specifies the procedure to call when converting an
          event.
││__

The _X_E_S_e_t_E_v_e_n_t_T_o_W_i_r_e function defines a procedure to be
called when an event needs to be converted from host format
(_X_E_v_e_n_t) to wire format (_x_E_v_e_n_t) form.  The event number
defines which protocol event number to install a conversion
procedure for.  _X_E_S_e_t_E_v_e_n_t_T_o_W_i_r_e returns any previously
defined procedure.  It returns zero if the conversion fails
or nonzero otherwise.

                            Note

     You can replace a core event conversion function
     with one of your own, although this is not encour­
     aged.  It would, however, allow you to intercept a
     core event and modify it before being sent to
     another client.

When Xlib needs to convert an event from host format to wire
format, your procedure is called with these arguments:

__
││
(*_p_r_o_c)(_d_i_s_p_l_a_y, _r_e, _e_v_e_n_t)
     Display *_d_i_s_p_l_a_y;
     XEvent *_r_e;
     xEvent *_e_v_e_n_t;

││__

The re argument is a pointer to the host format event, and
the event argument is a pointer to where the 32‐byte wire
event structure should be stored.  You should fill in the
type with the type from the _X_E_v_e_n_t structure.  All other
members then should be copied from the host format to the



                             662255





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_x_E_v_e_n_t structure.
__
││
Bool (*XESetWireToError(_d_i_s_p_l_a_y, _e_r_r_o_r___n_u_m_b_e_r, _p_r_o_c)()
      Display *_d_i_s_p_l_a_y;
      int _e_r_r_o_r___n_u_m_b_e_r;
      Bool (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_r_r_o_r___n_u_m_b_e_r
          Specifies the error code.

_p_r_o_c      Specifies the procedure to call when an error is
          received.
││__

The _X_E_S_e_t_W_i_r_e_T_o_E_r_r_o_r function defines a procedure to be
called when an extension error needs to be converted from
wire format to host format.  The error number defines which
protocol error code to install the conversion procedure for.
_X_E_S_e_t_W_i_r_e_T_o_E_r_r_o_r returns any previously defined procedure.

Use this function for extension errors that contain addi­
tional error values beyond those in a core X error, when
multiple wire errors must be combined into a single Xlib
error, or when it is necessary to intercept an X error
before it is otherwise examined.

When Xlib needs to convert an error from wire format to host
format, the procedure is called with these arguments:

__
││
Bool (*_p_r_o_c)(_d_i_s_p_l_a_y, _h_e, _w_e)
     Display *_d_i_s_p_l_a_y;
     XErrorEvent *_h_e;
     xError *_w_e;

││__

The he argument is a pointer to where the host format error
should be stored.  The structure pointed at by he is guaran­
teed to be as large as an _X_E_v_e_n_t structure and so can be
cast to a type larger than an _X_E_r_r_o_r_E_v_e_n_t to store addi­
tional values.  If the error is to be completely ignored by
Xlib (for example, several protocol error structures will be
combined into one Xlib error), then the function should
return _F_a_l_s_e; otherwise, it should return _T_r_u_e.







                             662266





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int (*XESetError(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when an error is
          received.
││__

Inside Xlib, there are times that you may want to suppress
the calling of the external error handling when an error
occurs.  This allows status to be returned on a call at the
cost of the call being synchronous (though most such func­
tions are query operations, in any case, and are typically
programmed to be synchronous).

When Xlib detects a protocol error in ___X_R_e_p_l_y, it calls your
procedure with these arguments:

__
││
int (*_p_r_o_c)(_d_i_s_p_l_a_y, _e_r_r, _c_o_d_e_s, _r_e_t___c_o_d_e)
     Display *_d_i_s_p_l_a_y;
     xError *_e_r_r;
     XExtCodes *_c_o_d_e_s;
     int *_r_e_t___c_o_d_e;

││__

The err argument is a pointer to the 32‐byte wire format
error.  The codes argument is a pointer to the extension
codes structure.  The ret_code argument is the return code
you may want ___X_R_e_p_l_y returned to.

If your procedure returns a zero value, the error is not
suppressed, and the client’s error handler is called.  (For
further information, see section 11.8.2.)  If your procedure
returns nonzero, the error is suppressed, and ___X_R_e_p_l_y
returns the value of ret_code.












                             662277





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char  *(*XESetErrorString(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      char *(*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call to obtain an error
          string.
││__

The _X_G_e_t_E_r_r_o_r_T_e_x_t function returns a string to the user for
an error.  _X_E_S_e_t_E_r_r_o_r_S_t_r_i_n_g allows you to define a procedure
to be called that should return a pointer to the error mes­
sage.  The following is an example.

__
││
(*_p_r_o_c)(_d_i_s_p_l_a_y, _c_o_d_e, _c_o_d_e_s, _b_u_f_f_e_r, _n_b_y_t_e_s)
     Display *_d_i_s_p_l_a_y;
     int _c_o_d_e;
     XExtCodes *_c_o_d_e_s;
     char *_b_u_f_f_e_r;
     int _n_b_y_t_e_s;

││__

Your procedure is called with the error code for every error
detected.  You should copy nbytes of a null‐terminated
string containing the error message into buffer.
__
││
void (*XESetPrintErrorValues(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      void (*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when an error is
          printed.
││__

The _X_E_S_e_t_P_r_i_n_t_E_r_r_o_r_V_a_l_u_e_s function defines a procedure to be
called when an extension error is printed, to print the
error values.  Use this function for extension errors that
contain additional error values beyond those in a core X



                             662288





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


error.  It returns any previously defined procedure.

When Xlib needs to print an error, the procedure is called
with these arguments:

__
││
void (*_p_r_o_c)(_d_i_s_p_l_a_y, _e_v, _f_p)
     Display *_d_i_s_p_l_a_y;
     XErrorEvent *_e_v;
     void *_f_p;

││__

The structure pointed at by ev is guaranteed to be as large
as an _X_E_v_e_n_t structure and so can be cast to a type larger
than an _X_E_r_r_o_r_E_v_e_n_t to obtain additional values set by using
_X_E_S_e_t_W_i_r_e_T_o_E_r_r_o_r.  The underlying type of the fp argument is
system dependent; on a POSIX‐compliant system, fp should be
cast to type FILE*.
__
││
int (*XESetFlushGC(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int *(*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when a GC is
          flushed.
││__

The procedure set by the _X_E_S_e_t_F_l_u_s_h_G_C function has the same
interface as the procedure set by the _X_E_S_e_t_C_o_p_y_G_C function,
but is called when a GC cache needs to be updated in the
server.

















                             662299





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int (*XESetBeforeFlush(_d_i_s_p_l_a_y, _e_x_t_e_n_s_i_o_n, _p_r_o_c))()
      Display *_d_i_s_p_l_a_y;
      int _e_x_t_e_n_s_i_o_n;
      int *(*_p_r_o_c)();


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_e_x_t_e_n_s_i_o_n Specifies the extension number.

_p_r_o_c      Specifies the procedure to call when a buffer is
          flushed.
││__

The _X_E_S_e_t_B_e_f_o_r_e_F_l_u_s_h function defines a procedure to be
called when data is about to be sent to the server.  When
data is about to be sent, your procedure is called one or
more times with these arguments:

__
││
void (*_p_r_o_c)(_d_i_s_p_l_a_y, _c_o_d_e_s, _d_a_t_a, _l_e_n)
     Display *_d_i_s_p_l_a_y;
     XExtCodes *_c_o_d_e_s;
     char *_d_a_t_a;
     long _l_e_n;

││__

The data argument specifies a portion of the outgoing data
buffer, and its length in bytes is specified by the len
argument.  Your procedure must not alter the contents of the
data and must not do additional protocol requests to the
same display.

HHooookkss oonnttoo XXlliibb DDaattaa SSttrruuccttuurreess

Various Xlib data structures have provisions for extension
procedures to chain extension supplied data onto a list.
These structures are _G_C, _V_i_s_u_a_l, _S_c_r_e_e_n, _S_c_r_e_e_n_F_o_r_m_a_t, _D_i_s_­
_p_l_a_y, and _X_F_o_n_t_S_t_r_u_c_t.  Because the list pointer is always
the first member in the structure, a single set of proce­
dures can be used to manipulate the data on these lists.

The following structure is used in the functions in this
section and is defined in <_X_1_1_/_X_l_i_b_._h>:










                             663300





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
typedef struct _XExtData {
     int number;              /* number returned by XInitExtension */
     struct _XExtData *next;  /* next item on list of data for structure */
     int (*free_private)();   /* if defined,  called to free private */
     XPointer private_data;   /* data private to this extension. */
} XExtData;

││__

When any of the data structures listed above are freed, the
list is walked, and the structure’s free procedure (if any)
is called.  If free is NULL, then the library frees both the
data pointed to by the private_data member and the structure
itself.

__
││
union {Display *display;
     GC gc;
     Visual *visual;
     Screen *screen;
     ScreenFormat *pixmap_format;
     XFontStruct *font } XEDataObject;

││__

__
││
XExtData **XEHeadOfExtensionList(_o_b_j_e_c_t)
     XEDataObject _o_b_j_e_c_t;


_o_b_j_e_c_t    Specifies the object.
││__

The _X_E_H_e_a_d_O_f_E_x_t_e_n_s_i_o_n_L_i_s_t function returns a pointer to the
list of extension structures attached to the specified
object.  In concert with _X_A_d_d_T_o_E_x_t_e_n_s_i_o_n_L_i_s_t, _X_E_H_e_a_d_O_f_E_x_t_e_n_­
_s_i_o_n_L_i_s_t allows an extension to attach arbitrary data to any
of the structures of types contained in _X_E_D_a_t_a_O_b_j_e_c_t.
















                             663311





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XAddToExtensionList(_s_t_r_u_c_t_u_r_e, _e_x_t___d_a_t_a)
      XExtData **_s_t_r_u_c_t_u_r_e;
      XExtData *_e_x_t___d_a_t_a;


_s_t_r_u_c_t_u_r_e Specifies the extension list.

_e_x_t___d_a_t_a  Specifies the extension data structure to add.
││__

The structure argument is a pointer to one of the data
structures enumerated above.  You must initialize
ext_data‐>number with the extension number before calling
this function.
__
││
XExtData *XFindOnExtensionList(_s_t_r_u_c_t_u_r_e, _n_u_m_b_e_r)
      struct _XExtData **_s_t_r_u_c_t_u_r_e;
      int _n_u_m_b_e_r;


_s_t_r_u_c_t_u_r_e Specifies the extension list.

_n_u_m_b_e_r    Specifies the extension number from _X_I_n_i_t_E_x_t_e_n_­
          _s_i_o_n.
││__

The _X_F_i_n_d_O_n_E_x_t_e_n_s_i_o_n_L_i_s_t function returns the first exten­
sion data structure for the extension numbered number.  It
is expected that an extension will add at most one extension
data structure to any single data structure’s extension data
list.  There is no way to find additional structures.

The _X_A_l_l_o_c_I_D macro, which allocates and returns a resource
ID, is defined in <_X_1_1_/_X_l_i_b_._h>.
__
││
XAllocID(_d_i_s_p_l_a_y)
     Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__

This macro is a call through the _D_i_s_p_l_a_y structure to an
internal resource ID allocator.  It returns a resource ID
that you can use when creating new resources.

The _X_A_l_l_o_c_I_D_s macro allocates and returns an array of
resource ID.






                             663322





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XAllocIDs(_d_i_s_p_l_a_y, _i_d_s___r_e_t_u_r_n, _c_o_u_n_t)
     Display *_d_i_s_p_l_a_y;
     XID *_i_d_s___r_e_t_u_r_n;
     int _c_o_u_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_i_d_s___r_e_t_u_r_n
          Returns the resource IDs.

_r_e_p       Specifies the number of resource IDs requested.
││__

This macro is a call through the _D_i_s_p_l_a_y structure to an
internal resource ID allocator.  It returns resource IDs to
the array supplied by the caller.  To correctly handle auto­
matic reuse of resource IDs, you must call _X_A_l_l_o_c_I_D_s when
requesting multiple resource IDs.  This call might generate
protocol requests.

GGCC CCaacchhiinngg

GCs are cached by the library to allow merging of indepen­
dent change requests to the same GC into single protocol
requests.  This is typically called a write‐back cache.  Any
extension procedure whose behavior depends on the contents
of a GC must flush the GC cache to make sure the server has
up‐to‐date contents in its GC.

The _F_l_u_s_h_G_C macro checks the dirty bits in the library’s GC
structure and calls ___X_F_l_u_s_h_G_C_C_a_c_h_e if any elements have
changed.  The _F_l_u_s_h_G_C macro is defined as follows:
__
││
FlushGC(_d_i_s_p_l_a_y, _g_c)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.
││__

Note that if you extend the GC to add additional resource ID
components, you should ensure that the library stub sends
the change request immediately.  This is because a client
can free a resource immediately after using it, so if you
only stored the value in the cache without forcing a proto­
col request, the resource might be destroyed before being
set into the GC.  You can use the ___X_F_l_u_s_h_G_C_C_a_c_h_e procedure
to force the cache to be flushed.  The ___X_F_l_u_s_h_G_C_C_a_c_h_e



                             663333





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


procedure is defined as follows:
__
││
_XFlushGCCache(_d_i_s_p_l_a_y, _g_c)
      Display *_d_i_s_p_l_a_y;
      GC _g_c;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_g_c        Specifies the GC.
││__


GGrraapphhiiccss BBaattcchhiinngg

If you extend X to add more poly graphics primitives, you
may be able to take advantage of facilities in the library
to allow back‐to‐back single calls to be transformed into
poly requests.  This may dramatically improve performance of
programs that are not written using poly requests.  A
pointer to an _x_R_e_q, called last_req in the display struc­
ture, is the last request being processed.  By checking that
the last request type, drawable, gc, and other options are
the same as the new one and that there is enough space left
in the buffer, you may be able to just extend the previous
graphics request by extending the length field of the
request and appending the data to the buffer.  This can
improve performance by five times or more in naive programs.
For example, here is the source for the _X_D_r_a_w_P_o_i_n_t stub.
(Writing extension stubs is discussed in the next section.)


























                             663344





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

 __
││
     #include <X11/Xlibint.h>

     /* precompute the maximum size of batching request allowed */

     static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);

     XDrawPoint(dpy, d, gc, x, y)
         register Display *dpy;
         Drawable d;
         GC gc;
         int x, y; /* INT16 */
     {
         xPoint *point;
         LockDisplay(dpy);
         FlushGC(dpy, gc);
         {
         register xPolyPointReq *req = (xPolyPointReq *) dpy‐>last_req;
         /* if same as previous request, with same drawable, batch requests */
         if (
               (req‐>reqType == X_PolyPoint)
            && (req‐>drawable == d)
            && (req‐>gc == gc‐>gid)
            && (req‐>coordMode == CoordModeOrigin)
            && ((dpy‐>bufptr + sizeof (xPoint)) <= dpy‐>bufmax)
            && (((char *)dpy‐>bufptr ‐ (char *)req) < size) ) {
              point = (xPoint *) dpy‐>bufptr;
              req‐>length += sizeof (xPoint) >> 2;
              dpy‐>bufptr += sizeof (xPoint);
              }

         else {
             GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
             req‐>drawable = d;
             req‐>gc = gc‐>gid;
             req‐>coordMode = CoordModeOrigin;
             point = (xPoint *) (req + 1);
             }
         point‐>x = x;
         point‐>y = y;
         }
         UnlockDisplay(dpy);
         SyncHandle();
     }
││__

To keep clients from generating very long requests that may
monopolize the server, there is a symbol defined in
<_X_1_1_/_X_l_i_b_i_n_t_._h> of EPERBATCH on the number of requests
batched.  Most of the performance benefit occurs in the
first few merged requests.  Note that _F_l_u_s_h_G_C is called
_b_e_f_o_r_e picking up the value of last_req, because it may mod­
ify this field.




                             663355





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


WWrriittiinngg EExxtteennssiioonn SSttuubbss

All X requests always contain the length of the request,
expressed as a 16‐bit quantity of 32 bits.  This means that
a single request can be no more than 256K bytes in length.
Some servers may not support single requests of such a
length.  The value of dpy‐>max_request_size contains the
maximum length as defined by the server implementation.  For
further information, see ‘‘X Window System Protocol.’’

RReeqquueessttss,, RReepplliieess,, aanndd XXpprroottoo..hh

The <_X_1_1_/_X_p_r_o_t_o_._h> file contains three sets of definitions
that are of interest to the stub implementor: request names,
request structures, and reply structures.

You need to generate a file equivalent to <_X_1_1_/_X_p_r_o_t_o_._h> for
your extension and need to include it in your stub proce­
dure.  Each stub procedure also must include <_X_1_1_/_X_l_i_b_­
_i_n_t_._h>.

The identifiers are deliberately chosen in such a way that,
if the request is called X_DoSomething, then its request
structure is xDoSomethingReq, and its reply is xDoSomethin­
gReply.  The GetReq family of macros, defined in <_X_1_1_/_X_l_i_b_­
_i_n_t_._h>, takes advantage of this naming scheme.

For each X request, there is a definition in <_X_1_1_/_X_p_r_o_t_o_._h>
that looks similar to this:


     #define X_DoSomething   42

In your extension header file, this will be a minor opcode,
instead of a major opcode.

RReeqquueesstt FFoorrmmaatt

Every request contains an 8‐bit major opcode and a 16‐bit
length field expressed in units of 4 bytes.  Every request
consists of 4 bytes of header (containing the major opcode,
the length field, and a data byte) followed by zero or more
additional bytes of data.  The length field defines the
total length of the request, including the header.  The
length field in a request must equal the minimum length
required to contain the request.  If the specified length is
smaller or larger than the required length, the server
should generate a _B_a_d_L_e_n_g_t_h error.  Unused bytes in a
request are not required to be zero.  Extensions should be
designed in such a way that long protocol requests can be
split up into smaller requests, if it is possible to exceed
the maximum request size of the server.  The protocol guar­
antees the maximum request size to be no smaller than 4096
units (16384 bytes).



                             663366





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Major opcodes 128 through 255 are reserved for extensions.
Extensions are intended to contain multiple requests, so
extension requests typically have an additional minor opcode
encoded in the second data byte in the request header, but
the placement and interpretation of this minor opcode as
well as all other fields in extension requests are not
defined by the core protocol.  Every request is implicitly
assigned a sequence number (starting with one) used in
replies, errors, and events.

To help but not cure portability problems to certain
machines, the _B_1_6 and _B_3_2 macros have been defined so that
they can become bitfield specifications on some machines.
For example, on a Cray, these should be used for all 16‐bit
and 32‐bit quantities, as discussed below.

Most protocol requests have a corresponding structure type­
def in <_X_1_1_/_X_p_r_o_t_o_._h>, which looks like:

__
││
typedef struct _DoSomethingReq {
     CARD8 reqType;           /* X_DoSomething */
     CARD8 someDatum;         /* used differently in different requests */
     CARD16 length B16;       /* total # of bytes in request, divided by 4 */
     ...
     /* request‐specific data */
     ...
} xDoSomethingReq;

││__

If a core protocol request has a single 32‐bit argument, you
need not declare a request structure in your extension
header file.  Instead, such requests use the _x_R_e_s_o_u_r_c_e_R_e_q
structure in <_X_1_1_/_X_p_r_o_t_o_._h>.  This structure is used for any
request whose single argument is a _W_i_n_d_o_w, _P_i_x_m_a_p, _D_r_a_w_a_b_l_e,
_G_C_o_n_t_e_x_t, _F_o_n_t, _C_u_r_s_o_r, _C_o_l_o_r_m_a_p, _A_t_o_m, or _V_i_s_u_a_l_I_D.

__
││
typedef struct _ResourceReq {
     CARD8 reqType;           /* the request type, e.g. X_DoSomething */
     BYTE pad;                /* not used */
     CARD16 length B16;       /* 2 (= total # of bytes in request, divided by 4) */
     CARD32 id B32;           /* the Window, Drawable, Font, GContext, etc. */
} xResourceReq;

││__

If convenient, you can do something similar in your exten­
sion header file.





                             663377





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


In both of these structures, the reqType field identifies
the type of the request (for example, X_MapWindow or X_Cre­
atePixmap).  The length field tells how long the request is
in units of 4‐byte longwords.  This length includes both the
request structure itself and any variable‐length data, such
as strings or lists, that follow the request structure.
Request structures come in different sizes, but all requests
are padded to be multiples of four bytes long.

A few protocol requests take no arguments at all.  Instead,
they use the _x_R_e_q structure in <_X_1_1_/_X_p_r_o_t_o_._h>, which con­
tains only a reqType and a length (and a pad byte).

If the protocol request requires a reply, then
<_X_1_1_/_X_p_r_o_t_o_._h> also contains a reply structure typedef:

__
││
typedef struct _DoSomethingReply {
     BYTE type;               /* always X_Reply */
     BYTE someDatum;          /* used differently in different requests */
     CARD16 sequenceNumber B16;/* # of requests sent so far */
     CARD32 length B32;       /* # of additional bytes, divided by 4 */
     ...
     /* request‐specific data */
     ...
} xDoSomethingReply;

││__

Most of these reply structures are 32 bytes long.  If there
are not that many reply values, then they contain a suffi­
cient number of pad fields to bring them up to 32 bytes.
The length field is the total number of bytes in the request
minus 32, divided by 4.  This length will be nonzero only
if:

⋅    The reply structure is followed by variable‐length
     data, such as a list or string.

⋅    The reply structure is longer than 32 bytes.

Only _G_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s, _Q_u_e_r_y_F_o_n_t, _Q_u_e_r_y_K_e_y_m_a_p, and
_G_e_t_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l have reply structures longer than 32
bytes in the core protocol.

A few protocol requests return replies that contain no data.
<_X_1_1_/_X_p_r_o_t_o_._h> does not define reply structures for these.
Instead, they use the _x_G_e_n_e_r_i_c_R_e_p_l_y structure, which con­
tains only a type, length, and sequence number (and suffi­
cient padding to make it 32 bytes long).






                             663388





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


SSttaarrttiinngg ttoo WWrriittee aa SSttuubb PPrroocceedduurree

An Xlib stub procedure should start like this:


     #include "<X11/Xlibint.h>

     XDoSomething (arguments, ... )
     /* argument declarations */
     {

     register XDoSomethingReq *req;
     ...

If the protocol request has a reply, then the variable dec­
larations should include the reply structure for the
request.  The following is an example:


     xDoSomethingReply rep;


LLoocckkiinngg DDaattaa SSttrruuccttuurreess

To lock the display structure for systems that want to sup­
port multithreaded access to a single display connection,
each stub will need to lock its critical section.  Gener­
ally, this section is the point from just before the appro­
priate GetReq call until all arguments to the call have been
stored into the buffer.  The precise instructions needed for
this locking depend upon the machine architecture.  Two
calls, which are generally implemented as macros, have been
provided.
__
││
LockDisplay(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;



UnlockDisplay(_d_i_s_p_l_a_y)
      Display *_d_i_s_p_l_a_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.
││__


SSeennddiinngg tthhee PPrroottooccooll RReeqquueesstt aanndd AArrgguummeennttss

After the variable declarations, a stub procedure should
call one of four macros defined in <_X_1_1_/_X_l_i_b_i_n_t_._h>: _G_e_t_R_e_q,
_G_e_t_R_e_q_E_x_t_r_a, _G_e_t_R_e_s_R_e_q, or _G_e_t_E_m_p_t_y_R_e_q.  All of these macros
take, as their first argument, the name of the protocol



                             663399





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


request as declared in <_X_1_1_/_X_p_r_o_t_o_._h> except with X_
removed.  Each one declares a _D_i_s_p_l_a_y structure pointer,
called dpy, and a pointer to a request structure, called
req, which is of the appropriate type.  The macro then
appends the request structure to the output buffer, fills in
its type and length field, and sets req to point to it.

If the protocol request has no arguments (for instance,
X_GrabServer), then use _G_e_t_E_m_p_t_y_R_e_q.


     GetEmptyReq (DoSomething, req);

If the protocol request has a single 32‐bit argument (such
as a _P_i_x_m_a_p, _W_i_n_d_o_w, _D_r_a_w_a_b_l_e, _A_t_o_m, and so on), then use
_G_e_t_R_e_s_R_e_q.  The second argument to the macro is the 32‐bit
object.  _X___M_a_p_W_i_n_d_o_w is a good example.


     GetResReq (DoSomething, rid, req);

The rid argument is the _P_i_x_m_a_p, _W_i_n_d_o_w, or other resource
ID.

If the protocol request takes any other argument list, then
call _G_e_t_R_e_q.  After the _G_e_t_R_e_q, you need to set all the
other fields in the request structure, usually from argu­
ments to the stub procedure.


     GetReq (DoSomething, req);
     /* fill in arguments here */
     req‐>arg1 = arg1;
     req‐>arg2 = arg2;
     ...

A few stub procedures (such as _X_C_r_e_a_t_e_G_C and _X_C_r_e_a_t_e_P_i_x_m_a_p)
return a resource ID to the caller but pass a resource ID as
an argument to the protocol request.  Such procedures use
the macro _X_A_l_l_o_c_I_D to allocate a resource ID from the range
of IDs that were assigned to this client when it opened the
connection.


     rid = req‐>rid = XAllocID();
     ...
     return (rid);

Finally, some stub procedures transmit a fixed amount of
variable‐length data after the request.  Typically, these
procedures (such as _X_M_o_v_e_W_i_n_d_o_w and _X_S_e_t_B_a_c_k_g_r_o_u_n_d) are spe­
cial cases of more general functions like _X_M_o_v_e_R_e_s_i_z_e_W_i_n_d_o_w
and _X_C_h_a_n_g_e_G_C.  These procedures use _G_e_t_R_e_q_E_x_t_r_a, which is
the same as _G_e_t_R_e_q except that it takes an additional



                             664400





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


argument (the number of extra bytes to allocate in the out­
put buffer after the request structure).  This number should
always be a multiple of four.

VVaarriiaabbllee LLeennggtthh AArrgguummeennttss

Some protocol requests take additional variable‐length data
that follow the _x_D_o_S_o_m_e_t_h_i_n_g_R_e_q structure.  The format of
this data varies from request to request.  Some requests
require a sequence of 8‐bit bytes, others a sequence of
16‐bit or 32‐bit entities, and still others a sequence of
structures.

It is necessary to add the length of any variable‐length
data to the length field of the request structure.  That
length field is in units of 32‐bit longwords.  If the data
is a string or other sequence of 8‐bit bytes, then you must
round the length up and shift it before adding:


     req‐>length += (nbytes+3)>>2;

To transmit variable‐length data, use the _D_a_t_a macros.  If
the data fits into the output buffer, then this macro copies
it to the buffer.  If it does not fit, however, the _D_a_t_a
macro calls ___X_S_e_n_d, which transmits first the contents of
the buffer and then your data.  The _D_a_t_a macros take three
arguments: the display, a pointer to the beginning of the
data, and the number of bytes to be sent.
__
││
Data(_d_i_s_p_l_a_y, (char *) _d_a_t_a, _n_b_y_t_e_s);

Data16(_d_i_s_p_l_a_y, (short *) _d_a_t_a, _n_b_y_t_e_s);

Data32(_d_i_s_p_l_a_y, (long *) _d_a_t_a, _n_b_y_t_e_s);

││__

_D_a_t_a, _D_a_t_a_1_6, and _D_a_t_a_3_2 are macros that may use their last
argument more than once, so that argument should be a vari­
able rather than an expression such as
‘‘nitems*sizeof(item)’’.  You should do that kind of compu­
tation in a separate statement before calling them.  Use the
appropriate macro when sending byte, short, or long data.

If the protocol request requires a reply, then call the pro­
cedure ___X_S_e_n_d instead of the _D_a_t_a macro.  ___X_S_e_n_d takes the
same arguments, but because it sends your data immediately
instead of copying it into the output buffer (which would
later be flushed anyway by the following call on ___X_R_e_p_l_y),
it is faster.





                             664411





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


RReepplliieess

If the protocol request has a reply, then call ___X_R_e_p_l_y after
you have finished dealing with all the fixed‐length and
variable‐length arguments.  ___X_R_e_p_l_y flushes the output
buffer and waits for an _x_R_e_p_l_y packet to arrive.  If any
events arrive in the meantime, ___X_R_e_p_l_y places them in the
queue for later use.
__
││
Status _XReply(_d_i_s_p_l_a_y, _r_e_p, _e_x_t_r_a, _d_i_s_c_a_r_d)
      Display *_d_i_s_p_l_a_y;
      xReply *_r_e_p;
      int _e_x_t_r_a;
      Bool _d_i_s_c_a_r_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_r_e_p       Specifies the reply structure.

_e_x_t_r_a     Specifies the number of 32‐bit words expected
          after the replay.

_d_i_s_c_a_r_d   Specifies if any data beyond that specified in the
          extra argument should be discarded.
││__

The ___X_R_e_p_l_y function waits for a reply packet and copies its
contents into the specified rep.  ___X_R_e_p_l_y handles error and
event packets that occur before the reply is received.
___X_R_e_p_l_y takes four arguments:

⋅    A _D_i_s_p_l_a_y * structure

⋅    A pointer to a reply structure (which must be cast to
     an _x_R_e_p_l_y *)

⋅    The number of additional 32‐bit words (beyond
     sizeof(_x_R_e_p_l_y) = 32 bytes) in the reply structure

⋅    A Boolean that indicates whether ___X_R_e_p_l_y is to discard
     any additional bytes beyond those it was told to read

Because most reply structures are 32 bytes long, the third
argument is usually 0.  The only core protocol exceptions
are the replies to _G_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s, _Q_u_e_r_y_F_o_n_t,
_Q_u_e_r_y_K_e_y_m_a_p, and _G_e_t_K_e_y_b_o_a_r_d_C_o_n_t_r_o_l, which have longer
replies.

The last argument should be _F_a_l_s_e if the reply structure is
followed by additional variable‐length data (such as a list
or string).  It should be _T_r_u_e if there is not any variable‐
length data.



                             664422





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


                            Note

     This last argument is provided for upward‐compati­
     bility reasons to allow a client to communicate
     properly with a hypothetical later version of the
     server that sends more data than the client
     expected.  For example, some later version of
     _G_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s might use a larger, but com­
     patible, _x_G_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s_R_e_p_l_y that contains
     additional attribute data at the end.

___X_R_e_p_l_y returns _T_r_u_e if it received a reply successfully or
_F_a_l_s_e if it received any sort of error.

For a request with a reply that is not followed by variable‐
length data, you write something like:


     _XReply(display, (xReply *)&rep, 0, True);
     *ret1 = rep.ret1;
     *ret2 = rep.ret2;
     *ret3 = rep.ret3;
     ...
     UnlockDisplay(dpy);
     SyncHandle();
     return (rep.ret4);
     }

If there is variable‐length data after the reply, change the
_T_r_u_e to _F_a_l_s_e, and use the appropriate ___X_R_e_a_d function to
read the variable‐length data.

__
││
_XRead(_d_i_s_p_l_a_y, _d_a_t_a___r_e_t_u_r_n, _n_b_y_t_e_s)
       Display *_d_i_s_p_l_a_y;
       char *_d_a_t_a___r_e_t_u_r_n;
       long _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_a_t_a___r_e_t_u_r_n
          Specifies the buffer.

_n_b_y_t_e_s    Specifies the number of bytes required.
││__

The ___X_R_e_a_d function reads the specified number of bytes into
data_return.







                             664433





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
_XRead16(_d_i_s_p_l_a_y, _d_a_t_a___r_e_t_u_r_n, _n_b_y_t_e_s)
       Display *_d_i_s_p_l_a_y;
       short *_d_a_t_a___r_e_t_u_r_n;
       long _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_a_t_a___r_e_t_u_r_n
          Specifies the buffer.

_n_b_y_t_e_s    Specifies the number of bytes required.
││__

The ___X_R_e_a_d_1_6 function reads the specified number of bytes,
unpacking them as 16‐bit quantities, into the specified
array as shorts.

__
││
_XRead32(_d_i_s_p_l_a_y, _d_a_t_a___r_e_t_u_r_n, _n_b_y_t_e_s)
       Display *_d_i_s_p_l_a_y;
       long *_d_a_t_a___r_e_t_u_r_n;
       long _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_a_t_a___r_e_t_u_r_n
          Specifies the buffer.

_n_b_y_t_e_s    Specifies the number of bytes required.
││__

The ___X_R_e_a_d_3_2 function reads the specified number of bytes,
unpacking them as 32‐bit quantities, into the specified
array as longs.



















                             664444





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
_XRead16Pad(_d_i_s_p_l_a_y, _d_a_t_a___r_e_t_u_r_n, _n_b_y_t_e_s)
       Display *_d_i_s_p_l_a_y;
       short *_d_a_t_a___r_e_t_u_r_n;
       long _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_a_t_a___r_e_t_u_r_n
          Specifies the buffer.

_n_b_y_t_e_s    Specifies the number of bytes required.
││__

The ___X_R_e_a_d_1_6_P_a_d function reads the specified number of
bytes, unpacking them as 16‐bit quantities, into the speci­
fied array as shorts.  If the number of bytes is not a mul­
tiple of four, ___X_R_e_a_d_1_6_P_a_d reads and discards up to two
additional pad bytes.

__
││
_XReadPad(_d_i_s_p_l_a_y, _d_a_t_a___r_e_t_u_r_n, _n_b_y_t_e_s)
       Display *_d_i_s_p_l_a_y;
       char *_d_a_t_a___r_e_t_u_r_n;
       long _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d_a_t_a___r_e_t_u_r_n
          Specifies the buffer.

_n_b_y_t_e_s    Specifies the number of bytes required.
││__

The ___X_R_e_a_d_P_a_d function reads the specified number of bytes
into data_return.  If the number of bytes is not a multiple
of four, ___X_R_e_a_d_P_a_d reads and discards up to three additional
pad bytes.

Each protocol request is a little different.  For further
information, see the Xlib sources for examples.

SSyynncchhrroonnoouuss CCaalllliinngg

Each procedure should have a call, just before returning to
the user, to a macro called _S_y_n_c_H_a_n_d_l_e.  If synchronous mode
is enabled (see _X_S_y_n_c_h_r_o_n_i_z_e), the request is sent immedi­
ately.  The library, however, waits until any error the pro­
cedure could generate at the server has been handled.





                             664455





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


AAllllooccaattiinngg aanndd DDeeaallllooccaattiinngg MMeemmoorryy

To support the possible reentry of these procedures, you
must observe several conventions when allocating and deallo­
cating memory, most often done when returning data to the
user from the window system of a size the caller could not
know in advance (for example, a list of fonts or a list of
extensions).  The standard C library functions on many sys­
tems are not protected against signals or other multi­
threaded uses.  The following analogies to standard I/O
library functions have been defined:

_X_m_a_l_l_o_c()   Replaces _m_a_l_l_o_c()
_X_F_r_e_e()     Replaces _f_r_e_e()
_X_c_a_l_l_o_c()   Replaces _c_a_l_l_o_c()


These should be used in place of any calls you would make to
the normal C library functions.

If you need a single scratch buffer inside a critical sec­
tion (for example, to pack and unpack data to and from the
wire protocol), the general memory allocators may be too
expensive to use (particularly in output functions, which
are performance critical).  The following function returns a
scratch buffer for use within a critical section:
__
││
char *_XAllocScratch(_d_i_s_p_l_a_y, _n_b_y_t_e_s)
      Display *_d_i_s_p_l_a_y;
      unsigned long _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_b_y_t_e_s    Specifies the number of bytes required.
││__

This storage must only be used inside of a critical section
of your stub.  The returned pointer cannot be assumed valid
after any call that might permit another thread to execute
inside Xlib.  For example, the pointer cannot be assumed
valid after any use of the _G_e_t_R_e_q or _D_a_t_a families of
macros, after any use of ___X_R_e_p_l_y, or after any use of the
___X_S_e_n_d or ___X_R_e_a_d families of functions.


The following function returns a scratch buffer for use
across critical sections:








                             664466





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
char *_XAllocTemp(_d_i_s_p_l_a_y, _n_b_y_t_e_s)
      Display *_d_i_s_p_l_a_y;
      unsigned long _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_n_b_y_t_e_s    Specifies the number of bytes required.
││__

This storage can be used across calls that might permit
another thread to execute inside Xlib.  The storage must be
explicitly returned to Xlib.  The following function returns
the storage:
__
││
void _XFreeTemp(_d_i_s_p_l_a_y, _b_u_f, _n_b_y_t_e_s)
      Display *_d_i_s_p_l_a_y;
      char *_b_u_f;
      unsigned long _n_b_y_t_e_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_b_u_f       Specifies the buffer to return.

_n_b_y_t_e_s    Specifies the size of the buffer.
││__

You must pass back the same pointer and size that were
returned by ___X_A_l_l_o_c_T_e_m_p.

PPoorrttaabbiilliittyy CCoonnssiiddeerraattiioonnss

Many machine architectures, including many of the more
recent RISC architectures, do not correctly access data at
unaligned locations; their compilers pad out structures to
preserve this characteristic.  Many other machines capable
of unaligned references pad inside of structures as well to
preserve alignment, because accessing aligned data is usu­
ally much faster.  Because the library and the server use
structures to access data at arbitrary points in a byte
stream, all data in request and reply packets _m_u_s_t be natu­
rally aligned; that is, 16‐bit data starts on 16‐bit bound­
aries in the request and 32‐bit data on 32‐bit boundaries.
All requests _m_u_s_t be a multiple of 32 bits in length to pre­
serve the natural alignment in the data stream.  You must
pad structures out to 32‐bit boundaries.  Pad information
does not have to be zeroed unless you want to preserve such
fields for future use in your protocol requests.  Floating
point varies radically between machines and should be
avoided completely if at all possible.




                             664477





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


This code may run on machines with 16‐bit ints.  So, if any
integer argument, variable, or return value either can take
only nonnegative values or is declared as a _C_A_R_D_1_6 in the
protocol, be sure to declare it as _u_n_s_i_g_n_e_d _i_n_t and not as
_i_n_t.  (This, of course, does not apply to Booleans or enu­
merations.)

Similarly, if any integer argument or return value is
declared _C_A_R_D_3_2 in the protocol, declare it as an _u_n_s_i_g_n_e_d
_l_o_n_g and not as _i_n_t or _l_o_n_g.  This also goes for any inter­
nal variables that may take on values larger than the maxi­
mum 16‐bit _u_n_s_i_g_n_e_d _i_n_t.

The library currently assumes that a _c_h_a_r is 8 bits, a _s_h_o_r_t
is 16 bits, an _i_n_t is 16 or 32 bits, and a _l_o_n_g is 32 bits.
The _P_a_c_k_D_a_t_a macro is a half‐hearted attempt to deal with
the possibility of 32 bit shorts.  However, much more work
is needed to make this work properly.

DDeerriivviinngg tthhee CCoorrrreecctt EExxtteennssiioonn OOppccooddee

The remaining problem a writer of an extension stub proce­
dure faces that the core protocol does not face is to map
from the call to the proper major and minor opcodes.  While
there are a number of strategies, the simplest and fastest
is outlined below.

1.   Declare an array of pointers, _NFILE long (this is nor­
     mally found in <_s_t_d_i_o_._h> and is the number of file
     descriptors supported on the system) of type _X_E_x_t_C_o_d_e_s.
     Make sure these are all initialized to NULL.

2.   When your stub is entered, your initialization test is
     just to use the display pointer passed in to access the
     file descriptor and an index into the array.  If the
     entry is NULL, then this is the first time you are
     entering the procedure for this display.  Call your
     initialization procedure and pass to it the display
     pointer.

3.   Once in your initialization procedure, call _X_I_n_i_t_E_x_t_e_n_­
     _s_i_o_n; if it succeeds, store the pointer returned into
     this array.  Make sure to establish a close display
     handler to allow you to zero the entry.  Do whatever
     other initialization your extension requires.  (For
     example, install event handlers and so on.)  Your ini­
     tialization procedure would normally return a pointer
     to the _X_E_x_t_C_o_d_e_s structure for this extension, which is
     what would normally be found in your array of pointers.

4.   After returning from your initialization procedure, the
     stub can now continue normally, because it has its
     major opcode safely in its hand in the _X_E_x_t_C_o_d_e_s struc­
     ture.



                             664488





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                           AAppppeennddiixx DD

                     CCoommppaattiibbiilliittyy FFuunnccttiioonnss




The X Version 11 and X Version 10 functions discussed in
this appendix are obsolete, have been superseded by newer X
Version 11 functions, and are maintained for compatibility
reasons only.

XX VVeerrssiioonn 1111 CCoommppaattiibbiilliittyy FFuunnccttiioonnss

You can use the X Version 11 compatibility functions to:

⋅    Set standard properties

⋅    Set and get window sizing hints

⋅    Set and get an _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure

⋅    Parse window geometry

⋅    Get X environment defaults

SSeettttiinngg SSttaannddaarrdd PPrrooppeerrttiieess

To specify a minimum set of properties describing the sim­
plest application, use _X_S_e_t_S_t_a_n_d_a_r_d_P_r_o_p_e_r_t_i_e_s.  This func­
tion has been superseded by _X_S_e_t_W_M_P_r_o_p_e_r_t_i_e_s and sets all or
portions of the WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND,
and WM_NORMAL_HINTS properties.






















                             664499





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetStandardProperties(_d_i_s_p_l_a_y, _w, _w_i_n_d_o_w___n_a_m_e, _i_c_o_n___n_a_m_e, _i_c_o_n___p_i_x_m_a_p, _a_r_g_v, _a_r_g_c, _h_i_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      char *_w_i_n_d_o_w___n_a_m_e;
      char *_i_c_o_n___n_a_m_e;
      Pixmap _i_c_o_n___p_i_x_m_a_p;
      char **_a_r_g_v;
      int _a_r_g_c;
      XSizeHints *_h_i_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_w_i_n_d_o_w___n_a_m_e
          Specifies the window name, which should be a null‐
          terminated string.

_i_c_o_n___n_a_m_e Specifies the icon name, which should be a null‐
          terminated string.

_i_c_o_n___p_i_x_m_a_p
          Specifies the bitmap that is to be used for the
          icon or _N_o_n_e.

_a_r_g_v      Specifies the application’s argument list.

_a_r_g_c      Specifies the number of arguments.

_h_i_n_t_s     Specifies a pointer to the size hints for the win­
          dow in its normal state.
││__

The _X_S_e_t_S_t_a_n_d_a_r_d_P_r_o_p_e_r_t_i_e_s function provides a means by
which simple applications set the most essential properties
with a single call.  _X_S_e_t_S_t_a_n_d_a_r_d_P_r_o_p_e_r_t_i_e_s should be used
to give a window manager some information about your pro­
gram’s preferences.  It should not be used by applications
that need to communicate more information than is possible
with _X_S_e_t_S_t_a_n_d_a_r_d_P_r_o_p_e_r_t_i_e_s.  (Typically, argv is the argv
array of your main program.)  If the strings are not in the
Host Portable Character Encoding, the result is implementa­
tion‐dependent.

_X_S_e_t_S_t_a_n_d_a_r_d_P_r_o_p_e_r_t_i_e_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w
errors.

SSeettttiinngg aanndd GGeettttiinngg WWiinnddooww SSiizziinngg HHiinnttss

Xlib provides functions that you can use to set or get win­
dow sizing hints.  The functions discussed in this section
use the flags and the _X_S_i_z_e_H_i_n_t_s structure, as defined in



                             665500





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


the <_X_1_1_/_X_u_t_i_l_._h> header file and use the WM_NORMAL_HINTS
property.


To set the size hints for a given window in its normal
state, use _X_S_e_t_N_o_r_m_a_l_H_i_n_t_s.  This function has been super­
seded by _X_S_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s.
__
││
XSetNormalHints(_d_i_s_p_l_a_y, _w, _h_i_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_h_i_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_h_i_n_t_s     Specifies a pointer to the size hints for the win­
          dow in its normal state.
││__

The _X_S_e_t_N_o_r_m_a_l_H_i_n_t_s function sets the size hints structure
for the specified window.  Applications use _X_S_e_t_N_o_r_m_a_l_H_i_n_t_s
to inform the window manager of the size or position desir­
able for that window.  In addition, an application that
wants to move or resize itself should call _X_S_e_t_N_o_r_m_a_l_H_i_n_t_s
and specify its new desired location and size as well as
making direct Xlib calls to move or resize.  This is because
window managers may ignore redirected configure requests,
but they pay attention to property changes.

To set size hints, an application not only must assign val­
ues to the appropriate members in the hints structure but
also must set the flags member of the structure to indicate
which information is present and where it came from.  A call
to _X_S_e_t_N_o_r_m_a_l_H_i_n_t_s is meaningless, unless the flags member
is set to indicate which members of the structure have been
assigned values.

_X_S_e_t_N_o_r_m_a_l_H_i_n_t_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To return the size hints for a window in its normal state,
use _X_G_e_t_N_o_r_m_a_l_H_i_n_t_s.  This function has been superseded by
_X_G_e_t_W_M_N_o_r_m_a_l_H_i_n_t_s.










                             665511





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetNormalHints(_d_i_s_p_l_a_y, _w, _h_i_n_t_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_h_i_n_t_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_h_i_n_t_s___r_e_t_u_r_n
          Returns the size hints for the window in its
          normal state.
││__

The _X_G_e_t_N_o_r_m_a_l_H_i_n_t_s function returns the size hints for a
window in its normal state.  It returns a nonzero status if
it succeeds or zero if the application specified no normal
size hints for this window.

_X_G_e_t_N_o_r_m_a_l_H_i_n_t_s can generate a _B_a_d_W_i_n_d_o_w error.


The next two functions set and read the WM_ZOOM_HINTS prop­
erty.

To set the zoom hints for a window, use _X_S_e_t_Z_o_o_m_H_i_n_t_s.  This
function is no longer supported by the _I_n_t_e_r_‐_C_l_i_e_n_t _C_o_m_m_u_n_i_­
_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l.
__
││
XSetZoomHints(_d_i_s_p_l_a_y, _w, _z_h_i_n_t_s)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_z_h_i_n_t_s;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_z_h_i_n_t_s    Specifies a pointer to the zoom hints.
││__

Many window managers think of windows in one of three
states: iconic, normal, or zoomed.  The _X_S_e_t_Z_o_o_m_H_i_n_t_s func­
tion provides the window manager with information for the
window in the zoomed state.

_X_S_e_t_Z_o_o_m_H_i_n_t_s can generate _B_a_d_A_l_l_o_c and _B_a_d_W_i_n_d_o_w errors.


To read the zoom hints for a window, use _X_G_e_t_Z_o_o_m_H_i_n_t_s.



                             665522





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


This function is no longer supported by the _I_n_t_e_r_‐_C_l_i_e_n_t
_C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l.
__
││
Status XGetZoomHints(_d_i_s_p_l_a_y, _w, _z_h_i_n_t_s___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_z_h_i_n_t_s___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_z_h_i_n_t_s___r_e_t_u_r_n
          Returns the zoom hints.
││__

The _X_G_e_t_Z_o_o_m_H_i_n_t_s function returns the size hints for a win­
dow in its zoomed state.  It returns a nonzero status if it
succeeds or zero if the application specified no zoom size
hints for this window.

_X_G_e_t_Z_o_o_m_H_i_n_t_s can generate a _B_a_d_W_i_n_d_o_w error.


To set the value of any property of type WM_SIZE_HINTS, use
_X_S_e_t_S_i_z_e_H_i_n_t_s.  This function has been superseded by _X_S_e_t_W_M_­
_S_i_z_e_H_i_n_t_s.
__
││
XSetSizeHints(_d_i_s_p_l_a_y, _w, _h_i_n_t_s, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_h_i_n_t_s;
      Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_h_i_n_t_s     Specifies a pointer to the size hints.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_S_e_t_S_i_z_e_H_i_n_t_s function sets the _X_S_i_z_e_H_i_n_t_s structure for
the named property and the specified window.  This is used
by _X_S_e_t_N_o_r_m_a_l_H_i_n_t_s and _X_S_e_t_Z_o_o_m_H_i_n_t_s and can be used to set
the value of any property of type WM_SIZE_HINTS.  Thus, it
may be useful if other properties of that type get defined.





                             665533





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_S_e_t_S_i_z_e_H_i_n_t_s can generate _B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, and _B_a_d_W_i_n_d_o_w
errors.


To read the value of any property of type WM_SIZE_HINTS, use
_X_G_e_t_S_i_z_e_H_i_n_t_s.  This function has been superseded by _X_G_e_t_W_M_­
_S_i_z_e_H_i_n_t_s.
__
││
Status XGetSizeHints(_d_i_s_p_l_a_y, _w, _h_i_n_t_s___r_e_t_u_r_n, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XSizeHints *_h_i_n_t_s___r_e_t_u_r_n;
      Atom _p_r_o_p_e_r_t_y;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_h_i_n_t_s___r_e_t_u_r_n
          Returns the size hints.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_G_e_t_S_i_z_e_H_i_n_t_s function returns the _X_S_i_z_e_H_i_n_t_s structure
for the named property and the specified window.  This is
used by _X_G_e_t_N_o_r_m_a_l_H_i_n_t_s and _X_G_e_t_Z_o_o_m_H_i_n_t_s.  It also can be
used to retrieve the value of any property of type
WM_SIZE_HINTS.  Thus, it may be useful if other properties
of that type get defined.  _X_G_e_t_S_i_z_e_H_i_n_t_s returns a nonzero
status if a size hint was defined or zero otherwise.

_X_G_e_t_S_i_z_e_H_i_n_t_s can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w errors.

GGeettttiinngg aanndd SSeettttiinngg aann XXSSttaannddaarrddCCoolloorrmmaapp SSttrruuccttuurree

To get the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure associated with one
of the described atoms, use _X_G_e_t_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p.  This
function has been superseded by _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p.
















                             665544





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
Status XGetStandardColormap(_d_i_s_p_l_a_y, _w, _c_o_l_o_r_m_a_p___r_e_t_u_r_n, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XStandardColormap *_c_o_l_o_r_m_a_p___r_e_t_u_r_n;
      Atom _p_r_o_p_e_r_t_y;          /* RGB_BEST_MAP, etc. */


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_c_o_l_o_r_m_a_p___r_e_t_u_r_n
          Returns the colormap associated with the specified
          atom.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_G_e_t_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p function returns the colormap defi­
nition associated with the atom supplied as the property
argument.  _X_G_e_t_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p returns a nonzero status if
successful and zero otherwise.  For example, to fetch the
standard _G_r_a_y_S_c_a_l_e colormap for a display, you use _X_G_e_t_S_t_a_n_­
_d_a_r_d_C_o_l_o_r_m_a_p with the following syntax:

__
││
XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);

││__

See section 14.3 for the semantics of standard colormaps.

_X_G_e_t_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w
errors.


To set a standard colormap, use _X_S_e_t_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p.  This
function has been superseded by _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p.

















                             665555





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XSetStandardColormap(_d_i_s_p_l_a_y, _w, _c_o_l_o_r_m_a_p, _p_r_o_p_e_r_t_y)
      Display *_d_i_s_p_l_a_y;
      Window _w;
      XStandardColormap *_c_o_l_o_r_m_a_p;
      Atom _p_r_o_p_e_r_t_y;          /* RGB_BEST_MAP, etc. */


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_w         Specifies the window.

_c_o_l_o_r_m_a_p  Specifies the colormap.

_p_r_o_p_e_r_t_y  Specifies the property name.
││__

The _X_S_e_t_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p function usually is only used by
window or session managers.

_X_S_e_t_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p can generate _B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, _B_a_d_­
_D_r_a_w_a_b_l_e, and _B_a_d_W_i_n_d_o_w errors.

PPaarrssiinngg WWiinnddooww GGeeoommeettrryy

To parse window geometry given a user‐specified position and
a default position, use _X_G_e_o_m_e_t_r_y.  This function has been
superseded by _X_W_M_G_e_o_m_e_t_r_y.





























                             665566





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
int XGeometry(_d_i_s_p_l_a_y, _s_c_r_e_e_n, _p_o_s_i_t_i_o_n, _d_e_f_a_u_l_t___p_o_s_i_t_i_o_n, _b_w_i_d_t_h, _f_w_i_d_t_h, _f_h_e_i_g_h_t, _x_a_d_d_e_r,
                  _y_a_d_d_e_r, _x___r_e_t_u_r_n, _y___r_e_t_u_r_n, _w_i_d_t_h___r_e_t_u_r_n, _h_e_i_g_h_t___r_e_t_u_r_n)
      Display *_d_i_s_p_l_a_y;
      int _s_c_r_e_e_n;
      char *_p_o_s_i_t_i_o_n, *_d_e_f_a_u_l_t___p_o_s_i_t_i_o_n;
      unsigned int _b_w_i_d_t_h;
      unsigned int _f_w_i_d_t_h, _f_h_e_i_g_h_t;
      int _x_a_d_d_e_r, _y_a_d_d_e_r;
      int *_x___r_e_t_u_r_n, *_y___r_e_t_u_r_n;
      int *_w_i_d_t_h___r_e_t_u_r_n, *_h_e_i_g_h_t___r_e_t_u_r_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_s_c_r_e_e_n    Specifies the screen.

_p_o_s_i_t_i_o_n
_d_e_f_a_u_l_t___p_o_s_i_t_i_o_n
          Specify the geometry specifications.

_b_w_i_d_t_h    Specifies the border width.

_f_h_e_i_g_h_t
_f_w_i_d_t_h    Specify the font height and width in pixels
          (increment size).

_x_a_d_d_e_r
_y_a_d_d_e_r    Specify additional interior padding needed in the
          window.

_x___r_e_t_u_r_n
_y___r_e_t_u_r_n  Return the x and y offsets.

_w_i_d_t_h___r_e_t_u_r_n
_h_e_i_g_h_t___r_e_t_u_r_n
          Return the width and height determined.
││__

You pass in the border width (bwidth), size of the incre­
ments fwidth and fheight (typically font width and height),
and any additional interior space (xadder and yadder) to
make it easy to compute the resulting size.  The _X_G_e_o_m_e_t_r_y
function returns the position the window should be placed
given a position and a default position.  _X_G_e_o_m_e_t_r_y deter­
mines the placement of a window using a geometry specifica­
tion as specified by _X_P_a_r_s_e_G_e_o_m_e_t_r_y and the additional
information about the window.  Given a fully qualified
default geometry specification and an incomplete geometry
specification, _X_P_a_r_s_e_G_e_o_m_e_t_r_y returns a bitmask value as
defined above in the _X_P_a_r_s_e_G_e_o_m_e_t_r_y call, by using the posi­
tion argument.





                             665577





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


The returned width and height will be the width and height
specified by default_position as overridden by any user‐
specified position.  They are not affected by fwidth,
fheight, xadder, or yadder.  The x and y coordinates are
computed by using the border width, the screen width and
height, padding as specified by xadder and yadder, and the
fheight and fwidth times the width and height from the geom­
etry specifications.

GGeettttiinngg tthhee XX EEnnvviirroonnmmeenntt DDeeffaauullttss

The _X_G_e_t_D_e_f_a_u_l_t function provides a primitive interface to
the resource manager facilities discussed in chapter 15.  It
is only useful in very simple applications.


__
││
char *XGetDefault(_d_i_s_p_l_a_y, _p_r_o_g_r_a_m, _o_p_t_i_o_n)
      Display *_d_i_s_p_l_a_y;
      char *_p_r_o_g_r_a_m;
      char *_o_p_t_i_o_n;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_p_r_o_g_r_a_m   Specifies the program name for the Xlib defaults
          (usually argv[0] of the main program).

_o_p_t_i_o_n    Specifies the option name.
││__

The _X_G_e_t_D_e_f_a_u_l_t function returns the value of the resource
_p_r_o_g._o_p_t_i_o_n, where _p_r_o_g is the program argument with the
directory prefix removed and _o_p_t_i_o_n must be a single compo­
nent.  Note that multilevel resources cannot be used with
_X_G_e_t_D_e_f_a_u_l_t.  The class "Program.Name" is always used for
the resource lookup.  If the specified option name does not
exist for this program, _X_G_e_t_D_e_f_a_u_l_t returns NULL.  The
strings returned by _X_G_e_t_D_e_f_a_u_l_t are owned by Xlib and should
not be modified or freed by the client.

If a database has been set with _X_r_m_S_e_t_D_a_t_a_b_a_s_e, that
database is used for the lookup.  Otherwise, a database is
created and is set in the display (as if by calling _X_r_m_S_e_t_­
_D_a_t_a_b_a_s_e).  The database is created in the current locale.
To create a database, _X_G_e_t_D_e_f_a_u_l_t uses resources from the
RESOURCE_MANAGER property on the root window of screen zero.
If no such property exists, a resource file in the user’s
home directory is used.  On a POSIX‐conformant system, this
file is _$_H_O_M_E_/_._X_d_e_f_a_u_l_t_s.  After loading these defaults,
_X_G_e_t_D_e_f_a_u_l_t merges additional defaults specified by the XEN­
VIRONMENT environment variable.  If XENVIRONMENT is defined,
it contains a full path name for the additional resource



                             665588





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


file.  If XENVIRONMENT is not defined, _X_G_e_t_D_e_f_a_u_l_t looks for
_$_H_O_M_E_/_._X_d_e_f_a_u_l_t_s_‐_n_a_m_e_, _w_h_e_r_e _n_a_m_e _s_p_e_c_i_f_i_e_s _t_h_e _n_a_m_e _o_f _t_h_e
_m_a_c_h_i_n_e _o_n _w_h_i_c_h _t_h_e _a_p_p_l_i_c_a_t_i_o_n _i_s _r_u_n_n_i_n_g_.

XX VVeerrssiioonn 1100 CCoommppaattiibbiilliittyy FFuunnccttiioonnss

You can use the X Version 10 compatibility functions to:

⋅    Draw and fill polygons and curves

⋅    Associate user data with a value

DDrraawwiinngg aanndd FFiilllliinngg PPoollyyggoonnss aanndd CCuurrvveess

Xlib provides functions that you can use to draw or fill
arbitrary polygons or curves.  These functions are provided
mainly for compatibility with X Version 10 and have no
server support.  That is, they call other Xlib functions,
not the server directly.  Thus, if you just have straight
lines to draw, using _X_D_r_a_w_L_i_n_e_s or _X_D_r_a_w_S_e_g_m_e_n_t_s is much
faster.

The functions discussed here provide all the functionality
of the X Version 10 functions _X_D_r_a_w, _X_D_r_a_w_F_i_l_l_e_d, _X_D_r_a_w_P_a_t_­
_t_e_r_n_e_d, _X_D_r_a_w_D_a_s_h_e_d, and _X_D_r_a_w_T_i_l_e_d.  They are as compatible
as possible given X Version 11’s new line‐drawing functions.
One thing to note, however, is that _V_e_r_t_e_x_D_r_a_w_L_a_s_t_P_o_i_n_t is
no longer supported.  Also, the error status returned is the
opposite of what it was under X Version 10 (this is the X
Version 11 standard error status).  _X_A_p_p_e_n_d_V_e_r_t_e_x and
_X_C_l_e_a_r_V_e_r_t_e_x_F_l_a_g from X Version 10 also are not supported.

Just how the graphics context you use is set up actually
determines whether you get dashes or not, and so on.  Lines
are properly joined if they connect and include the closing
of a closed figure  (see _X_D_r_a_w_L_i_n_e_s).  The functions dis­
cussed here fail (return zero) only if they run out of mem­
ory or are passed a _V_e_r_t_e_x list that has a _V_e_r_t_e_x with _V_e_r_­
_t_e_x_S_t_a_r_t_C_l_o_s_e_d set that is not followed by a _V_e_r_t_e_x with
_V_e_r_t_e_x_E_n_d_C_l_o_s_e_d set.


To achieve the effects of the X Version 10 _X_D_r_a_w, _X_D_r_a_w_­
_D_a_s_h_e_d, and _X_D_r_a_w_P_a_t_t_e_r_n_e_d, use _X_D_r_a_w.













                             665599





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
#include <X11/X10.h>

Status XDraw(_d_i_s_p_l_a_y, _d, _g_c, _v_l_i_s_t, _v_c_o_u_n_t)
     Display *_d_i_s_p_l_a_y;
     Drawable _d;
     GC _g_c;
     Vertex *_v_l_i_s_t;
     int _v_c_o_u_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_v_l_i_s_t     Specifies a pointer to the list of vertices that
          indicate what to draw.

_v_c_o_u_n_t    Specifies how many vertices are in vlist.
││__

The _X_D_r_a_w function draws an arbitrary polygon or curve.  The
figure drawn is defined by the specified list of vertices
(vlist).  The points are connected by lines as specified in
the flags in the vertex structure.

Each Vertex, as defined in <_X_1_1_/_X_1_0_._h>, is a structure with
the following members:

__
││
typedef struct _Vertex {
     short x,y;
     unsigned short flags;
} Vertex;

││__

The x and y members are the coordinates of the vertex that
are relative to either the upper left inside corner of the
drawable (if _V_e_r_t_e_x_R_e_l_a_t_i_v_e is zero) or the previous vertex
(if _V_e_r_t_e_x_R_e_l_a_t_i_v_e is one).

The flags, as defined in <_X_1_1_/_X_1_0_._h>, are as follows:











                             666600





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
_V_e_r_t_e_x_R_e_l_a_t_i_v_e    0x0001   /* else abso­
                           lute */
_V_e_r_t_e_x_D_o_n_t_D_r_a_w    0x0002   /* else draw */
_V_e_r_t_e_x_C_u_r_v_e_d      0x0004   /* else
                           straight */
_V_e_r_t_e_x_S_t_a_r_t_­      0x0008   /* else not */
_C_l_o_s_e_d
_V_e_r_t_e_x_E_n_d_C_l_o_s_e_d   0x0010   /* else not */

││__


⋅    If _V_e_r_t_e_x_R_e_l_a_t_i_v_e is not set, the coordinates are abso­
     lute (that is, relative to the drawable’s origin).  The
     first vertex must be an absolute vertex.

⋅    If _V_e_r_t_e_x_D_o_n_t_D_r_a_w is one, no line or curve is drawn
     from the previous vertex to this one.  This is analo­
     gous to picking up the pen and moving to another place
     before drawing another line.

⋅    If _V_e_r_t_e_x_C_u_r_v_e_d is one, a spline algorithm is used to
     draw a smooth curve from the previous vertex through
     this one to the next vertex.  Otherwise, a straight
     line is drawn from the previous vertex to this one.  It
     makes sense to set _V_e_r_t_e_x_C_u_r_v_e_d to one only if a previ­
     ous and next vertex are both defined (either explicitly
     in the array or through the definition of a closed
     curve).

⋅    It is permissible for _V_e_r_t_e_x_D_o_n_t_D_r_a_w bits and _V_e_r_t_e_x_­
     _C_u_r_v_e_d bits both to be one.  This is useful if you want
     to define the previous point for the smooth curve but
     do not want an actual curve drawing to start until this
     point.

⋅    If _V_e_r_t_e_x_S_t_a_r_t_C_l_o_s_e_d is one, then this point marks the
     beginning of a closed curve.  This vertex must be fol­
     lowed later in the array by another vertex whose effec­
     tive coordinates are identical and that has a _V_e_r_t_e_x_­
     _E_n_d_C_l_o_s_e_d bit of one.  The points in between form a
     cycle to determine predecessor and successor vertices
     for the spline algorithm.

This function uses these GC components: function, plane‐
mask, line‐width, line‐style, cap‐style, join‐style, fill‐
style, subwindow‐mode, clip‐x‐origin, clip‐y‐origin, and
clip‐mask.  It also uses these GC mode‐dependent components:
foreground, background, tile, stipple, tile‐stipple‐x‐ori­
gin, tile‐stipple‐y‐origin, dash‐offset, and dash‐list.


To achieve the effects of the X Version 10 _X_D_r_a_w_T_i_l_e_d and



                             666611





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


_X_D_r_a_w_F_i_l_l_e_d, use _X_D_r_a_w_F_i_l_l_e_d.
__
││
#include <X11/X10.h>

Status XDrawFilled(_d_i_s_p_l_a_y, _d, _g_c, _v_l_i_s_t, _v_c_o_u_n_t)
     Display *_d_i_s_p_l_a_y;
     Drawable _d;
     GC _g_c;
     Vertex *_v_l_i_s_t;
     int _v_c_o_u_n_t;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_d         Specifies the drawable.

_g_c        Specifies the GC.

_v_l_i_s_t     Specifies a pointer to the list of vertices that
          indicate what to draw.

_v_c_o_u_n_t    Specifies how many vertices are in vlist.
││__

The _X_D_r_a_w_F_i_l_l_e_d function draws arbitrary polygons or curves
and then fills them.

This function uses these GC components: function, plane‐
mask, line‐width, line‐style, cap‐style, join‐style, fill‐
style, subwindow‐mode, clip‐x‐origin, clip‐y‐origin, and
clip‐mask.  It also uses these GC mode‐dependent components:
foreground, background, tile, stipple, tile‐stipple‐x‐ori­
gin, tile‐stipple‐y‐origin, dash‐offset, dash‐list, fill‐
style, and fill‐rule.

AAssssoocciiaattiinngg UUsseerr DDaattaa wwiitthh aa VVaalluuee

These functions have been superseded by the context manage­
ment functions (see section 16.10).  It is often necessary
to associate arbitrary information with resource IDs.  Xlib
provides the _X_A_s_s_o_c_T_a_b_l_e functions that you can use to make
such an association.  Application programs often need to be
able to easily refer to their own data structures when an
event arrives.  The _X_A_s_s_o_c_T_a_b_l_e system provides users of the
X library with a method for associating their own data
structures with X resources (_P_i_x_m_a_p_s, _F_o_n_t_s, _W_i_n_d_o_w_s, and so
on).

An _X_A_s_s_o_c_T_a_b_l_e can be used to type X resources.  For exam­
ple, the user may want to have three or four types of win­
dows, each with different properties.  This can be accom­
plished by associating each X window ID with a pointer to a
window property data structure  defined  by  the user.  A



                             666622





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


generic type has been defined in the X library for resource
IDs.  It is called an XID.

There are a few  guidelines  that  should be observed when
using an _X_A_s_s_o_c_T_a_b_l_e:

⋅    All  XIDs  are  relative  to  the  specified display.

⋅    Because  of  the  hashing  scheme  used  by  the  asso­
     ciation mechanism, the following rules for determining
     the size of a _X_A_s_s_o_c_T_a_b_l_e should be followed.  Associa­
     tions will be  made  and  looked  up  more efficiently
     if  the  table  size  (number  of  buckets in the hash­
     ing system) is a power of two and if there are not more
     than 8 XIDs  per bucket.


To return a pointer to a new _X_A_s_s_o_c_T_a_b_l_e, use _X_C_r_e_a_t_e_A_s_­
_s_o_c_T_a_b_l_e.
__
││
XAssocTable *XCreateAssocTable(_s_i_z_e)
      int _s_i_z_e;


_s_i_z_e      Specifies the number of buckets in the hash system
          of _X_A_s_s_o_c_T_a_b_l_e.
││__

The size argument specifies the number of buckets in the
hash system of _X_A_s_s_o_c_T_a_b_l_e.  For  reasons  of  efficiency
the number of buckets should be a power of two.  Some size
suggestions  might  be:  use  32 buckets  per  100  objects,
and a reasonable maximum number of objects per buckets is 8.
If  an  error  allocating  memory  for  the _X_A_s_s_o_c_T_a_b_l_e
occurs, a NULL pointer is returned.


To create an entry in a given _X_A_s_s_o_c_T_a_b_l_e, use _X_M_a_k_e_A_s_s_o_c.


















                             666633





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XMakeAssoc(_d_i_s_p_l_a_y, _t_a_b_l_e, _x___i_d, _d_a_t_a)
      Display *_d_i_s_p_l_a_y;
      XAssocTable *_t_a_b_l_e;
      XID _x___i_d;
      char *_d_a_t_a;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_t_a_b_l_e     Specifies the assoc table.

_x___i_d      Specifies the X resource ID.

_d_a_t_a      Specifies the data to be associated with the X
          resource ID.
││__

The _X_M_a_k_e_A_s_s_o_c function inserts data into an _X_A_s_s_o_c_T_a_b_l_e
keyed on an XID.  Data is inserted into the table only once.
Redundant inserts are ignored.  The queue in each associa­
tion bucket is sorted from the lowest XID to the highest
XID.


To obtain data from a given _X_A_s_s_o_c_T_a_b_l_e, use _X_L_o_o_k_U_p_A_s_s_o_c.
__
││
char *XLookUpAssoc(_d_i_s_p_l_a_y, _t_a_b_l_e, _x___i_d)
      Display *_d_i_s_p_l_a_y;
      XAssocTable *_t_a_b_l_e;
      XID _x___i_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_t_a_b_l_e     Specifies the assoc table.

_x___i_d      Specifies the X resource ID.
││__

The _X_L_o_o_k_U_p_A_s_s_o_c function retrieves the data stored in an
_X_A_s_s_o_c_T_a_b_l_e by its XID.  If  an appropriately  matching XID
can be found in the table, _X_L_o_o_k_U_p_A_s_s_o_c returns the data
associated with it.  If the x_id cannot be found in the
table, it returns NULL.


To delete an entry from a given _X_A_s_s_o_c_T_a_b_l_e, use _X_D_e_l_e_t_e_A_s_­
_s_o_c.







                             666644





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22

__
││
XDeleteAssoc(_d_i_s_p_l_a_y, _t_a_b_l_e, _x___i_d)
      Display *_d_i_s_p_l_a_y;
      XAssocTable *_t_a_b_l_e;
      XID _x___i_d;


_d_i_s_p_l_a_y   Specifies the connection to the X server.

_t_a_b_l_e     Specifies the assoc table.

_x___i_d      Specifies the X resource ID.
││__

The _X_D_e_l_e_t_e_A_s_s_o_c function deletes an association in an _X_A_s_­
_s_o_c_T_a_b_l_e keyed on its XID.  Redundant deletes (and deletes
of nonexistent XIDs) are ignored.  Deleting associations in
no way impairs the performance of an _X_A_s_s_o_c_T_a_b_l_e.


To free the memory associated with a given _X_A_s_s_o_c_T_a_b_l_e, use
_X_D_e_s_t_r_o_y_A_s_s_o_c_T_a_b_l_e.
__
││
XDestroyAssocTable(_t_a_b_l_e)
      XAssocTable *_t_a_b_l_e;


_t_a_b_l_e     Specifies the assoc table.
││__



























                             666655





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22




                          GGlloossssaarryy



AAcccceessss ccoonnttrrooll lliisstt

     X maintains a list of hosts from which client programs
     can be run.  By default, only programs on the local
     host and hosts specified in an initial list read by the
     server can use the display.  This access control list
     can be changed by clients on the local host.  Some
     server implementations can also implement other autho­
     rization mechanisms in addition to or in place of this
     mechanism.  The action of this mechanism can be condi­
     tional based on the authorization protocol name and
     data received by the server at connection setup.

AAccttiivvee ggrraabb

     A grab is active when the pointer or keyboard is actu­
     ally owned by the single grabbing client.

AAnncceessttoorrss

     If W is an inferior of A, then A is an ancestor of W.

AAttoomm

     An atom is a unique ID corresponding to a string name.
     Atoms are used to identify properties, types, and
     selections.

BBaacckkggrroouunndd

     An _I_n_p_u_t_O_u_t_p_u_t window can have a background, which is
     defined as a pixmap.  When regions of the window have
     their contents lost or invalidated, the server automat­
     ically tiles those regions with the background.

BBaacckkiinngg ssttoorree

     When a server maintains the contents of a window, the
     pixels saved off‐screen are known as a backing store.












                             666666





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


BBaassee ffoonntt nnaammee

     A font name used to select a family of fonts whose mem­
     bers may be encoded in various charsets.  The _C_h_a_r_S_e_­
     _t_R_e_g_i_s_t_r_y and _C_h_a_r_S_e_t_E_n_c_o_d_i_n_g fields of an XLFD name
     identify the charset of the font.  A base font name may
     be a full XLFD name, with all fourteen ’‐’ delimiters,
     or an abbreviated XLFD name containing only the first
     12 fields of an XLFD name, up to but not including
     _C_h_a_r_S_e_t_R_e_g_i_s_t_r_y, with or without the thirteenth ’‐’, or
     a non‐XLFD name.  Any XLFD fields may contain wild
     cards.

     When creating an _X_F_o_n_t_S_e_t, Xlib accepts from the client
     a list of one or more base font names which select one
     or more font families.  They are combined with charset
     names obtained from the encoding of the locale to load
     the fonts required to render text.

BBiitt ggrraavviittyy

     When a window is resized, the contents of the window
     are not necessarily discarded.  It is possible to
     request that the server relocate the previous contents
     to some region of the window (though no guarantees are
     made).  This attraction of window contents for some
     location of a window is known as bit gravity.

BBiitt ppllaannee

     When a pixmap or window is thought of as a stack of
     bitmaps, each bitmap is called a bit plane or plane.

BBiittmmaapp

     A bitmap is a pixmap of depth one.

BBoorrddeerr

     An _I_n_p_u_t_O_u_t_p_u_t window can have a border of equal thick­
     ness on all four sides of the window.  The contents of
     the border are defined by a pixmap, and the server
     automatically maintains the contents of the border.
     Exposure events are never generated for border regions.

BBuuttttoonn ggrraabbbbiinngg

     Buttons on the pointer can be passively grabbed by a
     client.  When the button is pressed, the pointer is
     then actively grabbed by the client.







                             666677





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


BByyttee oorrddeerr

     For image (pixmap/bitmap) data, the server defines the
     byte order, and clients with different native byte
     ordering must swap bytes as necessary.  For all other
     parts of the protocol, the client defines the byte
     order, and the server swaps bytes as necessary.

CChhaarraacctteerr

     A member of a set of elements used for the organiza­
     tion, control, or representation of text (ISO2022, as
     adapted by XPG3).  Note that in ISO2022 terms, a char­
     acter is not bound to a coded value until it is identi­
     fied as part of a coded character set.

CChhaarraacctteerr ggllyypphh

     The abstract graphical symbol for a character.  Charac­
     ter glyphs may or may not map one‐to‐one to font
     glyphs, and may be context‐dependent, varying with the
     adjacent characters.  Multiple characters may map to a
     single character glyph.

CChhaarraacctteerr sseett

     A collection of characters.

CChhaarrsseett

     An encoding with a uniform, state‐independent mapping
     from characters to codepoints.  A coded character set.

     For display in X, there can be a direct mapping from a
     charset to one font, if the width of all characters in
     the charset is either one or two bytes.  A text string
     encoded in an encoding such as Shift‐JIS cannot be
     passed directly to the X server, because the text imag­
     ing requests accept only single‐width charsets (either
     8 or 16 bits).  Charsets which meet these restrictions
     can serve as ‘‘font charsets’’.  Font charsets strictly
     speaking map font indices to font glyphs, not charac­
     ters to character glyphs.

     Note that a single font charset is sometimes used as
     the encoding of a locale, for example, ISO8859‐1.

CChhiillddrreenn

     The children of a window are its first‐level subwin­
     dows.






                             666688





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


CCllaassss

     Windows can be of different classes or types.  See the
     entries for _I_n_p_u_t_O_n_l_y and _I_n_p_u_t_O_u_t_p_u_t windows for fur­
     ther information about valid window types.

CClliieenntt

     An application program connects to the window system
     server by some interprocess communication (IPC) path,
     such as a TCP connection or a shared memory buffer.
     This program is referred to as a client of the window
     system server.  More precisely, the client is the IPC
     path itself.  A program with multiple paths open to the
     server is viewed as multiple clients by the protocol.
     Resource lifetimes are controlled by connection life­
     times, not by program lifetimes.

CClliippppiinngg rreeggiioonn

     In a graphics context, a bitmap or list of rectangles
     can be specified to restrict output to a particular
     region of the window.  The image defined by the bitmap
     or rectangles is called a clipping region.

CCooddeedd cchhaarraacctteerr

     A character bound to a codepoint.

CCooddeedd cchhaarraacctteerr sseett

     A set of unambiguous rules that establishes a character
     set and the one‐to‐one relationship between each char­
     acter of the set and its bit representation.  (ISO2022,
     as adapted by XPG3) A definition of a one‐to‐one map­
     ping of a set of characters to a set of codepoints.

CCooddeeppooiinntt

     The coded representation of a single character in a
     coded character set.

CCoolloorrmmaapp

     A colormap consists of a set of entries defining color
     values.  The colormap associated with a window is used
     to display the contents of the window; each pixel value
     indexes the colormap to produce an RGB value that
     drives the guns of a monitor.  Depending on hardware
     limitations, one or more colormaps can be installed at
     one time so that windows associated with those maps
     display with true colors.





                             666699





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


CCoonnnneeccttiioonn

     The IPC path between the server and client program is
     known as a connection.  A client program typically (but
     not necessarily) has one connection to the server over
     which requests and events are sent.

CCoonnttaaiinnmmeenntt

     A window contains the pointer if the window is viewable
     and the hotspot of the cursor is within a visible
     region of the window or a visible region of one of its
     inferiors.  The border of the window is included as
     part of the window for containment.  The pointer is in
     a window if the window contains the pointer but no
     inferior contains the pointer.

CCoooorrddiinnaattee ssyysstteemm

     The coordinate system has X horizontal and Y vertical,
     with the origin [0, 0] at the upper left.  Coordinates
     are integral and coincide with pixel centers.  Each
     window and pixmap has its own coordinate system.  For a
     window, the origin is inside the border at the inside
     upper‐left corner.

CCuurrssoorr

     A cursor is the visible shape of the pointer on a
     screen.  It consists of a hotspot, a source bitmap, a
     shape bitmap, and a pair of colors.  The cursor defined
     for a window controls the visible appearance when the
     pointer is in that window.

DDeepptthh

     The depth of a window or pixmap is the number of bits
     per pixel it has.  The depth of a graphics context is
     the depth of the drawables it can be used in conjunc­
     tion with graphics output.

DDeevviiccee

     Keyboards, mice, tablets, track‐balls, button boxes,
     and so on are all collectively known as input devices.
     Pointers can have one or more buttons (the most common
     number is three).  The core protocol only deals with
     two devices: the keyboard and the pointer.









                             667700





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


DDiirreeccttCCoolloorr

     _D_i_r_e_c_t_C_o_l_o_r is a class of colormap in which a pixel
     value is decomposed into three separate subfields for
     indexing.  The first subfield indexes an array to pro­
     duce red intensity values.  The second subfield indexes
     a second array to produce blue intensity values.  The
     third subfield indexes a third array to produce green
     intensity values.  The RGB (red, green, and blue) val­
     ues in the colormap entry can be changed dynamically.

DDiissppllaayy

     A server, together with its screens and input devices,
     is called a display.  The Xlib _D_i_s_p_l_a_y structure con­
     tains all information about the particular display and
     its screens as well as the state that Xlib needs to
     communicate with the display over a particular connec­
     tion.

DDrraawwaabbllee

     Both windows and pixmaps can be used as sources and
     destinations in graphics operations.  These windows and
     pixmaps are collectively known as drawables.  However,
     an _I_n_p_u_t_O_n_l_y window cannot be used as a source or des­
     tination in a graphics operation.

EEnnccooddiinngg

     A set of unambiguous rules that establishes a character
     set and a relationship between the characters and their
     representations.  The character set does not have to be
     fixed to a finite pre‐defined set of characters.  The
     representations do not have to be of uniform length.
     Examples are an ISO2022 graphic set, a state‐indepen­
     dent or state‐dependent combination of graphic sets,
     possibly including control sets, and the X Compound
     Text encoding.

     In X, encodings are identified by a string which
     appears as: the _C_h_a_r_S_e_t_R_e_g_i_s_t_r_y and _C_h_a_r_S_e_t_E_n_c_o_d_i_n_g
     components of an XLFD name; the name of a charset of
     the locale for which a font could not be found; or an
     atom which identifies the encoding of a text property
     or which names an encoding for a text selection target
     type.  Encoding names should be composed of characters
     from the X Portable Character Set.









                             667711





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


EEssccaappeemmeenntt

     The escapement of a string is the distance in pixels in
     the primary draw direction from the drawing origin to
     the origin of the next character (that is, the one fol­
     lowing the given string) to be drawn.

EEvveenntt

     Clients are informed of information asynchronously by
     means of events.  These events can be either asyn­
     chronously generated from devices or generated as side
     effects of client requests.  Events are grouped into
     types.  The server never sends an event to a client
     unless the client has specifically asked to be informed
     of that type of event.  However, clients can force
     events to be sent to other clients.  Events are typi­
     cally reported relative to a window.

EEvveenntt mmaasskk

     Events are requested relative to a window.  The set of
     event types a client requests relative to a window is
     described by using an event mask.

EEvveenntt pprrooppaaggaattiioonn

     Device‐related events propagate from the source window
     to ancestor windows until some client has expressed
     interest in handling that type of event or until the
     event is discarded explicitly.

EEvveenntt ssoouurrccee

     The deepest viewable window that the pointer is in is
     called the source of a device‐related event.

EEvveenntt ssyynncchhrroonniizzaattiioonn

     There are certain race conditions possible when demul­
     tiplexing device events to clients (in particular,
     deciding where pointer and keyboard events should be
     sent when in the middle of window management opera­
     tions).  The event synchronization mechanism allows
     synchronous processing of device events.

EExxppoossuurree eevveenntt

     Servers do not guarantee to preserve the contents of
     windows when windows are obscured or reconfigured.
     Exposure events are sent to clients to inform them when
     contents of regions of windows have been lost.





                             667722





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


EExxtteennssiioonn

     Named extensions to the core protocol can be defined to
     extend the system.  Extensions to output requests,
     resources, and event types are all possible and
     expected.

FFoonntt

     A font is an array of glyphs (typically characters).
     The protocol does no translation or interpretation of
     character sets.  The client simply indicates values
     used to index the glyph array.  A font contains addi­
     tional metric information to determine interglyph and
     interline spacing.

FFoonntt ggllyypphh

     The abstract graphical symbol for an index into a font.

FFrroozzeenn eevveennttss

     Clients can freeze event processing during keyboard and
     pointer grabs.

GGCC

     GC is an abbreviation for graphics context.  See GGrraapphh­­
     iiccss ccoonntteexxtt.

GGllyypphh

     An identified abstract graphical symbol independent of
     any actual image.  (ISO/IEC/DIS 9541‐1) An abstract
     visual representation of a graphic character, not bound
     to a codepoint.

GGllyypphh iimmaaggee

     An image of a glyph, as obtained from a glyph represen­
     tation displayed on a presentation surface.
     (ISO/IEC/DIS 9541‐1)

GGrraabb

     Keyboard keys, the keyboard, pointer buttons, the
     pointer, and the server can be grabbed for exclusive
     use by a client.  In general, these facilities are not
     intended to be used by normal applications but are
     intended for various input and window managers to
     implement various styles of user interfaces.






                             667733





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


GGrraapphhiiccss ccoonntteexxtt

     Various information for graphics output is stored in a
     graphics context (GC), such as foreground pixel, back­
     ground pixel, line width, clipping region, and so on.
     A graphics context can only be used with drawables that
     have the same root and the same depth as the graphics
     context.

GGrraavviittyy

     The contents of windows and windows themselves have a
     gravity, which determines how the contents move when a
     window is resized.  See BBiitt ggrraavviittyy and WWiinnddooww ggrraavviittyy.

GGrraayySSccaallee

     _G_r_a_y_S_c_a_l_e can be viewed as a degenerate case of _P_s_e_u_d_o_­
     _C_o_l_o_r, in which the red, green, and blue values in any
     given colormap entry are equal and thus, produce shades
     of gray.  The gray values can be changed dynamically.

HHoosstt PPoorrttaabbllee CChhaarraacctteerr EEnnccooddiinngg

     The encoding of the X Portable Character Set on the
     host.  The encoding itself is not defined by this stan­
     dard, but the encoding must be the same in all locales
     supported by Xlib on the host.  If a string is said to
     be in the Host Portable Character Encoding, then it
     only contains characters from the X Portable Character
     Set, in the host encoding.

HHoottssppoott

     A cursor has an associated hotspot, which defines the
     point in the cursor corresponding to the coordinates
     reported for the pointer.

IIddeennttiiffiieerr

     An identifier is a unique value associated with a
     resource that clients use to name that resource.  The
     identifier can be used over any connection to name the
     resource.

IInnffeerriioorrss

     The inferiors of a window are all of the subwindows
     nested below it: the children, the children’s children,
     and so on.







                             667744





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


IInnppuutt ffooccuuss

     The input focus is usually a window defining the scope
     for processing of keyboard input.  If a generated key­
     board event usually would be reported to this window or
     one of its inferiors, the event is reported as usual.
     Otherwise, the event is reported with respect to the
     focus window.  The input focus also can be set such
     that all keyboard events are discarded and such that
     the focus window is dynamically taken to be the root
     window of whatever screen the pointer is on at each
     keyboard event.

IInnppuutt mmaannaaggeerr

     Control over keyboard input is typically provided by an
     input manager client, which usually is part of a window
     manager.

IInnppuuttOOnnllyy wwiinnddooww

     An _I_n_p_u_t_O_n_l_y window is a window that cannot be used for
     graphics requests.  _I_n_p_u_t_O_n_l_y windows are invisible and
     are used to control such things as cursors, input event
     generation, and grabbing.  _I_n_p_u_t_O_n_l_y windows cannot
     have _I_n_p_u_t_O_u_t_p_u_t windows as inferiors.

IInnppuuttOOuuttppuutt wwiinnddooww

     An _I_n_p_u_t_O_u_t_p_u_t window is the normal kind of window that
     is used for both input and output.  _I_n_p_u_t_O_u_t_p_u_t windows
     can have both _I_n_p_u_t_O_u_t_p_u_t and _I_n_p_u_t_O_n_l_y windows as
     inferiors.

IInntteerrnnaattiioonnaalliizzaattiioonn

     The process of making software adaptable to the
     requirements of different native languages, local cus­
     toms, and character string encodings.  Making a com­
     puter program adaptable to different locales without
     program source modifications or recompilation.

IISSOO22002222

     ISO standard for code extension techniques for 7‐bit
     and 8‐bit coded character sets.

KKeeyy ggrraabbbbiinngg

     Keys on the keyboard can be passively grabbed by a
     client.  When the key is pressed, the keyboard is then
     actively grabbed by the client.





                             667755





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


KKeeyybbooaarrdd ggrraabbbbiinngg

     A client can actively grab control of the keyboard, and
     key events will be sent to that client rather than the
     client the events would normally have been sent to.

KKeeyyssyymm

     An encoding of a symbol on a keycap on a keyboard.

LLaattiinn‐‐11

     The coded character set defined by the ISO8859‐1 stan­
     dard.

LLaattiinn PPoorrttaabbllee CChhaarraacctteerr EEnnccooddiinngg

     The encoding of the X Portable Character Set using the
     Latin‐1 codepoints plus ASCII control characters.  If a
     string is said to be in the Latin Portable Character
     Encoding, then it only contains characters from the X
     Portable Character Set, not all of Latin‐1.

LLooccaallee

     The international environment of a computer program
     defining the ‘‘localized’’ behavior of that program at
     run‐time.  This information can be established from one
     or more sets of localization data.  ANSI C defines
     locale‐specific processing by C system library calls.
     See ANSI C and the X/Open Portability Guide specifica­
     tions for more details.  In this specification, on
     implementations that conform to the ANSI C library, the
     ‘‘current locale’’ is the current setting of the
     LC_CTYPE _s_e_t_l_o_c_a_l_e category.  Associated with each
     locale is a text encoding.  When text is processed in
     the context of a locale, the text must be in the encod­
     ing of the locale.  The current locale affects Xlib in
     its:

     ⋅    Encoding and processing of input method text

     ⋅    Encoding of resource files and values

     ⋅    Encoding and imaging of text strings

     ⋅    Encoding and decoding for inter‐client text commu­
          nication









                             667766





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


LLooccaallee nnaammee

     The identifier used to select the desired locale for
     the host C library and X library functions.  On ANSI C
     library compliant systems, the locale argument to the
     _s_e_t_l_o_c_a_l_e function.

LLooccaalliizzaattiioonn

     The process of establishing information within a com­
     puter system specific to the operation of particular
     native languages, local customs and coded character
     sets.  (XPG3)

MMaappppeedd

     A window is said to be mapped if a map call has been
     performed on it.  Unmapped windows and their inferiors
     are never viewable or visible.

MMooddiiffiieerr kkeeyyss

     Shift, Control, Meta, Super, Hyper, Alt, Compose,
     Apple, CapsLock, ShiftLock, and similar keys are called
     modifier keys.

MMoonnoocchhrroommee

     Monochrome is a special case of _S_t_a_t_i_c_G_r_a_y in which
     there are only two colormap entries.

MMuullttiibbyyttee

     A character whose codepoint is stored in more than one
     byte; any encoding which can contain multibyte charac­
     ters; text in a multibyte encoding.  The ‘‘char *’’
     null‐terminated string datatype in ANSI C.  Note that
     references in this document to multibyte strings imply
     only that the strings _m_a_y contain multibyte characters.

OObbssccuurree

     A window is obscured if some other window obscures it.
     A window can be partially obscured and so still have
     visible regions.  Window A obscures window B if both
     are viewable _I_n_p_u_t_O_u_t_p_u_t windows, if A is higher in the
     global stacking order, and if the rectangle defined by
     the outside edges of A intersects the rectangle defined
     by the outside edges of B.  Note the distinction
     between obscures and occludes.  Also note that window
     borders are included in the calculation.






                             667777





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


OOcccclluuddee

     A window is occluded if some other window occludes it.
     Window A occludes window B if both are mapped, if A is
     higher in the global stacking order, and if the rectan­
     gle defined by the outside edges of A intersects the
     rectangle defined by the outside edges of B.  Note the
     distinction between occludes and obscures.  Also note
     that window borders are included in the calculation and
     that _I_n_p_u_t_O_n_l_y windows never obscure other windows but
     can occlude other windows.

PPaaddddiinngg

     Some padding bytes are inserted in the data stream to
     maintain alignment of the protocol requests on natural
     boundaries.  This increases ease of portability to some
     machine architectures.

PPaarreenntt wwiinnddooww

     If C is a child of P, then P is the parent of C.

PPaassssiivvee ggrraabb

     Grabbing a key or button is a passive grab.  The grab
     activates when the key or button is actually pressed.

PPiixxeell vvaalluuee

     A pixel is an N‐bit value, where N is the number of bit
     planes used in a particular window or pixmap (that is,
     is the depth of the window or pixmap).  A pixel in a
     window indexes a colormap to derive an actual color to
     be displayed.

PPiixxmmaapp

     A pixmap is a three‐dimensional array of bits.  A
     pixmap is normally thought of as a two‐dimensional
     array of pixels, where each pixel can be a value from 0
     to 2_N−1, and where N is the depth (z axis) of the
     pixmap.  A pixmap can also be thought of as a stack of
     N bitmaps.  A pixmap can only be used on the screen
     that it was created in.

PPllaannee

     When a pixmap or window is thought of as a stack of
     bitmaps, each bitmap is called a plane or bit plane.







                             667788





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


PPllaannee mmaasskk

     Graphics operations can be restricted to only affect a
     subset of bit planes of a destination.  A plane mask is
     a bit mask describing which planes are to be modified.
     The plane mask is stored in a graphics context.

PPooiinntteerr

     The pointer is the pointing device currently attached
     to the cursor and tracked on the screens.

PPooiinntteerr ggrraabbbbiinngg

     A client can actively grab control of the pointer.
     Then button and motion events will be sent to that
     client rather than the client the events would normally
     have been sent to.

PPooiinnttiinngg ddeevviiccee

     A pointing device is typically a mouse, tablet, or some
     other device with effective dimensional motion.  The
     core protocol defines only one visible cursor, which
     tracks whatever pointing device is attached as the
     pointer.

PPOOSSIIXX

     Portable Operating System Interface, ISO/IEC 9945‐1
     (IEEE Std 1003.1).

PPOOSSIIXX PPoorrttaabbllee FFiilleennaammee CChhaarraacctteerr SSeett

     The set of 65 characters which can be used in naming
     files on a POSIX‐compliant host that are correctly pro­
     cessed in all locales.  The set is:


     a..z A..Z 0..9 ._‐


PPrrooppeerrttyy

     Windows can have associated properties that consist of
     a name, a type, a data format, and some data.  The pro­
     tocol places no interpretation on properties.  They are
     intended as a general‐purpose naming mechanism for
     clients.  For example, clients might use properties to
     share information such as resize hints, program names,
     and icon formats with a window manager.






                             667799





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


PPrrooppeerrttyy lliisstt

     The property list of a window is the list of properties
     that have been defined for the window.

PPsseeuuddooCCoolloorr

     _P_s_e_u_d_o_C_o_l_o_r is a class of colormap in which a pixel
     value indexes the colormap entry to produce an indepen­
     dent RGB value; that is, the colormap is viewed as an
     array of triples (RGB values).  The RGB values can be
     changed dynamically.

RReeccttaannggllee

     A rectangle specified by [x,y,w,h] has an infinitely
     thin outline path with corners at [x,y], [x+w,y],
     [x+w,y+h], and [x, y+h].  When a rectangle is filled,
     the lower‐right edges are not drawn.  For example, if
     w=h=0, nothing would be drawn.  For w=h=1, a single
     pixel would be drawn.

RReeddiirreeccttiinngg ccoonnttrrooll

     Window managers (or client programs) may enforce window
     layout policy in various ways.  When a client attempts
     to change the size or position of a window, the opera­
     tion may be redirected to a specified client rather
     than the operation actually being performed.

RReeppllyy

     Information requested by a client program using the X
     protocol is sent back to the client with a reply.  Both
     events and replies are multiplexed on the same connec­
     tion.  Most requests do not generate replies, but some
     requests generate multiple replies.

RReeqquueesstt

     A command to the server is called a request.  It is a
     single block of data sent over a connection.

RReessoouurrccee

     Windows, pixmaps, cursors, fonts, graphics contexts,
     and colormaps are known as resources.  They all have
     unique identifiers associated with them for naming pur­
     poses.  The lifetime of a resource usually is bounded
     by the lifetime of the connection over which the
     resource was created.






                             668800





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


RRGGBB vvaalluueess

     RGB values are the red, green, and blue intensity val­
     ues that are used to define a color.  These values are
     always represented as 16‐bit, unsigned numbers, with 0
     the minimum intensity and 65535 the maximum intensity.
     The X server scales these values to match the display
     hardware.

RRoooott

     The root of a pixmap or graphics context is the same as
     the root of whatever drawable was used when the pixmap
     or GC was created.  The root of a window is the root
     window under which the window was created.

RRoooott wwiinnddooww

     Each screen has a root window covering it.  The root
     window cannot be reconfigured or unmapped, but other­
     wise it acts as a full‐fledged window.  A root window
     has no parent.

SSaavvee sseett

     The save set of a client is a list of other clients’
     windows that, if they are inferiors of one of the
     client’s windows at connection close, should not be
     destroyed and that should be remapped if currently
     unmapped.  Save sets are typically used by window man­
     agers to avoid lost windows if the manager should ter­
     minate abnormally.

SSccaannlliinnee

     A scanline is a list of pixel or bit values viewed as a
     horizontal row (all values having the same y coordi­
     nate) of an image, with the values ordered by increas­
     ing the x coordinate.

SSccaannlliinnee oorrddeerr

     An image represented in scanline order contains scan­
     lines ordered by increasing the y coordinate.

SSccrreeeenn

     A server can provide several independent screens, which
     typically have physically independent monitors.  This
     would be the expected configuration when there is only
     a single keyboard and pointer shared among the screens.
     A _S_c_r_e_e_n structure contains the information about that
     screen and is linked to the _D_i_s_p_l_a_y structure.




                             668811





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


SSeelleeccttiioonn

     A selection can be thought of as an indirect property
     with dynamic type.  That is, rather than having the
     property stored in the X server, it is maintained by
     some client (the owner).  A selection is global and is
     thought of as belonging to the user and being main­
     tained by clients, rather than being private to a par­
     ticular window subhierarchy or a particular set of
     clients.  When a client asks for the contents of a
     selection, it specifies a selection target type, which
     can be used to control the transmitted representation
     of the contents.  For example, if the selection is
     ‘‘the last thing the user clicked on,’’ and that is
     currently an image, then the target type might specify
     whether the contents of the image should be sent in XY
     format or Z format.

     The target type can also be used to control the class
     of contents transmitted; for example, asking for the
     ‘‘looks’’ (fonts, line spacing, indentation, and so
     forth) of a paragraph selection, rather than the text
     of the paragraph.  The target type can also be used for
     other purposes.  The protocol does not constrain the
     semantics.

SSeerrvveerr

     The server, which is also referred to as the X server,
     provides the basic windowing mechanism.  It handles IPC
     connections from clients, multiplexes graphics requests
     onto the screens, and demultiplexes input back to the
     appropriate clients.

SSeerrvveerr ggrraabbbbiinngg

     The server can be grabbed by a single client for exclu­
     sive use.  This prevents processing of any requests
     from other client connections until the grab is com­
     pleted.  This is typically only a transient state for
     such things as rubber‐banding, pop‐up menus, or execut­
     ing requests indivisibly.

SShhiifftt sseeqquueennccee

     ISO2022 defines control characters and escape sequences
     which temporarily (single shift) or permanently (lock­
     ing shift) cause a different character set to be in
     effect (‘‘invoking’’ a character set).








                             668822





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


SSiibblliinngg

     Children of the same parent window are known as sibling
     windows.

SSttaacckkiinngg oorrddeerr

     Sibling windows, similar to sheets of paper on a desk,
     can stack on top of each other.  Windows above both
     obscure and occlude lower windows.  The relationship
     between sibling windows is known as the stacking order.

SSttaattee‐‐ddeeppeennddeenntt eennccooddiinngg

     An encoding in which an invocation of a charset can
     apply to multiple characters in sequence.  A state‐
     dependent encoding begins in an ‘‘initial state’’ and
     enters other ‘‘shift states’’ when specific ‘‘shift
     sequences’’ are encountered in the byte sequence.  In
     ISO2022 terms, this means use of locking shifts, not
     single shifts.

SSttaattee‐‐iinnddeeppeennddeenntt eennccooddiinngg

     Any encoding in which the invocations of the charsets
     are fixed, or span only a single character.  In ISO2022
     terms, this means use of at most single shifts, not
     locking shifts.

SSttaattiiccCCoolloorr

     _S_t_a_t_i_c_C_o_l_o_r can be viewed as a degenerate case of _P_s_e_u_­
     _d_o_C_o_l_o_r in which the RGB values are predefined and
     read‐only.

SSttaattiiccGGrraayy

     _S_t_a_t_i_c_G_r_a_y can be viewed as a degenerate case of
     _G_r_a_y_S_c_a_l_e in which the gray values are predefined and
     read‐only.  The values are typically linear or near‐
     linear increasing ramps.

SSttaattuuss

     Many Xlib functions return a success status.  If the
     function does not succeed, however, its arguments are
     not disturbed.

SSttiippppllee

     A stipple pattern is a bitmap that is used to tile a
     region to serve as an additional clip mask for a fill
     operation with the foreground color.




                             668833





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


SSTTRRIINNGG eennccooddiinngg

     Latin‐1, plus tab and newline.

SSttrriinngg EEqquuiivvaalleennccee

     Two ISO Latin‐1 STRING8 values are considered equal if
     they are the same length and if corresponding bytes are
     either equal or are equivalent as follows:  decimal
     values 65 to 90 inclusive (characters ‘‘A’’ to ‘‘Z’’)
     are pairwise equivalent to decimal values 97 to 122
     inclusive (characters ‘‘a’’ to ‘‘z’’), decimal values
     192 to 214 inclusive (characters ‘‘A grave’’ to ‘‘O
     diaeresis’’) are pairwise equivalent to decimal values
     224 to 246 inclusive (characters ‘‘a grave’’ to ‘‘o
     diaeresis’’), and decimal values 216 to 222 inclusive
     (characters ‘‘O oblique’’ to ‘‘THORN’’) are pairwise
     equivalent to decimal values 246 to 254 inclusive
     (characters ‘‘o oblique’’ to ‘‘thorn’’).

TTiillee

     A pixmap can be replicated in two dimensions to tile a
     region.  The pixmap itself is also known as a tile.

TTiimmeessttaammpp

     A timestamp is a time value expressed in milliseconds.
     It is typically the time since the last server reset.
     Timestamp values wrap around (after about 49.7 days).
     The server, given its current time is represented by
     timestamp T, always interprets timestamps from clients
     by treating half of the timestamp space as being ear­
     lier in time than T and half of the timestamp space as
     being later in time than T.  One timestamp value, rep­
     resented by the constant _C_u_r_r_e_n_t_T_i_m_e, is never gener­
     ated by the server.  This value is reserved for use in
     requests to represent the current server time.

TTrruueeCCoolloorr

     _T_r_u_e_C_o_l_o_r can be viewed as a degenerate case of _D_i_r_e_c_t_­
     _C_o_l_o_r in which the subfields in the pixel value
     directly encode the corresponding RGB values.  That is,
     the colormap has predefined read‐only RGB values.  The
     values are typically linear or near‐linear increasing
     ramps.










                             668844





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


TTyyppee

     A type is an arbitrary atom used to identify the inter­
     pretation of property data.  Types are completely unin­
     terpreted by the server.  They are solely for the bene­
     fit of clients.  X predefines type atoms for many fre­
     quently used types, and clients also can define new
     types.

VViieewwaabbllee

     A window is viewable if it and all of its ancestors are
     mapped.  This does not imply that any portion of the
     window is actually visible.  Graphics requests can be
     performed on a window when it is not viewable, but out­
     put will not be retained unless the server is maintain­
     ing backing store.

VViissiibbllee

     A region of a window is visible if someone looking at
     the screen can actually see it; that is, the window is
     viewable and the region is not occluded by any other
     window.

WWhhiitteessppaaccee

     Any spacing character.  On implementations that conform
     to the ANSI C library, whitespace is any character for
     which _i_s_s_p_a_c_e returns true.

WWiinnddooww ggrraavviittyy

     When windows are resized, subwindows may be reposi­
     tioned automatically relative to some position in the
     window.  This attraction of a subwindow to some part of
     its parent is known as window gravity.

WWiinnddooww mmaannaaggeerr

     Manipulation of windows on the screen and much of the
     user interface (policy) is typically provided by a win­
     dow manager client.














                             668855





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


XX PPoorrttaabbllee CChhaarraacctteerr SSeett

     A basic set of 97 characters which are assumed to exist
     in all locales supported by Xlib.  This set contains
     the following characters:


a..z A..Z 0..9 !"#$%&’()*+,‐./:;<=>?@[\]^_‘{|}~ <space>,
<tab>, and <newline>


     This is the left/lower half (also called the G0 set) of
     the graphic character set of ISO8859‐1 plus <space>,
     <tab>, and <newline>.  It is also the set of graphic
     characters in 7‐bit ASCII plus the same three control
     characters.  The actual encoding of these characters on
     the host is system dependent; see the Host Portable
     Character Encoding.

XXLLFFDD

     The X Logical Font Description Conventions that define
     a standard syntax for structured font names.

XXYY ffoorrmmaatt

     The data for a pixmap is said to be in XY format if it
     is organized as a set of bitmaps representing individ­
     ual bit planes with the planes appearing from most‐sig­
     nificant to least‐significant bit order.

ZZ ffoorrmmaatt

     The data for a pixmap is said to be in Z format if it
     is organized as a set of pixel values in scanline
     order.

RReeffeerreenncceess

ANSI Programming Language ‐ C: ANSI X3.159‐1989, December
14, 1989.

Draft Proposed Multibyte Extension of ANSI C, Draft 1.1,
November 30, 1989, SC22/C WG/SWG IPSJ/ITSCJ Japan.

ISO2022: Information processing ‐ ISO 7‐bit and 8‐bit coded
character sets ‐ Code extension techniques.

ISO8859‐1: Information processing ‐ 8‐bit single‐byte coded
graphic character sets ‐ Part 1: Latin alphabet No. 1.

POSIX: Information Technology ‐ Portable Operating System
Interface (POSIX) ‐ Part 1: System Application Program
Interface (API) [C Language], ISO/IEC 9945‐1.



                             668866





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22


Text of ISO/IEC/DIS 9541‐1, Information Processing ‐ Font
Information Interchange ‐ Part 1:  Architecture.

X/Open Portability Guide, Issue 3, December 1988 (XPG3),
X/Open Company, Ltd, Prentice‐Hall, Inc. 1989. ISBN
0‐13‐685835‐8.  (See especially Volume 3:  XSI Supplementary
Definitions.)


















































                             668877





XXlliibb −− CC LLiibbrraarryy                                lliibbXX1111 11..33..22



























































                             668888









                     TTaabbllee ooff CCoonntteennttss


Table of Contents  . . . . . . . . . . . . . . . . . . .  ii
Acknowledgments  . . . . . . . . . . . . . . . . . . . . iii
Chapter 1: Introduction to Xlib  . . . . . . . . . . . .   1
1.1. Overview of the X Window System . . . . . . . . . .   2
1.2. Errors  . . . . . . . . . . . . . . . . . . . . . .   4
1.3. Standard Header Files . . . . . . . . . . . . . . .   4
1.4. Generic Values and Types  . . . . . . . . . . . . .   6
1.5. Naming and Argument Conventions within Xlib . . . .   7
1.6. Programming Considerations  . . . . . . . . . . . .   8
1.7. Character Sets and Encodings  . . . . . . . . . . .   8
1.8. Formatting Conventions  . . . . . . . . . . . . . .   9
Chapter 2: Display Functions . . . . . . . . . . . . . .  11
2.1. Opening the Display . . . . . . . . . . . . . . . .  11
2.2. Obtaining Information about the Display, Image
Formats, or Screens  . . . . . . . . . . . . . . . . . .  13
2.2.1. Display Macros  . . . . . . . . . . . . . . . . .  14
2.2.2. Image Format Functions and Macros . . . . . . . .  23
2.2.3. Screen Information Macros . . . . . . . . . . . .  27
2.3. Generating a NoOperation Protocol Request . . . . .  33
2.4. Freeing Client‐Created Data . . . . . . . . . . . .  34
2.5. Closing the Display . . . . . . . . . . . . . . . .  34
2.6. Using X Server Connection Close Operations  . . . .  35
2.7. Using Xlib with Threads . . . . . . . . . . . . . .  37
2.8. Using Internal Connections  . . . . . . . . . . . .  38
Chapter 3: Window Functions  . . . . . . . . . . . . . .  42
3.1. Visual Types  . . . . . . . . . . . . . . . . . . .  42
3.2. Window Attributes . . . . . . . . . . . . . . . . .  44
3.2.1. Background Attribute  . . . . . . . . . . . . . .  48
3.2.2. Border Attribute  . . . . . . . . . . . . . . . .  49
3.2.3. Gravity Attributes  . . . . . . . . . . . . . . .  50
3.2.4. Backing Store Attribute . . . . . . . . . . . . .  51
3.2.5. Save Under Flag . . . . . . . . . . . . . . . . .  52
3.2.6. Backing Planes and Backing Pixel Attributes
 . . . . . . . . . . . . . . . . . . . . . . . . . . . .  52
3.2.7. Event Mask and Do Not Propagate Mask
Attributes . . . . . . . . . . . . . . . . . . . . . . .  53
3.2.8. Override Redirect Flag  . . . . . . . . . . . . .  53
3.2.9. Colormap Attribute  . . . . . . . . . . . . . . .  53
3.2.10. Cursor Attribute . . . . . . . . . . . . . . . .  54
3.3. Creating Windows  . . . . . . . . . . . . . . . . .  54
3.4. Destroying Windows  . . . . . . . . . . . . . . . .  59
3.5. Mapping Windows . . . . . . . . . . . . . . . . . .  60
3.6. Unmapping Windows . . . . . . . . . . . . . . . . .  62
3.7. Configuring Windows . . . . . . . . . . . . . . . .  63
3.8. Changing Window Stacking Order  . . . . . . . . . .  70
3.9. Changing Window Attributes  . . . . . . . . . . . .  74
Chapter 4: Window Information Functions  . . . . . . . .  81
4.1. Obtaining Window Information  . . . . . . . . . . .  81
4.2. Translating Screen Coordinates  . . . . . . . . . .  87
4.3. Properties and Atoms  . . . . . . . . . . . . . . .  89












4.4. Obtaining and Changing Window Properties  . . . . .  94
4.5. Selections  . . . . . . . . . . . . . . . . . . . . 101
Chapter 5: Pixmap and Cursor Functions . . . . . . . . . 105
5.1. Creating and Freeing Pixmaps  . . . . . . . . . . . 105
5.2. Creating, Recoloring, and Freeing Cursors . . . . . 106
Chapter 6: Color Management Functions  . . . . . . . . . 112
6.1. Color Structures  . . . . . . . . . . . . . . . . . 113
6.2. Color Strings . . . . . . . . . . . . . . . . . . . 117
6.2.1. RGB Device String Specification . . . . . . . . . 118
6.2.2. RGB Intensity String Specification  . . . . . . . 119
6.2.3. Device‐Independent String Specifications  . . . . 119
6.3. Color Conversion Contexts and Gamut Mapping . . . . 120
6.4. Creating, Copying, and Destroying Colormaps . . . . 121
6.5. Mapping Color Names to Values . . . . . . . . . . . 123
6.6. Allocating and Freeing Color Cells  . . . . . . . . 127
6.7. Modifying and Querying Colormap Cells . . . . . . . 135
6.8. Color Conversion Context Functions  . . . . . . . . 142
6.8.1. Getting and Setting the Color Conversion Con­
text of a Colormap . . . . . . . . . . . . . . . . . . . 143
6.8.2. Obtaining the Default Color Conversion Con­
text . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.8.3. Color Conversion Context Macros . . . . . . . . . 144
6.8.4. Modifying Attributes of a Color Conversion
Context  . . . . . . . . . . . . . . . . . . . . . . . . 146
6.8.5. Creating and Freeing a Color Conversion Con­
text . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.9. Converting between Color Spaces . . . . . . . . . . 150
6.10. Callback Functions . . . . . . . . . . . . . . . . 151
6.10.1. Prototype Gamut Compression Procedure  . . . . . 152
6.10.2. Supplied Gamut Compression Procedures  . . . . . 154
6.10.3. Prototype White Point Adjustment Procedure
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.10.4. Supplied White Point Adjustment Procedures
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.11. Gamut Querying Functions . . . . . . . . . . . . . 159
6.11.1. Red, Green, and Blue Queries . . . . . . . . . . 160
6.11.2. CIELab Queries . . . . . . . . . . . . . . . . . 163
6.11.3. CIELuv Queries . . . . . . . . . . . . . . . . . 167
6.11.4. TekHVC Queries . . . . . . . . . . . . . . . . . 171
6.12. Color Management Extensions  . . . . . . . . . . . 176
6.12.1. Color Spaces . . . . . . . . . . . . . . . . . . 177
6.12.2. Adding Device‐Independent Color Spaces . . . . . 177
6.12.3. Querying Color Space Format and Prefix . . . . . 178
6.12.4. Creating Additional Color Spaces . . . . . . . . 178
6.12.5. Parse String Callback  . . . . . . . . . . . . . 180
6.12.6. Color Specification Conversion Callback  . . . . 180
6.12.7. Function Sets  . . . . . . . . . . . . . . . . . 183
6.12.8. Adding Function Sets . . . . . . . . . . . . . . 183
6.12.9. Creating Additional Function Sets  . . . . . . . 184
Chapter 7: Graphics Context Functions  . . . . . . . . . 187
7.1. Manipulating Graphics Context/State . . . . . . . . 187
7.2. Using Graphics Context Convenience Routines . . . . 201
7.2.1. Setting the Foreground, Background, Function,
or Plane Mask  . . . . . . . . . . . . . . . . . . . . . 201












7.2.2. Setting the Line Attributes and Dashes  . . . . . 204
7.2.3. Setting the Fill Style and Fill Rule  . . . . . . 207
7.2.4. Setting the Fill Tile and Stipple . . . . . . . . 207
7.2.5. Setting the Current Font  . . . . . . . . . . . . 212
7.2.6. Setting the Clip Region . . . . . . . . . . . . . 212
7.2.7. Setting the Arc Mode, Subwindow Mode, and
Graphics Exposure  . . . . . . . . . . . . . . . . . . . 215
Chapter 8: Graphics Functions  . . . . . . . . . . . . . 217
8.1. Clearing Areas  . . . . . . . . . . . . . . . . . . 217
8.2. Copying Areas . . . . . . . . . . . . . . . . . . . 219
8.3. Drawing Points, Lines, Rectangles, and Arcs . . . . 222
8.3.1. Drawing Single and Multiple Points  . . . . . . . 223
8.3.2. Drawing Single and Multiple Lines . . . . . . . . 225
8.3.3. Drawing Single and Multiple Rectangles  . . . . . 227
8.3.4. Drawing Single and Multiple Arcs  . . . . . . . . 229
8.4. Filling Areas . . . . . . . . . . . . . . . . . . . 232
8.4.1. Filling Single and Multiple Rectangles  . . . . . 233
8.4.2. Filling a Single Polygon  . . . . . . . . . . . . 234
8.4.3. Filling Single and Multiple Arcs  . . . . . . . . 236
8.5. Font Metrics  . . . . . . . . . . . . . . . . . . . 237
8.5.1. Loading and Freeing Fonts . . . . . . . . . . . . 242
8.5.2. Obtaining and Freeing Font Names and Informa­
tion . . . . . . . . . . . . . . . . . . . . . . . . . . 246
8.5.3. Computing Character String Sizes  . . . . . . . . 248
8.5.4. Computing Logical Extents . . . . . . . . . . . . 249
8.5.5. Querying Character String Sizes . . . . . . . . . 252
8.6. Drawing Text  . . . . . . . . . . . . . . . . . . . 254
8.6.1. Drawing Complex Text  . . . . . . . . . . . . . . 255
8.6.2. Drawing Text Characters . . . . . . . . . . . . . 257
8.6.3. Drawing Image Text Characters . . . . . . . . . . 258
8.7. Transferring Images between Client and Server
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Chapter 9: Window and Session Manager Functions  . . . . 269
9.1. Changing the Parent of a Window . . . . . . . . . . 269
9.2. Controlling the Lifetime of a Window  . . . . . . . 271
9.3. Managing Installed Colormaps  . . . . . . . . . . . 272
9.4. Setting and Retrieving the Font Search Path . . . . 275
9.5. Grabbing the Server . . . . . . . . . . . . . . . . 276
9.6. Killing Clients . . . . . . . . . . . . . . . . . . 277
9.7. Controlling the Screen Saver  . . . . . . . . . . . 278
9.8. Controlling Host Access . . . . . . . . . . . . . . 281
9.8.1. Adding, Getting, or Removing Hosts  . . . . . . . 281
9.8.2. Changing, Enabling, or Disabling Access Con­
trol . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Chapter 10: Events . . . . . . . . . . . . . . . . . . . 287
10.1. Event Types  . . . . . . . . . . . . . . . . . . . 287
10.2. Event Structures . . . . . . . . . . . . . . . . . 288
10.3. Event Masks  . . . . . . . . . . . . . . . . . . . 291
10.4. Event Processing Overview  . . . . . . . . . . . . 292
10.5. Keyboard and Pointer Events  . . . . . . . . . . . 294
10.5.1. Pointer Button Events  . . . . . . . . . . . . . 294
10.5.2. Keyboard and Pointer Events  . . . . . . . . . . 295
10.6. Window Entry/Exit Events . . . . . . . . . . . . . 299
10.6.1. Normal Entry/Exit Events . . . . . . . . . . . . 301












10.6.2. Grab and Ungrab Entry/Exit Events  . . . . . . . 303
10.7. Input Focus Events . . . . . . . . . . . . . . . . 304
10.7.1. Normal Focus Events and Focus Events While
Grabbed  . . . . . . . . . . . . . . . . . . . . . . . . 305
10.7.2. Focus Events Generated by Grabs  . . . . . . . . 309
10.8. Key Map State Notification Events  . . . . . . . . 309
10.9. Exposure Events  . . . . . . . . . . . . . . . . . 310
10.9.1. Expose Events  . . . . . . . . . . . . . . . . . 310
10.9.2. GraphicsExpose and NoExpose Events . . . . . . . 311
10.10. Window State Change Events  . . . . . . . . . . . 313
10.10.1. CirculateNotify Events  . . . . . . . . . . . . 313
10.10.2. ConfigureNotify Events  . . . . . . . . . . . . 314
10.10.3. CreateNotify Events . . . . . . . . . . . . . . 315
10.10.4. DestroyNotify Events  . . . . . . . . . . . . . 316
10.10.5. GravityNotify Events  . . . . . . . . . . . . . 317
10.10.6. MapNotify Events  . . . . . . . . . . . . . . . 318
10.10.7. MappingNotify Events  . . . . . . . . . . . . . 318
10.10.8. ReparentNotify Events . . . . . . . . . . . . . 319
10.10.9. UnmapNotify Events  . . . . . . . . . . . . . . 320
10.10.10. VisibilityNotify Events  . . . . . . . . . . . 321
10.11. Structure Control Events  . . . . . . . . . . . . 322
10.11.1. CirculateRequest Events . . . . . . . . . . . . 323
10.11.2. ConfigureRequest Events . . . . . . . . . . . . 323
10.11.3. MapRequest Events . . . . . . . . . . . . . . . 324
10.11.4. ResizeRequest Events  . . . . . . . . . . . . . 325
10.12. Colormap State Change Events  . . . . . . . . . . 326
10.13. Client Communication Events . . . . . . . . . . . 327
10.13.1. ClientMessage Events  . . . . . . . . . . . . . 327
10.13.2. PropertyNotify Events . . . . . . . . . . . . . 328
10.13.3. SelectionClear Events . . . . . . . . . . . . . 328
10.13.4. SelectionRequest Events . . . . . . . . . . . . 329
10.13.5. SelectionNotify Events  . . . . . . . . . . . . 330
Chapter 11: Event Handling Functions . . . . . . . . . . 332
11.1. Selecting Events . . . . . . . . . . . . . . . . . 332
11.2. Handling the Output Buffer . . . . . . . . . . . . 333
11.3. Event Queue Management . . . . . . . . . . . . . . 335
11.4. Manipulating the Event Queue . . . . . . . . . . . 336
11.4.1. Returning the Next Event . . . . . . . . . . . . 336
11.4.2. Selecting Events Using a Predicate Procedure
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
11.4.3. Selecting Events Using a Window or Event
Mask . . . . . . . . . . . . . . . . . . . . . . . . . . 340
11.5. Putting an Event Back into the Queue . . . . . . . 345
11.6. Sending Events to Other Applications . . . . . . . 345
11.7. Getting Pointer Motion History . . . . . . . . . . 347
11.8. Handling Protocol Errors . . . . . . . . . . . . . 349
11.8.1. Enabling or Disabling Synchronization  . . . . . 349
11.8.2. Using the Default Error Handlers . . . . . . . . 350
Chapter 12: Input Device Functions . . . . . . . . . . . 356
12.1. Pointer Grabbing . . . . . . . . . . . . . . . . . 356
12.2. Keyboard Grabbing  . . . . . . . . . . . . . . . . 364
12.3. Resuming Event Processing  . . . . . . . . . . . . 369
12.4. Moving the Pointer . . . . . . . . . . . . . . . . 372
12.5. Controlling Input Focus  . . . . . . . . . . . . . 373












12.6. Manipulating the Keyboard and Pointer Settings
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
12.7. Manipulating the Keyboard Encoding . . . . . . . . 383
Chapter 13: Locales and Internationalized Text Func­
tions  . . . . . . . . . . . . . . . . . . . . . . . . . 393
13.1. X Locale Management  . . . . . . . . . . . . . . . 394
13.2. Locale and Modifier Dependencies . . . . . . . . . 396
13.3. Variable Argument Lists  . . . . . . . . . . . . . 398
13.4. Output Methods . . . . . . . . . . . . . . . . . . 399
13.4.1. Output Method Overview . . . . . . . . . . . . . 399
13.4.2. Output Method Functions  . . . . . . . . . . . . 400
13.4.3. X Output Method Values . . . . . . . . . . . . . 403
13.4.3.1. Required Char Set  . . . . . . . . . . . . . . 403
13.4.3.2. Query Orientation  . . . . . . . . . . . . . . 404
13.4.3.3. Directional Dependent Drawing  . . . . . . . . 404
13.4.3.4. Context Dependent Drawing  . . . . . . . . . . 405
13.4.4. Output Context Functions . . . . . . . . . . . . 405
13.4.5. Output Context Values  . . . . . . . . . . . . . 408
13.4.5.1. Base Font Name . . . . . . . . . . . . . . . . 409
13.4.5.2. Missing CharSet  . . . . . . . . . . . . . . . 410
13.4.5.3. Default String . . . . . . . . . . . . . . . . 410
13.4.5.4. Orientation  . . . . . . . . . . . . . . . . . 410
13.4.5.5. Resource Name and Class  . . . . . . . . . . . 411
13.4.5.6. Font Info  . . . . . . . . . . . . . . . . . . 411
13.4.5.7. OM Automatic . . . . . . . . . . . . . . . . . 412
13.4.6. Creating and Freeing a Font Set  . . . . . . . . 412
13.4.7. Obtaining Font Set Metrics . . . . . . . . . . . 418
13.4.8. Drawing Text Using Font Sets . . . . . . . . . . 427
13.5. Input Methods  . . . . . . . . . . . . . . . . . . 431
13.5.1. Input Method Overview  . . . . . . . . . . . . . 431
13.5.1.1. Input Method Architecture  . . . . . . . . . . 433
13.5.1.2. Input Contexts . . . . . . . . . . . . . . . . 435
13.5.1.3. Getting Keyboard Input . . . . . . . . . . . . 436
13.5.1.4. Focus Management . . . . . . . . . . . . . . . 436
13.5.1.5. Geometry Management  . . . . . . . . . . . . . 437
13.5.1.6. Event Filtering  . . . . . . . . . . . . . . . 438
13.5.1.7. Callbacks  . . . . . . . . . . . . . . . . . . 439
13.5.1.8. Visible Position Feedback Masks  . . . . . . . 439
13.5.1.9. Preedit String Management  . . . . . . . . . . 440
13.5.2. Input Method Management  . . . . . . . . . . . . 442
13.5.2.1. Hot Keys . . . . . . . . . . . . . . . . . . . 443
13.5.2.2. Preedit State Operation  . . . . . . . . . . . 444
13.5.3. Input Method Functions . . . . . . . . . . . . . 444
13.5.4. Input Method Values  . . . . . . . . . . . . . . 449
13.5.4.1. Query Input Style  . . . . . . . . . . . . . . 450
13.5.4.2. Resource Name and Class  . . . . . . . . . . . 452
13.5.4.3. Destroy Callback . . . . . . . . . . . . . . . 452
13.5.4.4. Query IM/IC Values List  . . . . . . . . . . . 453
13.5.4.5. Visible Position . . . . . . . . . . . . . . . 453
13.5.4.6. Preedit Callback Behavior  . . . . . . . . . . 454
13.5.5. Input Context Functions  . . . . . . . . . . . . 454
13.5.6. Input Context Values . . . . . . . . . . . . . . 459
13.5.6.1. Input Style  . . . . . . . . . . . . . . . . . 461
13.5.6.2. Client Window  . . . . . . . . . . . . . . . . 461












13.5.6.3. Focus Window . . . . . . . . . . . . . . . . . 461
13.5.6.4. Resource Name and Class  . . . . . . . . . . . 462
13.5.6.5. Geometry Callback  . . . . . . . . . . . . . . 462
13.5.6.6. Filter Events  . . . . . . . . . . . . . . . . 462
13.5.6.7. Destroy Callback . . . . . . . . . . . . . . . 463
13.5.6.8. String Conversion Callback . . . . . . . . . . 463
13.5.6.9. String Conversion  . . . . . . . . . . . . . . 463
13.5.6.10. Reset State . . . . . . . . . . . . . . . . . 464
13.5.6.11. Hot Keys  . . . . . . . . . . . . . . . . . . 465
13.5.6.12. Hot Key State . . . . . . . . . . . . . . . . 466
13.5.6.13. Preedit and Status Attributes . . . . . . . . 466
13.5.6.13.1. Area  . . . . . . . . . . . . . . . . . . . 466
13.5.6.13.2. Area Needed . . . . . . . . . . . . . . . . 467
13.5.6.13.3. Spot Location . . . . . . . . . . . . . . . 467
13.5.6.13.4. Colormap  . . . . . . . . . . . . . . . . . 468
13.5.6.13.5. Foreground and Background . . . . . . . . . 468
13.5.6.13.6. Background Pixmap . . . . . . . . . . . . . 468
13.5.6.13.7. Font Set  . . . . . . . . . . . . . . . . . 468
13.5.6.13.8. Line Spacing  . . . . . . . . . . . . . . . 469
13.5.6.13.9. Cursor  . . . . . . . . . . . . . . . . . . 469
13.5.6.13.10. Preedit State  . . . . . . . . . . . . . . 469
13.5.6.13.11. Preedit State Notify Callback  . . . . . . 470
13.5.6.13.12. Preedit and Status Callbacks . . . . . . . 470
13.5.7. Input Method Callback Semantics  . . . . . . . . 471
13.5.7.1. Geometry Callback  . . . . . . . . . . . . . . 472
13.5.7.2. Destroy Callback . . . . . . . . . . . . . . . 473
13.5.7.3. String Conversion Callback . . . . . . . . . . 473
13.5.7.4. Preedit State Callbacks  . . . . . . . . . . . 476
13.5.7.5. Preedit Draw Callback  . . . . . . . . . . . . 477
13.5.7.6. Preedit Caret Callback . . . . . . . . . . . . 481
13.5.7.7. Status Callbacks . . . . . . . . . . . . . . . 483
13.5.8. Event Filtering  . . . . . . . . . . . . . . . . 485
13.5.9. Getting Keyboard Input . . . . . . . . . . . . . 486
13.5.10. Input Method Conventions  . . . . . . . . . . . 489
13.5.10.1. Client Conventions  . . . . . . . . . . . . . 489
13.5.10.2. Synchronization Conventions . . . . . . . . . 489
13.6. String Constants . . . . . . . . . . . . . . . . . 489
Chapter 14: Inter‐Client Communication Functions . . . . 492
14.1. Client to Window Manager Communication . . . . . . 494
14.1.1. Manipulating Top‐Level Windows . . . . . . . . . 494
14.1.2. Converting String Lists  . . . . . . . . . . . . 497
14.1.3. Setting and Reading Text Properties  . . . . . . 503
14.1.4. Setting and Reading the WM_NAME Property . . . . 504
14.1.5. Setting and Reading the WM_ICON_NAME Prop­
erty . . . . . . . . . . . . . . . . . . . . . . . . . . 507
14.1.6. Setting and Reading the WM_HINTS Property
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
14.1.7. Setting and Reading the WM_NORMAL_HINTS
Property . . . . . . . . . . . . . . . . . . . . . . . . 512
14.1.8. Setting and Reading the WM_CLASS Property
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
14.1.9. Setting and Reading the WM_TRANSIENT_FOR
Property . . . . . . . . . . . . . . . . . . . . . . . . 520
14.1.10. Setting and Reading the WM_PROTOCOLS Prop­












erty . . . . . . . . . . . . . . . . . . . . . . . . . . 521
14.1.11. Setting and Reading the WM_COLORMAP_WINDOWS
Property . . . . . . . . . . . . . . . . . . . . . . . . 522
14.1.12. Setting and Reading the WM_ICON_SIZE Prop­
erty . . . . . . . . . . . . . . . . . . . . . . . . . . 524
14.1.13. Using Window Manager Convenience Functions
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
14.2. Client to Session Manager Communication  . . . . . 530
14.2.1. Setting and Reading the WM_COMMAND Property
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
14.2.2. Setting and Reading the WM_CLIENT_MACHINE
Property . . . . . . . . . . . . . . . . . . . . . . . . 531
14.3. Standard Colormaps . . . . . . . . . . . . . . . . 532
14.3.1. Standard Colormap Properties and Atoms . . . . . 536
14.3.2. Setting and Obtaining Standard Colormaps . . . . 537
Chapter 15: Resource Manager Functions . . . . . . . . . 541
15.1. Resource File Syntax . . . . . . . . . . . . . . . 542
15.2. Resource Manager Matching Rules  . . . . . . . . . 544
15.3. Quarks . . . . . . . . . . . . . . . . . . . . . . 545
15.4. Creating and Storing Databases . . . . . . . . . . 549
15.5. Merging Resource Databases . . . . . . . . . . . . 553
15.6. Looking Up Resources . . . . . . . . . . . . . . . 554
15.7. Storing into a Resource Database . . . . . . . . . 558
15.8. Enumerating Database Entries . . . . . . . . . . . 562
15.9. Parsing Command Line Options . . . . . . . . . . . 564
Chapter 16: Application Utility Functions  . . . . . . . 567
16.1. Using Keyboard Utility Functions . . . . . . . . . 567
16.1.1. KeySym Classification Macros . . . . . . . . . . 571
16.2. Using Latin‐1 Keyboard Event Functions . . . . . . 572
16.3. Allocating Permanent Storage . . . . . . . . . . . 574
16.4. Parsing the Window Geometry  . . . . . . . . . . . 575
16.5. Manipulating Regions . . . . . . . . . . . . . . . 577
16.5.1. Creating, Copying, or Destroying Regions . . . . 577
16.5.2. Moving or Shrinking Regions  . . . . . . . . . . 579
16.5.3. Computing with Regions . . . . . . . . . . . . . 579
16.5.4. Determining if Regions Are Empty or Equal
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
16.5.5. Locating a Point or a Rectangle in a Region
 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
16.6. Using Cut Buffers  . . . . . . . . . . . . . . . . 583
16.7. Determining the Appropriate Visual Type  . . . . . 586
16.8. Manipulating Images  . . . . . . . . . . . . . . . 589
16.9. Manipulating Bitmaps . . . . . . . . . . . . . . . 593
16.10. Using the Context Manager . . . . . . . . . . . . 598
Appendix A: Xlib Functions and Protocol Requests . . . . 602
Appendix B:  X Font Cursors  . . . . . . . . . . . . . . 614
Appendix C: Extensions . . . . . . . . . . . . . . . . . 615
Appendix D: Compatibility Functions  . . . . . . . . . . 649
Glossary . . . . . . . . . . . . . . . . . . . . . . . . 666
Index  . . . . . . . . . . . . . . . . . . . . . . . . . 689










