














       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 CCoonnvveennttiioonnss MMaannuuaall

                        VVeerrssiioonn 22..00

                   XX CCoonnssoorrttiiuum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 66






                      David Rosenthal
                   Sun Microsystems, Inc.


            Version 2 edited by Stuart W. Marks
                       SunSoft, Inc.
















































X Window System is a trademark of X Consortium, Inc.


Copyright  1988, 1991, 1993, 1994 X Consortium

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 X Con
sortium shall not be used in advertising or otherwise to
promote the sale, use or other dealings in this Software
without prior written authorization from the X Consortium.



Copyright  1987, 1988, 1989, 1993, 1994 Sun Microsystems,
Inc.

Permission to use, copy, modify, and distribute this docu
mentation for any purpose and without fee is hereby granted,
provided that the above copyright notice and this permission
notice appear in all copies.  Sun Microsystems makes no rep
resentations about the suitability for any purpose of the
information in this document.  This documentation is pro
vided as is without express or implied warranty.



                             ii

































































                             vi










                   PPrreeffaaccee ttoo VVeerrssiioonn 22..00



The goal of the ICCCM Version 2.0 effort was to add new
facilities, to fix problems with earlier drafts, and to
improve readability and understandability, while maintaining
compatibility with the earlier versions.  This document is
the product of over two years of discussion among the mem
bers of the X Consortium's wwmmttaallkk working group.  The fol
lowing people deserve thanks for their contributions:


     Gabe Beged-Dov                Bill Janssen
     Chan Benson                   Vania Joloboff
     Jordan Brown                  Phil Karlton
     Larry Cable                   Kaleb Keithley
     Ellis Cohen                   Mark Manasse
     Donna Converse                Ralph Mor
     Brian Cripe                   Todd Newman
     Susan Dahlberg                Bob Scheifler
     Peter Daifuku                 Keith Taylor
     Andrew deBlois                Jim VanGilder
     Clive Feather                 Mike Wexler
     Stephen Gildea                Michael Yee
     Christian Jacobi


It has been a privilege for me to work with this fine group
of people.

Stuart W. Marks
December 1993






















                             vii










                   PPrreeffaaccee ttoo VVeerrssiioonn 11..11



David Rosenthal had overall architectural responsibility for
the conventions defined in this document; he wrote most of
the text and edited the document, but its the development
has been a communal effort.  The details were thrashed out
in meetings at the January 1988 MIT X Conference and at the
1988 Summer Usenix conference, and through months (and
megabytes) of argument on the _w_m_t_a_l_k mail alias.  Thanks are
due to everyone who contributed, and especially to the fol
lowing people.

For the Selection section:


     Jerry Farrell
     Phil Karlton
     Loretta Guarino Reid
     Mark Manasse
     Bob Scheifler


For the Cut-Buffer section:


     Andrew Palay.


For the Window and Session Manager sections:


     Todd Brunhoff                 Matt Landau
     Ellis Cohen                   Mark Manasse
     Jim Fulton                    Bob Scheifler
     Hania Gajewska                Ralph Swick
     Jordan Hubbard                Mike Wexler
     Kerry Kimbrough               Glenn Widener
     Audrey Ishizaki


For the Device Color Characterization section:

     Keith Packard.


In addition, thanks are due to those who contributed to the
public review:


     Gary Combs                    John Irwin



                            viii








     Errol Crary                   Vania Joloboff
     Nancy Cyprych                 John Laporta
     John Diamant                  Ken Lee
     Clive Feather                 Stuart Marks
     Burns Fisher                  Alan Mimms
     Richard Greco                 Colas Nahaboo
     Tim Greenwood                 Mark Patrick
     Kee Hinckley                  Steve Pitschke
     Brian Holt                    Brad Reed
     John Interrante               John Thomas















































                             ix








11..  IInnttrroodduuccttiioonn

It was an explicit design goal of X Version 11 to specify
mechanism, not policy.  As a result, a client that converses
with the server using the protocol defined by the _X _W_i_n_d_o_w
_S_y_s_t_e_m _P_r_o_t_o_c_o_l, _V_e_r_s_i_o_n _1_1 may operate correctly in isola
tion but may not coexist properly with others sharing the
same server.

Being a good citizen in the X Version 11 world involves
adhering to conventions that govern inter-client communica
tions in the following areas:

   Selection mechanism

   Cut buffers

   Window manager

   Session manager

   Manipulation of shared resources

   Device color characterization

This document proposes suitable conventions without attempt
ing to enforce any particular user interface.  To permit
clients written in different languages to communicate, these
conventions are expressed solely in terms of protocol opera
tions, not in terms of their associated Xlib interfaces,
which are probably more familiar.  The binding of these
operations to the Xlib interface for C and to the equivalent
interfaces for other languages is the subject of other docu
ments.

11..11..  EEvvoolluuttiioonn ooff tthhee CCoonnvveennttiioonnss

In the interests of timely acceptance, 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 (ICCCM) covers only a minimal
set of required conventions.  These conventions will be
added to and updated as appropriate, based on the experi
ences of the X Consortium.

As far as possible, these conventions are upwardly compati
ble with those in the February 25, 1988, draft that was dis
tributed with the X Version 11, Release 2 of the software.
In some areas, semantic problems were discovered with those
conventions, and, thus, complete upward compatibility could
not be assured.  These areas are noted in the text and are
summarized in Appendix A.

In the course of developing these conventions, a number of
minor changes to the protocol were identified as desirable.
They also are identified in the text, are summarized in



                              11





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


Appendix B, and are offered as input to a future protocol
revision process.  If and when a protocol revision incorpo
rating these changes is undertaken, it is anticipated that
the ICCCM will need to be revised.  Because it is difficult
to ensure that clients and servers are upgraded simultane
ously, clients using the revised conventions should examine
the minor protocol revision number and be prepared to use
the older conventions when communicating with an older
server.

It is expected that these revisions will ensure that clients
using the conventions appropriate to protocol minor revision
_n will interoperate correctly with those that use the con
ventions appropriate to protocol minor revision _n+1 if the
server supports both.

11..22..  AAttoommss

Many of the conventions use atoms.  To assist the reader,
the following sections attempt to amplify the description of
atoms that is provided in the protocol specification.

11..22..11..  WWhhaatt AArree AAttoommss??

At the conceptual level, atoms are unique names that clients
can use to communicate information to each other.  They can
be thought of as a bundle of octets, like a string but with
out an encoding being specified.  The elements are not nec
essarily ASCII characters, and no case folding happens.1

The protocol designers felt that passing these sequences of
bytes back and forth across the wire would be too costly.
Further, they thought it important that events as they
appear on the wire have a fixed size (in fact, 32 bytes) and
that because some events contain atoms, a fixed-size repre
sentation for them was needed.

To allow a fixed-size representation, a protocol request
(_I_n_t_e_r_n_A_t_o_m) was provided to register a byte sequence with
the server, which returns a 32-bit value (with the top three
bits zero) that maps to the byte sequence.  The inverse
operator is also available (_G_e_t_A_t_o_m_N_a_m_e).

11..22..22..  PPrreeddeeffiinneedd AAttoommss

The protocol specifies a number of atoms as being prede
fined:


-----------
  1 The comment in the protocol specification for
_I_n_t_e_r_n_A_t_o_m that ISO Latin-1 encoding should be
used is in the nature of a convention; the server
treats the string as a byte sequence.



                              22





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


     Predefined atoms are not strictly necessary and
     may not be useful in all environments, but they
     will eliminate many _I_n_t_e_r_n_A_t_o_m requests in most
     applications.  Note that they are predefined only
     in the sense of having numeric values, not in the
     sense of having required semantics.

Predefined atoms are an implementation trick to avoid the
cost of interning many of the atoms that are expected to be
used during the startup phase of all applications.  The
results of the _I_n_t_e_r_n_A_t_o_m requests, which require a hand
shake, can be assumed _a _p_r_i_o_r_i.

Language interfaces should probably cache the atom-name map
pings and get them only when required.  The CLX interface,
for instance, makes no distinction between predefined atoms
and other atoms; all atoms are viewed as symbols at the
interface.  However, a CLX implementation will typically
keep a symbol or atom cache and will typically initialize
this cache with the predefined atoms.

11..22..33..  NNaammiinngg CCoonnvveennttiioonnss

The built-in atoms are composed of uppercase ASCII charac
ters with the logical words separated by an underscore char
acter (_), for example, WM_ICON_NAME.  The protocol specifi
cation recommends that atoms used for private vendor-spe
cific reasons should begin with an underscore.  To prevent
conflicts among organizations, additional prefixes should be
chosen (for example,  _DEC_WM_DECORATION_GEOMETRY).

The names were chosen in this fashion to make it easy to use
them in a natural way within LISP.  Keyword constructors
allow the programmer to specify the atoms as LISP atoms.  If
the atoms were not all uppercase, special quoting conven
tions would have to be used.

11..22..44..  SSeemmaannttiiccss

The core protocol imposes no semantics on atoms except as
they are used in FONTPROP structures.  For further informa
tion on FONTPROP semantics, see 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.

11..22..55..  NNaammee SSppaacceess

The protocol defines six distinct spaces in which atoms are
interpreted.  Any particular atom may or may not have some
valid interpretation with respect to each of these name
spaces.







                              33





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


--------------------------------------------------------------------
SSppaaccee              BBrriieeffllyy     EExxaammpplleess
--------------------------------------------------------------------
Property name      Name        WM_HINTS, WM_NAME, RGB_BEST_MAP, ...
Property type      Type        WM_HINTS, CURSOR, RGB_COLOR_MAP, ...
Selection name     Selection   PRIMARY, SECONDARY, CLIPBOARD
Selection target   Target      FILE_NAME, POSTSCRIPT, PIXMAP, ...
Font property                  QUAD_WIDTH, POINT_SIZE, ...
_C_l_i_e_n_t_M_e_s_s_a_g_e                  WM_SAVE_YOURSELF, _DEC_SAVE_EDITS,
type                           ...
--------------------------------------------------------------------


11..22..66..  DDiissccrriimmiinnaatteedd NNaammeess

Sometimes a protocol requires there to be an arbitrary num
ber of similar objects which need unique names (usually
because the objects are created dynamically, so that names
cannot be invented in advance). For example, a colormap-gen
erating program might use the selection mechanism to offer
colormaps for each screen, and so needs a selection name for
each screen.  Such names are called "discriminated names"
and are discriminated by some entity. This entity can be:

         a screen
         an X resource (a window, a colormap, a visual, etc.)
         a client


If it is only necessary to generate a fixed set of names for
each value of the discriminating entity, then the discrimi
nated names are formed by suffixing an ordinary name accord
ing to the value of the entity.

If _n_a_m_e is a descriptive portion for the name, _d is a deci
mal number with no leading zeroes, and _x is a hexadecimal
number with exactly 8 digits, and using uppercase letters,
then such discriminated names shall have the form:

---------------------------------------------------------
NNaammee DDiissccrriimmiinnaatteedd BByy   FFoorrmm      EExxaammppllee
---------------------------------------------------------
screen number           _n_a_m_e_S_d   WM_COMMS_S2
X resource              _n_a_m_e_R_x   GROUP_LEADER_R1234ABCD
---------------------------------------------------------


To discriminate a name by client, use an X resource ID cre
ated by that client.  This resource can be of any type.

Sometimes it is simply necessary to generate a unique set of
names (for example, for the properties on a window used by a
MULTIPLE selection).  These names should have the form:




                              4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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


     U_d                  (e.g.  U0  U1  U2  U3  ...)


if the names stand totally alone, and the form:

     _n_a_m_e_U_d             (e.g.  FOO_U0  BAR_U0  FOO_U1  BAR_U1  ...)


if they come in sets (here there are two sets, named "FOO"
and "BAR").  The stand-alone U_d form should only be used if
it is clear that the module using it has complete control
over the relevant namespace, or has the active cooperation
of all other entities which might also use these names.
(Naming properties on a window created specifically for a
particular selection is such a use; naming properties on the
root window is almost certainly not.)

In a particularly difficult case, it might be necessary to
combine both forms of discrimination. If this happens, the U
form should come after the other form, thus:

         FOO_R12345678_U23


                         Rationale

     Existing protocols will not be changed to use
     these naming conventions, because doing so will
     cause too much disruption.  However, it is
     expected that future protocols -- both standard
     and private -- will use these conventions.


22..  PPeeeerr--ttoo--PPeeeerr CCoommmmuunniiccaattiioonn bbyy MMeeaannss ooff SSeelleeccttiioonnss

Selections are the primary mechanism that X Version 11
defines for the exchange of information between clients, for
example, by cutting and pasting between windows.  Note that
there can be an arbitrary number of selections (each named
by an atom) and that they are global to the server.  Section
2.6 discusses the choice of an atom.  Each selection is
owned by a client and is attached to a window.

Selections communicate between an owner and a requestor.
The owner has the data representing the value of its selec
tion, and the requestor receives it.  A requestor wishing to
obtain the value of a selection provides the following:

   The name of the selection

   The name of a property

   A window




                              55





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   The atom representing the data type required

   Optionally, some parameters for the request

If the selection is currently owned, the owner receives an
event and is expected to do the following:

   Convert the contents of the selection to the requested
    data type

   Place this data in the named property on the named win
    dow

   Send the requestor an event to let it know the property
    is available

Clients are strongly encouraged to use this mechanism.  In
particular, displaying text in a permanent window without
providing the ability to select and convert it into a string
is definitely considered antisocial.

Note that all data transferred between an owner and a
requestor must usually go by means of the server in an X
Version 11 environment.  A client cannot assume that another
client can open the same files or even communicate directly.
The other client may be talking to the server by means of a
completely different networking mechanism (for example,  one
client might be DECnet and the other TCP/IP).  Thus, passing
indirect references to data (such as file names,  host names
and port numbers, and so on) is permitted only if both
clients specifically agree.

22..11..  AAccqquuiirriinngg SSeelleeccttiioonn OOwwnneerrsshhiipp

A client wishing to acquire ownership of a particular selec
tion should call _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r_, which is defined as fol
lows:

__
||    _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r

_s_e_l_e_c_t_i_o_n: ATOM
_o_w_n_e_r: WINDOW or _N_o_n_e
||__  _t_i_m_e: TIMESTAMP or _C_u_r_r_e_n_t_T_i_m_e


The client should set the specified selection to the atom
that represents the selection, set the specified owner to
some window that the client created, and set the specified
time to some time between the current last-change time of
the selection concerned and the current server time.  This
time value usually will be obtained from the timestamp of
the event that triggers the acquisition of the selection.
Clients should not set the time value to _C_u_r_r_e_n_t_T_i_m_e,



                              66





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


because if they do so, they have no way of finding when they
gained ownership of the selection.  Clients must use a win
dow they created so that requestors can route events to the
owner of the selection.2

                         Convention

     Clients attempting to acquire a selection must set
     the time value of the _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request to
     the timestamp of the event triggering the acquisi
     tion attempt, not to _C_u_r_r_e_n_t_T_i_m_e.  A zero-length
     append to a property is a way to obtain a time
     stamp for this purpose; the timestamp is in the
     corresponding _P_r_o_p_e_r_t_y_N_o_t_i_f_y event.


If the time in the _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request is in the
future relative to the server's current time or is in the
past relative to the last time the specified selection
changed hands, the _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request appears to the
client to succeed, but ownership is not actually trans
ferred.

Because clients cannot name other clients directly, the
specified owner window is used to refer to the owning client
in the replies to _G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r, 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, and possibly as a place to put prop
erties describing the selection in question.  To discover
the owner of a particular selection, a client should invoke
_G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r, which is defined as follows:

__
||    _G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r

_s_e_l_e_c_t_i_o_n: ATOM

->

||__  owner: WINDOW or _N_o_n_e


                         Convention

     Clients are expected to provide some visible con
     firmation of selection ownership.  To make this
     feedback reliable, a client must perform a
     sequence like the following:


-----------
  2 At present, no part of the protocol requires
requestors to send events to the owner of a selec
tion.  This restriction is imposed to prepare for
possible future extensions.



                              77





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


SetSelectionOwner(selection=PRIMARY, owner=Window, time=timestamp)
owner = GetSelectionOwner(selection=PRIMARY)
if (owner != Window) Failure



If the _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request succeeds (not merely
appears to succeed), the client that issues it is recorded
by the server as being the owner of the selection for the
time period starting at the specified time.

22..22..  RReessppoonnssiibbiilliittiieess ooff tthhee SSeelleeccttiioonn OOwwnneerr

When a requestor wants the value of a selection, the owner
receives a _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t event, which is defined as fol
lows:

__
||    _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t

_o_w_n_e_r: WINDOW
_s_e_l_e_c_t_i_o_n: ATOM
_t_a_r_g_e_t: ATOM
_p_r_o_p_e_r_t_y: ATOM or _N_o_n_e
_r_e_q_u_e_s_t_o_r: WINDOW
||__  _t_i_m_e: TIMESTAMP or _C_u_r_r_e_n_t_T_i_m_e


The specified owner and selection will be the values that
were specified in the _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request.  The owner
should compare the timestamp with the period it has owned
the selection and, if the time is outside, refuse the _S_e_l_e_c_
_t_i_o_n_R_e_q_u_e_s_t by sending the requestor window a _S_e_l_e_c_t_i_o_n_N_o_
_t_i_f_y event with the property set to _N_o_n_e (by means of a
_S_e_n_d_E_v_e_n_t request with an empty event mask).

More advanced selection owners are free to maintain a his
tory of the value of the selection and to respond to
requests for the value of the selection during periods they
owned it even though they do not own it now.

If the specified property is _N_o_n_e, the requestor is an obso
lete client.  Owners are encouraged to support these clients
by using the specified target atom as the property name to
be used for the reply.

Otherwise, the owner should use the target to decide the
form into which the selection should be converted.  Some
targets may be defined such that requestors can pass parame
ters along with the request.  The owner will find these
parameters in the property named in the selection request.
The type, format, and contents of this property are depen
dent upon the definition of the target.  If the target is
not defined to have parameters, the owner should ignore the



                              88





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


property if it is present.  If the selection cannot be con
verted into a form based on the target (and parameters, if
any), the owner should refuse the _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t as previ
ously described.

If the specified property is not _N_o_n_e, the owner should
place the data resulting from converting the selection into
the specified property on the requestor window and should
set the property's type to some appropriate value, which
need not be the same as the specified target.

                         Convention

     All properties used to reply to _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t
     events must be placed on the requestor window.


In either case, if the data comprising the selection cannot
be stored on the requestor window (for example, because the
server cannot provide sufficient memory), the owner must
refuse the _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t, as previously described.  See
also section 2.5.

If the property is successfully stored, the owner should
acknowledge the successful conversion by sending the
requestor window a _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event (by means of a
_S_e_n_d_E_v_e_n_t request with an empty mask).  _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y is
defined as follows:

__
||    _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y

_r_e_q_u_e_s_t_o_r: WINDOW
_s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t: ATOM
_p_r_o_p_e_r_t_y: ATOM or _N_o_n_e
||__  _t_i_m_e: TIMESTAMP or _C_u_r_r_e_n_t_T_i_m_e


The owner should set the specified selection, target, time,
and property arguments to the values received in the _S_e_l_e_c_
_t_i_o_n_R_e_q_u_e_s_t event.  (Note that setting the property argument
to _N_o_n_e indicates that the conversion requested could not be
made.)

                         Convention

     The selection, target, time, and property argu
     ments in the _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event should be set
     to the values received in the _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t
     event.


If the owner receives more than one _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t event
with the same requestor, selection, target, and timestamp,



                              99





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


it must respond to them in the same order in which they were
received.

                         Rationale

     It is possible for a requestor to have multiple
     outstanding requests that use the same requestor
     window, selection, target, and timestamp, and that
     differ only in the property.  If this occurs, and
     one of the conversion requests fails, the result
     ing _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event will have its property
     argument set to _N_o_n_e.  This may make it impossible
     for the requestor to determine which conversion
     request had failed, unless the requests are
     responded to in order.


The data stored in the property must eventually be deleted.
A convention is needed to assign the responsibility for
doing so.

                         Convention

     Selection requestors are responsible for deleting
     properties whose names they receive in _S_e_l_e_c_t_i_o_n_
     _N_o_t_i_f_y events (see section 2.4) or in properties
     with type MULTIPLE.


A selection owner will often need confirmation that the data
comprising the selection has actually been transferred.
(For example, if the operation has side effects on the
owner's internal data structures, these should not take
place until the requestor has indicated that it has success
fully received the data.)  Owners should express interest in
_P_r_o_p_e_r_t_y_N_o_t_i_f_y events for the specified requestor window and
wait until the property in the _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event has
been deleted before assuming that the selection data has
been transferred.  For the MULTIPLE request, if the differ
ent conversions require separate confirmation, the selection
owner can also watch for the deletion of the individual
properties named in the property in the _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y
event.

When some other client acquires a selection, the previous
owner receives a _S_e_l_e_c_t_i_o_n_C_l_e_a_r event, which is defined as
follows:










                             1100





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66

__
||    _S_e_l_e_c_t_i_o_n_C_l_e_a_r

_o_w_n_e_r: WINDOW
_s_e_l_e_c_t_i_o_n: ATOM
||__  _t_i_m_e: TIMESTAMP


The timestamp argument is the time at which the ownership
changed hands, and the owner argument is the window the pre
vious owner specified in its _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request.

If an owner loses ownership while it has a transfer in
progress (that is, before it receives notification that the
requestor has received all the data), it must continue to
service the ongoing transfer until it is complete.

If the selection value completely changes, but the owner
happens to be the same client (for example, selecting a
totally different piece of text in the same xxtteerrmm as
before), then the client should reacquire the selection own
ership as if it were not the owner, providing a new time
stamp. If the selection value is modified, but can still
reasonably be viewed as the same selected object,3 the owner
should take no action.

22..33..  GGiivviinngg UUpp SSeelleeccttiioonn OOwwnneerrsshhiipp

Clients may either give up selection ownership voluntarily
or lose it forcibly as the result of some other client's
actions.

22..33..11..  VVoolluunnttaarriillyy GGiivviinngg UUpp SSeelleeccttiioonn OOwwnneerrsshhiipp

To relinquish ownership of a selection voluntarily, a client
should execute a _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request for that selec
tion atom, with owner specified as _N_o_n_e and the time speci
fied as the timestamp that was used to acquire the selec
tion.

Alternatively, the client may destroy the window used as the
owner value of the _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request, or the client
may terminate.  In both cases, the ownership of the selec
tion involved will revert to _N_o_n_e.

22..33..22..  FFoorrcciibbllyy GGiivviinngg UUpp SSeelleeccttiioonn OOwwnneerrsshhiipp

If a client gives up ownership of a selection or if some
other client executes a _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r for it and thus
reassigns it forcibly, the previous owner will receive a
_S_e_l_e_c_t_i_o_n_C_l_e_a_r event. For the definition of a _S_e_l_e_c_t_i_o_n_C_l_e_a_r
-----------
  3 The division between these two cases is a mat
ter of judgement on the part of the software
developer.



                             1111





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


event, see section 2.2.

The timestamp is the time the selection changed hands.  The
specified owner is the window that was specified by the cur
rent owner in its _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request.

22..44..  RReeqquueessttiinngg aa SSeelleeccttiioonn

A client that wishes to obtain the value of a selection in a
particular form (the requestor) issues a _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n
request, which is defined as follows:

__
||    _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n

_s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t: ATOM
_p_r_o_p_e_r_t_y: ATOM or _N_o_n_e
_r_e_q_u_e_s_t_o_r: WINDOW
||__  _t_i_m_e: TIMESTAMP or _C_u_r_r_e_n_t_T_i_m_e


The selection argument specifies the particular selection
involved, and the target argument specifies the required
form of the information.  For information about the choice
of suitable atoms to use, see section 2.6.  The requestor
should set the requestor argument to a window that it cre
ated; the owner will place the reply property there.  The
requestor should set the time argument to the timestamp on
the event that triggered the request for the selection
value.  Note that clients should not specify _C_u_r_r_e_n_t_T_i_m_e.

                         Convention

     Clients should not use _C_u_r_r_e_n_t_T_i_m_e for the time
     argument of a _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request.  Instead,
     they should use the timestamp of the event that
     caused the request to be made.


The requestor should set the property argument to the name
of a property that the owner can use to report the value of
the selection.  Requestors should ensure that the named
property does not exist on the window before issuing the
_C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request.4 The exception to this rule is
when the requestor intends to pass parameters with the
request; see below.

                         Rationale

     It is necessary for requestors to delete the prop
     erty before issuing the request so that the target
     can later be extended to take parameters without
     introducing an incompatibility.  Also note that
     the requestor of a selection need not know the



                             1122





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


     client that owns the selection nor the window on
     which the selection was acquired.


Some targets may be defined such that requestors can pass
parameters along with the request.  If the requestor wishes
to provide parameters to a request, they should be placed in
the specified property on the requestor window before the
requestor issues the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request, and this
property should be named in the request.

Some targets may be defined so that parameters are optional.
If no parameters are to be supplied with the request of such
a target, the requestor must ensure that the property does
not exist before issuing the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request.

The protocol allows the property field to be set to _N_o_n_e, in
which case the owner is supposed to choose a property name.
However, it is difficult for the owner to make this choice
safely.

                        Conventions


1.   Requestors should not use _N_o_n_e for the property argu
     ment of a _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request.

2.   Owners receiving _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n requests with a prop
     erty argument of _N_o_n_e are talking to an obsolete
     client.  They should choose the target atom as the
     property name to be used for the reply.


The result of the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request is that a _S_e_l_e_c_
_t_i_o_n_N_o_t_i_f_y event will be received.  For the definition of a
_S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event, see section 2.2.

The requestor, selection, time, and target arguments will be
the same as those on the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request.

If the property argument is _N_o_n_e, the conversion has been
refused.  This can mean either that there is no owner for
the selection, that the owner does not support the conver
sion implied by the target, or that the server did not have
-----------
  4 This requirement is new in version 2.0, and in
general, existing clients do not conform to this
requirement.  To prevent these clients from break
ing, no existing targets should be extended to
take parameters until sufficient time has passed
for clients to be updated.  Note that the MULTIPLE
target was defined to take parameters in version
1.0 and its definition is not changing.  There is
thus no conformance problem with MULTIPLE.



                             1133





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


sufficient space to accommodate the data.

If the property argument is not _N_o_n_e, then that property
will exist on the requestor window.  The value of the selec
tion can be retrieved from this property by using the _G_e_t_
_P_r_o_p_e_r_t_y request, which is defined as follows:

__
||    _G_e_t_P_r_o_p_e_r_t_y

_w_i_n_d_o_w: WINDOW
_p_r_o_p_e_r_t_y: ATOM
_t_y_p_e: ATOM or _A_n_y_P_r_o_p_e_r_t_y_T_y_p_e
_l_o_n_g_-_o_f_f_s_e_t, _l_o_n_g_-_l_e_n_g_t_h: CARD32
_d_e_l_e_t_e: BOOL

->

type: ATOM or _N_o_n_e
format: {0, 8, 16, 32}
bytes-after: CARD32
||__  value: LISTofINT8 or LISTofINT16 or LISTofINT32


When using _G_e_t_P_r_o_p_e_r_t_y to retrieve the value of a selection,
the property argument should be set to the corresponding
value in the _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event.  Because the requestor
has no way of knowing beforehand what type the selection
owner will use, the type argument should be set to
_A_n_y_P_r_o_p_e_r_t_y_T_y_p_e.  Several _G_e_t_P_r_o_p_e_r_t_y requests may be needed
to retrieve all the data in the selection; each should set
the long-offset argument to the amount of data received so
far, and the size argument to some reasonable buffer size
(see section 2.5).  If the returned value of bytes-after is
zero, the whole property has been transferred.

Once all the data in the selection has been retrieved (which
may require getting the values of several properties -- see
section 2.7), the requestor should delete the property in
the _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y request by using a _G_e_t_P_r_o_p_e_r_t_y request
with the delete argument set to _T_r_u_e.  As previously dis
cussed, the owner has no way of knowing when the data has
been transferred to the requestor unless the property is
removed.

                         Convention

     The requestor must delete the property named in
     the _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y once all the data has been
     retrieved.  The requestor should invoke either
     _D_e_l_e_t_e_P_r_o_p_e_r_t_y or _G_e_t_P_r_o_p_e_r_t_y(delete==True) after
     it has successfully retrieved all the data in the
     selection.  For further information, see section
     2.5.



                             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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


22..55..  LLaarrggee DDaattaa TTrraannssffeerrss

Selections can get large, which poses two problems:

   Transferring large amounts of data to the server is
    expensive.

   All servers will have limits on the amount of data that
    can be stored in properties.  Exceeding this limit will
    result in an _A_l_l_o_c error on the _C_h_a_n_g_e_P_r_o_p_e_r_t_y request
    that the selection owner uses to store the data.

The problem of limited server resources is addressed by the
following conventions:

                        Conventions


1.   Selection owners should transfer the data describing a
     large selection (relative to the maximum-request-size
     they received in the connection handshake) using the
     INCR property mechanism (see section 2.7.2).

2.   Any client using _S_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r to acquire selection
     ownership should arrange to process _A_l_l_o_c errors in
     property change requests.  For clients using Xlib, this
     involves using the _X_S_e_t_E_r_r_o_r_H_a_n_d_l_e_r function to over
     ride the default handler.

3.   A selection owner must confirm that no _A_l_l_o_c error
     occurred while storing the properties for a selection
     before replying with a confirming _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y
     event.

4.   When storing large amounts of data (relative to maxi
     mum-request-size), clients should use a sequence of
     _C_h_a_n_g_e_P_r_o_p_e_r_t_y(mode==Append) requests for reasonable
     quantities of data.  This avoids locking servers up and
     limits the waste of data an _A_l_l_o_c error would cause.

5.   If an _A_l_l_o_c error occurs during the storing of the
     selection data, all properties stored for this selec
     tion should be deleted and the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request
     should be refused (see section 2.2).

6.   To avoid locking servers up for inordinate lengths of
     time, requestors retrieving large quantities of data
     from a property should perform a series of _G_e_t_P_r_o_p_e_r_t_y
     requests, each asking for a reasonable amount of data.








                             1155





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


                     Advice to Implementors

     Single-threaded servers should take care to avoid lock
     ing up during large data transfers.


22..66..  UUssee ooff SSeelleeccttiioonn AAttoommss

Defining a new atom consumes resources in the server that
are not released until the server reinitializes.  Thus,
reducing the need for newly minted atoms is an important
goal for the use of the selection atoms.

22..66..11..  SSeelleeccttiioonn AAttoommss

There can be an arbitrary number of selections, each named
by an atom.  To conform with the inter-client conventions,
however, clients need deal with only these three selections:

   PRIMARY

   SECONDARY

   CLIPBOARD

Other selections may be used freely for private communica
tion among related groups of clients.

22..66..11..11..  TThhee PPRRIIMMAARRYY SSeelleeccttiioonn

The selection named by the atom PRIMARY is used for all com
mands that take only a single argument and is the principal
means of communication between clients that use the selec
tion mechanism.

22..66..11..22..  TThhee SSEECCOONNDDAARRYY SSeelleeccttiioonn

The selection named by the atom SECONDARY is used:

   As the second argument to commands taking two arguments
    (for example, "exchange primary and secondary selec
    tions")

   As a means of obtaining data when there is a primary
    selection and the user does not want to disturb it

22..66..11..33..  TThhee CCLLIIPPBBOOAARRDD SSeelleeccttiioonn

The selection named by the atom CLIPBOARD is used to hold
data that is being transferred between clients, that is,
data that usually is being cut or copied, and then pasted.
Whenever a client wants to transfer data to the clipboard:





                             1166





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   It should assert ownership of the CLIPBOARD.

   If it succeeds in acquiring ownership, it should be pre
    pared to respond to a request for the contents of the
    CLIPBOARD in the usual way (retaining the data to be
    able to return it).  The request may be generated by the
    clipboard client described below.

   If it fails to acquire ownership, a cutting client
    should not actually perform the cut or provide feedback
    that would suggest that it has actually transferred data
    to the clipboard.

The owner should repeat this process whenever the data to be
transferred would change.

Clients wanting to paste data from the clipboard should
request the contents of the CLIPBOARD selection in the usual
way.

Except while a client is actually deleting or copying data,
the owner of the CLIPBOARD selection may be a single, spe
cial client implemented for the purpose.  This client main
tains the content of the clipboard up-to-date and responds
to requests for data from the clipboard as follows:

   It should assert ownership of the CLIPBOARD selection
    and reassert it any time the clipboard data changes.

   If it loses the selection (because another client has
    some new data for the clipboard), it should:

    -    Obtain the contents of the selection from the new
         owner by using the timestamp in the _S_e_l_e_c_t_i_o_n_C_l_e_a_r
         event.

    -    Attempt to reassert ownership of the CLIPBOARD
         selection by using the same timestamp.

    -    Restart the process using a newly acquired time
         stamp if this attempt fails.  This timestamp should
         be obtained by asking the current owner of the
         CLIPBOARD selection to convert it to a TIMESTAMP.
         If this conversion is refused or if the same time
         stamp is received twice, the clipboard client
         should acquire a fresh timestamp in the usual way
         (for example by a zero-length append to a prop
         erty).

   It should respond to requests for the CLIPBOARD contents
    in the usual way.

A special CLIPBOARD client is not necessary.  The protocol
used by the cutting client and the pasting client is the



                             1177





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


same whether the CLIPBOARD client is running or not.  The
reasons for running the special client include:

   Stability - If the cutting client were to crash or ter
    minate, the clipboard value would still be available.

   Feedback - The clipboard client can display the contents
    of the clipboard.

   Simplicity - A client deleting data does not have to
    retain it for so long, thus reducing the chance of race
    conditions causing problems.

The reasons not to run the clipboard client include:

   Performance - Data is only transferred if it is actually
    required (that is, when some client actually wants the
    data).

   Flexibility - The clipboard data may be available as
    more than one target.

22..66..22..  TTaarrggeett AAttoommss

The atom that a requestor supplies as the target of a _C_o_n_
_v_e_r_t_S_e_l_e_c_t_i_o_n request determines the form of the data sup
plied.  The set of such atoms is extensible, but a generally
accepted base set of target atoms is needed.  As a starting
point for this, the following table contains those that have
been suggested so far.

---------------------------------------------------------------------
AAttoomm                 TTyyppee            DDaattaa RReecceeiivveedd
---------------------------------------------------------------------
ADOBE_PORTABLE_DOCUMENT_FORMAT
                     STRING          [1]
APPLE_PICT           APPLE_PICT      [2]
BACKGROUND           PIXEL           A list of pixel values
BITMAP               BITMAP          A list of bitmap IDs
CHARACTER_POSITION   SPAN            The start and end of the selec
                                     tion in bytes
CLASS                TEXT            (see section 4.1.2.5)
CLIENT_WINDOW        WINDOW          Any top-level window owned by
                                     the selection owner
COLORMAP             COLORMAP        A list of colormap IDs
COLUMN_NUMBER        SPAN            The start and end column num
                                     bers
COMPOUND_TEXT        COMPOUND_TEXT   Compound Text
DELETE               NULL            (see section 2.6.3.1)
DRAWABLE             DRAWABLE        A list of drawable IDs
ENCAPSULATED_POSTSCRIPT
                     STRING          [3], Appendix H5
ENCAPSULATED_POSTSCRIPT_INTERCHANGE




                             1188





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


---------------------------------------------------------------------
AAttoomm                 TTyyppee            DDaattaa RReecceeiivveedd
---------------------------------------------------------------------
                     STRING          [3], Appendix H
FILE_NAME            TEXT            The full path name of a file
FOREGROUND           PIXEL           A list of pixel values
HOST_NAME            TEXT            (see section 4.1.2.9)
INSERT_PROPERTY      NULL            (see section 2.6.3.3)
INSERT_SELECTION     NULL            (see section 2.6.3.2)
LENGTH               INTEGER         The number of bytes in the
                                     selection6
LINE_NUMBER          SPAN            The start and end line numbers
LIST_LENGTH          INTEGER         The number of disjoint parts of
                                     the selection
MODULE               TEXT            The name of the selected proce
                                     dure
MULTIPLE             ATOM_PAIR       (see the discussion that fol
                                     lows)
NAME                 TEXT            (see section 4.1.2.1)
ODIF                 TEXT            ISO Office Document Interchange
                                     Format
OWNER_OS             TEXT            The operating system of the
                                     owner client
PIXMAP               PIXMAP7         A list of pixmap IDs
POSTSCRIPT           STRING          [3]
PROCEDURE            TEXT            The name of the selected proce
                                     dure
PROCESS              INTEGER, TEXT   The process ID of the owner
STRING               STRING          ISO Latin-1 (+TAB+NEWLINE) text
TARGETS              ATOM            A list of valid target atoms
TASK                 INTEGER, TEXT   The task ID of the owner
TEXT                 TEXT            The text in the owner's choice
                                     of encoding
TIMESTAMP            INTEGER         The timestamp used to acquire
                                     the selection
USER                 TEXT            The name of the user running
                                     the owner
---------------------------------------------------------------------


-----------
  5 Earlier versions of this document erroneously
specified that conversion of the PIXMAP target
return a property of type DRAWABLE instead of
PIXMAP.  Implementors should be aware of this and
may want to support the DRAWABLE type as well to
allow for compatibility with older clients.
  6 The targets ENCAPSULATED_POSTSCRIPT and ENCAP
SULATED_POSTSCRIPT_INTERCHANGE are equivalent to
the targets _ADOBE_EPS and _ADOBE_EPSI (respec
tively) that appear in the selection targets reg
istry.  The _ADOBE_ targets are deprecated, but
clients are encouraged to continue to support them
for backward compatibility.



                             1199





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


References:

[1]  Adobe Systems, Incorporated.  _P_o_r_t_a_b_l_e _D_o_c_u_m_e_n_t _F_o_r_m_a_t
     _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l_.  Addison-Wesley, ISBN 0-201-62628-4.

[2]  Apple Computer, Incorporated.  _I_n_s_i_d_e _M_a_c_i_n_t_o_s_h_, _V_o_l_u_m_e
     _V_.  Chapter 4, "Color QuickDraw," Color Picture Format.
     ISBN 0-201-17719-6.

[3]  Adobe Systems, Incorporated.  _P_o_s_t_S_c_r_i_p_t _L_a_n_g_u_a_g_e _R_e_f_
     _e_r_e_n_c_e _M_a_n_u_a_l_.  Addison-Wesley, ISBN 0-201-18127-4.

It is expected that this table will grow over time.

Selection owners are required to support the following tar
gets.  All other targets are optional.

   TARGETS - The owner should return a list of atoms that
    represent the targets for which an attempt to convert
    the current selection will succeed (barring unforseeable
    problems such as _A_l_l_o_c errors).  This list should
    include all the required atoms.

   MULTIPLE - The MULTIPLE target atom is valid only when a
    property is specified on the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n request.
    If the property argument in the _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t event
    is _N_o_n_e and the target is MULTIPLE, it should be
    refused.

    When a selection owner receives a _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t(tar
    get==MULTIPLE) request, the contents of the property
    named in the request will be a list of atom pairs: the
    first atom naming a target and the second naming a prop
    erty (_N_o_n_e is not valid here).  The effect should be as
    if the owner had received a sequence of _S_e_l_e_c_t_i_o_n_R_e_q_u_e_s_t
    events (one for each atom pair) except that:

    -    The owner should reply with a _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y only
         when all the requested conversions have been per
         formed.

    -    If the owner fails to convert the target named by
         an atom in the MULTIPLE property, it should replace
         that atom in the property with _N_o_n_e.

-----------
  7 This definition is ambiguous, as the selection
may be converted into any of several targets which
may return differing amounts of data.  The
requestor has no way of knowing which, if any, of
these targets corresponds to the result of LENGTH.
Clients are advised that no guarantees can be made
about the result of a conversion to LENGTH; its
use is thus deprecated.



                             2200





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


                           Convention

         The entries in a MULTIPLE property must be
         processed in the order they appear in the
         property.  For further information, see sec
         tion 2.6.3.


    The requestor should delete each individual property
    when it has copied the data from that conversion, and
    the property specified in the MULTIPLE request when it
    has copied all the data.

    The requests are otherwise to be processed indepen
    dently, and they should succeed or fail independently.
    The MULTIPLE target is an optimization that reduces the
    amount of protocol traffic between the owner and the
    requestor; it is not a transaction mechanism.  For exam
    ple, a client may issue a MULTIPLE request with two tar
    gets: a data target and the DELETE target.  The DELETE
    target will still be processed even if the conversion of
    the data target fails.

   TIMESTAMP - To avoid some race conditions, it is impor
    tant that requestors be able to discover the timestamp
    the owner used to acquire ownership.  Until and unless
    the protocol is changed so that a _G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r
    request returns the timestamp used to acquire ownership,
    selection owners must support conversion to TIMESTAMP,
    returning the timestamp they used to obtain the selec
    tion.

22..66..33..  SSeelleeccttiioonn TTaarrggeettss wwiitthh SSiiddee EEffffeeccttss

Some targets (for example, DELETE) have side effects.  To
render these targets unambiguous, the entries in a MULTIPLE
property must be processed in the order that they appear in
the property.

In general, targets with side effects will return no infor
mation, that is, they will return a zero-length property of
type NULL.  (Type NULL means the result of _I_n_t_e_r_n_A_t_o_m on the
string "NULL", not the value zero.)  In all cases, the
requested side effect must be performed before the conver
sion is accepted.  If the requested side effect cannot be
performed, the corresponding conversion request must be
refused.

                        Conventions


1.   Targets with side effects should return no information
     (that is, they should have a zero-length property of
     type NULL).



                             2211





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


2.   The side effect of a target must be performed before
     the conversion is accepted.

3.   If the side effect of a target cannot be performed, the
     corresponding conversion request must be refused.


                             Problem

     The need to delay responding to the _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n
     request until a further conversion has succeeded poses
     problems for the Intrinsics interface that need to be
     addressed.


These side effect targets are used to implement operations
such as "exchange PRIMARY and SECONDARY selections."

22..66..33..11..  DDEELLEETTEE

When the owner of a selection receives a request to convert
it to DELETE, it should delete the corresponding selection
(whatever doing so means for its internal data structures)
and return a zero-length property of type NULL if the dele
tion was successful.

22..66..33..22..  IINNSSEERRTT__SSEELLEECCTTIIOONN

When the owner of a selection receives a request to convert
it to INSERT_SELECTION, the property named will be of type
ATOM_PAIR.  The first atom will name a selection, and the
second will name a target.  The owner should use the selec
tion mechanism to convert the named selection into the named
target and should insert it at the location of the selection
for which it got the INSERT_SELECTION request (whatever
doing so means for its internal data structures).

22..66..33..33..  IINNSSEERRTT__PPRROOPPEERRTTYY

When the owner of a selection receives a request to convert
it to INSERT_PROPERTY, it should insert the property named
in the request at the location of the selection for which it
got the INSERT_SELECTION request (whatever doing so means
for its internal data structures).

22..77..  UUssee ooff SSeelleeccttiioonn PPrrooppeerrttiieess

The names of the properties used in selection data transfer
are chosen by the requestor.  The use of _N_o_n_e property
fields in _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n requests (which request the
selection owner to choose a name) is not permitted by these
conventions.





                             2222





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


The selection owner always chooses the type of the property
in the selection data transfer.  Some types have special
semantics assigned by convention, and these are reviewed in
the following sections.

In all cases, a request for conversion to a target should
return either a property of one of the types listed in the
previous table for that target or a property of type INCR
and then a property of one of the listed types.

Certain selection properties may contain resource IDs.  The
selection owner should ensure that the resource is not
destroyed and that its contents are not changed until after
the selection transfer is complete.  Requestors that rely on
the existence or on the proper contents of a resource must
operate on the resource (for example, by copying the con
tents of a pixmap) before deleting the selection property.

The selection owner will return a list of zero or more items
of the type indicated by the property type.  In general, the
number of items in the list will correspond to the number of
disjoint parts of the selection.  Some targets (for example,
side-effect targets) will be of length zero irrespective of
the number of disjoint selection parts.  In the case of
fixed-size items, the requestor may determine the number of
items by the property size.  Selection property types are
listed in the table below.  For variable-length items such
as text, the separators are also listed.

-------------------------------------
TTyyppee AAttoomm       FFoorrmmaatt   SSeeppaarraattoorr
-------------------------------------
APPLE_PICT        8      Self-sizing
ATOM              32     Fixed-size
ATOM_PAIR         32     Fixed-size
BITMAP            32     Fixed-size
C_STRING          8      Zero
COLORMAP          32     Fixed-size
COMPOUND_TEXT     8      Zero
DRAWABLE          32     Fixed-size
INCR              32     Fixed-size
INTEGER           32     Fixed-size
PIXEL             32     Fixed-size
PIXMAP            32     Fixed-size
SPAN              32     Fixed-size
STRING            8      Zero
WINDOW            32     Fixed-size
-------------------------------------


It is expected that this table will grow over time.






                             2233





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


22..77..11..  TTEEXXTT PPrrooppeerrttiieess

In general, the encoding for the characters in a text string
property is specified by its type.  It is highly desirable
for there to be a simple, invertible mapping between string
property types and any character set names embedded within
font names in any font naming standard adopted by the Con
sortium.

The atom TEXT is a polymorphic target.  Requesting conver
sion into TEXT will convert into whatever encoding is conve
nient for the owner.  The encoding chosen will be indicated
by the type of the property returned.  TEXT is not defined
as a type; it will never be the returned type from a selec
tion conversion request.

If the requestor wants the owner to return the contents of
the selection in a specific encoding, it should request con
version into the name of that encoding.

In the table in section 2.6.2, the word TEXT (in the Type
column) is used to indicate one of the registered encoding
names.  The type would not actually be TEXT; it would be
STRING or some other ATOM naming the encoding chosen by the
owner.

STRING as a type or a target specifies the ISO Latin-1 char
acter set plus the control characters TAB (octal 11) and
NEWLINE (octal 12).  The spacing interpretation of TAB is
context dependent.  Other ASCII control characters are
explicitly not included in STRING at the present time.

COMPOUND_TEXT as a type or a target specifies the Compound
Text interchange format; see the _C_o_m_p_o_u_n_d _T_e_x_t _E_n_c_o_d_i_n_g.

There are some text objects where the source or intended
user, as the case may be, does not have a specific character
set for the text, but instead merely requires a zero-termi
nated sequence of bytes with no other restriction; no ele
ment of the selection mechanism may assume that any byte
value is forbidden or that any two differing sequences are
equivalent.8  For these objects, the type C_STRING should be
used.





-----------
  8 Note that this is different from STRING, where
many byte values are forbidden, and from COM
POUND_TEXT, where, for example, inserting the
sequence 27, 40, 66 (designate ASCII into GL) at
the start does not alter the meaning.



                             224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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


                         Rationale

     An example of the need for C_STRING is to transmit
     the names of files; many operating systems do not
     interpret filenames as having a character set. For
     example, the same character string uses a differ
     ent sequence of bytes in ASCII and EBCDIC, and so
     most operating systems see these as different
     filenames, and offer no way to treat them as the
     same. Thus no character-set based property type is
     suitable.


Type STRING, COMPOUND_TEXT, and C_STRING properties will
consist of a list of elements separated by null characters;
other encodings will need to specify an appropriate list
format.

22..77..22..  IINNCCRR PPrrooppeerrttiieess

Requestors may receive a property of type INCR9 in response
to any target that results in selection data.  This indi
cates that the owner will send the actual data incremen
tally.  The contents of the INCR property will be an inte
ger, which represents a lower bound on the number of bytes
of data in the selection.  The requestor and the selection
owner transfer the data in the selection in the following
manner.

The selection requestor starts the transfer process by
deleting the (type==INCR) property forming the reply to the
selection.

The selection owner then:

   Appends the data in suitable-size chunks to the same
    property on the same window as the selection reply with
    a type corresponding to the actual type of the converted
    selection.  The size should be less than the maximum-
    request-size in the connection handshake.

   Waits between each append for a
    _P_r_o_p_e_r_t_y_N_o_t_i_f_y(state==Deleted) event that shows that the
    requestor has read the data.  The reason for doing this
    is to limit the consumption of space in the server.

   Waits (after the entire data has been transferred to the
    server) until a _P_r_o_p_e_r_t_y_N_o_t_i_f_y(state==Deleted) event
    that shows that the data has been read by the requestor
-----------
  9 These properties were called INCREMENTAL in an
earlier draft.  The protocol for using them has
changed, and so the name has changed to avoid con
fusion.



                             2255





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


    and then writes zero-length data to the property.

The selection requestor:

   Waits for the _S_e_l_e_c_t_i_o_n_N_o_t_i_f_y event.

   Loops:

    -    Retrieving data using _G_e_t_P_r_o_p_e_r_t_y with the delete
         argument _T_r_u_e.

    -    Waiting for a _P_r_o_p_e_r_t_y_N_o_t_i_f_y with the state argu
         ment _N_e_w_V_a_l_u_e.

   Waits until the property named by the _P_r_o_p_e_r_t_y_N_o_t_i_f_y
    event is zero-length.

   Deletes the zero-length property.

The type of the converted selection is the type of the first
partial property.  The remaining partial properties must
have the same type.

22..77..33..  DDRRAAWWAABBLLEE PPrrooppeerrttiieess

Requestors may receive properties of type PIXMAP, BITMAP,
DRAWABLE, or WINDOW, which contain an appropriate ID.  While
information about these drawables is available from the
server by means of the _G_e_t_G_e_o_m_e_t_r_y request, the following
items are not:

   Foreground pixel

   Background pixel

   Colormap ID

In general, requestors converting into targets whose
returned type in the table in section 2.6.2 is one of the
DRAWABLE types should expect to convert also into the fol
lowing targets (using the MULTIPLE mechanism):

   FOREGROUND returns a PIXEL value.

   BACKGROUND returns a PIXEL value.

   COLORMAP returns a colormap ID.

22..77..44..  SSPPAANN PPrrooppeerrttiieess

Properties with type SPAN contain a list of cardinal-pairs
with the length of the cardinals determined by the format.
The first specifies the starting position, and the second
specifies the ending position plus one.  The base is zero.



                             2266





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


If they are the same, the span is zero-length and is before
the specified position.  The units are implied by the target
atom, such as LINE_NUMBER or CHARACTER_POSITION.

22..88..  MMaannaaggeerr SSeelleeccttiioonnss

Certain clients, often called managers, take on responsibil
ity for managing shared resources.  A client that manages a
shared resource should take ownership of an appropriate
selection, named using the conventions described in sections
1.2.3 and 1.2.6.  A client that manages multiple shared
resources (or groups of resources) should take ownership of
a selection for each one.

The manager may support conversion of various targets for
that selection.  Managers are encouraged to use this tech
nique as the primary means by which clients interact with
the managed resource.  Note that the conventions for inter
acting with the window manager predate this section; as a
result many interactions with the window manager use other
techniques.

Before a manager takes ownership of a manager selection, it
should use the _G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request to check whether
the selection is already owned by another client, and where
appropriate, it should ask the user if the new manager
should replace the old one.  If so, it may then take owner
ship of the selection.  Managers should acquire the selec
tion using a window created expressly for this purpose.
Managers must conform to the rules for selection owners
described in sections 2.1 and 2.2, and they must also sup
port the required targets listed in section 2.6.2.

If a manager loses ownership of a manager selection, this
means that a new manager is taking over its responsibili
ties.  The old manager must release all resources it has
managed, and must then destroy the window that owned the
selection.  For example, a window manager losing ownership
of WM_S2 must deselect from _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t on the root
window of screen 2 before destroying the window that owned
WM_S2.

When the new manager notices that the window owning the
selection has been destroyed, it knows that it can success
fully proceed to control the resource it is planning to man
age.  If the old manager does not destroy the window within
a reasonable time, the new manager should check with the
user before destroying the window itself or killing the old
manager.

If a manager wants to give up, on its own, management of a
shared resource controlled by a selection, it must do so by
releasing the resources it is managing, and then by destroy
ing the window that owns the selection.  It should not first



                             2277





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


disown the selection, since this introduces a race condi
tion.

Clients who are interesting in knowing when the owner of a
manager selection is no longer managing the corresponding
shared resource should select for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y on the
window owning the selection so they can be notified when the
window is destroyed.  Clients are warned that after doing a
_G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r and selecting for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y, they
should do a _G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r again to ensure that the owner
did not change after initially getting the selection owner
and before selecting for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y.

Immediately after a manager successfully acquires ownership
of a manager selection, it should announce its arrival by
sending a _C_l_i_e_n_t_M_e_s_s_a_g_e event.  This event should be sent
using the _S_e_n_d_E_v_e_n_t protocol request with the following
arguments:

---------------------------------------------------------------
AArrgguummeenntt         VVaalluuee
---------------------------------------------------------------
destination:     the root window of screen 0, or the root win
                 dow of the appropriate screen if the manager
                 is managing a screen-specific resource
propagate:       False
event-mask:      _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y
event:           _C_l_i_e_n_t_M_e_s_s_a_g_e
    type:        MANAGER
    format:      32
    data[0]:10   timestamp
    data[1]:     manager selection atom
    data[2]:     the window owning the selection
    data[3]:     manager-selection-specific data
    data[4]:     manager-selection-specific data
---------------------------------------------------------------


Clients that wish to know when a specific manager has
started should select for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y on the appropriate
root window, and should watch for the appropriate MANAGER
_C_l_i_e_n_t_M_e_s_s_a_g_e.

33..  PPeeeerr--ttoo--PPeeeerr CCoommmmuunniiccaattiioonn bbyy MMeeaannss ooff CCuutt BBuuffffeerrss

The cut buffer mechanism is much simpler but much less pow
erful than the selection mechanism.  The selection mechanism
is active in that it provides a link between the owner and
-----------
  10 We use the notation data[n] to indicate the
nth element of the LISTofINT8, LISTofINT16, or
LISTofINT32 in the data field of the
_C_l_i_e_n_t_M_e_s_s_a_g_e, according to the format field.  The
list is indexed from zero.



                             2288





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


requestor clients.  The cut buffer mechanism is passive; an
owner places data in a cut buffer from which a requestor
retrieves the data at some later time.

The cut buffers consist of eight properties on the root of
screen zero, named by the predefined atoms CUT_BUFFER0 to
CUT_BUFFER7.  These properties must, at present, have type
STRING and format 8.  A client that uses the cut buffer
mechanism must initially ensure that all eight properties
exist by using _C_h_a_n_g_e_P_r_o_p_e_r_t_y requests to append zero-length
data to each.

A client that stores data in the cut buffers (an owner)
first must rotate the ring of buffers by plus 1 by using
_R_o_t_a_t_e_P_r_o_p_e_r_t_i_e_s requests to rename each buffer; that is,
CUT_BUFFER0 to CUT_BUFFER1, CUT_BUFFER1 to CUT_BUFFER2, ...,
and CUT_BUFFER7 to CUT_BUFFER0.  It then must store the data
into CUT_BUFFER0 by using a _C_h_a_n_g_e_P_r_o_p_e_r_t_y request in mode
_R_e_p_l_a_c_e.

A client that obtains data from the cut buffers should use a
_G_e_t_P_r_o_p_e_r_t_y request to retrieve the contents of CUT_BUFFER0.

In response to a specific user request, a client may rotate
the cut buffers by minus 1 by using _R_o_t_a_t_e_P_r_o_p_e_r_t_i_e_s
requests to rename each buffer; that is, CUT_BUFFER7 to
CUT_BUFFER6, CUT_BUFFER6 to CUT_BUFFER5, ..., and
CUT_BUFFER0 to CUT_BUFFER7.

Data should be stored to the cut buffers and the ring
rotated only when requested by explicit user action.  Users
depend on their mental model of cut buffer operation and
need to be able to identify operations that transfer data to
and fro.

44..  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

To permit window managers to perform their role of mediating
the competing demands for resources such as screen space,
the clients being managed must adhere to certain conventions
and must expect the window managers to do likewise.  These
conventions are covered here from the client's point of
view.

In general, these conventions are somewhat complex and will
undoubtedly change as new window management paradigms are
developed.  Thus, there is a strong bias toward defining
only those conventions that are essential and that apply
generally to all window management paradigms.  Clients
designed to run with a particular window manager can easily
define private protocols to add to these conventions, but
they must be aware that their users may decide to run some
other window manager no matter how much the designers of the
private protocol are convinced that they have seen the "one



                             2299





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


true light" of user interfaces.

It is a principle of these conventions that a general client
should neither know nor care which window manager is running
or, indeed, if one is running at all.  The conventions do
not support all client functions without a window manager
running; for example, the concept of Iconic is not directly
supported by clients.  If no window manager is running, the
concept of Iconic does not apply.  A goal of the conventions
is to make it possible to kill and restart window managers
without loss of functionality.

Each window manager will implement a particular window man
agement policy; the choice of an appropriate window manage
ment policy for the user's circumstances is not one for an
individual client to make but will be made by the user or
the user's system administrator.  This does not exclude the
possibility of writing clients that use a private protocol
to restrict themselves to operating only under a specific
window manager.  Rather, it merely ensures that no claim of
general utility is made for such programs.

For example, the claim is often made: "The client I'm writ
ing is important, and it needs to be on top." Perhaps it is
important when it is being run in earnest, and it should
then be run under the control of a window manager that rec
ognizes "important" windows through some private protocol
and ensures that they are on top.  However, imagine, for
example, that the "important" client is being debugged.
Then,  ensuring that it is always on top is no longer the
appropriate window management policy, and it should be run
under a window manager that allows other windows (for exam
ple, the debugger) to appear on top.

44..11..  CClliieenntt''ss AAccttiioonnss

In general, the object of the X Version 11 design is that
clients should, as far as possible, do exactly what they
would do in the absence of a window manager, except for the
following:

   Hinting to the window manager about the resources they
    would like to obtain

   Cooperating with the window manager by accepting the
    resources they are allocated even if they are not those
    requested

   Being prepared for resource allocations to change at any
    time







                             3300





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..11..11..  CCrreeaattiinngg aa TToopp--LLeevveell WWiinnddooww

A client's _t_o_p_-_l_e_v_e_l _w_i_n_d_o_w is a window whose override-redi
rect attribute is _F_a_l_s_e.  It must either be a child of a
root window, or it must have been a child of a root window
immediately prior to having been reparented by the window
manager.  If the client reparents the window away from the
root, the window is no longer a top-level window; but it can
become a top-level window again if the client reparents it
back to the root.

A client usually would expect to create its top-level win
dows as children of one or more of the root windows by using
some boilerplate like the following:


win = XCreateSimpleWindow(dpy, DefaultRootWindow(dpy), xsh.x, xsh.y,
                    xsh.width, xsh.height, bw, bd, bg);


If a particular one of the root windows was required, how
ever, it could use something like the following:


win = XCreateSimpleWindow(dpy, RootWindow(dpy, screen), xsh.x, xsh.y,
                    xsh.width, xsh.height, bw, bd, bg);


Ideally, it should be possible to override the choice of a
root window and allow clients (including window managers) to
treat a nonroot window as a pseudo-root.  This would allow,
for example, the testing of window managers and the use of
application-specific window managers to control the subwin
dows owned by the members of a related suite of clients.
Doing so properly requires an extension, the design of which
is under study.

From the client's point of view, the window manager will
regard its top-level window as being in one of three states:

   Normal

   Iconic

   Withdrawn

Newly created windows start in the Withdrawn state.  Transi
tions between states happen when the top-level window is
mapped and unmapped and when the window manager receives
certain messages.  For further details, see sections 4.1.2.4
and 4.1.4.






                             3311





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..11..22..  CClliieenntt PPrrooppeerrttiieess

Once the client has one or more top-level windows, it should
place properties on those windows to inform the window man
ager of the behavior that the client desires.  Window man
agers will assume values they find convenient for any of
these properties that are not supplied; clients that depend
on particular values must explicitly supply them.  The win
dow manager will not change properties written by the
client.

The window manager will examine the contents of these prop
erties when the window makes the transition from the With
drawn state and will monitor some properties for changes
while the window is in the Iconic or Normal state.  When the
client changes one of these properties, it must use _R_e_p_l_a_c_e
mode to overwrite the entire property with new data; the
window manager will retain no memory of the old value of the
property.  All fields of the property must be set to suit
able values in a single _R_e_p_l_a_c_e mode _C_h_a_n_g_e_P_r_o_p_e_r_t_y request.
This ensures that the full contents of the property will be
available to a new window manager if the existing one
crashes, if it is shut down and restarted, or if the session
needs to be shut down and restarted by the session manager.

                         Convention

     Clients writing or rewriting window manager prop
     erties must ensure that the entire content of each
     property remains valid at all times.


Some of these properties may contain the IDs of resources,
such as windows or pixmaps.  Clients should ensure that
these resources exist for at least as long as the window on
which the property resides.

If these properties are longer than expected, clients should
ignore the remainder of the property.  Extending these prop
erties is reserved to the X Consortium; private extensions
to them are forbidden.  Private additional communication
between clients and window managers should take place using
separate properties.  The only exception to this rule is the
WM_PROTOCOLS property, which may be of arbitrary length and
which may contain atoms representing private protocols; see
section 4.1.2.7.

The next sections describe each of the properties the
clients need to set, in turn.  They are summarized in the
table in section 4.4.







                             3322





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..11..22..11..  WWMM__NNAAMMEE PPrrooppeerrttyy

The WM_NAME property is an uninterpreted string that the
client wants the window manager to display in association
with the window (for example, in a window headline bar).

The encoding used for this string (and all other uninter
preted string properties) is implied by the type of the
property.  The type atoms to be used for this purpose are
described in section 2.7.1.

Window managers are expected to make an effort to display
this information.  Simply ignoring WM_NAME is not acceptable
behavior.  Clients can assume that at least the first part
of this string is visible to the user and that if the infor
mation is not visible to the user, it is because the user
has taken an explicit action to make it invisible.

On the other hand, there is no guarantee that the user can
see the WM_NAME string even if the window manager supports
window headlines.  The user may have placed the headline
off-screen or have covered it by other windows.  WM_NAME
should not be used for application-critical information or
to announce asynchronous changes of an application's state
that require timely user response.  The expected uses are to
permit the user to identify one of a number of instances of
the same client and to provide the user with noncritical
state information.

Even window managers that support headline bars will place
some limit on the length of the WM_NAME string that can be
visible; brevity here will pay dividends.

44..11..22..22..  WWMM__IICCOONN__NNAAMMEE PPrrooppeerrttyy

The WM_ICON_NAME property is an uninterpreted string that
the client wants to be displayed in association with the
window when it is iconified (for example, in an icon label).
In other respects, including the type, it is similar to
WM_NAME.  For obvious geometric reasons, fewer characters
will normally be visible in WM_ICON_NAME than WM_NAME.

Clients should not attempt to display this string in their
icon pixmaps or windows; rather, they should rely on the
window manager to do so.

44..11..22..33..  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

The type of the WM_NORMAL_HINTS property is WM_SIZE_HINTS.
Its contents are as follows:







                             3333





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


-------------------------------------------------------------
FFiieelldd         TTyyppee            CCoommmmeennttss
-------------------------------------------------------------
flags         CARD32          (see the next table)
pad           4*CARD32        For backwards compatibility
min_width     INT32           If missing, assume base_width
min_height    INT32           If missing, assume base_height
max_width     INT32
max_height    INT32
width_inc     INT32
height_inc    INT32
min_aspect    (INT32,INT32)
max_aspect    (INT32,INT32)
base_width    INT32           If missing, assume min_width
base_height   INT32           If missing, assume min_height
win_gravity   INT32           If missing, assume _N_o_r_t_h_W_e_s_t
-------------------------------------------------------------


The WM_SIZE_HINTS.flags bit definitions are as follows:

-----------------------------------------------------------------
NNaammee         VVaalluuee   FFiieelldd
-----------------------------------------------------------------
_U_S_P_o_s_i_t_i_o_n      1    User-specified x, y
_U_S_S_i_z_e          2    User-specified width, height
_P_P_o_s_i_t_i_o_n       4    Program-specified position
_P_S_i_z_e           8    Program-specified size
_P_M_i_n_S_i_z_e       16    Program-specified minimum size
_P_M_a_x_S_i_z_e       32    Program-specified maximum size
_P_R_e_s_i_z_e_I_n_c     64    Program-specified resize increments
_P_A_s_p_e_c_t       128    Program-specified min and max aspect ratios
_P_B_a_s_e_S_i_z_e     256    Program-specified base size
_P_W_i_n_G_r_a_v_     512    Program-specified window gravity
_i_t_y
-----------------------------------------------------------------


To indicate that the size and position of the window (when a
transition from the Withdrawn state occurs) was specified by
the user, the client should set the _U_S_P_o_s_i_t_i_o_n and _U_S_S_i_z_e
flags, which allow a window manager to know that the user
specifically asked where the window should be placed or how
the window should be sized and that further interaction is
superfluous.  To indicate that it was specified by the
client without any user involvement, the client should set
_P_P_o_s_i_t_i_o_n and _P_S_i_z_e.

The size specifiers refer to the width and height of the
client's window excluding borders.

The win_gravity may be any of the values specified for
WINGRAVITY in the core protocol except for _U_n_m_a_p: _N_o_r_t_h_W_e_s_t
(1), _N_o_r_t_h (2), _N_o_r_t_h_E_a_s_t (3), _W_e_s_t (4), _C_e_n_t_e_r (5), _E_a_s_t



                             334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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


(6), _S_o_u_t_h_W_e_s_t (7), _S_o_u_t_h (8), and _S_o_u_t_h_E_a_s_t (9).  It speci
fies how and whether the client window wants to be shifted
to make room for the window manager frame.

If the win_gravity is _S_t_a_t_i_c, the window manager frame is
positioned so that the inside border of the client window
inside the frame is in the same position on the screen as it
was when the client requested the transition from Withdrawn
state.  Other values of win_gravity specify a window refer
ence point.  For _N_o_r_t_h_W_e_s_t, _N_o_r_t_h_E_a_s_t, _S_o_u_t_h_W_e_s_t, and _S_o_u_t_h_
_E_a_s_t the reference point is the specified outer corner of
the window (on the outside border edge).  For _N_o_r_t_h, _S_o_u_t_h,
_E_a_s_t, and _W_e_s_t the reference point is the center of the
specified outer edge of the window border.  For _C_e_n_t_e_r the
reference point is the center of the window.  The reference
point of the window manager frame is placed at the location
on the screen where the reference point of the client window
was when the client requested the transition from Withdrawn
state.

The min_width and min_height elements specify the minimum
size that the window can be for the client to be useful.
The max_width and max_height elements specify the maximum
size.  The base_width and base_height elements in conjunc
tion with width_inc and height_inc define an arithmetic pro
gression of preferred window widths and heights for nonnega
tive integers _i and _j:



               _w_i_d_t_h=_b_a_s_e__w_i_d_t_h+(_i_w_i_d_t_h__i_n_c)


              _h_e_i_g_h_t=_b_a_s_e__h_e_i_g_h_t+(_j_h_e_i_g_h_t__i_n_c)



Window managers are encouraged to use _i and _j instead of
width and height in reporting window sizes to users.  If a
base size is not provided, the minimum size is to be used in
its place and vice versa.

The min_aspect and max_aspect fields are fractions with the
numerator first and the denominator second, and they allow a
client to specify the range of aspect ratios it prefers.
Window managers that honor aspect ratios should take into
account the base size in determining the preferred window
size.  If a base size is provided along with the aspect
ratio fields, the base size should be subtracted from the
window size prior to checking that the aspect ratio falls in
range.  If a base size is not provided, nothing should be
subtracted from the window size.  (The minimum size is not
to be used in place of the base size for this purpose.)




                             3355





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..11..22..44..  WWMM__HHIINNTTSS PPrrooppeerrttyy

The WM_HINTS property (whose type is WM_HINTS) is used to
communicate to the window manager.  It conveys the informa
tion the window manager needs other than the window geome
try, which is available from the window itself; the con
straints on that geometry, which is available from the
WM_NORMAL_HINTS structure; and various strings, which need
separate properties, such as WM_NAME.  The contents of the
properties are as follows:

-----------------------------------------------------------
FFiieelldd           TTyyppee     CCoommmmeennttss
-----------------------------------------------------------
flags           CARD32   (see the next table)
input           CARD32   The client's input model
initial_state   CARD32   The state when first mapped
icon_pixmap     PIXMAP   The pixmap for the icon image
icon_window     WINDOW   The window for the icon image
icon_x          INT32    The icon location
icon_y          INT32
icon_mask       PIXMAP   The mask for the icon shape
window_group    WINDOW   The ID of the group leader window
-----------------------------------------------------------


The WM_HINTS.flags bit definitions are as follows:

-------------------------------------------------
NNaammee              VVaalluuee   FFiieelldd
-------------------------------------------------
_I_n_p_u_t_H_i_n_t            1    input
_S_t_a_t_e_H_i_n_t            2    initial_state
_I_c_o_n_P_i_x_m_a_p_H_i_n_t       4    icon_pixmap
_I_c_o_n_W_i_n_d_o_w_H_i_n_t       8    icon_window
_I_c_o_n_P_o_s_i_t_i_o_n_       16    icon_x & icon_y
_H_i_n_t
_I_c_o_n_M_a_s_k_H_i_n_t        32    icon_mask
_W_i_n_d_o_w_G_r_o_u_p_H_i_n_t     64    window_group
_M_e_s_s_a_g_e_H_i_n_t        128    (this bit is obsolete)
_U_r_g_e_n_c_y_H_i_n_t        256    urgency
-------------------------------------------------


Window managers are free to assume convenient values for all
fields of the WM_HINTS property if a window is mapped with
out one.

The input field is used to communicate to the window manager
the input focus model used by the client (see section
4.1.7).

Clients with the Globally Active and No Input models should
set the input flag to _F_a_l_s_e.  Clients with the Passive and



                             3366





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


Locally Active models should set the input flag to _T_r_u_e.

From the client's point of view, the window manager will
regard the client's top-level window as being in one of
three states:

   Normal

   Iconic

   Withdrawn

The semantics of these states are described in section
4.1.4.  Newly created windows start in the Withdrawn state.
Transitions between states happen when a top-level window is
mapped and unmapped and when the window manager receives
certain messages.

The value of the initial_state field determines the state
the client wishes to be in at the time the top-level window
is mapped from the Withdrawn state, as shown in the follow
ing table:

--------------------------------------------
SSttaattee         VVaalluuee   CCoommmmeennttss
--------------------------------------------
_N_o_r_m_a_l_S_t_a_t_e     1     The window is visible
_I_c_o_n_i_c_S_t_a_t_e     3     The icon is visible
--------------------------------------------


The icon_pixmap field may specify a pixmap to be used as an
icon.  This pixmap should be:

   One of the sizes specified in the WM_ICON_SIZE property
    on the root if it exists (see section 4.1.3.2).

   1-bit deep.  The window manager will select, through the
    defaults database, suitable background (for the 0 bits)
    and foreground (for the 1 bits) colors.  These defaults
    can, of course, specify different colors for the icons
    of different clients.

The icon_mask specifies which pixels of the icon_pixmap
should be used as the icon, allowing for icons to appear
nonrectangular.

The icon_window field is the ID of a window the client wants
used as its icon.  Most, but not all, window managers will
support icon windows.  Those that do not are likely to have
a user interface in which small windows that behave like
icons are completely inappropriate.  Clients should not
attempt to remedy the omission by working around it.




                             3377





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


Clients that need more capabilities from the icons than a
simple two-color bitmap should use icon windows.  Rules for
clients that do are set out in section 4.1.9.

The (icon_x,icon_y) coordinate is a hint to the window man
ager as to where it should position the icon.  The policies
of the window manager control the positioning of icons, so
clients should not depend on attention being paid to this
hint.

The window_group field lets the client specify that this
window belongs to a group of windows.  An example is a sin
gle client manipulating multiple children of the root win
dow.

                        Conventions


1.   The window_group field should be set to the ID of the
     group leader.  The window group leader may be a window
     that exists only for that purpose; a placeholder group
     leader of this kind would never be mapped either by the
     client or by the window manager.

2.   The properties of the window group leader are those for
     the group as a whole (for example, the icon to be shown
     when the entire group is iconified).


Window managers may provide facilities for manipulating the
group as a whole.  Clients, at present, have no way to oper
ate on the group as a whole.

The messages bit, if set in the flags field, indicates that
the client is using an obsolete window manager communication
protocol,11 rather than the WM_PROTOCOLS mechanism of sec
tion 4.1.2.7.

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 must make some effort to draw the user's attention to
this window while this flag is set.  The window manager must
also monitor the state of this flag for the entire time the
window is in the Normal or Iconic state and must take appro
priate action when the state of the flag changes.  The flag
-----------
  11 This obsolete protocol was described in the
July 27, 1988 draft of the ICCCM.  Windows using
it can also be detected because their WM_HINTS
properties are four bytes longer than expected.
Window managers are free to support clients using
the obsolete protocol in a backwards compatibility
mode.



                             3388





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


is otherwise independent of the window's state; in particu
lar, the window manager is not required to deiconify the
window if the client sets the flag on an Iconic window.
Clients must provide some means by which the user can cause
the _U_r_g_e_n_c_y_H_i_n_t flag to be set to zero or the window to be
withdrawn.  The user's action can either mitigate the actual
condition that made the window urgent, or it can merely shut
off the alarm.

                         Rationale

     This mechanism is useful for alarm dialog boxes or
     reminder windows, in cases where mapping the win
     dow is not enough (e.g. in the presence of multi-
     workspace or virtual desktop window managers), and
     where using an override-redirect window is too
     intrusive.  For example, the window manager may
     attract attention to an urgent window by adding an
     indicator to its title bar or its icon.  Window
     managers may also take additional action for a
     window that is newly urgent, such as by flashing
     its icon (if the window is iconic) or by raising
     it to the top of the stack.


44..11..22..55..  WWMM__CCLLAASSSS PPrrooppeerrttyy

The WM_CLASS property (of type STRING without control char
acters) contains two consecutive null-terminated strings.
These specify the Instance and Class names to be used by
both the client and the window manager for looking up
resources for the application or as identifying information.
This property must be present when the window leaves the
Withdrawn state and may be changed only while the window is
in the Withdrawn state.  Window managers may examine the
property only when they start up and when the window leaves
the Withdrawn state, but there should be no need for a
client to change its state dynamically.

The two strings, respectively, are:

   A string that names the particular instance of the
    application to which the client that owns this window
    belongs.  Resources that are specified by instance name
    override any resources that are specified by class name.
    Instance names can be specified by the user in an oper
    ating-system specific manner.  On POSIX-conformant sys
    tems, the following conventions are used:

    -    If "-name NAME" is given on the command line, NAME
         is used as the instance name.

    -    Otherwise, if the environment variable
         RESOURCE_NAME is set, its value will be used as the



                             3399





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


         instance name.

    -    Otherwise, the trailing part of the name used to
         invoke the program (argv[0] stripped of any direc
         tory names) is used as the instance name.

   A string that names the general class of applications to
    which the client that owns this window belongs.
    Resources that are specified by class apply to all
    applications that have the same class name.  Class names
    are specified by the application writer.  Examples of
    commonly used class names include: "Emacs", "XTerm",
    "XClock", "XLoad", and so on.

Note that WM_CLASS strings are null-terminated and, thus,
differ from the general conventions that STRING properties
are null-separated.  This inconsistency is necessary for
backwards compatibility.

44..11..22..66..  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

The WM_TRANSIENT_FOR property (of type WINDOW) contains the
ID of another top-level window.  The implication is that
this window is a pop-up on behalf of the named window, and
window managers may decide not to decorate transient windows
or may treat them differently in other ways.  In particular,
window managers should present newly mapped WM_TRANSIENT_FOR
windows without requiring any user interaction, even if map
ping top-level windows normally does require interaction.
Dialogue boxes, for example, are an example of windows that
should have WM_TRANSIENT_FOR set.

It is important not to confuse WM_TRANSIENT_FOR with over
ride-redirect.  WM_TRANSIENT_FOR should be used in those
cases where the pointer is not grabbed while the window is
mapped (in other words, if other windows are allowed to be
active while the transient is up).  If other windows must be
prevented from processing input (for example, when imple
menting pop-up menus), use override-redirect and grab the
pointer while the window is mapped.

44..11..22..77..  WWMM__PPRROOTTOOCCOOLLSS PPrrooppeerrttyy

The WM_PROTOCOLS property (of type ATOM) is a list of atoms.
Each atom identifies a communication protocol between the
client and the window manager in which the client is willing
to participate.  Atoms can identify both standard protocols
and private protocols specific to individual window man
agers.

All the protocols in which a client can volunteer to take
part involve the window manager sending the client a
_C_l_i_e_n_t_M_e_s_s_a_g_e event and the client taking appropriate
action.  For details of the contents of the event, see



                             4400





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


section 4.2.8.  In each case, the protocol transactions are
initiated by the window manager.

The WM_PROTOCOLS property is not required.  If it is not
present, the client does not want to participate in any win
dow manager protocols.

The X Consortium will maintain a registry of protocols to
avoid collisions in the name space.  The following table
lists the protocols that have been defined to date.

-----------------------------------------------------------------------
PPrroottooccooll            SSeeccttiioonn     PPuurrppoossee
-----------------------------------------------------------------------
WM_TAKE_FOCUS        4.1.7      Assignment of input focus
WM_SAVE_YOURSELF   Appendix C   Save client state request (deprecated)
WM_DELETE_WINDOW    4.2.8.1     Request to delete top-level window
-----------------------------------------------------------------------

It is expected that this table will grow over time.

44..11..22..88..  WWMM__CCOOLLOORRMMAAPP__WWIINNDDOOWWSS PPrrooppeerrttyy

The WM_COLORMAP_WINDOWS property (of type WINDOW) on a top-
level window is a list of the IDs of windows that may need
colormaps installed that differ from the colormap of the
top-level window.  The window manager will watch this list
of windows for changes in their colormap attributes.  The
top-level window is always (implicitly or explicitly) on the
watch list.  For the details of this mechanism, see section
4.1.8.

44..11..22..99..  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

The client should set the WM_CLIENT_MACHINE property (of one
of the TEXT types) to a string that forms the name of the
machine running the client as seen from the machine running
the server.

44..11..33..  WWiinnddooww MMaannaaggeerr PPrrooppeerrttiieess

The properties that were described in the previous section
are those that the client is responsible for maintaining on
its top-level windows.  This section describes the proper
ties that the window manager places on client's top-level
windows and on the root.

44..11..33..11..  WWMM__SSTTAATTEE PPrrooppeerrttyy

The window manager will place a WM_STATE property (of type
WM_STATE) on each top-level client window that is not in the
Withdrawn state.  Top-level windows in the Withdrawn state
may or may not have the WM_STATE property.  Once the top-
level window has been withdrawn, the client may re-use it



                             4411





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


for another purpose.  Clients that do so should remove the
WM_STATE property if it is still present.

Some clients (such as xxpprroopp) will ask the user to click over
a window on which the program is to operate.  Typically, the
intent is for this to be a top-level window.  To find a top-
level window, clients should search the window hierarchy
beneath the selected location for a window with the WM_STATE
property.  This search must be recursive in order to cover
all window manager reparenting possibilities.  If no window
with a WM_STATE property is found, it is recommended that
programs use a mapped child-of-root window if one is present
beneath the selected location.

The contents of the WM_STATE property are defined as fol
lows:

--------------------------------------
FFiieelldd   TTyyppee     CCoommmmeennttss
--------------------------------------
state   CARD32   (see the next table)
icon    WINDOW   ID of icon window
--------------------------------------


The following table lists the WM_STATE.state values:

-----------------------
SSttaattee            VVaalluuee
-----------------------
_W_i_t_h_d_r_a_w_n_S_t_a_t_e     0
_N_o_r_m_a_l_S_t_a_t_e        1
_I_c_o_n_i_c_S_t_a_t_e        3
-----------------------


Adding other fields to this property is reserved to the X
Consortium.  Values for the state field other than those
defined in the above table are reserved for use by X Consor
tium.

The state field describes the window manager's idea of the
state the window is in, which may not match the client's
idea as expressed in the initial_state field of the WM_HINTS
property (for example, if the user has asked the window man
ager to iconify the window).  If it is _N_o_r_m_a_l_S_t_a_t_e, the win
dow manager believes the client should be animating its win
dow.  If it is _I_c_o_n_i_c_S_t_a_t_e, the client should animate its
icon window.  In either state, clients should be prepared to
handle exposure events from either window.

When the window is withdrawn, the window manager will either
change the state field's value to _W_i_t_h_d_r_a_w_n_S_t_a_t_e or it will
remove the WM_STATE property entirely.



                             4422





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


The icon field should contain the window ID of the window
that the window manager uses as the icon for the window on
which this property is set.  If no such window exists, the
icon field should be _N_o_n_e.  Note that this window could be
but is not necessarily the same window as the icon window
that the client may have specified in its WM_HINTS property.
The WM_STATE icon may be a window that the window manager
has supplied and that contains the client's icon pixmap, or
it may be an ancestor of the client's icon window.

44..11..33..22..  WWMM__IICCOONN__SSIIZZEE PPrrooppeerrttyy

A window manager that wishes to place constraints on the
sizes of icon pixmaps and/or windows should place a property
called WM_ICON_SIZE on the root.  The contents of this prop
erty are listed in the following table.

--------------------------------------------------------
FFiieelldd        TTyyppee     CCoommmmeennttss
--------------------------------------------------------
min_width    CARD32   The data for the icon size series
min_height   CARD32
max_width    CARD32
max_height   CARD32
width_inc    CARD32
height_inc   CARD32
--------------------------------------------------------


For more details see section 14.1.12 in _X_l_i_b _- _C _L_a_n_g_u_a_g_e _X
_I_n_t_e_r_f_a_c_e.

44..11..44..  CChhaannggiinngg WWiinnddooww SSttaattee

From the client's point of view, the window manager will
regard each of the client's top-level windows as being in
one of three states, whose semantics are as follows:

   _N_o_r_m_a_l_S_t_a_t_e - The client's top-level window is viewable.

   _I_c_o_n_i_c_S_t_a_t_e - The client's top-level window is iconic
    (whatever that means for this window manager).  The
    client can assume that its top-level window is not view
    able, its icon_window (if any) will be viewable and,
    failing that, its icon_pixmap (if any) or its
    WM_ICON_NAME will be displayed.

   _W_i_t_h_d_r_a_w_n_S_t_a_t_e - Neither the client's top-level window
    nor its icon is visible.

In fact, the window manager may implement states with seman
tics other than those described above.  For example, a win
dow manager might implement a concept of an "inactive" state
in which an infrequently used client's window would be



                             4433





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


represented as a string in a menu.  But this state is invis
ible to the client, which would see itself merely as being
in the Iconic state.

Newly created top-level windows are in the Withdrawn state.
Once the window has been provided with suitable properties,
the client is free to change its state as follows:

   Withdrawn -> Normal - The client should map the window
    with WM_HINTS.initial_state being _N_o_r_m_a_l_S_t_a_t_e.

   Withdrawn -> Iconic - The client should map the window
    with WM_HINTS.initial_state being _I_c_o_n_i_c_S_t_a_t_e.

   Normal -> Iconic - The client should send a _C_l_i_e_n_t_M_e_s_
    _s_a_g_e event as described later in this section.

   Normal -> Withdrawn - The client should unmap the window
    and follow it with a synthetic _U_n_m_a_p_N_o_t_i_f_y event as
    described later in this section.

   Iconic -> Normal - The client should map the window.
    The contents of WM_HINTS.initial_state are irrelevant in
    this case.

   Iconic -> Withdrawn - The client should unmap the window
    and follow it with a synthetic _U_n_m_a_p_N_o_t_i_f_y event as
    described later in this section.

Only the client can effect a transition into or out of the
Withdrawn state.  Once a client's window has left the With
drawn state, the window will be mapped if it is in the Nor
mal state and the window will be unmapped if it is in the
Iconic state.  Reparenting window managers must unmap the
client's window when it is in the Iconic state, even if an
ancestor window being unmapped renders the client's window
unviewable.  Conversely, if a reparenting window manager
renders the client's window unviewable by unmapping an
ancestor, the client's window is by definition in the Iconic
state and must also be unmapped.

                   Advice to Implementors

     Clients can select for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y on their
     top-level windows to track transitions between
     Normal and Iconic states.  Receipt of a _M_a_p_N_o_t_i_f_y
     event will indicate a transition to the Normal
     state, and receipt of an _U_n_m_a_p_N_o_t_i_f_y event will
     indicate a transition to the Iconic state.


When changing the state of the window to Withdrawn, the
client must (in addition to unmapping the window) send a
synthetic _U_n_m_a_p_N_o_t_i_f_y event by using a _S_e_n_d_E_v_e_n_t request



                             444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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


with the following arguments:

----------------------------------------------------------------
AArrgguummeenntt              VVaalluuee
----------------------------------------------------------------
destination:          The root
propagate:            _F_a_l_s_e
event-mask:           (_S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_|_S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y)
event: an _U_n_m_a_p_N_o_
_t_i_f_y with:
    event:            The root
    window:           The window itself
    from-configure:   _F_a_l_s_e
----------------------------------------------------------------


                         Rationale

     The reason for requiring the client to send a syn
     thetic _U_n_m_a_p_N_o_t_i_f_y event is to ensure that the
     window manager gets some notification of the
     client's desire to change state, even though the
     window may already be unmapped when the desire is
     expressed.


                   Advice to Implementors

     For compatibility with obsolete clients, window
     managers should trigger the transition to the
     Withdrawn state on the real _U_n_m_a_p_N_o_t_i_f_y rather
     than waiting for the synthetic one.  They should
     also trigger the transition if they receive a syn
     thetic _U_n_m_a_p_N_o_t_i_f_y on a window for which they have
     not yet received a real _U_n_m_a_p_N_o_t_i_f_y.


When a client withdraws a window, the window manager will
then update or remove the WM_STATE property as described in
section 4.1.3.1.  Clients that want to re-use a client win
dow (e.g. by mapping it again or reparenting it elsewhere)
after withdrawing it must wait for the withdrawal to be com
plete before proceeding.  The preferred method for doing
this is for clients to wait for the window manager to update
or remove the WM_STATE property.12
-----------
  12 Earlier versions of these conventions prohib
ited clients from reading the WM_STATE property.
Clients operating under the earlier conventions
used the technique of tracking _R_e_p_a_r_e_n_t_N_o_t_i_f_y
events to wait for the top-level window to be
reparented back to the root window.  This is still
a valid technique; however, it works only for
reparenting window managers, and the WM_STATE



                             4455





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


If the transition is from the Normal to the Iconic state,
the client should send a _C_l_i_e_n_t_M_e_s_s_a_g_e event to the root
with:

   Window == the window to be iconified

   Type13 == the atom WM_CHANGE_STATE

   Format == 32

   Data[0] == IconicState

                           Rationale

         The format of this _C_l_i_e_n_t_M_e_s_s_a_g_e event does
         not match the format of _C_l_i_e_n_t_M_e_s_s_a_g_e_s in sec
         tion 4.2.8.  This is because they are sent by
         the window manager to clients, and this mes
         sage is sent by clients to the window manager.


Other values of data[0] are reserved for future extensions
to these conventions.  The parameters of the _S_e_n_d_E_v_e_n_t
request should be those described for the synthetic _U_n_m_a_p_N_o_
_t_i_f_y event.

                   Advice to Implementors

     Clients can also select for _V_i_s_i_b_i_l_i_t_y_C_h_a_n_g_e
     events on their top-level or icon windows.  They
     will then receive a _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y(state==Fully
     Obscured) event when the window concerned becomes
     completely obscured even though mapped (and thus,
     perhaps a waste of time to update) and a
     _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y(state!=FullyObscured) event when
     it becomes even partly viewable.


                   Advice to Implementors

     When a window makes a transition from the Normal
     state to either the Iconic or to the Withdrawn
     state, clients should be aware that the window
     manager may make transients for this window inac
     cessible.  Clients should not rely on transient
     windows being available to the user when the tran
     sient owner window is not in the Normal state.
-----------
technique is to be preferred.
  13 The type field of the _C_l_i_e_n_t_M_e_s_s_a_g_e event
(called the message_type field by Xlib) should not
be confused with the code field of the event
itself, which will have the value 33
(_C_l_i_e_n_t_M_e_s_s_a_g_e).



                             4466





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


     When withdrawing a window, clients are advised to
     withdraw transients for the window.


44..11..55..  CCoonnffiigguurriinngg tthhee WWiinnddooww

Clients can resize and reposition their top-level windows by
using the _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w request.  The attributes of the
window that can be altered with this request are as follows:

   The [x,y] location of the window's upper left-outer cor
    ner

   The [width,height] of the inner region of the window
    (excluding borders)

   The border width of the window

   The window's position in the stack

The coordinate system in which the location is expressed is
that of the root (irrespective of any reparenting that may
have occurred).  The border width to be used and win_gravity
position hint to be used are those most recently requested
by the client.  Client configure requests are interpreted by
the window manager in the same manner as the initial window
geometry mapped from the Withdrawn state, as described in
section 4.1.2.3.  Clients must be aware that there is no
guarantee that the window manager will allocate them the
requested size or location and must be prepared to deal with
any size and location.  If the window manager decides to
respond to a _C_o_n_f_i_g_u_r_e_R_e_q_u_e_s_t request by:

   Not changing the size, location, border width, or stack
    ing order of the window at all

    A client will receive a synthetic _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event
    that describes the (unchanged) geometry of the window.
    The (x,y) coordinates will be in the root coordinate
    system, adjusted for the border width the client
    requested, irrespective of any reparenting that has
    taken place.  The border_width will be the border width
    the client requested.  The client will not receive a
    real _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event because no change has actu
    ally taken place.

   Moving or restacking the window without resizing it or
    changing its border width

    A client will receive a synthetic _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event
    following the change that describes the new geometry of
    the window.  The event's (x,y) coordinates will be in
    the root coordinate system adjusted for the border width
    the client requested.  The border_width will be the



                             4477





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


    border width the client requested.  The client may not
    receive a real _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event that describes this
    change because the window manager may have reparented
    the top-level window.  If the client does receive a real
    event, the synthetic event will follow the real one.

   Resizing the window or changing its border width
    (regardless of whether the window was also moved or
    restacked)

    A client that has selected for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y events
    will receive a real _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event.  Note that
    the coordinates in this event are relative to the par
    ent, which may not be the root if the window has been
    reparented.  The coordinates will reflect the actual
    border width of the window (which the window manager may
    have changed).  The _T_r_a_n_s_l_a_t_e_C_o_o_r_d_i_n_a_t_e_s request can be
    used to convert the coordinates if required.

The general rule is that coordinates in real _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y
events are in the parent's space; in synthetic events, they
are in the root space.

                   Advice to Implementors

     Clients cannot distinguish between the case where
     a top-level window is resized and moved from the
     case where the window is resized but not moved,
     since a real _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event will be
     received in both cases.  Clients that are con
     cerned with keeping track of the absolute position
     of a top-level window should keep a piece of state
     indicating whether they are certain of its posi
     tion.  Upon receipt of a real _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y
     event on the top-level window, the client should
     note that the position is unknown.  Upon receipt
     of a synthetic _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event, the client
     should note the position as known, using the posi
     tion in this event.  If the client receives a
     _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,
     _M_o_t_i_o_n_N_o_t_i_f_y, _E_n_t_e_r_N_o_t_i_f_y, or _L_e_a_v_e_N_o_t_i_f_y event on
     the window (or on any descendant), the client can
     deduce the top-level window's position from the
     difference between the (event-x, event-y) and
     (root-x, root-y) coordinates in these events.
     Only when the position is unknown does the client
     need to use the _T_r_a_n_s_l_a_t_e_C_o_o_r_d_i_n_a_t_e_s request to
     find the position of a top-level window.


Clients should be aware that their borders may not be visi
ble.  Window managers are free to use reparenting techniques
to decorate client's top-level windows with borders contain
ing titles,  controls, and other details to maintain a



                             4488





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


consistent look-and-feel.  If they do, they are likely to
override the client's attempts to set the border width and
set it to zero.  Clients, therefore, should not depend on
the top-level window's border being visible or use it to
display any critical information.  Other window managers
will allow the top-level windows border to be visible.

                         Convention

     Clients should set the desired value of the bor
     der-width attribute on all _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w
     requests to avoid a race condition.


Clients that change their position in the stack must be
aware that they may have been reparented, which means that
windows that used to be siblings no longer are.  Using a
nonsibling as the sibling parameter on a _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w
request will cause an error.

                         Convention

     Clients that use a _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w request to
     request a change in their position in the stack
     should do so using _N_o_n_e in the sibling field.


Clients that must position themselves in the stack relative
to some window that was originally a sibling must do the
_C_o_n_f_i_g_u_r_e_W_i_n_d_o_w request (in case they are running under a
nonreparenting window manager), be prepared to deal with a
resulting error, and then follow with a synthetic _C_o_n_f_i_g_u_r_
_e_R_e_q_u_e_s_t event by invoking a _S_e_n_d_E_v_e_n_t request with the fol
lowing arguments:

---------------------------------------------------------------
AArrgguummeenntt             VVaalluuee
---------------------------------------------------------------
destination:         The root
propagate:           _F_a_l_s_e
event-mask:          (_S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t_|_S_u_b_s_t_r_u_c_t_u_r_e_N_o_t_i_f_y)
event: a _C_o_n_f_i_g_u_r_
_e_R_e_q_u_e_s_t with:
    event:           The root
    window:          The window itself
    ...              Other parameters from the _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w
                     request
---------------------------------------------------------------


Window managers are in any case free to position windows in
the stack as they see fit, and so clients should not rely on
receiving the stacking order they have requested.  Clients
should ignore the above-sibling field of both real and



                             4499





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


synthetic _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y events received on their top-level
windows because this field may not contain useful informa
tion.

44..11..66..  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

The attributes that may be supplied when a window is created
may be changed by using the _C_h_a_n_g_e_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s request.
The window attributes are listed in the following table.

-------------------------------------------
AAttttrriibbuuttee                PPrriivvaattee ttoo CClliieenntt
-------------------------------------------
Background pixmap               Yes
Background pixel                Yes
Border pixmap                   Yes
Border pixel                    Yes
Bit gravity                     Yes
Window gravity                  No
Backing-store hint              Yes
Save-under hint                 No
Event mask                      No
Do-not-propagate mask           Yes
Override-redirect flag          No
Colormap                        Yes
Cursor                          Yes
-------------------------------------------


Most attributes are private to the client and will never be
interfered with by the window manager.  For the attributes
that are not private to the client:

   The window manager is free to override the window grav
    ity; a reparenting window manager may want to set the
    top-level window's window gravity for its own purposes.

   Clients are free to set the save-under hint on their
    top-level windows, but they must be aware that the hint
    may be overridden by the window manager.

   Windows, in effect, have per-client event masks, and so,
    clients may select for whatever events are convenient
    irrespective of any events the window manager is select
    ing for.  There are some events for which only one
    client at a time may select, but the window manager
    should not select for them on any of the client's win
    dows.

   Clients can set override-redirect on top-level windows
    but are encouraged not to do so except as described in
    sections 4.1.10 and 4.2.9.





                             5500





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..11..77..  IInnppuutt FFooccuuss

There are four models of input handling:

   No Input - The client never expects keyboard input.  An
    example would be _x_l_o_a_d or another output-only client.

   Passive Input - The client expects keyboard input but
    never explicitly sets the input focus.  An example would
    be a simple client with no subwindows, which will accept
    input in _P_o_i_n_t_e_r_R_o_o_t mode or when the window manager
    sets the input focus to its top-level window (in click-
    to-type mode).

   Locally Active Input - The client expects keyboard input
    and explicitly sets the input focus, but it only does so
    when one of its windows already has the focus.  An exam
    ple would be a client with subwindows defining various
    data entry fields that uses Next and Prev keys to move
    the input focus between the fields.  It does so when its
    top-level window has acquired the focus in _P_o_i_n_t_e_r_R_o_o_t
    mode or when the window manager sets the input focus to
    its top-level window (in click-to-type mode).

   Globally Active Input - The client expects keyboard
    input and explicitly sets the input focus, even when it
    is in windows the client does not own.  An example would
    be a client with a scroll bar that wants to allow users
    to scroll the window without disturbing the input focus
    even if it is in some other window.  It wants to acquire
    the input focus when the user clicks in the scrolled
    region but not when the user clicks in the scroll bar
    itself.  Thus, it wants to prevent the window manager
    from setting the input focus to any of its windows.

The four input models and the corresponding values of the
input field and the presence or absence of the WM_TAKE_FOCUS
atom in the WM_PROTOCOLS property are listed in the follow
ing table:

----------------------------------------------
IInnppuutt MMooddeell       IInnppuutt FFiieelldd   WWMM__TTAAKKEE__FFOOCCUUSS
----------------------------------------------
No Input             _F_a_l_s_e         Absent
Passive              _T_r_u_e          Absent
Locally Active       _T_r_u_e          Present
Globally Active      _F_a_l_s_e         Present
----------------------------------------------


Passive and Locally Active clients set the input field of
WM_HINTS to _T_r_u_e, which indicates that they require window
manager assistance  in acquiring the input focus.  No Input
and Globally Active clients set the input field to _F_a_l_s_e,



                             5511





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


which requests that the window manager not set the input
focus to their top-level window.

Clients that use a _S_e_t_I_n_p_u_t_F_o_c_u_s request must set the time
field to the timestamp of the event that caused them to make
the attempt.  This cannot be a _F_o_c_u_s_I_n event because they do
not have timestamps.  Clients may also acquire the focus
without a corresponding _E_n_t_e_r_N_o_t_i_f_y.  Note that clients must
not use _C_u_r_r_e_n_t_T_i_m_e in the time field.

Clients using the Globally Active model can only use a _S_e_t_
_I_n_p_u_t_F_o_c_u_s request to acquire the input focus when they do
not already have it on receipt of one of the following
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

   Passive-grabbed _K_e_y_P_r_e_s_s

   Passive-grabbed _K_e_y_R_e_l_e_a_s_e

In general, clients should avoid using passive-grabbed key
events for this purpose, except when they are unavoidable
(as, for example, a selection tool that establishes a pas
sive grab on the keys that cut,  copy,  or paste).

The method by which the user commands the window manager to
set the focus to a window is up to the window manager.  For
example, clients cannot determine whether they will see the
click that transfers the focus.

Windows with the atom WM_TAKE_FOCUS in their WM_PROTOCOLS
property may receive a _C_l_i_e_n_t_M_e_s_s_a_g_e event from the window
manager (as described in section 4.2.8) with WM_TAKE_FOCUS
in its data[0] field and a valid timestamp (i.e. not
_C_u_r_r_e_n_t_T_i_m_e) in its data[1] field.  If they want the focus,
they should respond with a _S_e_t_I_n_p_u_t_F_o_c_u_s request with its
window field set to the window of theirs that last had the
input focus or to their default input window, and the time
field set to the timestamp in the message.  For further
information, see section 4.2.7.

A client could receive WM_TAKE_FOCUS when opening from an
icon or when the user has clicked outside the top-level win
dow in an area that indicates to the window manager that it
should assign the focus (for example, clicking in the head
line bar can be used to assign the focus).

The goal is to support window managers that want to assign
the input focus to a top-level window in such a way that the
top-level window either can assign it to one of its subwin
dows or can decline the offer of the focus.  For example, a



                             5522





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


clock or a text editor with no currently open frames might
not want to take focus even though the window manager gener
ally believes that clients should take the input focus after
being deiconified or raised.

Clients that set the input focus need to decide a value for
the revert-to field of the _S_e_t_I_n_p_u_t_F_o_c_u_s request.  This
determines the behavior of the input focus if the window the
focus has been set to becomes not viewable.  The value can
be any of the following:

   _P_a_r_e_n_t - In general, clients should use this value when
    assigning focus to one of their subwindows.  Unmapping
    the subwindow will cause focus to revert to the parent,
    which is probably what you want.

   _P_o_i_n_t_e_r_R_o_o_t - Using this value with a click-to-type
    focus management policy leads to race conditions because
    the window becoming unviewable may coincide with the
    window manager deciding to move the focus elsewhere.

   _N_o_n_e - Using this value causes problems if the window
    manager reparents the window, as most window managers
    will, and then crashes.  The input focus will be _N_o_n_e,
    and there will probably be no way to change it.

Note that neither _P_o_i_n_t_e_r_R_o_o_t nor _N_o_n_e is really safe to
use.

                         Convention

     Clients that invoke a _S_e_t_I_n_p_u_t_F_o_c_u_s request should
     set the revert-to argument to _P_a_r_e_n_t.


A convention is also required for clients that want to give
up the input focus.  There is no safe value set for them to
set the input focus to; therefore, they should ignore input
material.

                         Convention

     Clients should not give up the input focus of
     their own volition.  They should ignore input that
     they receive instead.


44..11..88..  CCoolloorrmmaappss

The window manager is responsible for installing and unin
stalling colormaps on behalf of clients with top-level win
dows that the window manager manages.





                             5533





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


Clients provide the window manager with hints as to which
colormaps to install and uninstall.  Clients must not
install or uninstall colormaps themselves (except under the
circumstances noted below).  When a client's top-level win
dow gets the colormap focus (as a result of whatever col
ormap focus policy is implemented by the window manager),
the window manager will ensure that one or more of the
client's colormaps are installed.

Clients whose top-level windows and subwindows all use the
same colormap should set its ID in the colormap field of the
top-level window's attributes.  They should not set a
WM_COLORMAP_WINDOWS property on the top-level window.  If
they want to change the colormap, they should change the
top-level window's colormap attribute.  The window manager
will track changes to the window's colormap attribute and
install colormaps as appropriate.

Clients that create windows can use the value _C_o_p_y_F_r_o_m_P_a_r_e_n_t
to inherit their parent's colormap.  Window managers will
ensure that the root window's colormap field contains a col
ormap that is suitable for clients to inherit.  In particu
lar, the colormap will provide distinguishable colors for
_B_l_a_c_k_P_i_x_e_l and _W_h_i_t_e_P_i_x_e_l.

Top-level windows that have subwindows or override-redirect
pop-up windows whose colormap requirements differ from the
top-level window should have a WM_COLORMAP_WINDOWS property.
This property contains a list of IDs for windows whose col
ormaps the window manager should attempt to have installed
when, in the course of its individual colormap focus policy,
it assigns the colormap focus to the top-level window (see
section 4.1.2.8).  The list is ordered by the importance to
the client of having the colormaps installed.  The window
manager will track changes to this property and will track
changes to the colormap attribute of the windows in the
property.

If the relative importance of colormaps changes, the client
should update the WM_COLORMAP_WINDOWS property to reflect
the new ordering.  If the top-level window does not appear
in the list, the window manager will assume it to be of
higher priority than any window in the list.

WM_TRANSIENT_FOR windows either can have their own WM_COL
ORMAP_WINDOWS property or can appear in the property of the
window they are transient for, as appropriate.

                         Rationale

     An alternative design was considered for how
     clients should hint to the window manager about
     their colormap requirements.  This alternative
     design specified a list of colormaps instead of a



                             554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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


     list of windows.  The current design, a list of
     windows, was chosen for two reasons.  First, it
     allows window managers to find the visuals of the
     colormaps, thus permitting visual-dependent col
     ormap installation policies.  Second, it allows
     window managers to select for _V_i_s_i_b_i_l_i_t_y_C_h_a_n_g_e
     events on the windows concerned and to ensure that
     colormaps are only installed if the windows that
     need them are visible.  The alternative design
     allows for neither of these policies.


                   Advice to Implementors

     Clients should be aware of the min-installed-maps
     and max-installed-maps fields of the connection
     setup information, and the effect that the minimum
     value has on the "required list" defined by the
     Protocol in the description of the _I_n_s_t_a_l_l_C_o_l_o_r_m_a_p
     request.  Briefly, the min-installed-maps most
     recently installed maps are guaranteed to be
     installed.  This value is often one; clients need
     ing multiple colormaps should beware.


Whenever possible, clients should use the mechanisms
described above and let the window manager handle colormap
installation.  However, clients are permitted to perform
colormap installation on their own while they have the
pointer grabbed.  A client performing colormap installation
must notify the window manager prior to the first installa
tion.  When the client has finished its colormap installa
tion, it must also notify the window manager.  The client
notifies the window manager by issuing a _S_e_n_d_E_v_e_n_t request
with the following arguments:


----------------------------------------------------------
AArrgguummeenntt              VVaalluuee
----------------------------------------------------------
destination:          the root window of the screen on
                      which the colormap is being
                      installed
propagate:            _F_a_l_s_e
event-mask:           _C_o_l_o_r_m_a_p_C_h_a_n_g_e
event: a _C_l_i_e_n_t_M_e_s_
_s_a_g_e with:
  window:             the root window, as above
  type:               WM_COLORMAP_NOTIFY
  format:             32
  data[0]:            the timestamp of the event that
                      caused the client to start or stop
                      installing colormaps




                             5555





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


  data[1]:            1 if the client is starting col
                      ormap installation, 0 if the client
                      is finished with colormap installa
                      tion
  data[2]:            reserved, must be zero
  data[3]:            reserved, must be zero
  data[4]:            reserved, must be zero
----------------------------------------------------------


This feature was introduced in version 2.0 of this document,
and there will be a significant period of time before all
window managers can be expected to implement this feature.
Before using this feature, clients must check the compliance
level of the window manager (using the mechanism described
in section 4.3) to verify that it supports this feature.
This is necessary to prevent colormap installation conflicts
between clients and older window managers.

Window managers should refrain from installing colormaps
while a client has requested control of colormap installa
tion.  The window manager should continue to track the set
of installed colormaps so that it can reinstate its colormap
focus policy when the client has finished colormap installa
tion.

This technique has race conditions that may result in the
colormaps continuing to be installed even after a client has
issued its notification message.  For example, the window
manager may have issued some _I_n_s_t_a_l_l_C_o_l_o_r_m_a_p requests that
are not executed until after the client's _S_e_n_d_E_v_e_n_t and
_I_n_s_t_a_l_l_C_o_l_o_r_m_a_p requests, thus uninstalling the client's
colormaps.  If this occurs while the client still has the
pointer grabbed and before the client has issued the "fin
ished" message, the client may reinstall the desired col
ormaps.

                   Advice to Implementors

     Clients are expected to use this mechanism for
     things such as popup windows and for animations
     that use override-redirect windows.

     If a client fails to issue the "finished" message,
     the window manager may be left in a state where
     its colormap installation policy is suspended.
     Window manager implementors may want to implement
     a feature that resets colormap installation policy
     in response to a command from the user.








                             5566





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..11..99..  IIccoonnss

A client can hint to the window manager about the desired
appearance of its icon by setting:

   A string in WM_ICON_NAME

    All clients should do this because it provides a fall
    back for window managers whose ideas about icons differ
    widely from those of the client.

   A _P_i_x_m_a_p into the icon_pixmap field of the WM_HINTS
    property and possibly another into the icon_mask field

    The window manager is expected to display the pixmap
    masked by the mask.  The pixmap should be one of the
    sizes found in the WM_ICON_SIZE property on the root.
    If this property is not found, the window manager is
    unlikely to display icon pixmaps.  Window managers usu
    ally will clip or tile pixmaps that do not match
    WM_ICON_SIZE.

   A window into the icon_window field of the WM_HINTS
    property

    The window manager is expected to map that window when
    ever the client is in the Iconic state.  In general, the
    size of the icon window should be one of those specified
    in WM_ICON_SIZE on the root, if it exists.  Window man
    agers are free to resize icon windows.

In the Iconic state, the window manager usually will ensure
that:

   If the window's WM_HINTS.icon_window is set, the window
    it names is visible.

   If the window's WM_HINTS.icon_window is not set but the
    window's WM_HINTS.icon_pixmap is set, the pixmap it
    names is visible.

   Otherwise, the window's WM_ICON_NAME string is visible.

Clients should observe the following conventions about their
icon windows:

                        Conventions


1.   The icon window should be an _I_n_p_u_t_O_u_t_p_u_t child of the
     root.

2.   The icon window should be one of the sizes specified in
     the WM_ICON_SIZE property on the root.



                             5577





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


3.   The icon window should use the root visual and default
     colormap for the screen in question.

4.   Clients should not map their icon windows.

5.   Clients should not unmap their icon windows.

6.   Clients should not configure their icon windows.

7.   Clients should not set override-redirect on their icon
     windows or select for _R_e_s_i_z_e_R_e_d_i_r_e_c_t events on them.

8.   Clients must not depend on being able to receive input
     events by means of their icon windows.

9.   Clients must not manipulate the borders of their icon
     windows.

10.  Clients must select for _E_x_p_o_s_u_r_e events on their icon
     window and repaint it when requested.


Window managers will differ as to whether they support input
events to client's icon windows; most will allow the client
to receive some subset of the keys and buttons.

Window managers will ignore any WM_NAME, WM_ICON_NAME,
WM_NORMAL_HINTS, WM_HINTS, WM_CLASS, WM_TRANSIENT_FOR,
WM_PROTOCOLS, WM_COLORMAP_WINDOWS, WM_COMMAND, or
WM_CLIENT_MACHINE properties they find on icon windows.

44..11..1100..  PPoopp--uupp WWiinnddoowwss

Clients that wish to pop up a window can do one of three
things:

1.   They can create and map another normal top-level win
     dow, which will get decorated and managed as normal by
     the window manager.  See the discussion of window
     groups that follows.

2.   If the window will be visible for a relatively short
     time and deserves a somewhat lighter treatment, they
     can set the WM_TRANSIENT_FOR property.  They can expect
     less decoration but can set all the normal window man
     ager properties on the window.  An example would be a
     dialog box.

3.   If the window will be visible for a very short time and
     should not be decorated at all, the client can set
     override-redirect on the window.  In general, this
     should be done only if the pointer is grabbed while the
     window is mapped.  The window manager will never inter
     fere with these windows, which should be used with



                             5588





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


     caution.  An example of an appropriate use is a pop-up
     menu.

                     Advice to Implementors

          The user will not be able to move, resize,
          restack, or transfer the input focus to over
          ride-redirect windows, since the window man
          ager is not managing them.  If it is neces
          sary for a client to receive keystrokes on an
          override-redirect window, either the client
          must grab the keyboard, or the client must
          have another top-level window that is not
          override-redirect and that has selected the
          Locally Active or Globally Active focus
          model.  The client may set the focus to the
          override-redirect window when the other win
          dow receives a WM_TAKE_FOCUS message or one
          of the events listed in section 4.1.7 in the
          description of the Globally Active focus
          model.


Window managers are free to decide if WM_TRANSIENT_FOR win
dows should be iconified when the window they are transient
for is.  Clients displaying WM_TRANSIENT_FOR windows that
have (or request to have) the window they are transient for
iconified do not need to request that the same operation be
performed on the WM_TRANSIENT_FOR window; the window manager
will change its state if that is the policy it wishes to
enforce.

44..11..1111..  WWiinnddooww GGrroouuppss

A set of top-level windows that should be treated from the
user's point of view as related (even though they may belong
to a number of clients) should be linked together using the
window_group field of the WM_HINTS structure.

One of the windows (that is, the one the others point to)
will be the group leader and will carry the group as opposed
to the individual properties.  Window managers may treat the
group leader differently from other windows in the group.
For example, group leaders may have the full set of decora
tions, and other group members may have a restricted set.

It is not necessary that the client ever map the group
leader; it may be a window that exists solely as a place
holder.

It is up to the window manager to determine the policy for
treating the windows in a group.  At present, there is no
way for a client to request a group, as opposed to an indi
vidual, operation.



                             5599





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..22..  CClliieenntt RReessppoonnsseess ttoo WWiinnddooww MMaannaaggeerr AAccttiioonnss

The window manager performs a number of operations on client
resources, primarily on their top-level windows.  Clients
must not try to fight this but may elect to receive notifi
cation of the window manager's operations.

44..22..11..  RReeppaarreennttiinngg

Clients must be aware that some window managers will repar
ent their top-level windows so that a window that was cre
ated as a child of the root will be displayed as a child of
some window belonging to the window manager.  The effects
that this reparenting will have on the client are as fol
lows:

   The parent value returned by a _Q_u_e_r_y_T_r_e_e request will no
    longer be the value supplied to the _C_r_e_a_t_e_W_i_n_d_o_w request
    that created the reparented window.  There should be no
    need for the client to be aware of the identity of the
    window to which the top-level window has been repar
    ented.  In particular, a client that wishes to create
    further top-level windows should continue to use the
    root as the parent for these new windows.

   The server will interpret the (x,y) coordinates in a
    _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w request in the new parent's coordinate
    space.  In fact, they usually will not be interpreted by
    the server because a reparenting window manager usually
    will have intercepted these operations (see section
    4.2.2).  Clients should use the root coordinate space
    for these requests (see section 4.1.5).

   _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w requests that name a specific sibling
    window may fail because the window named, which used to
    be a sibling, no longer is after the reparenting opera
    tion (see section 4.1.5).

   The (x,y) coordinates returned by a _G_e_t_G_e_o_m_e_t_r_y request
    are in the parent's coordinate space and are thus not
    directly useful after a reparent operation.

   A background of _P_a_r_e_n_t_R_e_l_a_t_i_v_e will have unpredictable
    results.

   A cursor of _N_o_n_e will have unpredictable results.

Clients that want to be notified when they are reparented
can select for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y events on their top-level
window.  They will receive a _R_e_p_a_r_e_n_t_N_o_t_i_f_y event if and
when reparenting takes place.  When a client withdraws a
top-level window, the window manager will reparent it back
to the root window if the window had been reparented else
where.



                             6600





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


If the window manager reparents a client's window, the
reparented window will be placed in the save-set of the par
ent window.  This means that the reparented window will not
be destroyed if the window manager terminates and will be
remapped if it was unmapped.  Note that this applies to all
client windows the window manager reparents, including tran
sient windows and client icon windows.

44..22..22..  RReeddiirreeccttiioonn ooff OOppeerraattiioonnss

Clients must be aware that some window managers will arrange
for some client requests to be intercepted and redirected.
Redirected requests are not executed; they result instead in
events being sent to the window manager, which may decide to
do nothing, to alter the arguments, or to perform the
request on behalf of the client.

The possibility that a request may be redirected means that
a client cannot assume that any redirectable request is
actually performed when the request is issued or is actually
performed at all.  The requests that may be redirected are
_M_a_p_W_i_n_d_o_w, _C_o_n_f_i_g_u_r_e_W_i_n_d_o_w, and _C_i_r_c_u_l_a_t_e_W_i_n_d_o_w.

                   Advice to Implementors

     The following is incorrect because the _M_a_p_W_i_n_d_o_w
     request may be intercepted and the _P_o_l_y_L_i_n_e output
     made to an unmapped window:


     MapWindow A
     PolyLine A GC <point> <point> ...


The client must wait for an _E_x_p_o_s_e event before drawing in
the window.14

This next example incorrectly assumes that the _C_o_n_f_i_g_u_r_e_W_i_n_
_d_o_w request is actually executed with the arguments sup
plied:


     ConfigureWindow width=N height=M
     <output assuming window is N by M>


The client should select for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y on its window
and monitor the window's size by tracking _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y
-----------
  14 This is true even if the client set the back
ing-store attribute to _A_l_w_a_y_s.  The backing-store
attribute is a only a hint, and the server may
stop maintaining backing store contents at any
time.



                             6611





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


events.

Clients must be especially careful when attempting to set
the focus to a window that they have just mapped.  This
sequence may result in an X protocol error:


     MapWindow B
     SetInputFocus B


If the _M_a_p_W_i_n_d_o_w request has been intercepted, the window
will still be unmapped, causing the _S_e_t_I_n_p_u_t_F_o_c_u_s request to
generate the error.  The solution to this problem is for
clients to select for _V_i_s_i_b_i_l_i_t_y_C_h_a_n_g_e on the window and to
delay the issuance of the _S_e_t_I_n_p_u_t_F_o_c_u_s request until they
have received a _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y event indicating that the
window is visible.

This technique does not guarantee correct operation.  The
user may have iconified the window by the time the _S_e_t_I_n_p_u_t_
_F_o_c_u_s request reaches the server, still causing an error.
Or, the window manager may decide to map the window into
Iconic state, in which case the window will not be visible.
This will delay the generation of the _V_i_s_i_b_i_l_i_t_y_N_o_t_i_f_y event
indefinitely.  Clients must be prepared to handle these
cases.


A window with the override-redirect bit set is immune from
redirection, but the bit should be set on top-level windows
only in cases where other windows should be prevented from
processing input while the override-redirect window is
mapped (see section 4.1.10) and while responding to _R_e_s_i_z_
_e_R_e_q_u_e_s_t events (see section 4.2.9).

Clients that have no non-Withdrawn top-level windows and
that map an override-redirect top-level window are taking
over total responsibility for the state of the system.  It
is their responsibility to:

   Prevent any preexisting window manager from interfering
    with their activities

   Restore the status quo exactly after they unmap the win
    dow so that any preexisting window manager does not get
    confused

In effect,  clients of this kind are acting as temporary
window managers.  Doing so is strongly discouraged because
these clients will be unaware of the user interface policies
the window manager is trying to maintain and because their
user interface behavior is likely to conflict with that of
less demanding clients.



                             6622





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..22..33..  WWiinnddooww MMoovvee

If the window manager moves a top-level window without
changing its size, the client will receive a synthetic _C_o_n_
_f_i_g_u_r_e_N_o_t_i_f_y event following the move that describes the new
location in terms of the root coordinate space.  Clients
must not respond to being moved by attempting to move them
selves to a better location.

Any real _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event on a top-level window implies
that the window's position on the root may have changed,
even though the event reports that the window's position in
its parent is unchanged because the window may have been
reparented.  Note that the coordinates in the event will
not, in this case, be directly useful.

The window manager will send these events by using a _S_e_n_d_E_
_v_e_n_t request with the following arguments:

-----------------------------------
AArrgguummeenntt       VVaalluuee
-----------------------------------
destination:   The client's window
propagate:     _F_a_l_s_e
event-mask:    _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y
-----------------------------------


44..22..44..  WWiinnddooww RReessiizzee

The client can elect to receive notification of being
resized by selecting for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y events on its top-
level windows.  It will receive a _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y event.
The size information in the event will be correct, but the
location will be in the parent window (which may not be the
root).

The response of the client to being resized should be to
accept the size it has been given and to do its best with
it.  Clients must not respond to being resized by attempting
to resize themselves to a better size.  If the size is
impossible to work with, clients are free to request to
change to the Iconic state.

44..22..55..  IIccoonniiffyy aanndd DDeeiiccoonniiffyy

A top-level window that is not Withdrawn will be in the Nor
mal state if it is mapped and in the Iconic state if it is
unmapped.  This will be true even if the window has been
reparented; the window manager will unmap the window as well
as its parent when switching to the Iconic state.

The client can elect to be notified of these state changes
by selecting for _S_t_r_u_c_t_u_r_e_N_o_t_i_f_y events on the top-level



                             6633





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


window.  It will receive a _U_n_m_a_p_N_o_t_i_f_y event when it goes
Iconic and a _M_a_p_N_o_t_i_f_y event when it goes Normal.

44..22..66..  CCoolloorrmmaapp CChhaannggee

Clients that wish to be notified of their colormaps being
installed or uninstalled should select for _C_o_l_o_r_m_a_p_N_o_t_i_f_y
events on their top-level windows and on any windows they
have named in WM_COLORMAP_WINDOWS properties on their top-
level windows.  They will receive _C_o_l_o_r_m_a_p_N_o_t_i_f_y events with
the new field FALSE when the colormap for that window is
installed or uninstalled.

44..22..77..  IInnppuutt FFooccuuss

Clients can request notification that they have the input
focus by selecting for _F_o_c_u_s_C_h_a_n_g_e events on their top-level
windows; they will receive _F_o_c_u_s_I_n and _F_o_c_u_s_O_u_t events.
Clients that need to set the input focus to one of their
subwindows should not do so unless they have set
WM_TAKE_FOCUS in their WM_PROTOCOLS property and have done
one of the following:

   Set the input field of WM_HINTS to _T_r_u_e and actually
    have the input focus in one of their top-level windows

   Set the input field of WM_HINTS to _F_a_l_s_e and have
    received a suitable event as described in section 4.1.7

   Have received a WM_TAKE_FOCUS message as described in
    section 4.1.7

Clients should not warp the pointer in an attempt to trans
fer the focus; they should set the focus and leave the
pointer alone.  For further information, see section 6.2.

Once a client satisfies these conditions, it may transfer
the focus to another of its windows by using the _S_e_t_I_n_p_u_t_F_o_
_c_u_s request, which is defined as follows:

__
||    _S_e_t_I_n_p_u_t_F_o_c_u_s

_f_o_c_u_s: WINDOW or _P_o_i_n_t_e_r_R_o_o_t or _N_o_n_e
_r_e_v_e_r_t_-_t_o: {_P_a_r_e_n_t, _P_o_i_n_t_e_r_R_o_o_t, _N_o_n_e}
||__  _t_i_m_e: TIMESTAMP or _C_u_r_r_e_n_t_T_i_m_e


                        Conventions


1.   Clients that use a _S_e_t_I_n_p_u_t_F_o_c_u_s request must set the
     time argument to the timestamp of the event that caused
     them to make the attempt.  This cannot be a _F_o_c_u_s_I_n



                             664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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


     event because they do not have timestamps.  Clients may
     also acquire the focus without a corresponding _E_n_t_e_r_
     _N_o_t_i_f_y event.  Clients must not use _C_u_r_r_e_n_t_T_i_m_e for the
     time argument.

2.   Clients that use a _S_e_t_I_n_p_u_t_F_o_c_u_s request to set the
     focus to one of their windows must set the revert-to
     field to _P_a_r_e_n_t.


44..22..88..  CClliieennttMMeessssaaggee EEvveennttss

There is no way for clients to prevent themselves being sent
_C_l_i_e_n_t_M_e_s_s_a_g_e events.

Top-level windows with a WM_PROTOCOLS property may be sent
_C_l_i_e_n_t_M_e_s_s_a_g_e events specific to the protocols named by the
atoms in the property (see section 4.1.2.7).  For all proto
cols, the _C_l_i_e_n_t_M_e_s_s_a_g_e events have the following:

   WM_PROTOCOLS as the type field

   Format 32

   The atom that names their protocol in the data[0] field

   A timestamp in their data[1] field

The remaining fields of the event, including the window
field, are determined by the protocol.

These events will be sent by using a _S_e_n_d_E_v_e_n_t request with
the following arguments:

--------------------------------------------
AArrgguummeenntt       VVaalluuee
--------------------------------------------
destination:   The client's window
propagate:     _F_a_l_s_e
event-mask:    () empty
event:         As specified by the protocol
--------------------------------------------


44..22..88..11..  WWiinnddooww DDeelleettiioonn

Clients, usually those with multiple top-level windows,
whose server connection must survive the deletion of some of
their top-level windows, should include the atom
WM_DELETE_WINDOW in the WM_PROTOCOLS property on each such
window.  They will receive a _C_l_i_e_n_t_M_e_s_s_a_g_e event as
described above whose data[0] field is WM_DELETE_WINDOW.





                             6655





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


Clients receiving a WM_DELETE_WINDOW message should behave
as if the user selected "delete window" from a hypothetical
menu.  They should perform any confirmation dialog with the
user and, if they decide to complete the deletion, should do
the following:

   Either change the window's state to Withdrawn (as
    described in section 4.1.4) or destroy the window

   Destroy any internal state associated with the window

If the user aborts the deletion during the confirmation dia
log, the client should ignore the message.

Clients are permitted to interact with the user and ask, for
example, whether a file associated with the window to be
deleted should be saved or the window deletion should be
cancelled.  Clients are not required to destroy the window
itself; the resource may be reused, but all associated state
(for example, backing store) should be released.

If the client aborts a destroy and the user then selects
DELETE WINDOW again, the window manager should start the
WM_DELETE_WINDOW protocol again.  Window managers should not
use _D_e_s_t_r_o_y_W_i_n_d_o_w requests on a window that has
WM_DELETE_WINDOW in its WM_PROTOCOLS property.

Clients that choose not to include WM_DELETE_WINDOW in the
WM_PROTOCOLS property may be disconnected from the server if
the user asks for one of the client's top-level windows to
be deleted.

44..22..99..  RReeddiirreeccttiinngg RReeqquueessttss

Normal clients can use the redirection mechanism just as
window managers do by selecting for _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t
events on a parent window or _R_e_s_i_z_e_R_e_d_i_r_e_c_t events on a win
dow itself.  However, at most, one client per window can
select for these events, and a convention is needed to avoid
clashes.

                         Convention

     Clients (including window managers) should select
     for _S_u_b_s_t_r_u_c_t_u_r_e_R_e_d_i_r_e_c_t and _R_e_s_i_z_e_R_e_d_i_r_e_c_t events
     only on windows that they own.


In particular, clients that need to take some special action
if they are resized can select for _R_e_s_i_z_e_R_e_d_i_r_e_c_t events on
their top-level windows.  They will receive a _R_e_s_i_z_e_R_e_q_u_e_s_t
event if the window manager resizes their window, and the
resize will not actually take place.  Clients are free to
make what use they like of the information that the window



                             6666





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


manager wants to change their size, but they must configure
the window to the width and height specified in the event in
a timely fashion.  To ensure that the resize will actually
happen at this stage instead of being intercepted and exe
cuted by the window manager (and thus restarting the pro
cess), the client needs temporarily to set override-redirect
on the window.

                         Convention

     Clients receiving _R_e_s_i_z_e_R_e_q_u_e_s_t events must
     respond by doing the following:

   Setting override-redirect on the window specified in the
    event

   Configuring the window specified in the event to the
    width and height specified in the event as soon as pos
    sible and before making any other geometry requests

   Clearing override-redirect on the window specified in
    the event


If a window manager detects that a client is not obeying
this convention, it is free to take whatever measures it
deems appropriate to deal with the client.

44..33..  CCoommmmuunniiccaattiioonn wwiitthh tthhee WWiinnddooww MMaannaaggeerr bbyy MMeeaannss ooff
SSeelleeccttiioonnss

For each screen they manage, window managers will acquire
ownership of a selection named WM_S_n, where _n is the screen
number, as described in section 1.2.6.  Window managers
should comply with the conventions for "Manager Selections"
described in section 2.8.  The intent is for clients to be
able to request a variety of information or services by
issuing conversion requests on this selection.  Window man
agers should support conversion of the following target on
their manager selection:


--------------------------------------------------------
AAttoomm      TTyyppee      DDaattaa RReecceeiivveedd
--------------------------------------------------------
VERSION   INTEGER   Two integers, which are the major
                    and minor release numbers (respec
                    tively) of the ICCCM with which the
                    window manager complies.  For this
                    version of the ICCCM, the numbers
                    are 2 and 0.15
--------------------------------------------------------





                             6677





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


44..44..  SSuummmmaarryy ooff WWiinnddooww MMaannaaggeerr PPrrooppeerrttyy TTyyppeess

The window manager properties are summarized in the follow
ing table (see also section 14.1 of _X_l_i_b _- _C _L_a_n_g_u_a_g_e _X
_I_n_t_e_r_f_a_c_e).

-----------------------------------------------------------
NNaammee                  TTyyppee            FFoorrmmaatt   SSeeee SSeeccttiioonn
-----------------------------------------------------------
WM_CLASS              STRING             8       4.1.2.5
WM_CLIENT_MACHINE     TEXT                       4.1.2.9
WM_COLORMAP_WINDOWS   WINDOW            32       4.1.2.8
WM_HINTS              WM_HINTS          32       4.1.2.4
WM_ICON_NAME          TEXT                       4.1.2.2
WM_ICON_SIZE          WM_ICON_SIZE      32       4.1.3.2
WM_NAME               TEXT                       4.1.2.1
WM_NORMAL_HINTS       WM_SIZE_HINTS     32       4.1.2.3
WM_PROTOCOLS          ATOM              32       4.1.2.7
WM_STATE              WM_STATE          32       4.1.3.1
WM_TRANSIENT_FOR      WINDOW            32       4.1.2.6
-----------------------------------------------------------


55..  SSeessssiioonn MMaannaaggeemmeenntt

This section contains some conventions for clients that par
ticipate in session management.  See _X _S_e_s_s_i_o_n _M_a_n_a_g_e_m_e_n_t
_P_r_o_t_o_c_o_l for further details.  Clients that do not support
this protocol cannot expect their window state (e.g.
WM_STATE, position, size and stacking order) to be preserved
across sessions.

55..11..  CClliieenntt SSuuppppoorrtt ffoorr SSeessssiioonn MMaannaaggeemmeenntt

Each session participant will obtain a unique client identi
fier (client-ID) from the session manager.  The client must
identify one top level window as the "client leader." This
window must be created by the client.  It may be in any
state, including the Withdrawn state.  The client leader
window must have a SM_CLIENT_ID property, which contains the
client-ID obtained from the session management protocol.
That property must:

   be of type STRING;

   be of format 8; and

-----------
  15 As a special case, clients not wishing to
implement a selection request may simply issue a
_G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request on the appropriate WM_S_n
selection.  If this selection is owned, clients
may assume that the window manager complies with
ICCCM version 2.0 or later.



                             6688





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   contain the client-ID as a string of XPCS characters
    encoded using ISO 8859-1.

All top-level, non-transient windows created by a client on
the same display as the client leader must have a
WM_CLIENT_LEADER property. This property contains a window
ID that identifies the client leader window.  The client
leader window must have a WM_CLIENT_LEADER property contain
ing its own window ID (i.e. the client leader window is
pointing to itself).  Transient windows need not have a
WM_CLIENT_LEADER property if the client leader can be deter
mined using the information in the WM_TRANSIENT_FOR prop
erty.  The WM_CLIENT_LEADER property must:

   be of type WINDOW;

   be of format 32; and

   contain the window ID of the client leader window.

A client must withdraw all of its top level windows on the
same display before modifiying either the WM_CLIENT_LEADER
or the SM_CLIENT_ID property of its client leader window.

It is necessary that other clients be able to uniquely iden
tify a window (across sessions) among all windows related to
the same client-ID.  For example, a window manager can
require this unique ID to restore geometry information from
a previous session, or a workspace manager could use it to
restore information about which windows are in which
workspace.  A client may optionally provide a WM_WINDOW_ROLE
property to uniquely identify a window within the scope
specified above.  The combination of SM_CLIENT_ID and
WM_WINDOW_ROLE can be used by other clients to uniquely
identify a window across sessions.

If the WM_WINDOW_ROLE property is not specified on a top
level window, a client that needs to uniquely identify that
window will try to use instead the values of WM_CLASS and
WM_NAME.  If a client has multiple windows with identical
WM_CLASS and WM_NAME properties, then it should provide a
WM_WINDOW_ROLE property.

The client must set the WM_WINDOW_ROLE property to a string
that uniquely identifies that window among all windows that
have the same client leader window.  The property must:

   be of type STRING;

   be of format 8; and

   contain a string restricted to the XPCS characters,
    encoded in ISO 8859-1.




                             6699





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


55..22..  WWiinnddooww MMaannaaggeerr SSuuppppoorrtt ffoorr SSeessssiioonn MMaannaaggeemmeenntt

A window manager supporting session management must register
with the session manager and obtain its own client-ID.  The
window manager should save and restore information such as
the WM_STATE, the layout of windows on the screen, and their
stacking order, for every client window that has a valid
SM_CLIENT_ID property (on itself, or on the window named by
WM_CLIENT_LEADER) and that can be uniquely identified.
Clients are allowed to change this state during the first
phase of the session checkpoint process.  Therefore, window
managers should request a second checkpoint phase and save
clients' state only during that phase.

66..  MMaanniippuullaattiioonn ooff SShhaarreedd RReessoouurrcceess

X Version 11 permits clients to manipulate a number of
shared resources, for example, the input focus, the pointer,
and colormaps.  Conventions are required so that clients
share resources in an orderly fashion.

66..11..  TThhee IInnppuutt FFooccuuss

Clients that explicitly set the input focus must observe one
of two modes:

   Locally active mode

   Globally active mode

                          Conventions


1.   Locally active clients should set the input focus to
     one of their windows only when it is already in one of
     their windows or when they receive a WM_TAKE_FOCUS mes
     sage.  They should set the input field of the WM_HINTS
     structure to _T_r_u_e.

2.   Globally active clients should set the input focus to
     one of their windows only when they receive a button
     event and a passive-grabbed key event, or when they
     receive a WM_TAKE_FOCUS message.  They should set the
     input field of the WM_HINTS structure to _F_a_l_s_e.

3.   In addition, clients should use the timestamp of the
     event that caused them to attempt to set the input
     focus as the time field on the _S_e_t_I_n_p_u_t_F_o_c_u_s request,
     not _C_u_r_r_e_n_t_T_i_m_e.








                             7700





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


66..22..  TThhee PPooiinntteerr

In general, clients should not warp the pointer.  Window
managers, however, may do so (for example, to maintain the
invariant that the pointer is always in the window with the
input focus).  Other window managers may want to preserve
the illusion that the user is in sole control of the
pointer.

                        Conventions


1.   Clients should not warp the pointer.

2.   Clients that insist on warping the pointer should do so
     only with the src-window argument of the _W_a_r_p_P_o_i_n_t_e_r
     request set to one of their windows.


66..33..  GGrraabbss

A client's attempt to establish a button or a key grab on a
window will fail if some other client has already estab
lished a conflicting grab on the same window.  The grabs,
therefore, are shared resources, and their use requires con
ventions.

In conformance with the principle that clients should
behave, as far as possible, when a window manager is running
as they would when it is not, a client that has the input
focus may assume that it can receive all the available keys
and buttons.

                         Convention

     Window managers should ensure that they provide
     some mechanism for their clients to receive events
     from all keys and all buttons, except for events
     involving keys whose KeySyms are registered as
     being for window management functions (for exam
     ple, a hypothetical WINDOW KeySym).


In other words, window managers must provide some mechanism
by which a client can receive events from every key and but
ton (regardless of modifiers) unless and until the X Consor
tium registers some KeySyms as being reserved for window
management functions.  Currently, no KeySyms are registered
for window management functions.

Even so, clients are advised to allow the key and button
combinations used to elicit program actions to be modified,
because some window managers may choose not to observe this
convention or may not provide a convenient method for the



                             7711





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


user to transmit events from some keys.

                         Convention

     Clients should establish button and key grabs only
     on windows that they own.


In particular, this convention means that a window manager
that wishes to establish a grab over the client's top-level
window should either establish the grab on the root, or
reparent the window and establish the grab on a proper
ancestor.  In some cases, a window manager may want to con
sume the event received, placing the window in a state where
a subsequent such event will go to the client.  Examples
are:

   Clicking in a window to set focus with the click not
    being offered to the client

   Clicking in a buried window to raise it, again, with the
    click not offered to the client

More typically, a window manager should add to rather than
replace the client's semantics for key+button combinations
by allowing the event to be used by the client after the
window manager is done with it.  To ensure this, the window
manager should establish the grab on the parent by using the
following:


     pointer/keyboard-mode == Synchronous


Then, the window manager should release the grab by using an
_A_l_l_o_w_E_v_e_n_t_s request with the following specified:


     mode == ReplayPointer/Keyboard


In this way, the client will receive the events as if they
had not been intercepted.

Obviously, these conventions place some constraints on pos
sible user interface policies.  There is a trade-off here
between freedom for window managers to implement their user
interface policies and freedom for clients to implement
theirs.  The dilemma is resolved by:

   Allowing window managers to decide if and when a client
    will receive an event from any given key or button





                             7722





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   Placing a requirement on the window manager to provide
    some mechanism, perhaps a "Quote" key, by which the user
    can send an event from any key or button to the client

66..44..  CCoolloorrmmaappss

Section 4.1.8 prescribes conventions for clients to communi
cate with the window manager about their colormap needs.  If
your clients are _D_i_r_e_c_t_C_o_l_o_r type applications, you should
consult section 14.3 of _X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e for
conventions connected with sharing standard colormaps.  They
should look for and create the properties described there on
the root window of the appropriate screen.

The contents of the RGB_COLOR_MAP type property are as fol
lows:

---------------------------------------------------------
FFiieelldd        TTyyppee       CCoommmmeennttss
---------------------------------------------------------
colormap     COLORMAP   ID of the colormap described
red_max      CARD32     Values for pixel calculations
red_mult     CARD32
green_max    CARD32
green_mult   CARD32
blue_max     CARD32
blue_mult    CARD32
base_pixel   CARD32
visual_id    VISUALID   Visual to which colormap belongs
kill_id      CARD32     ID for destroying the resources
---------------------------------------------------------


When deleting or replacing an RGB_COLOR_MAP, it is not suf
ficient to delete the property; it is important to free the
associated colormap resources as well.  If kill_id is
greater than one, the resources should be freed by issuing a
_K_i_l_l_C_l_i_e_n_t request with kill_id as the argument.  If kill_id
is one, the resources should be freed by issuing a _F_r_e_e_C_o_l_
_o_r_m_a_p request with colormap as the colormap argument.  If
kill_id is zero, no attempt should be made to free the
resources.  A client that creates an RGB_COLOR_MAP for which
the colormap resource is created specifically for this pur
pose should set kill_id to one (and can create more than one
such standard colormap using a single connection).  A client
that creates an RGB_COLOR_MAP for which the colormap
resource is shared in some way (for example, is the default
colormap for the root window) should create an arbitrary
resource and use its resource ID for kill_id (and should
create no other standard colormaps on the connection).







                             7733





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


                         Convention

     If an RGB_COLOR_MAP property is too short to con
     tain the visual_id field, it can be assumed that
     the visual_id is the root visual of the appropri
     ate screen.  If an RGB_COLOR_MAP property is too
     short to contain the kill_id field, a value of
     zero can be assumed.


During the connection handshake, the server informs the
client of the default colormap for each screen.  This is a
colormap for the root visual, and clients can use it to
improve the extent of colormap sharing if they use the root
visual.

66..55..  TThhee KKeeyybbooaarrdd MMaappppiinngg

The X server contains a table (which is read by _G_e_t_K_e_y_
_b_o_a_r_d_M_a_p_p_i_n_g requests) that describes the set of symbols
appearing on the corresponding key for each keycode gener
ated by the server.  This table does not affect the server's
operations in any way; it is simply a database used by
clients that attempt to understand the keycodes they
receive.  Nevertheless, it is a shared resource and requires
conventions.

It is possible for clients to modify this table by using a
_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g request.  In general, clients should
not do this.  In particular, this is not the way in which
clients should implement key bindings or key remapping.  The
conversion between a sequence of keycodes received from the
server and a string in a particular encoding is a private
matter for each client (as it must be in a world where
applications may be using different encodings to support
different languages and fonts).  See the Xlib reference man
ual for converting keyboard events to text.

The only valid reason for using a _C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g
request is when the symbols written on the keys have changed
as, for example, when a Dvorak key conversion kit or a set
of APL keycaps has been installed.  Of course, a client may
have to take the change to the keycap on trust.

The following illustrates a permissible interaction between
a client and a user:

Client:   "You just started me on a server without a Pause
          key.  Please choose a key to be the Pause key and
          press it now."

User:     Presses the Scroll Lock key





                             774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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


Client:   "Adding Pause to the symbols on the Scroll Lock
          key: Confirm or Abort."

User:     Confirms

Client:   Uses a _C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g request to add Pause
          to the keycode that already contains Scroll Lock
          and issues this request, "Please paint Pause on
          the Scroll Lock key."

                              Convention

               Clients should not use _C_h_a_n_g_e_K_e_y_
               _b_o_a_r_d_M_a_p_p_i_n_g requests.


If a client succeeds in changing the keyboard mapping table,
all clients will receive _M_a_p_p_i_n_g_N_o_t_i_f_y(request==Keyboard)
events.  There is no mechanism to avoid receiving these
events.

                         Convention

     Clients receiving _M_a_p_p_i_n_g_N_o_t_i_f_y(request==Keyboard)
     events should update any internal keycode transla
     tion tables they are using.


66..66..  TThhee MMooddiiffiieerr MMaappppiinngg

X Version 11 supports eight modifier bits of which three are
preassigned to Shift, Lock, and Control.  Each modifier bit
is controlled by the state of a set of keys, and these sets
are specified in a table accessed by _G_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g and
_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g requests.  This table is a shared
resource and requires conventions.

A client that needs to use one of the preassigned modifiers
should assume that the modifier table has been set up cor
rectly to control these modifiers.  The Lock modifier should
be interpreted as Caps Lock or Shift Lock according as the
keycodes in its controlling set include XK_Caps_Lock or
XK_Shift_Lock.

                         Convention

     Clients should determine the meaning of a modifier
     bit from the KeySyms being used to control it.


A client that needs to use an extra modifier (for example,
META) should do the following:





                             7755





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   Scan the existing modifier mappings.  If it finds a mod
    ifier that contains a keycode whose set of KeySyms
    includes XK_Meta_L or XK_Meta_R, it should use that mod
    ifier bit.

   If there is no existing modifier controlled by
    XK_Meta_L or XK_Meta_R, it should select an unused modi
    fier bit (one with an empty controlling set) and do the
    following:

    -    If there is a keycode with XL_Meta_L in its set of
         KeySyms, add that keycode to the set for the chosen
         modifier.

    -    If there is a keycode with XL_Meta_R in its set of
         KeySyms, add that keycode to the set for the chosen
         modifier.

    -    If the controlling set is still empty, interact
         with the user to select one or more keys to be
         META.

   If there are no unused modifier bits, ask the user to
    take corrective action.

                          Conventions


1.   Clients needing a modifier not currently in use should
     assign keycodes carrying suitable KeySyms to an unused
     modifier bit.

2.   Clients assigning their own modifier bits should ask
     the user politely to remove his or her hands from the
     key in question if their _S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g request
     returns a _B_u_s_y status.


There is no good solution to the problem of reclaiming
assignments to the five nonpreassigned modifiers when they
are no longer being used.

                         Convention

     The user must use _x_m_o_d_m_a_p or some other utility to
     deassign obsolete modifier mappings by hand.


When a client succeeds in performing a _S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g
request, all clients will receive
_M_a_p_p_i_n_g_N_o_t_i_f_y(request==Modifier) events.  There is no mecha
nism for preventing these events from being received.  A
client that uses one of the nonpreassigned modifiers that
receives one of these events should do a _G_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g



                             7766





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


request to discover the new mapping, and if the modifier it
is using has been cleared, it should reinstall the modifier.

Note that a _G_r_a_b_S_e_r_v_e_r request must be used to make the _G_e_t_
_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g and _S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g pair in these trans
actions atomic.

77..  DDeevviiccee CCoolloorr CChhaarraacctteerriizzaattiioonn

The X protocol provides explicit RGB values, which are used
to directly drive a monitor, and color names.  RGB values
provide a mechanism for accessing the full capabilities of
the display device, but at the expense of having the color
perceived by the user remain unknowable through the proto
col.  Color names were originally designed to provide access
to a device-independent color database by having the server
vendor tune the definitions of the colors in that textual
database.  Unfortunately, this still does not provide the
client any way of using an existing device-independent
color, nor for the client to get device-independent color
information back about colors that it has selected.

Furthermore, the client must be able to discover which set
of colors are displayable by the device (the device gamut),
both to allow colors to be intelligently modified to fit
within the device capabilities (gamut compression) and to
enable the user interface to display a representation of the
reachable color space to the user (gamut display).

Therefore, a system is needed that will provide full access
to device-independent color spaces for X clients.  This sys
tem should use a standard mechanism for naming the colors,
be able to provide names for existing colors, and provide
means by which unreachable colors can be modified to fall
within the device gamut.

We are fortunate in this area to have a seminal work, the
1931 CIE color standard, which is nearly universally agreed
upon as adequate for describing colors on CRT devices.  This
standard uses a tri-stimulus model called CIE XYZ in which
each perceivable color is specified as a triplet of numbers.
Other appropriate device-independent color models do exist,
but most of them are directly traceable back to this origi
nal work.

X device color characterization provides device-independent
color spaces to X clients.  It does this by providing the
barest possible amount of information to the client that
allows the client to construct a mapping between CIE XYZ and
the regular X RGB color descriptions.

Device color characterization is defined by the name and
contents of two window properties that, together, permit
converting between CIE XYZ space and linear RGB device space



                             7777





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


(such as standard CRTs).  Linear RGB devices require just
two pieces of information to completely characterize them:

    A 33 matrix _M and its inverse _M-1, which convert
     between XYZ and RGB intensity (_R_G_B_i_n_t_e_n_s_i_t_y):

                       _R_G_B_i_n_t_e_n_s_i_t_y=_M_X_Y_Z


                      _X_Y_Z=_M-1_R_G_B_i_n_t_e_n_s_i_t_y


    A way of mapping between RGB intensity and RGB protocol
     value.  XDCCC supports three mechanisms which will be
     outlined below.

If other device types are eventually necessary, additional
properties will be required to describe them.

77..11..  XXYYZZ <<---->> RRGGBB CCoonnvveerrssiioonn MMaattrriicceess

Because of the limited dynamic range of both XYZ and RGB
intensity, these matrices will be encoded using a fixed-
point representation of a 32-bit two's complement number
scaled by 227, giving a range of -16 to 16-e, where e=2-27.

These matrices will be packed into an 18-element list of
32-bit values, XYZ -> RGB matrix first, in row major order
and stored in the XDCCC_LINEAR_RGB_MATRICES properties (for
mat = 32) on the root window of each screen, using values
appropriate for that screen.

This will be encoded as shown in the following table:

         XDCCC_LINEAR_RGB_MATRICES property contents
---------------------------------------------------------------
FFiieelldd    TTyyppee                      CCoommmmeennttss
---------------------------------------------------------------
_M0,0     INT32   Interpreted as a fixed-point number -16<=_x<16
_M0,1     INT32
...
_M3,3     INT32
_M-10,0   INT32
_M-10,1   INT32
...
_M-13,3   INT32
---------------------------------------------------------------


77..22..  IInntteennssiittyy <<---->> RRGGBB VVaalluuee CCoonnvveerrssiioonn

XDCCC provides two representations for describing the con
version between RGB intensity and the actual X protocol RGB
values:



                             7788





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


     0    RGB value/RGB intensity level pairs
     1    RGB intensity ramp


In both cases, the relevant data will be stored in the
XDCCC_LINEAR_RGB_CORRECTION properties on the root window of
each screen, using values appropriate for that screen, in
whatever format provides adequate resolution.  Each property
can consist of multiple entries concatenated together, if
different visuals for the screen require different conver
sion data.  An entry with a VisualID of 0 specifies data for
all visuals of the screen that are not otherwise explicitly
listed.

The first representation is an array of RGB value/intensity
level pairs, with the RGB values in strictly increasing
order.  When converting, the client must linearly interpo
late between adjacent entries in the table to compute the
desired value.  This allows the server to perform gamma cor
rection itself and encode that fact in a short two-element
correction table.  The intensity will be encoded as an
unsigned number to be interpreted as a value between 0 and 1
(inclusive).  The precision of this value will depend on the
format of the property in which it is stored (8, 16 or 32
bits).  For 16-bit and 32-bit formats, the RGB value will
simply be the value stored in the property.  When stored in
8-bit format, the RGB value can be computed from the value
in the property by:

                _R_G_B_v_a_l_u_e=-_P-_r-_o-_p-_e-_r-_t-_y-_V2-_a5-_l5-_u-_e--6-5-5-3-5-


Because the three electron guns in the device may not be
exactly alike in response characteristics, it is necessary
to allow for three separate tables, one each for red, green,
and blue.  Therefore, each table will be preceded by the
number of entries in that table, and the set of tables will
be preceded by the number of tables.  When three tables are
provided, they will be in red, green, blue order.

This will be encoded as shown in the following table:

 XDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 0 Correction
----------------------------------------------------------------------
  FFiieelldd     TTyyppee                        CCoommmmeennttss
----------------------------------------------------------------------
VisualID0   CARD   Most-significant portion of VisualID
VisualID1   CARD   Exists if and only if the property format is 8
VisualID2   CARD   Exists if and only if the property format is 8
VisualID3   CARD   Least-significant portion, exists if and only if
                   the property format is 8 or 16
type        CARD   0 for this type of correction
count       CARD   Number of tables following (either 1 or 3)




                             7799





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


length      CARD   Number of pairs - 1 following in this table
value       CARD   X Protocol RGB value
intensity   CARD   Interpret as a number 0<=_i_n_t_e_n_s_i_t_y<=1
...         ...    Total of _l_e_n_g_t_h_+_1 pairs of value/intensity values
lengthg     CARD   Number of pairs - 1 following in this table (if
                   and only if _c_o_u_n_t is 3)
value       CARD   X Protocol RGB value
intensity   CARD   Interpret as a number 0<=_i_n_t_e_n_s_i_t_y<=1
...         ...    Total of _l_e_n_g_t_h_g_+_1 pairs of value/intensity values
lengthb     CARD   Number of pairs - 1 following in this table (if
                   and only if _c_o_u_n_t is 3)
value       CARD   X Protocol RGB value
intensity   CARD   Interpret as a number 0<=_i_n_t_e_n_s_i_t_y<=1
...         ...    Total of _l_e_n_g_t_h_b_+_1 pairs of value/intensity values
----------------------------------------------------------------------


The VisualID is stored in 4, 2, or 1 pieces, depending on
whether the property format is 8, 16, or 32, respectively.
The VisualID is always stored most-significant piece first.
Note that the length fields are stored as one less than the
actual length, so 256 entries can be stored in format 8.

The second representation is a simple array of intensities
for a linear subset of RGB values.  The expected size of
this table is the bits-per-rgb-value of the screen, but it
can be any length.  This is similar to the first mechanism,
except that the RGB value numbers are implicitly defined by
the index in the array (indices start at 0):

                  _R_G_B_v_a_l_u_e=-_A-_r-_r-_a_A-_y_r-_I_r-_n_a-_d_y-_e_S-_x_i-_z-6_e-5--51-3-5-

When converting, the client may linearly interpolate between
entries in this table.  The intensity values will be encoded
just as in the first representation.

This will be encoded as shown in the following table:

XDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 1 Correction
--------------------------------------------------------------------
  FFiieelldd      TTyyppee                      CCoommmmeennttss
--------------------------------------------------------------------
VisualID0    CARD   Most-significant portion of VisualID
VisualID1    CARD   Exists if and only if the property format is 8
VisualID2    CARD   Exists if and only if the property format is 8
VisualID3    CARD   Least-significant portion, exists if and only
                    if the property format is 8 or 16
type         CARD   1 for this type of correction
count        CARD   Number of tables following (either 1 or 3)
length       CARD   Number of elements - 1 following in this table
intensity    CARD   Interpret as a number 0<=_i_n_t_e_n_s_i_t_y<=1
...          ...    Total of _l_e_n_g_t_h_+_1 intensity elements





                             8800





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


lengthg      CARD   Number of elements - 1 following in this table
                    (if and only if _c_o_u_n_t is 3)
intensity    CARD   Interpret as a number 0<=_i_n_t_e_n_s_i_t_y<=1
...          ...    Total of _l_e_n_g_t_h_g_+_1 intensity elements
lengthb      CARD   Number of elements - 1 following in this table
                    (if and only if _c_o_u_n_t is 3)
intensity    CARD   Interpret as a number 0<=_i_n_t_e_n_s_i_t_y<=1
...          ...    Total of _l_e_n_g_t_h_b_+_1 intensity elements
--------------------------------------------------------------------


88..  CCoonncclluussiioonn

This document provides the protocol-level specification of
the minimal conventions needed to ensure that X Version 11
clients can interoperate properly.  This document specifies
interoperability conventions only for the X Version 11 pro
tocol.  Clients should be aware of other protocols that
should be used for better interoperation in the X environ
ment.  The reader is referred to _X _S_e_s_s_i_o_n _M_a_n_a_g_e_m_e_n_t _P_r_o_t_o_
_c_o_l for information on session management, and to _I_n_t_e_r_-
_C_l_i_e_n_t _E_x_c_h_a_n_g_e _P_r_o_t_o_c_o_l for information on general-purpose
communication among clients.

88..11..  TThhee XX RReeggiissttrryy

The X Consortium maintains a registry of certain X-related
items, to aid in avoiding conflicts and to aid in sharing of
such items.  Readers are encouraged to use the registry.
The classes of items kept in the registry that are relevant
to the ICCCM include property names, property types, selec
tion names, selection targets, WM_PROTOCOLS protocols,
_C_l_i_e_n_t_M_e_s_s_a_g_e types, and application classes.  Requests to
register items, or questions about registration, should be
addressed to

          xregistry@x.org

or to

          Registry
          X Consortium
          1 Memorial Dr
          Cambridge MA 02142-1301
          USA

Electronic mail will be acknowledged upon receipt.  Please
allow up to four weeks for a formal response to registration
and inquiries.

The registry is published as part of the X software distri
bution from the X Consortium.  All registered items must
have the postal address of someone responsible for the item,
or a reference to a document describing the item and the



                             8811





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


postal address of where to write to obtain the document.
























































                             8822





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66




                         AAppppeennddiixx AA


AA..  RReevviissiioonn HHiissttoorryy

This appendix describes the revision history of this docu
ment and summarizes the incompatibilities between this and
earlier versions.

AA..11..  TThhee XX1111RR22 DDrraafftt

The February 25, 1988 draft that was distributed as part of
X Version 11, Release 2 was clearly labeled as such, and
many areas were explicitly labeled as liable to change.
Nevertheless, in the revision work since then, we have been
very careful not to introduce gratuitous incompatibility.
As far as possible, we have tried to ensure that clients
obeying the conventions in the X11R2 draft would still work.

AA..22..  TThhee JJuullyy 2277,, 11998888 DDrraafftt

The Consortium review was based on a draft dated July 27,
1988.  This draft included several areas in which incompati
bilities with the X11R2 draft were necessary:

   The use of property _N_o_n_e in _C_o_n_v_e_r_t_S_e_l_e_c_t_i_o_n requests is
    no longer allowed.  Owners that receive them are free to
    use the target atom as the property to respond with,
    which will work in most cases.

   The protocol for INCREMENTAL type properties as selec
    tion replies has changed, and the name has been changed
    to INCR.  Selection requestors are free to implement the
    earlier protocol if they receive properties of type
    INCREMENTAL.

   The protocol for INDIRECT type properties as selection
    replies has changed, and the name has been changed to
    MULTIPLE.  Selection requestors are free to implement
    the earlier protocol if they receive properties of type
    INDIRECT.

   The protocol for the special CLIPBOARD client has
    changed.  The earlier protocol is subject to race condi
    tions and should not be used.

   The set of state values in WM_HINTS.initial_state has
    been reduced, but the values that are still valid are
    unchanged.  Window managers should treat the other val
    ues sensibly.





                             8833





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   The methods an application uses to change the state of
    its top-level window have changed but in such a way that
    cases that used to work will still work.

   The x, y, width, and height fields have been removed
    from the WM_NORMAL_HINTS property and replaced by pad
    fields.  Values set into these fields will be ignored.
    The position and size of the window should be set by
    setting the appropriate window attributes.

   A pair of base fields and a win_gravity field have been
    added to the WM_NORMAL_HINTS property.  Window managers
    will assume values for these fields if the client sets a
    short property.

AA..33..  TThhee PPuubblliicc RReevviieeww DDrraaffttss

The Consortium review resulted in several incompatible
changes.  These changes were included in drafts that were
distributed for public review during the first half of 1989.

   The messages field of the WM_HINTS property was found to
    be unwieldy and difficult to evolve.  It has been
    replaced by the WM_PROTOCOLS property, but clients that
    use the earlier mechanism can be detected because they
    set the messages bit in the flags field of the WM_HINTS
    property, and window managers can provide a backwards-
    compatibility mode.

   The mechanism described in the earlier draft by which
    clients installed their own subwindow colormaps could
    not be made to work reliably and mandated some features
    of the look and feel.  It has been replaced by the
    WM_COLORMAP_WINDOWS property.  Clients that use the ear
    lier mechanism can be detected by the WM_COLORMAPS prop
    erty they set on their top-level window, but providing a
    reliable backwards compatibility mode is not possible.

   The recommendations for window manager treatment of top-
    level window borders have been changed as those in the
    earlier draft produced problems with Visibility events.
    For nonwindow manager clients, there is no incompatibil
    ity.

   The pseudoroot facility in the earlier draft has been
    removed.  Although it has been successfully implemented,
    it turns out to be inadequate to support the uses envis
    aged.  An extension will be required to support these
    uses fully, and it was felt that the maximum freedom
    should be left to the designers of the extension.  In
    general, the previous mechanism was invisible to clients
    and no incompatibility should result.





                             884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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   The addition of the WM_DELETE_WINDOW protocol (which
    prevents the danger that multi-window clients may be
    terminated unexpectedly) has meant some changes in the
    WM_SAVE_YOURSELF protocol, to ensure that the two proto
    cols are orthogonal.  Clients using the earlier protocol
    can be detected (see WM_PROTOCOLS above) and supported
    in a backwards-compatibility mode.

   The conventions in Section 14.3.1. of _X_l_i_b _- _C _L_a_n_g_u_a_g_e
    _X _I_n_t_e_r_f_a_c_e regarding properties of type RGB_COLOR_MAP
    have been changed, but clients that use the earlier con
    ventions can be detected because their properties are
    four bytes shorter.  These clients will work correctly
    if the server supports only a single Visual or if they
    use only the Visual of the root.  These are the only
    cases in which they would have worked, anyway.

AA..44..  VVeerrssiioonn 11..00,, JJuullyy 11998899

The public review resulted in a set of mostly editorial
changes.  The changes in version 1.0 that introduced some
degree of incompatibility with the earlier drafts are:

   A new section (6.3) was added covering the window man
    ager's use of Grabs.  The restrictions it imposes should
    affect only window managers.

   The TARGETS selection target has been clarified, and it
    may be necessary for clients to add some entries to
    their replies.

   A selection owner using INCR transfer should no longer
    replace targets in a MULTIPLE property with the atom
    INCR.

   The contents of the _C_l_i_e_n_t_M_e_s_s_a_g_e event sent by a client
    to iconify itself has been clarified, but there should
    be no incompatibility because the earlier contents would
    not in fact have worked.

   The border-width in synthetic _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y events is
    now specified, but this should not cause any incompati
    bility.

   Clients are now asked to set a border-width on all _C_o_n_
    _f_i_g_u_r_e_W_i_n_d_o_w requests.

   Window manager properties on icon windows now will be
    ignored, but there should be no incompatibility because
    there was no specification that they be obeyed previ
    ously.

   The ordering of real and synthetic _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y
    events is now specified, but any incompatibility should



                             8855





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


    affect only window managers.

   The semantics of WM_SAVE_YOURSELF have been clarified
    and restricted to be a checkpoint operation only.
    Clients that were using it as part of a shutdown
    sequence may need to be modified, especially if they
    were interacting with the user during the shutdown.

   A kill_id field has been added to RGB_COLOR_MAP proper
    ties.  Clients using earlier conventions can be detected
    by the size of their RGB_COLOR_MAP properties, and the
    cases that would have worked will still work.

AA..55..  VVeerrssiioonn 11..11

Version 1.1 was released with X11R5 in September, 1991.  In
addition to some minor editorial changes, there were a few
semantic changes since Version 1.0:

   The section on Device Color Characterization was added.

   The meaning of the NULL property type was clarified.

   Appropriate references to Compound Text were added.

AA..66..  PPuubblliicc RReevviieeww DDrraafftt,, DDeecceemmbbeerr 11999933

The following changes have been made in preparing the public
review draft for Version 2.0.

   [P01] Addition of advice to clients on how to keep track
    of a top-level window's absolute position on the screen.

   [P03] A technique for clients to detect when it is safe
    to re-use a top-level window has been added.

   [P06] Section 4.1.8, on colormaps, has been rewritten.
    A new feature that allows clients to install their own
    colormaps has also been added.

   [P08] The LENGTH target has been deprecated.

   [P11] The manager selections facility was added.

   [P17] The definition of the aspect ratio fields of the
    WM_NORMAL_HINTS property has been changed to include the
    base size.

   [P19] _S_t_a_t_i_c_G_r_a_v_i_t_y has been added to the list of values
    allowed for the win_gravity field of the WM_HINTS prop
    erty.  The meaning of the _C_e_n_t_e_r_G_r_a_v_i_t_y value has been
    clarified.





                             8866





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   [P20] A means for clients to query the ICCCM compliance
    level of the window manager has been added.

   [P22] The definition of the MULTIPLE selection target
    has been clarified.

   [P25] A definition of "top-level window" has been added.
    The WM_STATE property has been defined and exposed to
    clients.

   [P26] The definition of window states has been clarified
    and the wording regarding window state changes has been
    made more consistent.

   [P27] Clarified the rules governing when window managers
    are required to send synthetic _C_o_n_f_i_g_u_r_e_N_o_t_i_f_y events.

   [P28] Added a recommended technique for setting the
    input focus to a window as soon as it is mapped.

   [P29] The required lifetime of resource IDs named in
    window manager properties has been specified.

   [P30] Advice for dealing with keystrokes and override-
    redirect windows has been added.

   [P31] A statement on the ownership of resources trans
    ferred through the selection mechanism has been added.

   [P32] The definition of the CLIENT_WINDOW target has
    been clarified.

   [P33] A rule about requiring the selection owner to re-
    acquire the selection under certain circumstances has
    been added.

   [P42] Added several new selection targets.

   [P44] Ambiguous wording regarding the withdrawal of top-
    level windows has been removed.

   [P45] A facility for requestors to pass parameters dur
    ing a selection request has been added.

   [P49] A convention on discrimated names has been added.

   [P57] The C_STRING property type was added.

   [P62] An ordering requirement on processing selection
    requests was added.

   [P63] The _V_i_s_i_b_l_e_H_i_n_t flag was added.





                             8877





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


   [P64] The session management section has been updated to
    align with the new session management protocol.  The old
    session management conventions have been moved to
    Appendix C.

   References to the never-forthcoming _W_i_n_d_o_w _a_n_d _S_e_s_s_i_o_n
    _M_a_n_a_g_e_r _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l have been removed.

   Information on the X Registry and references to the ses
    sion management and ICE documents have been added.

   Numerous editorial and typographical improvements have
    been made.

AA..77..  VVeerrssiioonn 22..00,, AApprriill 11999944

The following changes have been made in preparation for
releasing the final edition of Version 2.0 with X11R6.

   The PIXMAP selection target has been revised to return a
    property of type PIXMAP instead of type DRAWABLE.

   The session management section has been revised slightly
    to correspond with the changes to the _X _S_e_s_s_i_o_n _M_a_n_a_g_e_
    _m_e_n_t _P_r_o_t_o_c_o_l.

   Window managers are now prohibited from placing _C_u_r_r_e_n_t_
    _T_i_m_e in the timestamp field of WM_TAKE_FOCUS messages.

   In the WM_HINTS property, the _V_i_s_i_b_l_e_H_i_n_t flag has been
    renamed to _U_r_g_e_n_c_y_H_i_n_t.  Its semantics have also been
    defined more thoroughly.

   Additional editorial and typographical changes have been
    made.






















                             8888





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66




                           AAppppeennddiixx BB


BB..  SSuuggggeesstteedd PPrroottooccooll RReevviissiioonnss

During the development of these conventions, a number of
inadequacies have been discovered in the core X11 protocol.
They are summarized here as input to an eventual protocol
revision design process.

   There is no way for anyone to find out the last-change
    time of a selection.  The _G_e_t_S_e_l_e_c_t_i_o_n_O_w_n_e_r request
    should be changed to return the last-change time as well
    as the owner.

   There is no way for a client to find out which selection
    atoms are valid.

   There would be no need for WM_TAKE_FOCUS if the _F_o_c_u_s_I_n
    event contained a timestamp and a previous-focus field.
    This could avoid the potential race condition.  There is
    space in the event for this information; it should be
    added at the next protocol revision.

   There is a race condition in the _I_n_s_t_a_l_l_C_o_l_o_r_m_a_p
    request.  It does not take a timestamp and may be exe
    cuted after the top-level colormap has been uninstalled.
    The next protocol revision should provide the timestamp
    in the _I_n_s_t_a_l_l_C_o_l_o_r_m_a_p, _U_n_i_n_s_t_a_l_l_C_o_l_o_r_m_a_p, _L_i_s_t_
    _I_n_s_t_a_l_l_e_d_C_o_l_o_r_m_a_p_s requests and in the _C_o_l_o_r_m_a_p_N_o_t_i_f_y
    event.  The timestamp should be used in a similar way to
    the last-focus-change time for the input focus.  The
    lack of timestamps in these packets is the reason for
    restricting colormap installation to the window manager.

   The protocol needs to be changed to provide some way of
    identifying the Visual and the Screen of a colormap.

   There should be some way to reclaim assignments to the
    five non-preassigned modifiers when they are no longer
    needed.  The manual method is unpleasantly low-tech.














                             8899





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66




                           AAppppeennddiixx CC


CC..  OObbssoolleettee SSeessssiioonn MMaannaaggeerr CCoonnvveennttiioonnss

This appendix contains obsolete conventions for session man
agement using X properties and messages.  The conventions
described here are deprecated, and are described only for
historical interest.  For further information on session
management, see _X _S_e_s_s_i_o_n _M_a_n_a_g_e_m_e_n_t _P_r_o_t_o_c_o_l_.

CC..11..  PPrrooppeerrttiieess

The client communicates with the session manager by placing
two properties (WM_COMMAND and WM_CLIENT_MACHINE) on its
top-level window.  If the client has a group of top-level
windows, these properties should be placed on the group
leader window.

The window manager is responsible for placing a WM_STATE
property on each top-level client window for use by session
managers and other clients that need to be able to identify
top-level client windows and their state.

CC..11..11..  WWMM__CCOOMMMMAANNDD PPrrooppeerrttyy

The WM_COMMAND property represents the command used to start
or restart the client.  By updating this property, clients
should ensure that it always reflects a command that will
restart them in their current state.  The content and type
of the property depends on the operating system of the
machine running the client.  On POSIX-conformant systems
using ISO Latin-1 characters for their command lines, the
property should:

   Be of type STRING

   Contain a list of null-terminated strings

   Be initialized from argv

    Other systems will need to set appropriate conventions
    for the type and contents of WM_COMMAND properties.
    Window and session managers should not assume that
    STRING is the type of WM_COMMAND or that they will be
    able to understand or display its contents.

Note that WM_COMMAND strings are null-terminated and differ
from the general conventions that STRING properties are
null-separated.  This inconsistency is necessary for back
wards compatibility.




                             9900





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


A client with multiple top-level windows should ensure that
exactly one of them has a WM_COMMAND with nonzero length.
Zero-length WM_COMMAND properties can be used to reply to
WM_SAVE_YOURSELF messages on other top-level windows but
will otherwise be ignored.

CC..11..22..  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

This property is described in section 4.1.2.9.

CC..22..  TTeerrmmiinnaattiioonn

Because they communicate by means of unreliable network con
nections, clients must be prepared for their connection to
the server to be terminated at any time without warning.
They cannot depend on getting notification that termination
is imminent or on being able to use the server to negotiate
with the user about their fate.  For example, clients cannot
depend on being able to put up a dialog box.

Similarly, clients may terminate at any time without notice
to the session manager.  When a client terminates itself
rather than being terminated by the session manager, it is
viewed as having resigned from the session in question, and
it will not be revived if the session is revived.

CC..33..  CClliieenntt RReessppoonnsseess ttoo SSeessssiioonn MMaannaaggeerr AAccttiioonnss

Clients may need to respond to session manager actions in
two ways:

   Saving their internal state

   Deleting a window

CC..33..11..  SSaavviinngg CClliieenntt SSttaattee

Clients that want to be warned when the session manager
feels that they should save their internal state (for exam
ple, when termination impends) should include the atom
WM_SAVE_YOURSELF in the WM_PROTOCOLS property on their top-
level windows to participate in the WM_SAVE_YOURSELF proto
col.  They will receive a _C_l_i_e_n_t_M_e_s_s_a_g_e event as described
in section 4.2.8 with the atom WM_SAVE_YOURSELF in its
data[0] field.

Clients that receive WM_SAVE_YOURSELF should place them
selves in a state from which they can be restarted and
should update WM_COMMAND to be a command that will restart
them in this state.  The session manager will be waiting for
a _P_r_o_p_e_r_t_y_N_o_t_i_f_y event on WM_COMMAND as a confirmation that
the client has saved its state.  Therefore, WM_COMMAND
should be updated (perhaps with a zero-length append) even
if its contents are correct.  No interactions with the user



                             9911





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


are permitted during this process.

Once it has received this confirmation, the session manager
will feel free to terminate the client if that is what the
user asked for.  Otherwise, if the user asked for the ses
sion to be put to sleep, the session manager will ensure
that the client does not receive any mouse or keyboard
events.

After receiving a WM_SAVE_YOURSELF, saving its state, and
updating WM_COMMAND, the client should not change its state
(in the sense of doing anything that would require a change
to WM_COMMAND) until it receives a mouse or keyboard event.
Once it does so, it can assume that the danger is over.  The
session manager will ensure that these events do not reach
clients until the danger is over or until the clients have
been killed.

Irrespective of how they are arranged in window groups,
clients with multiple top-level windows should ensure the
following:

   Only one of their top-level windows has a nonzero-length
    WM_COMMAND property.

   They respond to a WM_SAVE_YOURSELF message by:

    -    First, updating the nonzero-length WM_COMMAND prop
         erty, if necessary

    -    Second, updating the WM_COMMAND property on the
         window for which they received the WM_SAVE_YOURSELF
         message if it was not updated in the first step

Receiving WM_SAVE_YOURSELF on a window is, conceptually, a
command to save the entire client state.16

CC..33..22..  WWiinnddooww DDeelleettiioonn

Windows are deleted using the WM_DELETE_WINDOW protocol,
which is described in section 4.2.8.1.



-----------
  16 This convention has changed since earlier
drafts because of the introduction of the protocol
in the next section.  In the public review draft,
there was ambiguity as to whether WM_SAVE_YOURSELF
was a checkpoint or a shutdown facility.  It is
now unambiguously a checkpoint facility; if a
shutdown facility is judged to be necessary, a
separate WM_PROTOCOLS protocol will be developed
and registered with the X Consortium.



                             9922





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


CC..44..  SSuummmmaarryy ooff SSeessssiioonn MMaannaaggeerr PPrrooppeerrttyy TTyyppeess

The session manager properties are listed in the following
table:

----------------------------------------------------
NNaammee                TTyyppee       FFoorrmmaatt   SSeeee SSeeccttiioonn
----------------------------------------------------
WM_CLIENT_MACHINE   TEXT                  4.1.2.9
WM_COMMAND          TEXT                   C.1.1
WM_STATE            WM_STATE     32       4.1.3.1
----------------------------------------------------













































                             9933





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66



























































                             994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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


                     TTaabbllee ooff CCoonntteennttss


Preface to Version 2.0 . . . . . . . . . . . . . . . . . vii
Preface to Version 1.1 . . . . . . . . . . . . . . . . .viii
1. Introduction  . . . . . . . . . . . . . . . . . . . .   1
1.1. Evolution of the Conventions  . . . . . . . . . . .   1
1.2. Atoms . . . . . . . . . . . . . . . . . . . . . . .   2
1.2.1. What Are Atoms?   . . . . . . . . . . . . . . . .   2
1.2.2. Predefined Atoms  . . . . . . . . . . . . . . . .   2
1.2.3. Naming Conventions  . . . . . . . . . . . . . . .   3
1.2.4. Semantics . . . . . . . . . . . . . . . . . . . .   3
1.2.5. Name Spaces . . . . . . . . . . . . . . . . . . .   3
1.2.6. Discriminated Names . . . . . . . . . . . . . . .   4
2. Peer-to-Peer Communication by Means of Selections
 . . . . . . . . . . . . . . . . . . . . . . . . . . . .   5
2.1. Acquiring Selection Ownership . . . . . . . . . . .   6
2.2. Responsibilities of the Selection Owner . . . . . .   8
2.3. Giving Up Selection Ownership . . . . . . . . . . .  11
2.3.1. Voluntarily Giving Up Selection Ownership . . . .  11
2.3.2. Forcibly Giving Up Selection Ownership  . . . . .  11
2.4. Requesting a Selection  . . . . . . . . . . . . . .  12
2.5. Large Data Transfers  . . . . . . . . . . . . . . .  15
2.6. Use of Selection Atoms  . . . . . . . . . . . . . .  16
2.6.1. Selection Atoms . . . . . . . . . . . . . . . . .  16
2.6.1.1. The PRIMARY Selection . . . . . . . . . . . . .  16
2.6.1.2. The SECONDARY Selection . . . . . . . . . . . .  16
2.6.1.3. The CLIPBOARD Selection . . . . . . . . . . . .  16
2.6.2. Target Atoms  . . . . . . . . . . . . . . . . . .  18
2.6.3. Selection Targets with Side Effects . . . . . . .  21
2.6.3.1. DELETE  . . . . . . . . . . . . . . . . . . . .  22
2.6.3.2. INSERT_SELECTION  . . . . . . . . . . . . . . .  22
2.6.3.3. INSERT_PROPERTY . . . . . . . . . . . . . . . .  22
2.7. Use of Selection Properties . . . . . . . . . . . .  22
2.7.1. TEXT Properties . . . . . . . . . . . . . . . . .  24
2.7.2. INCR Properties . . . . . . . . . . . . . . . . .  25
2.7.3. DRAWABLE Properties . . . . . . . . . . . . . . .  26
2.7.4. SPAN Properties . . . . . . . . . . . . . . . . .  26
2.8. Manager Selections  . . . . . . . . . . . . . . . .  27
3. Peer-to-Peer Communication by Means of Cut
Buffers  . . . . . . . . . . . . . . . . . . . . . . . .  28
4. Client to Window Manager Communication  . . . . . . .  29
4.1. Client's Actions  . . . . . . . . . . . . . . . . .  30
4.1.1. Creating a Top-Level Window . . . . . . . . . . .  31
4.1.2. Client Properties . . . . . . . . . . . . . . . .  32
4.1.2.1. WM_NAME Property  . . . . . . . . . . . . . . .  33
4.1.2.2. WM_ICON_NAME Property . . . . . . . . . . . . .  33
4.1.2.3. WM_NORMAL_HINTS Property  . . . . . . . . . . .  33
4.1.2.4. WM_HINTS Property . . . . . . . . . . . . . . .  36
4.1.2.5. WM_CLASS Property . . . . . . . . . . . . . . .  39
4.1.2.6. WM_TRANSIENT_FOR Property . . . . . . . . . . .  40
4.1.2.7. WM_PROTOCOLS Property . . . . . . . . . . . . .  40
4.1.2.8. WM_COLORMAP_WINDOWS Property  . . . . . . . . .  41
4.1.2.9. WM_CLIENT_MACHINE Property  . . . . . . . . . .  41



                             iii





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


4.1.3. Window Manager Properties . . . . . . . . . . . .  41
4.1.3.1. WM_STATE Property . . . . . . . . . . . . . . .  41
4.1.3.2. WM_ICON_SIZE Property . . . . . . . . . . . . .  43
4.1.4. Changing Window State . . . . . . . . . . . . . .  43
4.1.5. Configuring the Window  . . . . . . . . . . . . .  47
4.1.6. Changing Window Attributes  . . . . . . . . . . .  50
4.1.7. Input Focus . . . . . . . . . . . . . . . . . . .  51
4.1.8. Colormaps . . . . . . . . . . . . . . . . . . . .  53
4.1.9. Icons . . . . . . . . . . . . . . . . . . . . . .  57
4.1.10. Pop-up Windows . . . . . . . . . . . . . . . . .  58
4.1.11. Window Groups  . . . . . . . . . . . . . . . . .  59
4.2. Client Responses to Window Manager Actions  . . . .  60
4.2.1. Reparenting . . . . . . . . . . . . . . . . . . .  60
4.2.2. Redirection of Operations . . . . . . . . . . . .  61
4.2.3. Window Move . . . . . . . . . . . . . . . . . . .  63
4.2.4. Window Resize . . . . . . . . . . . . . . . . . .  63
4.2.5. Iconify and Deiconify . . . . . . . . . . . . . .  63
4.2.6. Colormap Change . . . . . . . . . . . . . . . . .  64
4.2.7. Input Focus . . . . . . . . . . . . . . . . . . .  64
4.2.8. ClientMessage Events  . . . . . . . . . . . . . .  65
4.2.8.1. Window Deletion . . . . . . . . . . . . . . . .  65
4.2.9. Redirecting Requests  . . . . . . . . . . . . . .  66
4.3. Communication with the Window Manager by Means
of Selections  . . . . . . . . . . . . . . . . . . . . .  67
4.4. Summary of Window Manager Property Types  . . . . .  68
5. Session Management  . . . . . . . . . . . . . . . . .  68
5.1. Client Support for Session Management . . . . . . .  68
5.2. Window Manager Support for Session Management
 . . . . . . . . . . . . . . . . . . . . . . . . . . . .  70
6. Manipulation of Shared Resources  . . . . . . . . . .  70
6.1. The Input Focus . . . . . . . . . . . . . . . . . .  70
6.2. The Pointer . . . . . . . . . . . . . . . . . . . .  71
6.3. Grabs . . . . . . . . . . . . . . . . . . . . . . .  71
6.4. Colormaps . . . . . . . . . . . . . . . . . . . . .  73
6.5. The Keyboard Mapping  . . . . . . . . . . . . . . .  74
6.6. The Modifier Mapping  . . . . . . . . . . . . . . .  75
7. Device Color Characterization . . . . . . . . . . . .  77
7.1. XYZ <--> RGB Conversion Matrices  . . . . . . . . . .  78
7.2. Intensity <--> RGB Value Conversion . . . . . . . . .  78
8. Conclusion  . . . . . . . . . . . . . . . . . . . . .  81
8.1. The X Registry  . . . . . . . . . . . . . . . . . .  81
A. Revision History  . . . . . . . . . . . . . . . . . .  83
A.1. The X11R2 Draft . . . . . . . . . . . . . . . . . .  83
A.2. The July 27, 1988 Draft . . . . . . . . . . . . . .  83
A.3. The Public Review Drafts  . . . . . . . . . . . . .  84
A.4. Version 1.0, July 1989  . . . . . . . . . . . . . .  85
A.5. Version 1.1 . . . . . . . . . . . . . . . . . . . .  86
A.6. Public Review Draft, December 1993  . . . . . . . .  86
A.7. Version 2.0, April 1994 . . . . . . . . . . . . . .  88
B. Suggested Protocol Revisions  . . . . . . . . . . . .  89
C. Obsolete Session Manager Conventions  . . . . . . . .  90
C.1. Properties  . . . . . . . . . . . . . . . . . . . .  90
C.1.1. WM_COMMAND Property . . . . . . . . . . . . . . .  90
C.1.2. WM_CLIENT_MACHINE Property  . . . . . . . . . . .  91



                             iv





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 CCoonnvveennttiioonnss        XX1111,, RReelleeaassee 66


C.2. Termination . . . . . . . . . . . . . . . . . . . .  91
C.3. Client Responses to Session Manager Actions . . . .  91
C.3.1. Saving Client State . . . . . . . . . . . . . . .  91
C.3.2. Window Deletion . . . . . . . . . . . . . . . . .  92
C.4. Summary of Session Manager Property Types . . . . .  93




















































                              v


