














          [1mInter-Client Communication Conventions Manual[0m

                       [1mVersion 2.0.xf86.1[0m

                          [1mXFree86 4.0.2[0m

                          [1mXFree86, Inc.[0m

                            [4mbased[24m [4mon[0m

                           [1mVersion 2.0[0m

                      [1mX Consortium Standard[0m

                    [1mX Version 11, Release 6.4[0m






                         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 (C) 1988, 1991, 1993, 1994 X Consortium

Permission  is  hereby granted, free of charge, to any person ob-
taining a copy of  this  software  and  associated  documentation
files  (the "Software"), to deal in the Software without restric-
tion, including without limitation the rights to use, copy,  mod-
ify,  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 PURPOSE  AND  NONIN-
FRINGEMENT.  IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY
CLAIM,  DAMAGES  OR OTHER LIABILITY, WHETHER IN AN ACTION OF CON-
TRACT, 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 Consortium
shall not be used in advertising  or  otherwise  to  promote  the
sale,  use or other dealings in this Software without prior writ-
ten authorization from the X Consortium.



Copyright (C) 1987, 1988, 1989, 1993, 1994 Sun Microsystems, Inc.

Permission to use, copy, modify, and distribute  this  documenta-
tion  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  representations  about
the  suitability for any purpose of the information in this docu-
ment.  This documentation is provided as is  without  express  or
implied warranty.







                                ii

































































                                vi










                     [1mPreface to Version 2.0[0m



The  goal  of the ICCCM Version 2.0 effort was to add new facili-
ties, to fix problems with earlier drafts, and to  improve  read-
ability  and  understandability,  while maintaining compatibility
with the earlier versions.  This document is the product of  over
two  years  of discussion among the members of the X Consortium's
[1mwmtalk [22mworking group.  The following people  deserve  thanks  for
their contributions:

Gabe     Beged-Dov                Bill    Janssen    Chan    Ben-
son                   Vania            Joloboff            Jordan
Brown                  Phil        Karlton        Larry       Ca-
ble                   Kaleb            Keithley             Ellis
Cohen                   Mark       Manasse       Donna       Con-
verse                Ralph Mor Brian Cripe                   Todd
Newman Susan  Dahlberg                Bob  Scheifler  Peter  Dai-
fuku                 Keith        Taylor        Andrew        de-
Blois                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










                     [1mPreface to Version 1.1[0m



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 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 mail alias.
Thanks are due to everyone who contributed, and especially to the
following 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       Ful-
ton                    Bob      Scheifler      Hania       Gajew-
ska                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  pub-
lic review:

Gary        Combs                    John       Irwin       Errol
Crary                   Vania           Joloboff            Nancy
Cyprych                 John        Laporta       John       Dia-
mant                  Ken Lee Clive  Feather                 Stu-
art   Marks   Burns  Fisher                  Alan  Mimms  Richard
Greco                 Colas       Nahaboo       Tim        Green-
wood                 Mark        Patrick        Kee        Hinck-
ley                  Steve             Pitschke             Brian
Holt                    Brad        Reed        John       Inter-
rante               John Thomas









                               viii








It was an explicit design goal of X Version 11 to specify  mecha-
nism,  not policy.  As a result, a client that converses with the
server using the protocol defined by the [4mX[24m [4mWindow[24m  [4mSystem[24m  [4mProto-[0m
[4mcol[24m,  [4mVersion[24m  [4m11[24m  may operate correctly in isolation 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 communications in the
following areas:

+o   Selection mechanism

+o   Cut buffers

+o   Window manager

+o   Session manager

+o   Manipulation of shared resources

+o   Device color characterization

This document proposes suitable conventions without attempting to
enforce any particular user interface.  To permit clients written
in different languages to communicate, these conventions are  ex-
pressed  solely  in terms of protocol operations, not in terms of
their associated Xlib interfaces, which are probably more  famil-
iar.  The binding of these operations to the Xlib interface for C
and  to the equivalent interfaces for other languages is the sub-
ject of other documents.

In the interests of timely acceptance, the [4mInter-Client[24m  [4mCommuni-[0m
[4mcation[24m  [4mConventions[24m  [4mManual[24m  (ICCCM) covers only a minimal set of
required conventions.  These conventions will be added to and up-
dated as appropriate, based on the experiences of the  X  Consor-
tium.

As  far  as  possible,  these conventions are upwardly compatible
with those in the February 25, 1988, draft that  was  distributed
with  the  X Version 11, Release 2, of the software.  In some ar-
eas, 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 Appendix B, and are
offered  as  input to a future protocol revision process.  If and
when a protocol revision incorporating these  changes  is  under-
taken,  it is anticipated that the ICCCM will need to be revised.
Because it is difficult to ensure that clients  and  servers  are
upgraded  simultaneously,  clients  using the revised conventions
should examine the minor protocol revision number and be prepared



                                [1m1[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


to use the older conventions when  communicating  with  an  older
server.

It  is expected that these revisions will ensure that clients us-
ing the conventions appropriate to protocol minor revision [4mn[24m will
interoperate correctly with those that use the conventions appro-
priate to protocol minor revision [4mn[24m + 1 if  the  server  supports
both.

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.

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 without an
encoding being specified.  The elements are not necessarily 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 representation  for  them  was
needed.

To allow a fixed-size representation, a protocol request was pro-
vided  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

The protocol specifies a number of atoms as being predefined:

     Predefined atoms are not strictly necessary and may not
     be  useful in all environments, but they will eliminate
     many 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  re-
quests, which require a handshake, can be assumed [4ma[24m [4mpriori[24m.

Language  interfaces should probably cache the atom-name mappings
and get them only when required.   The  CLX  interface,  for  in-
stance,  makes  no distinction between predefined atoms and other
atoms; all atoms are viewed as symbols at  the  interface.   How-
ever,  a  CLX implementation will typically keep a symbol or atom
cache  and  will  typically  initialize  this  cache   with   the
-----------
  [1] The comment in the protocol specification for that ISO
Latin-1 encoding should be used is in the nature of  a  con-
vention; the server treats the string as a byte sequence.



                                [1m2[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


predefined atoms.

The  built-in  atoms  are  composed of uppercase ASCII characters
with the logical words separated by an underscore character  (_),
for example, WM_ICON_NAME.  The protocol specification recommends
that  atoms used for private vendor-specific reasons should begin
with an underscore.  To prevent  conflicts  among  organizations,
additional prefixes should be chosen (for example,  _DEC_WM_DECO-
RATION_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 conventions would have  to  be
used.

The  core  protocol  imposes no semantics on atoms except as they
are used in FONTPROP  structures.   For  further  information  on
FONTPROP  semantics,  see  the [4mX[24m [4mLogical[24m [4mFont[24m [4mDescription[24m [4mConven-[0m
[4mtions[24m.

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

l l lw(3.6i).  _
[1mSpace     Briefly   Examples[0m
[1m_[0m
Property name  Name WM_HINTS, WM_NAME, RGB_BEST_MAP,  ...   Prop-
erty type    Type WM_HINTS, CURSOR, RGB_COLOR_MAP, ...  Selection
name Selection PRIMARY,   SECONDARY,   CLIPBOARD  Selection  tar-
get    Target    FILE_NAME, POSTSCRIPT, PIXMAP, ...   Font  prop-
erty       QUAD_WIDTH,  POINT_SIZE,  ...  T{ type T}   T{ T}   T{
WM_SAVE_YOURSELF, _DEC_SAVE_EDITS, ...  T}
_

Sometimes a protocol requires an arbitrary number of similar  ob-
jects  that  need  unique  names (usually because the objects are
created dynamically, so that names  cannot  be  invented  in  ad-
vance).  For example, a colormap-generating 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 discriminated names
are formed by suffixing an ordinary name according to  the  value
of the entity.




                                [1m3[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


If  [4mname[24m  is  a  descriptive portion for the name, [4md[24m is a decimal
number with no leading zeroes, and [4mx[24m is a hexadecimal number with
exactly 8 digits, and using uppercase letters, then such discrim-
inated names shall have the form:

lB lB lB l l l .  _
Name Discriminated by    Form Example
_
screen        number  [4mname[24m_S[4md[24m   WM_COMMS_S2         X         re-
source     [4mname[24m_R[4mx[24m   GROUP_LEADER_R1234ABCD
_

To discriminate a name by client, use an X resource ID created 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 MUL-
TIPLE selection).  These names should have the form:

     U[4md[24m                  (e.g.,  U0  U1  U2  U3  ...)

if the names stand totally alone, and the form:

     [4mname[24m_U[4md[24m             (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[4md[24m  form should be used only if it is
clear that the module using it has complete control over the rel-
evant namespace or has the active cooperation of all other  enti-
ties  that  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  com-
bine  both  forms  of discrimination. If this happens, the U form
should come after the other form, thus:

         FOO_R12345678_U23

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

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.





                                [1m4[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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

+o   The name of the selection

+o   The name of a property

+o   A window

+o   The atom representing the data type required

+o   Optionally, some parameters for the request

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

+o   Convert  the  contents of the selection to the requested data
    type

+o   Place this data in the named property on the named window

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

Clients  are  strongly encouraged to use this mechanism.  In par-
ticular, 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 envi-
ronment.  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 network-
ing 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) is  permitted  only
if both clients specifically agree.

A  client  wishing to acquire ownership of a particular selection
should call which is defined as follows:


  [4mselection[24m: ATOM
  [4mowner[24m: WINDOW or
  [4mtime[24m: TIMESTAMP or


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



                                [1m5[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


and the current server time.  This time value usually will be ob-
tained from the timestamp of the event that triggers the acquisi-
tion of the selection.  Clients should not set the time value  to
because  if  they  do  so,  they have no way of finding when they
gained ownership of the selection.  Clients  must  use  a  window
they  created so that requestors can route events to the owner of
the selection.[2] Clients attempting to acquire a selection  must
set  the  time value of the request to the timestamp of the event
triggering the acquisition attempt, not to A  zero-length  append
to  a  property  is a way to obtain a timestamp for this purpose;
the timestamp is in the corresponding event.

If the time in the 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 request appears to the
client to succeed, but ownership is not actually transferred.

Because clients cannot name other clients directly, the specified
owner window is used to refer to the owning client in the replies
to  in  and events, and possibly as a place to put properties de-
scribing the selection in question.  To discover the owner  of  a
particular  selection, a client should invoke which is defined as
follows:


  [4mselection[24m: ATOM

->

  owner: WINDOW or

Clients are expected to provide some visible confirmation of  se-
lection ownership.  To make this feedback reliable, a client must
perform a sequence like the following:

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

If  the  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 speci-
fied time.

When  a  requestor  wants the value of a selection, the owner re-
ceives a event, which is defined as follows:



-----------
  [2] At present, no  part  of  the  protocol  requires  re-
questors  to  send events to the owner of a selection.  This
restriction is imposed to prepare for possible future exten-
sions.



                                [1m6[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


  [4mowner[24m: WINDOW
  [4mselection[24m: ATOM
  [4mtarget[24m: ATOM
  [4mproperty[24m: ATOM or
  [4mrequestor[24m: WINDOW
  [4mtime[24m: TIMESTAMP or


The specified owner and selection will be the  values  that  were
specified in the request.  The owner should compare the timestamp
with  the  period  it has owned the selection and, if the time is
outside, refuse the by sending the requestor window a event  with
the  property  set  to (by means of a request with an empty event
mask).

More advanced selection owners are free to maintain a history  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 the requestor is an obsolete client.
Owners are encouraged to support these clients by using the spec-
ified 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 parameters along with
the request.  The owner will find these parameters in  the  prop-
erty  named in the selection request.  The type, format, and con-
tents of this property are dependent upon the definition  of  the
target.   If  the  target  is not defined to have parameters, the
owner should ignore the property if it is present.  If the selec-
tion cannot be converted into a form based on the target (and pa-
rameters, if any), the owner should refuse the as previously  de-
scribed.

If  the specified property is not the owner should place the data
resulting from converting the selection into the specified  prop-
erty  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.  All properties used to reply to 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 as
previously described.  See also section 2.5.

If the property is successfully stored, the owner should acknowl-
edge the successful conversion by sending the requestor window  a
event  (by means of a request with an empty mask).  is defined as
follows:





                                [1m7[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


  [4mrequestor[24m: WINDOW
  [4mselection[24m, [4mtarget[24m: ATOM
  [4mproperty[24m: ATOM or
  [4mtime[24m: TIMESTAMP or


The owner should set the specified selection, target,  time,  and
property  arguments  to  the values received in the event.  (Note
that setting the property argument to indicates that the  conver-
sion  requested could not be made.)  The selection, target, time,
and property arguments in the event should be set to  the  values
received in the event.

If  the  owner  receives  more  than  one event with the same re-
questor, selection, target, and timestamp it must respond to them
in the same order in which they were received.   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  resulting  event will have its
property argument set to This may make it impossible for the  re-
questor  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.
Selection requestors  are  responsible  for  deleting  properties
whose  names they receive in events (see section 2.4) or in prop-
erties with type MULTIPLE.

A selection owner will often need confirmation that the data com-
prising the selection has actually been transferred.  (For  exam-
ple,  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 successfully received the data.)  Own-
ers should express interest in events for the specified requestor
window and wait until the property in the event has been  deleted
before  assuming  that  the  selection data has been transferred.
For the MULTIPLE request, if the  different  conversions  require
separate confirmation, the selection owner can also watch for the
deletion  of  the  individual properties named in the property in
the event.

When some other client acquires a selection, the  previous  owner
receives a event, which is defined as follows:


  [4mowner[24m: WINDOW
  [4mselection[24m: ATOM
  [4mtime[24m: TIMESTAMP


The timestamp argument is the time at which the ownership changed
hands,  and  the  owner argument is the window the previous owner



                                [1m8[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


specified in its 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  [1mxterm  [22mas  before),  then  the  client
should  reacquire  the  selection ownership as if it were not the
owner, providing a new timestamp. If the selection value is modi-
fied, but can still reasonably be viewed as the same selected ob-
ject,[3] the owner should take no action.

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

To relinquish ownership of  a  selection  voluntarily,  a  client
should  execute  a  request  for  that selection atom, with owner
specified as and the time specified as  the  timestamp  that  was
used to acquire the selection.

Alternatively,  the  client  may  destroy  the window used as the
owner value of the request, or the client may terminate.  In both
cases, the ownership of the selection involved will revert to

If a client gives up ownership of a selection or  if  some  other
client executes a for it and thus reassigns it forcibly, the pre-
vious  owner will receive a event. For the definition of a event,
see section 2.2.

The timestamp is the time the selection changed hands.  The spec-
ified owner is the window that was specified by the current owner
in its request.

A client that wishes to obtain the value of a selection in a par-
ticular form (the requestor) issues a request, which  is  defined
as follows:


  [4mselection[24m, [4mtarget[24m: ATOM
  [4mproperty[24m: ATOM or
  [4mrequestor[24m: WINDOW
  [4mtime[24m: TIMESTAMP or


The  selection  argument  specifies  the particular selection in-
volved, 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
-----------
  [3] The division between these two cases is  a  matter  of
judgment on the part of the software developer.



                                [1m9[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


requestor  argument  to  a window that it created; 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  Clients  should  not  use for the time argument of a re-
quest.  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 selec-
tion.  Requestors should ensure that the named property does  not
exist  on the window before issuing the request.[4] The exception
to this rule is when the requestor  intends  to  pass  parameters
with  the request (see below).  It is necessary for requestors to
delete the property 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 client that owns the selection nor  the  window
on which the selection was acquired.

Some targets may be defined such that requestors can pass parame-
ters  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
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 tar-
get, the requestor must ensure that the property does  not  exist
before issuing the request.

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

1.   Requestors should not use for the property argument of a re-
     quest.

2.   Owners receiving requests with a property  argument  of  are
     talking  to an obsolete client.  They should choose the tar-
     get atom as the property name to be used for the reply.

The result of the request is that a event will be received.   For
the definition of a event, see section 2.2.

-----------
  [4] This  requirement  is new in version 2.0, and, in gen-
eral, existing clients do not conform to  this  requirement.
To  prevent these clients from breaking, no existing targets
should be extended to take parameters until sufficient  time
has  passed for clients to be updated.  Note that the MULTI-
PLE target was defined to take parameters in version 1.0 and
its definition is not changing.  There is  thus  no  confor-
mance problem with MULTIPLE.



                                [1m10[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


The  requestor, selection, time, and target arguments will be the
same as those on the request.

If the property argument is  the  conversion  has  been  refused.
This  can  mean  either that there is no owner for the selection,
that the owner does not support the  conversion  implied  by  the
target,  or  that the server did not have sufficient space to ac-
commodate the data.

If the property argument is not then that property will exist  on
the  requestor  window.   The  value  of the selection can be re-
trieved from this property by using the request, which is defined
as follows:


  [4mwindow[24m: WINDOW
  [4mproperty[24m: ATOM
  [4mtype[24m: ATOM or
  [4mlong-offset[24m, [4mlong-length[24m: CARD32
  [4mdelete[24m: BOOL

->

  type: ATOM or
  format: {0, 8, 16, 32}
  bytes-after: CARD32
  value: LISTofINT8 or LISTofINT16 or LISTofINT32


When using to retrieve the value of a selection, the property ar-
gument should be set to the corresponding  value  in  the  event.
Because  the requestor has no way of knowing beforehand what type
the selection owner will use, the type argument should be set  to
Several  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 request by
using a request with the delete argument  set  to  As  previously
discussed, the owner has no way of knowing when the data has been
transferred to the requestor unless the property is removed.  The
requestor must delete the property named in the once all the data
has  been retrieved.  The requestor should invoke either or after
it has successfully retrieved all the data in the selection.  For
further information, see section 2.5.

Selections can get large, which poses two problems:

+o   Transferring large amounts of data to the  server  is  expen-
    sive.



                                [1m11[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   All  servers  will have limits on the amount of data that can
    be stored in properties.  Exceeding this limit will result in
    an error on the request that  the  selection  owner  uses  to
    store the data.

The  problem of limited server resources is addressed by the fol-
lowing conventions:

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

2.   Any client  using  to  acquire  selection  ownership  should
     arrange  to process errors in property change requests.  For
     clients using Xlib, this  involves  using  the  function  to
     override the default handler.

3.   A  selection owner must confirm that no error occurred while
     storing the properties for a selection before replying  with
     a confirming event.

4.   When  storing large amounts of data (relative to maximum-re-
     quest-size), clients should use a sequence of  requests  for
     reasonable  quantities of data.  This avoids locking servers
     up and limits the waste of data an error would cause.

5.   If an error occurs during the storing of the selection data,
     all properties stored for this selection should  be  deleted
     and the 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  prop-
     erty  should perform a series of requests, each asking for a
     reasonable amount of data.  Single-threaded  servers  should
     take care to avoid locking up during large data transfers.

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.

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:

+o   PRIMARY

+o   SECONDARY

+o   CLIPBOARD

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



                                [1m12[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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

The selection named by the atom SECONDARY is used:

+o   As  the second argument to commands taking two arguments (for
    example, "exchange primary and secondary selections")

+o   As a means of obtaining data when there is a  primary  selec-
    tion and the user does not want to disturb it

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 and then pasted or copied and then pasted.
Whenever a client wants to transfer data to the clipboard:

+o   It should assert ownership of the CLIPBOARD.

+o   If it succeeds in acquiring ownership, it should be  prepared
    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 de-
    scribed below.

+o   If it fails to acquire ownership, a cutting client should not
    actually perform the cut or provide feedback that would  sug-
    gest 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, special  client
implemented  for  the purpose.  This client maintains the content
of the clipboard up-to-date and responds  to  requests  for  data
from the clipboard as follows:

+o   It should assert ownership of the CLIPBOARD selection and re-
    assert it any time the clipboard data changes.

+o   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 event.

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





                                [1m13[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


    -    Restart  the process using a newly acquired timestamp 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 re-
         fused or if the same timestamp is  received  twice,  the
         clipboard client should acquire a fresh timestamp in the
         usual  way  (for  example  by  a zero-length append to a
         property).

+o   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 same  whether
the  CLIPBOARD client is running or not.  The reasons for running
the special client include:

+o   Stability - If the cutting client were to crash or terminate,
    the clipboard value would still be available.

+o   Feedback - The clipboard client can display the  contents  of
    the clipboard.

+o   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:

+o   Performance  - Data is transferred only if it is actually re-
    quired (that is, when some client actually wants the data).

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

The atom that a requestor supplies as the target of a request de-
termines the form of the data supplied.  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  con-
tains those that have been suggested so far.

lw(1.8i) lw(1i) lw(3i) .  _
[1mAtom Type      Data Received[0m
_
l  s s .  ADOBE_PORTABLE_DOCUMENT_FORMAT lw(1.8i) lw(1i) lw(3i) .
     STRING    T{ [1] T}
APPLE_PICT     APPLE_PICT     T{       [2]        T}        BACK-
GROUND     PIXEL     A list of pixel values BITMAP    BITMAP    A
list  of bitmap IDs CHARACTER_POSITION  SPAN T{ The start and end
of the selection in bytes T} CLASS     TEXT (see section 4.1.2.5)
CLIENT_WINDOW  WINDOW    T{ Any top-level window owned by the se-
lection owner T} COLORMAP  COLORMAP  A list of colormap IDs  COL-
UMN_NUMBER  SPAN T{  The  start  and  end  column numbers T} COM-
POUND_TEXT  COMPOUND_TEXT  Compound   Text    DELETE    NULL (see



                                [1m14[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


lw(1.8i) lw(1i) lw(3i) .  _
[1mAtom Type      Data Received[0m
_
section 2.6.3.1) DRAWABLE  DRAWABLE  A list of drawable IDs
l  s  s  .   ENCAPSULATED_POSTSCRIPT  lw(1.8i)  lw(1i)  lw(3i)  .
     STRING    T{ [3], Appendix H[5] T}
l s  s  .   ENCAPSULATED_POSTSCRIPT_INTERCHANGE  lw(1.8i)  lw(1i)
lw(3i) .       STRING    T{ [3], Appendix H T}
FILE_NAME TEXT The    full    path   name   of   a   file   FORE-
GROUND     PIXEL     T{   A   list    of    pixel    values    T}
HOST_NAME TEXT (see       section      4.1.2.9)      INSERT_PROP-
ERTY     NULL (see section 2.6.3.3) INSERT_SELECTION    NULL (see
section 2.6.3.2) LENGTH    INTEGER   T{ The number  of  bytes  in
the selection[6] T} LINE_NUMBER    SPAN T{ The start and end line
numbers  T}  LIST_LENGTH    INTEGER   T{  The  number of disjoint
parts of the selection T} MODULE    TEXT T{ The name of  the  se-
lected  procedure  T}  MULTIPLE  ATOM_PAIR T{ (see the discussion
that follows) T} NAME TEXT (see section 4.1.2.1) ODIF TEXT T{ ISO
Office Document Interchange Format T} OWNER_OS  TEXT T{ The oper-
ating system  of  the  owner  client  T}  PIXMAP    T{  PIXMAP[7]
T}   T{  A  list of pixmap IDs T} POSTSCRIPT     STRING    T{ [3]
T} PROCEDURE TEXT T{  The  name  of  the  selected  procedure  T}
PROCESS   INTEGER,  TEXT T{  The  process  ID  of  the  owner  T}
STRING    STRING    ISO   Latin-1   (+TAB+NEWLINE)   text    TAR-
GETS   ATOM A  list  of valid target atoms TASK INTEGER, TEXT  T{
The task ID of the owner T} TEXT TEXT T{ The text in the  owner's
choice  of  encoding T} TIMESTAMP INTEGER   T{ The timestamp used
to acquire the selection T} USER TEXT T{ The  name  of  the  user
running the owner T} UTF8_STRING    TEXT T{ UTF-8 text T}
_

References:

[1]  Adobe Systems, Incorporated.  [4mPortable[24m [4mDocument[24m [4mFormat[24m  [4mRef-[0m
     [4merence[24m    [4mManual.[24m    Reading,   MA,   Addison-Wesley,   ISBN
-----------
  [5] Earlier  versions  of this document erroneously speci-
fied that conversion of the PIXMAP target returns 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   ENCAPSU-
LATED_POSTSCRIPT_INTERCHANGE  are  equivalent to the targets
_ADOBE_EPS and _ADOBE_EPSI (respectively) that appear in the
selection targets registry.  The _ADOBE_ targets are  depre-
cated,  but  clients  are  encouraged to continue to support
them for backward compatibility.
  [7] This definition is ambiguous, as the selection may  be
converted  into  any of several targets that may return dif-
fering 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.



                                [1m15[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


     0-201-62628-4.

[2]  Apple Computer, Incorporated.  [4mInside[24m [4mMacintosh,[24m  [4mVolume[24m  [4mV.[0m
     Chapter  4,  "Color  QuickDraw," Color Picture Format.  ISBN
     0-201-17719-6.

[3]  Adobe Systems, Incorporated.  [4mPostScript[24m [4mLanguage[24m  [4mReference[0m
     [4mManual.[24m  Reading, MA, 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 targets.
All other targets are optional.

+o   TARGETS - The owner should return a list of atoms that repre-
    sent the targets for which an attempt to convert the  current
    selection will succeed (barring unforseeable problems such as
    errors).  This list should include all the required atoms.

+o   MULTIPLE  -  The  MULTIPLE  target  atom is valid only when a
    property is specified on the request.  If the property  argu-
    ment in the event is and the target is MULTIPLE, it should be
    refused.

    When  a  selection  owner receives a 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
    property  is not valid here).  The effect should be as if the
    owner had received a sequence of events (one  for  each  atom
    pair) except that:

    -    The  owner  should  reply  with  a only when all the re-
         quested conversions have been performed.

    -    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
    The entries in a MULTIPLE property must be processed  in  the
    order  they appear in the property.  For further information,
    see section 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 independently, and
    they should succeed or fail independently.  The MULTIPLE tar-
    get  is  an  optimization that reduces the amount of protocol
    traffic between the owner and the  requestor;  it  is  not  a
    transaction  mechanism.   For  example,  a client may issue a
    MULTIPLE request with two targets:  a  data  target  and  the
    DELETE  target.   The  DELETE  target will still be processed
    even if the conversion of the data target fails.



                                [1m16[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   TIMESTAMP - To avoid some race conditions,  it  is  important
    that  requestors  be able to discover the timestamp the owner
    used to acquire ownership.  Until and unless the protocol  is
    changed  so  that a request returns the timestamp used to ac-
    quire ownership, selection owners must support conversion  to
    TIMESTAMP,  returning  the  timestamp they used to obtain the
    selection.

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 information,
that is, they will return a zero length property  of  type  NULL.
(Type  NULL  means  the  result  of on the string "NULL", not the
value zero.)  In all cases, the requested  side  effect  must  be
performed  before  the  conversion is accepted.  If the requested
side effect cannot be performed, the corresponding conversion re-
quest must be refused.

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

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 cor-
     responding  conversion request must be refused.  The need to
     delay responding to the 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."

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 deletion was successful.

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 selection 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_SELEC-
TION  request  (whatever  doing  so  means  for its internal data
structures).

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



                                [1m17[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


The  names  of the properties used in selection data transfer are
chosen by the requestor.  The use of property fields in  requests
(which  request the selection owner to choose a name) is not per-
mitted by these conventions.

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  ta-
ble  for  that target or a property of type INCR and then a prop-
erty of one of the listed types.

Certain selection properties may contain resource IDs.   The  se-
lection  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 contents of a pixmap) before  delet-
ing 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.

l c l.  _
[1mType Atom Format    Separator[0m
_
APPLE_PICT     8    T{    Self-sizing   T}   ATOM 32   Fixed-size
ATOM_PAIR 32   Fixed-size               BITMAP    32   Fixed-size
C_STRING  8    T{  Zero  T}  COLORMAP  32   T{ Fixed-size T} COM-
POUND_TEXT  8    Zero DRAWABLE  32   Fixed-size  INCR 32   Fixed-
size  INTEGER   32   Fixed-size  PIXEL     32   T{  Fixed-size T}
PIXMAP    32   Fixed-size                    SPAN 32   Fixed-size
STRING    8    Zero         UTF8_STRING    8    Zero         WIN-
DOW    32   Fixed-size
_

It is expected that this table will grow over time.

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 Consortium.



                                [1m18[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


The atom TEXT is a  polymorphic  target.   Requesting  conversion
into  TEXT  will convert into whatever encoding is convenient 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 selection conversion request.

If the requestor wants the owner to return the  contents  of  the
selection  in  a  specific encoding, it should request conversion
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 character
set plus the control characters TAB (hex  09)  and  NEWLINE  (hex
0A).   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 [4mCompound[24m [4mText[24m [4mEncoding[24m.

UTF8_STRING as a type or a  target  specifies  an  UTF-8  encoded
string, with NEWLINE (U+000A, hex 0A) as end-of-line marker.

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-terminated  sequence  of
bytes  with  no  other  restriction;  no element 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.  An example  of  the  need  for
C_STRING  is  to transmit the names of files; many operating sys-
tems do not interpret filenames as having a  character  set.  For
example,  the  same character string uses a different 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, UTF8_STRING, 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.

Requestors may receive a property of type INCR[9] in response  to
any target that results in selection data.  This  indicates  that
-----------
  [8] Note  that  this  is different from STRING, where many
byte values are forbidden, and  from  COMPOUND_TEXT,  where,
for  example,  inserting  the sequence 27, 40, 66 (designate
ASCII into GL) at the start does not alter the meaning.
  [9] These properties were called INCREMENTAL in an earlier
draft.   The protocol for using them has changed, and so the



                                [1m19[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


the  owner will send the actual data incrementally.  The contents
of the INCR property will be an integer, which represents a lower
bound on the number of bytes of data in the selection.   The  re-
questor  and  the selection owner transfer the data in the selec-
tion 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:

+o   Appends the data in suitable-size chunks to the same property
    on  the same window as the selection reply with a type corre-
    sponding to the actual type of the converted selection.   The
    size should be less than the maximum-request-size in the con-
    nection handshake.

+o   Waits between each append for a event that shows that the re-
    questor  has  read the data.  The reason for doing this is to
    limit the consumption of space in the server.

+o   Waits (after the entire data  has  been  transferred  to  the
    server)  until a event that shows that the data has been read
    by the requestor and then  writes  zero-length  data  to  the
    property.

The selection requestor:

+o   Waits for the event.

+o   Loops:

    -    Retrieving data using with the delete argument

    -    Waiting for a with the state argument

+o   Waits until the property named by the event is zero-length.

+o   Deletes the zero-length property.

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

Requestors may receive properties of type PIXMAP,  BITMAP,  DRAW-
ABLE, or WINDOW, which contain an appropriate ID.  While informa-
tion  about these drawables is available from the server by means
of the request, the following items are not:

+o   Foreground pixel


-----------
name has changed to avoid confusion.



                                [1m20[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   Background pixel

+o   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 following  targets  (using
the MULTIPLE mechanism):

+o   FOREGROUND returns a PIXEL value.

+o   BACKGROUND returns a PIXEL value.

+o   COLORMAP returns a colormap ID.

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.   If  they  are  the
same,  the  span is zero-length and is before the specified posi-
tion.  The  units  are  implied  by  the  target  atom,  such  as
LINE_NUMBER or CHARACTER_POSITION.

Certain  clients,  often  called managers, take on responsibility
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  re-
sources) 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 technique as  the
primary  means  by  which  clients  interact with the managed re-
source.  Note that the conventions for interacting with the  win-
dow  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 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 ownership of the selection.  Managers should ac-
quire the selection 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 support 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 responsibilities.  The  old
manager  must  release all resources it has managed and must then
destroy the window that owned the selection.  For example, a win-
dow manager losing ownership of WM_S2 must deselect from  on  the
root  window  of screen 2 before destroying the window that owned
WM_S2.



                                [1m21[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


When the new manager notices that the window owning the selection
has been destroyed, it knows that it can successfully proceed  to
control  the  resource it is planning to manage.  If the old man-
ager does not destroy the window within a  reasonable  time,  the
new manager should check with the user before destroying the win-
dow 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  destroying  the  window
that  owns  the selection.  It should not first disown the selec-
tion, since this introduces a race condition.

Clients who are interested in knowing when the owner of a manager
selection is no longer managing the corresponding shared resource
should select for on the window owning the selection so they  can
be  notified  when  the  window is destroyed.  Clients are warned
that after doing a and selecting for they should do  a  again  to
ensure  that the owner did not change after initially getting the
selection owner and before selecting for

Immediately after a manager successfully acquires ownership of  a
manager  selection,  it  should announce its arrival by sending a
event.  This event should be sent using the protocol request with
the following arguments:

l lw(4.5i) .  _
[1mArgument  Value[0m
_
destination:   T{ the root window of screen 0, or the root window
of the appropriate screen if the manager is  managing  a  screen-
specific  resource  T}  propagate:     False event-mask:    T{ T}
event:    T{   T}        type: MANAGER        format:    32    T{
    data[0]:[10]  T}   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 on the appropriate root window and should watch
for the appropriate MANAGER

The cut buffer mechanism is much simpler but much  less  powerful
than  the selection mechanism.  The selection mechanism is active
in that it provides  a  link  between  the  owner  and  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.
-----------
  [10] We use the notation data[n] to indicate the nth  ele-
ment  of  the LISTofINT8, LISTofINT16, or LISTofINT32 in the
data field of the according to the format field.   The  list
is indexed from zero.



                                [1m22[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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 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  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 request
in mode

A client that obtains data from the cut buffers should use a  re-
quest 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 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.

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  cov-
ered here from the client's point of view.

In  general,  these conventions are somewhat complex and will un-
doubtedly change as new window management  paradigms  are  devel-
oped.   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 par-
ticular 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 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 exam-
ple, 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.





                                [1m23[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


Each window manager will implement a particular window management
policy; the choice of an appropriate window management 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  adminis-
trator.  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 writing 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 recognizes "important"  win-
dows  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  ex-
ample, the debugger) to appear on top.

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:

+o   Hinting to the window manager about the resources they  would
    like to obtain

+o   Cooperating  with  the  window  manager  by accepting the re-
    sources they are allocated even if they  are  not  those  re-
    quested

+o   Being prepared for resource allocations to change at any time

A  client's  [4mtop-level[24m [4mwindow[24m is a window whose override-redirect
attribute is It must either be a child of a root  window,  or  it
must have been a child of a root window immediately prior to hav-
ing  been reparented by the window manager.  If the client repar-
ents 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 windows  as
children of one or more of the root windows by using some boiler-
plate 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, however, it
could use something like the following:

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




                                [1m24[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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-spe-
cific window managers to control the subwindows owned by the mem-
bers  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:

+o   Normal

+o   Iconic

+o   Withdrawn

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

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

The window manager will examine the contents of these  properties
when the window makes the transition from the Withdrawn 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 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  suitable  values in a single mode 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.  Clients writing  or  rewriting
window  manager properties 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 re-
sources exist for at least as long as the  window  on  which  the
property resides.

If  these properties are longer than expected, clients should ig-
nore the remainder of the property.  Extending  these  properties
is  reserved  to the X Consortium; private extensions to them are
forbidden.  Private additional communication between clients  and



                                [1m25[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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 represent-
ing 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 sec-
tion 4.4.

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

The encoding used for this string (and  all  other  uninterpreted
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 information 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 re-
sponse.  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.

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 re-
spects, including the type, it is similar to WM_NAME.  For  obvi-
ous  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 man-
ager to do so.

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





                                [1m26[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


lw(1i) lw(1i) lw(2i).  _
[1mField     Type Comments[0m
[1m_[0m
flags     CARD32    (see the next table) pad  4*CARD32  For back-
wards   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_as-
pect     (INT32,INT32)  base_width     INT32     If  missing, as-
sume  min_width   base_height    INT32     If   missing,   assume
min_height win_gravity    INT32     T{ If missing, assume T}
_

The WM_SIZE_HINTS.flags bit definitions are as follows:

lw(1i) nw(.5i) lw(3i).  _
[1mName Value     Field[0m
[1m_[0m
T{  T}   1    User-specified  x,  y  T{  T}   2    User-specified
width,  height   T{   T}   4    Program-specified   position   T{
T}   8    Program-specified  size  T{ T}   16   Program-specified
minimum  size  T{  T}   32   Program-specified  maximum  size  T{
T}   64   Program-specified  resize  increments T{ T}   128  Pro-
gram-specified min and max aspect  ratios  T{  T}   256  Program-
specified base size T{ T}   512  Program-specified window gravity
_

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 and 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  fur-
ther  interaction is superfluous.  To indicate that it was speci-
fied by the client  without  any  user  involvement,  the  client
should set and

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 (1), (2), (3), (4), (5), (6),
(7), (8), and (9).  It specifies how and whether the client  win-
dow  wants  to  be  shifted  to  make room for the window manager
frame.

If the win_gravity is 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  re-
quested  the  transition  from  Withdrawn state.  Other values of
win_gravity specify a window reference point.  For and the refer-
ence point is the specified outer corner of the  window  (on  the
outside  border edge).  For and the reference point is the center
of the specified outer edge of the window border.  For the refer-
ence point is the center of the window.  The reference  point  of



                                [1m27[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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 conjunction with width_inc
and height_inc define an arithmetic progression of preferred win-
dow widths and heights for non-negative integers [4mi[24m and [4mj[24m:


     width ~ = ~ base_width ~ + ~ ( i ~ times ~ width_inc )

    height ~ = ~ base_height ~ + ~ ( j ~ times ~ height_inc )

Window managers are encouraged to use [4mi[24m and [4mj[24m  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  nu-
merator first and the denominator second, and they allow a client
to  specify  the  range of aspect ratios it prefers.  Window man-
agers 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 as-
pect ratio falls in range.  If a base size is not provided, noth-
ing should be subtracted from the window size.  (The minimum size
is not to be used in place of the base size for this purpose.)

The  WM_HINTS property (whose type is WM_HINTS) is used to commu-
nicate to the window manager.  It  conveys  the  information  the
window  manager  needs  other  than the window geometry, which is
available from the window itself; the constraints on that  geome-
try,  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:

l l l.  _
[1mField     Type Comments[0m
[1m_[0m
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 im-
age  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    win-
dow_group   WINDOW    The ID of the group leader window
_

The WM_HINTS.flags bit definitions are as follows:




                                [1m28[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


lw(1.5i) nw(.5i) lw(1.5i).  _
[1mName Value     Field[0m
[1m_[0m
T{      T}   1    input     T{     T}   2    initial_state     T{
T}   4    icon_pixmap      T{      T}   8    icon_window       T{
T}   16   icon_x    &    icon_y    T{    T}   32   icon_mask   T{
T}   64   window_group T{ T}   128  (this  bit  is  obsolete)  T{
T}   256  urgency
_

Window  managers  are  free  to  assume convenient values for all
fields of the WM_HINTS property if a  window  is  mapped  without
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  Clients with the Passive and Locally Active
models should set the input flag to

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:

+o   Normal

+o   Iconic

+o   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 un-
mapped 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 following table:

l n l.  _
[1mState     Value     Comments[0m
[1m_[0m
T{  T}   1    The  window  is  visible.  T{ T}   3    The icon is
visible.
_

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

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

+o   1-bit  deep.  The window manager will select, through the de-
    faults database, suitable background (for  the  0  bits)  and



                                [1m29[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


    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 inter-
face in which small windows that behave like icons are completely
inappropriate.  Clients should not attempt to remedy the omission
by working around it.

Clients that need more capabilities from the icons than a  simple
2-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 manager 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 single client ma-
nipulating multiple children of the root window.

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 operate  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  proto-
col,[11]  rather  than  the  WM_PROTOCOLS  mechanism  of  section
4.1.2.7.


-----------
  [11] This obsolete protocol was described in the July  27,
1988,  draft of the ICCCM.  Windows using it can also be de-
tected because their WM_HINTS properties are 4 bytes  longer
than  expected.  Window managers are free to support clients
using the obsolete protocol  in  a  backwards  compatibility
mode.



                                [1m30[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


The  flag,  if  set in the flags field, indicates that the client
deems the window contents to be urgent, requiring the timely  re-
sponse  of the user.  The window manager 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 appropriate action when the state of the flag changes.
The flag is otherwise independent of the window's state; in  par-
ticular, the window manager is not required to deiconify the win-
dow  if  the  client  sets the flag on an Iconic window.  Clients
must provide some means by which the user can cause the  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 ur-
gent, or it can merely shut off the  alarm.   This  mechanism  is
useful for alarm dialog boxes or reminder windows, in cases where
mapping the window 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 win-
dow  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.

The WM_CLASS property (of type STRING without control characters)
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:

+o   A string that names the particular instance of  the  applica-
    tion  to which the client that owns this window belongs.  Re-
    sources that are specified by instance name override any  re-
    sources that are specified by class name.  Instance names can
    be specified by the user in an operating-system specific man-
    ner.   On POSIX-conformant systems, 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 instance name.

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



                                [1m31[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   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-sep-
arated.   This  inconsistency is necessary for backwards compati-
bility.

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 dif-
ferently in other ways.  In particular,  window  managers  should
present  newly  mapped WM_TRANSIENT_FOR windows without requiring
any user interaction, even if mapping 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  override-
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 tran-
sient is up).  If other windows must be prevented from processing
input (for example, when implementing pop-up  menus),  use  over-
ride-redirect and grab the pointer while the window is mapped.

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 partici-
pate.   Atoms  can  identify  both standard protocols and private
protocols specific to individual window managers.

All the protocols in which a client can volunteer  to  take  part
involve  the  window  manager  sending the client a event and the
client taking appropriate action.  For details of the contents of
the event, see section 4.2.8.  In each case, the protocol  trans-
actions 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 window manager
protocols.

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








                                [1m32[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


l c l.  _
[1mProtocol  Section   Purpose[0m
[1m_[0m
WM_TAKE_FOCUS  4.1.7     Assignment  of input focus WM_SAVE_YOUR-
SELF    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.

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  (im-
plicitly  or  explicitly)  on the watch list.  For the details of
this mechanism, see section 4.1.8.

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.

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  properties  that  the
window  manager  places  on client's top-level windows and on the
root.

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 for another purpose.
Clients  that  do so should remove the WM_STATE property if it is
still present.

Some clients (such as [1mxprop[22m) 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 win-
dow, clients should search the window hierarchy beneath  the  se-
lected  location  for  a window with the WM_STATE property.  This
search must be recursive in order to cover all window manager re-
parenting 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 follows:

l l l.  _
[1mField     Type Comments[0m
_
state     CARD32    (see the  next  table)  icon WINDOW    ID  of
icon window
_



                                [1m33[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


The following table lists the WM_STATE.state values:

l n.  _
[1mState     Value[0m
_
T{ T}   0 T{ T}   1 T{ T}   3
_

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

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  ex-
pressed  in the initial_state field of the WM_HINTS property (for
example, if the user has asked the window manager to iconify  the
window).   If it is the window manager believes the client should
be animating its window.  If it is the client should animate  its
icon window.  In either state, clients should be prepared to han-
dle exposure events from either window.

When  the  window  is  withdrawn,  the window manager will either
change the state field's value to or it will remove the  WM_STATE
property entirely.

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 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  win-
dow.

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  property  are
listed in the following table.

l l l.  _
[1mField     Type Comments[0m
[1m_[0m
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 [4mXlib[24m [4m-[24m [4mC[24m [4mLanguage[24m [4mX[24m [4mIn-[0m
[4mterface[24m.

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:



                                [1m34[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   - The client's top-level window is viewable.

+o   - 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  viewable,  its  icon_window  (if
    any)  will be viewable and, failing that, its icon_pixmap (if
    any) or its WM_ICON_NAME will be displayed.

+o   - Neither the client's top-level window nor its icon is visi-
    ble.

In fact, the window manager may implement states  with  semantics
other  than those described above.  For example, a window manager
might implement a concept of an "inactive" state in which an  in-
frequently  used client's window would be represented as a string
in a menu.  But this state is  invisible  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:

+o   Withdrawn  ->  Normal - The client should map the window with
    WM_HINTS.initial_state being

+o   Withdrawn -> Iconic - The client should map the  window  with
    WM_HINTS.initial_state being

+o   Normal  ->  Iconic  -  The  client should send a event as de-
    scribed later in this section.

+o   Normal -> Withdrawn - The client should unmap the window  and
    follow  it  with a synthetic event as described later in this
    section.

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

+o   Iconic -> Withdrawn - The client should unmap the window  and
    follow  it  with a synthetic event as described later in this
    section.

Only the client can effect a transition into or out of the  With-
drawn  state.   Once  a  client's  window  has left the Withdrawn
state, the window will be mapped if it is in the Normal state and
the window will be unmapped if it is in the Iconic state.  Repar-
enting 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  repar-
enting  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.  Clients can select
for on their  top-level  windows  to  track  transitions  between



                                [1m35[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


Normal  and  Iconic  states.   Receipt of a event will indicate a
transition to the Normal state, and receipt of an event will  in-
dicate 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 event
by using a request with the following arguments:

l lw(3.5i).  _
[1mArgument  Value[0m
[1m_[0m
destination:   The root propagate:     T{ T} event-mask:    T{ T}
T{ event: an with: T}   T{ T}      event:     The  root      win-
dow:    The window itself     from-configure: T{ T}
_

The  reason for requiring the client to send a synthetic event is
to ensure that the window manager gets some notification  of  the
client's  desire  to change state, even though the window may al-
ready be unmapped when the desire is expressed.  For  compatibil-
ity  with  obsolete  clients,  window managers should trigger the
transition to the Withdrawn state on the real rather than waiting
for the synthetic one.  They should also trigger  the  transition
if  they  receive a synthetic on a window for which they have not
yet received a real

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 window  (e.g.,  by
mapping  it  again or reparenting it elsewhere) after withdrawing
it must wait for the withdrawal to be complete 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]

If the transition is from the Normal to  the  Iconic  state,  the
client should send a event to the root with:

+o   Window == the window to be iconified

+o   Type[13] == the atom WM_CHANGE_STATE

+o   Format == 32

-----------
  [12] Earlier  versions  of  these  conventions  prohibited
clients from reading the WM_STATE property.  Clients operat-
ing under the earlier  conventions  used  the  technique  of
tracking  events  to wait for the top-level window to be re-
parented back to the root window.  This  is  still  a  valid
technique;  however,  it  works  only for reparenting window
managers, and the WM_STATE technique is to be preferred.
  [13] The  type field of the 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



                                [1m36[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   Data[0] == IconicState The format  of  this  event  does  not
    match  the  format of in section 4.2.8.  This is because they
    are sent by the window manager to clients, and  this  message
    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 request should be those
described for the synthetic event.  Clients can also  select  for
events  on  their  top-level or icon windows.  They will then re-
ceive a event when the window concerned  becomes  completely  ob-
scured  even  though mapped (and thus, perhaps a waste of time to
update) and a event when it becomes even partly viewable.  When a
window makes a transition from the Normal  state  to  either  the
Iconic  or  the Withdrawn state, clients should be aware that the
window manager may make transients for this window  inaccessible.
Clients  should  not rely on transient windows being available to
the user when the transient owner window is  not  in  the  Normal
state.   When  withdrawing a window, clients are advised to with-
draw transients for the window.

Clients can resize and reposition their top-level windows by  us-
ing  the  request.   The attributes of the window that can be al-
tered with this request are as follows:

+o   The [x,y] location of the window's upper left-outer corner

+o   The [width,height] of the inner region of the window (exclud-
    ing borders)

+o   The border width of the window

+o   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 oc-
curred).  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 de-
cides to respond to a request by:

+o   Not changing the size, location, border  width,  or  stacking
    order of the window at all.

    A  client  will  receive a synthetic event that describes the
    (unchanged) geometry of the window.   The  (x,y)  coordinates
    will  be in the root coordinate system, adjusted for the bor-
    der width the client requested, irrespective of any reparent-
    ing that has taken place.  The border_width will be the  bor-
    der  width the client requested.  The client will not receive



                                [1m37[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


    a real event because no change has actually taken place.

+o   Moving or restacking the window without resizing it or chang-
    ing its border width.

    A client will receive a synthetic 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  ad-
    justed  for  the border width the client requested.  The bor-
    der_width will be the border width the client requested.  The
    client may not receive  a  real  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.

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

    A client that has selected for events  will  receive  a  real
    event.   Note that the coordinates in this event are relative
    to the parent, 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 request can be used to convert the coordinates
    if required.

The general rule is that coordinates in real events  are  in  the
parent's  space; in synthetic events, they are in the root space.
Clients cannot distinguish between the  case  where  a  top-level
window is resized and moved from the case where the window is re-
sized  but not moved, since a real event will be received in both
cases.  Clients that are concerned with keeping track of the  ab-
solute  position  of  a  top-level  window should keep a piece of
state indicating whether they are certain of its position.   Upon
receipt  of  a  real  event  on  the top-level window, the client
should note that the position is unknown.  Upon receipt of a syn-
thetic event, the client should note the position as known, using
the position in this event.  If the client receives a or 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 re-
quest to find the position of a top-level window.

Clients should be aware that their borders may  not  be  visible.
Window  managers  are free to use reparenting techniques to deco-
rate client's top-level windows with borders  containing  titles,
controls,  and  other  details to maintain a consistent look-and-
feel.  If they do, they are likely to override the  client's  at-
tempts  to  set  the  border  width and set it to zero.  Clients,
therefore, should not depend on the top-level window's border be-
ing visible or use it to display any critical information.  Other
window managers will allow the top-level  windows  border  to  be
visible.   Clients  should  set  the desired value of the border-



                                [1m38[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


width attribute on all 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 request will cause an error.  Clients that
use a request to request a change in their position in the  stack
should do so using in the sibling field.

Clients  that  must  position themselves in the stack relative to
some window that was originally a sibling must do the 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 event by invoking a request with  the  following  argu-
ments:

l lw(3.5i).  _
[1mArgument  Value[0m
[1m_[0m
destination:   The root propagate:     T{ T} event-mask:    T{ T}
T{  event:  a  with:  T}   T{ T}     event:     The root     win-
dow:    The window itself T{     ...   T}   T{  Other  parameters
from the request T}
_

Window  managers  are in any case free to position windows in the
stack as they see fit, and so clients should not rely on  receiv-
ing  the  stacking order they have requested.  Clients should ig-
nore the above-sibling field of both real  and  synthetic  events
received  on  their  top-level windows because this field may not
contain useful information.

The attributes that may be supplied when a window is created  may
be  changed  by  using  the  request.   The window attributes are
listed in the following table:

l l l c.  _
[1mAttribute Private to Client[0m
[1m_[0m
Background   pixmap   Yes    Background    pixel    Yes    Border
pixmap  Yes  Border  pixel   Yes  Bit gravity    Yes Window grav-
ity 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  in-
terfered with by the window manager.  For the attributes that are
not private to the client:

+o   The  window manager is free to override the window gravity; a
    reparenting window manager may want to set the top-level win-
    dow's window gravity for its own purposes.




                                [1m39[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   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.

+o   Windows, in effect, have  per-client  event  masks,  and  so,
    clients  may  select for whatever events are convenient irre-
    spective of any events the window manager is  selecting  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 windows.

+o   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.

There are four models of input handling:

+o   No Input - The client never expects keyboard input.  An exam-
    ple would be or another output-only client.

+o   Passive Input - The client expects keyboard input  but  never
    explicitly  sets the input focus.  An example would be a sim-
    ple client with no subwindows, which  will  accept  input  in
    mode  or  when the window manager sets the input focus to its
    top-level window (in click-to-type mode).

+o   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 example 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  ac-
    quired  the focus in mode or when the window manager sets the
    input focus to its top-level window (in click-to-type mode).

+o   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 following table:








                                [1m40[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


l l l l c c.  _
[1mInput Model    Input Field    WM_TAKE_FOCUS[0m
[1m_[0m
T{ No Input T}   T{ T}   T{ Absent T} T{ Passive T}   T{  T}   T{
Absent  T}  T{ Locally Active T}   T{ T}   T{ Present T} T{ Glob-
ally Active T}   T{ T}   T{ Present T}
_

Passive and  Locally  Active  clients  set  the  input  field  of
WM_HINTS  to which indicates that they require window manager as-
sistance  in acquiring the input focus.  No  Input  and  Globally
Active  clients  set  the  input field to which requests that the
window manager not set the input focus to their top-level window.

Clients that use a request must set the time field to  the  time-
stamp  of  the  event that caused them to make the attempt.  This
cannot be a event because they do not have  timestamps.   Clients
may  also  acquire  the  focus  without a corresponding Note that
clients must not use in the time field.

Clients using the Globally Active model can only use a request to
acquire the input focus when they do not already have it  on  re-
ceipt of one of the following events:

+o

+o

+o   Passive-grabbed

+o   Passive-grabbed

In general, clients should avoid using passive-grabbed key events
for this purpose, except when they are unavoidable (as, for exam-
ple, a selection tool that establishes a passive 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  prop-
erty may receive a 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 in its data[1] field.   If  they  want
the  focus,  they  should  respond with a 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 window in an area



                                [1m41[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


that  indicates  to  the window manager that it should assign the
focus (for example, clicking in the headline 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 subwindows or can
decline  the  offer of the focus.  For example, a clock or a text
editor with no currently open frames might not want to take focus
even though the window manager generally  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 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:

+o   - 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.

+o   - Using this value with a click-to-type focus management pol-
    icy  leads to race conditions because the window becoming un-
    viewable may coincide with the  window  manager  deciding  to
    move the focus elsewhere.

+o   -  Using this value causes problems if the window manager re-
    parents the window, as most window managers  will,  and  then
    crashes.   The input focus will be and there will probably be
    no way to change it.

Note that neither nor is really safe to use.  Clients that invoke
a request should set the revert-to argument to

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.
Clients should not give up the input focus of their own volition.
They should ignore input that they receive instead.

The window manager is responsible for installing and uninstalling
colormaps  on  behalf  of clients with top-level windows that the
window manager manages.

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





                                [1m42[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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  at-
tribute.   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  to  inherit  their
parent's  colormap.   Window  managers  will ensure that the root
window's colormap field contains a colormap that is suitable  for
clients  to  inherit.   In  particular, the colormap will provide
distinguishable colors for and

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  colormaps  the  window
manager  should  attempt to have installed when, in the course of
its individual colormap focus policy, it assigns the colormap fo-
cus 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  prop-
erty and will track changes to the colormap attribute of the win-
dows 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  can  either  have  their  own  WM_COL-
ORMAP_WINDOWS  property  or  appear in the property of the window
they are transient for, as appropriate.   An  alternative  design
was  considered for how clients should hint to the window manager
about their colormap requirements.  This alternative design spec-
ified a list of colormaps instead of a list of windows.  The cur-
rent design, a list of  windows,  was  chosen  for  two  reasons.
First,  it allows window managers to find the visuals of the col-
ormaps, thus permitting  visual-dependent  colormap  installation
policies.  Second, it allows window managers to select for events
on  the  windows  concerned and to ensure that colormaps are only
installed if the windows that need them are visible.  The  alter-
native  design  allows  for  neither  of these policies.  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  Pro-
tocol  in  the  description of the request.  Briefly, the min-in-
stalled-maps most recently installed maps are  guaranteed  to  be
installed.   This  value  is  often one; clients needing multiple
colormaps should beware.





                                [1m43[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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 per-
forming colormap installation  must  notify  the  window  manager
prior  to  the  first installation.  When the client has finished
its colormap installation, it must also notify  the  window  man-
ager.   The  client  notifies the window manager by issuing a re-
quest with the following arguments:


tab(/) ; lB lB l lw(3.5i) _
Argument/Value
_ destination:/T{ the root window of the screen on which the col-
ormap is being installed T} propagate:/T{ T} event-mask:/T{ T} T{
event:  a  with:  T}    window:/the   root   window,   as   above
  type:/WM_COLORMAP_NOTIFY    format:/32    data[0]:/T{ the time-
stamp of the event that caused the client to start  or  stop  in-
stalling  colormaps  T}   data[1]:/T{ 1 if the client is starting
colormap installation, 0 if the client is finished with  colormap
installation  T}   data[2]:/reserved, must be zero   data[3]:/re-
served, 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 man-
agers  can  be  expected to implement this feature.  Before using
this feature, clients must check the compliance level of the win-
dow manager (using the mechanism described  in  section  4.3)  to
verify  that it supports this feature.  This is necessary to pre-
vent colormap installation conflicts between  clients  and  older
window managers.

Window  managers should refrain from installing colormaps while a
client has requested control of colormap installation.  The  win-
dow  manager  should  continue to track the set of installed col-
ormaps so that it can reinstate its colormap  focus  policy  when
the client has finished colormap installation.

This  technique  has  race conditions that may result in the col-
ormaps continuing to be installed even after a client has  issued
its  notification  message.   For example, the window manager may
have issued some requests that are not executed until  after  the
client's  and 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 "finished" message,  the  client
may reinstall the desired colormaps.  Clients are expected to use
this  mechanism  for things such as pop-up windows and for anima-
tions 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 im-
plement a feature that resets  colormap  installation  policy  in



                                [1m44[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


response to a command from the user.

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

+o   A string in WM_ICON_NAME.

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

+o   A 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 usually will clip or tile pixmaps
    that do not match WM_ICON_SIZE.

+o   A window into the icon_window field of the WM_HINTS property.

    The window manager is expected to map  that  window  whenever
    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 managers are
    free to resize icon windows.

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

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

+o   If  the window's WM_HINTS.icon_window is not set but the win-
    dow's WM_HINTS.icon_pixmap is set, the  pixmap  it  names  is
    visible.

+o   Otherwise, the window's WM_ICON_NAME string is visible.

Clients should observe the following conventions about their icon
windows:

1.   The icon window should be an child of the root.

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

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

4.   Clients should not map their icon windows.





                                [1m45[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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 win-
     dows or select for 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 win-
     dows.

10.  Clients must select for events on their icon window and  re-
     paint 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_NOR-
MAL_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.

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

1.   They can create and map  another  normal  top-level  window,
     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 manager 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 interfere with these  windows,
     which  should be used with caution.  An example of an appro-
     priate use is a pop-up menu.  The user will not be  able  to
     move,  resize, restack, or transfer the input focus to over-
     ride-redirect windows, since the window manager is not  man-
     aging them.  If it is necessary for a client to receive key-
     strokes  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 se-
     lected the Locally Active or Globally  Active  focus  model.
     The client may set the focus to the override-redirect window
     when  the  other  window receives a WM_TAKE_FOCUS message or
     one of the events listed in section 4.1.7 in the description



                                [1m46[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


     of the Globally Active focus model.

Window managers are free to decide  if  WM_TRANSIENT_FOR  windows
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_TRAN-
SIENT_FOR window; the window manager will  change  its  state  if
that is the policy it wishes to enforce.

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 indi-
vidual 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  decorations,  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 placeholder.

It is up to the window manager to determine the policy for treat-
ing  the  windows  in a group.  At present, there is no way for a
client to request a group, as opposed to  an  individual,  opera-
tion.

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

Clients must be aware that some  window  managers  will  reparent
their  top-level  windows  so that a window that was created as a
child of the root will be displayed as a child of some window be-
longing to the window manager.  The effects that this reparenting
will have on the client are as follows:

+o   The parent value returned by a request will no longer be  the
    value  supplied  to  the  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 reparented.  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.

+o   The server will interpret the (x,y) coordinates in a  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



                                [1m47[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


    space for these requests (see section 4.1.5).

+o   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 operation (see section 4.1.5).

+o   The  (x,y)  coordinates returned by a request are in the par-
    ent's coordinate space and are thus not directly useful after
    a reparent operation.

+o   A background of will have unpredictable results.

+o   A cursor of will have unpredictable results.

Clients that want to be notified when they are reparented can se-
lect for events on their top-level window.  They will  receive  a
event  if  and when reparenting takes place.  When a client with-
draws a top-level window, the window  manager  will  reparent  it
back  to  the root window if the window had been reparented else-
where.

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

Clients must be aware that some window managers will arrange  for
some  client  requests  to  be intercepted and redirected.  Redi-
rected 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 and The following
is incorrect because the request may be intercepted and the  out-
put made to an unmapped window:


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

The  client  must  wait  for  an event before drawing in the win-
dow.[14]
-----------
  [14] This is true even if the client set the backing-store
attribute to The backing-store attribute is a only  a  hint,
and  the  server may stop maintaining backing store contents
at any time.



                                [1m48[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


This next example incorrectly assumes that the request  is  actu-
ally executed with the arguments supplied:


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

The  client  should select for on its window and monitor the win-
dow's size by tracking events.

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


     MapWindow B
     SetInputFocus B

If the request has been intercepted, the window will still be un-
mapped,  causing the request to generate the error.  The solution
to this problem is for clients to select for on the window and to
delay the issuance of the request  until  they  have  received  a
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 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 event
indefinitely.  Clients must be prepared to handle these cases.

A  window with the override-redirect bit set is immune from redi-
rection, but the bit should be set on top-level windows  only  in
cases where other windows should be prevented from processing in-
put  while  the  override-redirect  window is mapped (see section
4.1.10) and while responding to 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  re-
sponsibility  for the state of the system.  It is their responsi-
bility to:

+o   Prevent any preexisting window manager from interfering  with
    their activities

+o   Restore the status quo exactly after they unmap the window 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.




                                [1m49[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


If  the  window manager moves a top-level window without changing
its size, the client will receive a synthetic event following the
move that describes the new location in terms of the root coordi-
nate space.  Clients must not respond to being moved by  attempt-
ing to move themselves to a better location.

Any  real  event  on a top-level window implies that the window's
position on the root may have changed, even though the event  re-
ports  that  the window's position in its parent is unchanged be-
cause the window may have been reparented.  Note that the coordi-
nates in the event will not, in this case, be directly useful.

The window manager will send these events by using a request with
the following arguments:

l l.  _
[1mArgument  Value[0m
[1m_[0m
destination:   The client's window  propagate:     T{  T}  event-
mask:    T{ T}
_

The  client can elect to receive notification of being resized by
selecting for events on its top-level windows.  It will receive a
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  them-
selves to a better size.  If the size is impossible to work with,
clients are free to request to change to the Iconic state.

A  top-level  window  that is not Withdrawn will be in the Normal
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 se-
lecting  for  events  on the top-level window.  It will receive a
event when it goes Iconic and a event when it goes Normal.

Clients that wish to be notified of  their  colormaps  being  in-
stalled  or  uninstalled  should  select for events on their top-
level windows and on any  windows  they  have  named  in  WM_COL-
ORMAP_WINDOWS  properties  on their top-level windows.  They will
receive events with the new field FALSE  when  the  colormap  for
that window is installed or uninstalled.

Clients  can  request notification that they have the input focus
by selecting for events on their top-level windows; they will re-
ceive and events.  Clients that need to set the  input  focus  to



                                [1m50[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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:

+o   Set the input field of WM_HINTS to and actually have the  in-
    put focus in one of their top-level windows

+o   Set  the input field of WM_HINTS to and have received a suit-
    able event as described in section 4.1.7

+o   Have received a WM_TAKE_FOCUS message as described in section
    4.1.7

Clients should not warp the pointer in an attempt to transfer 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 fo-
cus  to another of its windows by using the request, which is de-
fined as follows:


  [4mfocus[24m: WINDOW or or
  [4mrevert-to[24m:
  [4mtime[24m: TIMESTAMP or


1.   Clients that use a request must set the time argument to the
     timestamp of the event that caused them to make the attempt.
     This cannot be a event because they do not have  timestamps.
     Clients  may  also acquire the focus without a corresponding
     event.  Clients must not use for the time argument.

2.   Clients that use a request to set the focus to one of  their
     windows must set the revert-to field to

There  is  no  way  for  clients to prevent themselves being sent
events.

Top-level windows with a WM_PROTOCOLS property may be sent events
specific to the protocols named by the atoms in the property (see
section 4.1.2.7).  For all protocols, the events have the follow-
ing:

+o   WM_PROTOCOLS as the type field

+o   Format 32

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

+o   A timestamp in their data[1] field

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



                                [1m51[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


These  events  will be sent by using a request with the following
arguments:

l l.  _
[1mArgument  Value[0m
[1m_[0m
destination:   The client's window  propagate:     T{  T}  event-
mask:    () empty event:    As specified by the protocol
_

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
event as described above whose data[0] field is WM_DELETE_WINDOW.

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:

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

+o   Destroy any internal state associated with the window.

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

Clients  are permitted to interact with the user and ask, for ex-
ample, 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  re-
source  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_WIN-
DOW protocol again.  Window managers should not use 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.

Normal  clients  can use the redirection mechanism just as window
managers do by selecting for events on a parent window or  events
on  a window itself.  However, at most, one client per window can
select for these events, and a  convention  is  needed  to  avoid
clashes.   Clients  (including window managers) should select for
and events only on windows that they own.





                                [1m52[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


In particular, clients that need to take some special  action  if
they  are  resized  can select for events on their top-level win-
dows.  They will receive a 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 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  actu-
ally  happen  at this stage instead of being intercepted and exe-
cuted by the window manager (and thus  restarting  the  process),
the client needs temporarily to set override-redirect on the win-
dow.   Clients receiving events must respond by doing the follow-
ing:

+o   Setting override-redirect on  the  window  specified  in  the
    event

+o   Configuring  the  window  specified in the event to the width
    and height specified in the event as soon as possible and be-
    fore making any other geometry requests

+o   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  appro-
priate to deal with the client.

For  each screen they manage, window managers will acquire owner-
ship of a selection named WM_S[4mn[24m, where [4mn[24m 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 managers should support conversion of the fol-
lowing target on their manager selection:


l l lw(3.5i) .  _
[1mAtom Type Data Received[0m
_
VERSION   INTEGER   T{  Two integers, which are the major and mi-
nor release numbers (respectively) of the ICCCM  with  which  the
window manager complies.  For this version of the ICCCM, the num-
bers are 2 and 0.[15] T}
_


-----------
  [15] As a special case, clients not wishing to implement a
selection  request  may simply issue a request on the appro-
priate WM_S[4mn[24m selection.  If this selection is owned, clients
may assume that the window manager complies with ICCCM  ver-
sion 2.0 or later.



                                [1m53[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


The window manager properties are summarized in the following ta-
ble (see also section 14.1 of [4mXlib[24m [4m-[24m [4mC[24m [4mLanguage[24m [4mX[24m [4mInterface[24m).

l l n c.  _
[1mName Type Format    See Section[0m
[1m_[0m
WM_CLASS  STRING    8    4.1.2.5                    WM_CLIENT_MA-
CHINE   TEXT      4.1.2.9                WM_COLORMAP_WINDOWS WIN-
DOW    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_NOR-
MAL_HINTS     WM_SIZE_HINTS  32   4.1.2.3               WM_PROTO-
COLS   ATOM 32   4.1.2.7         WM_STATE  WM_STATE  32   4.1.3.1
WM_TRANSIENT_FOR    WINDOW    32   4.1.2.6
_

This  section contains some conventions for clients that partici-
pate in session management.  See [4mX[24m  [4mSession[24m  [4mManagement[24m  [4mProtocol[0m
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.

Each session participant will obtain a unique  client  identifier
(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:

+o   Be of type STRING

+o   Be of format 8

+o   Contain  the client-ID as a string of XPCS characters encoded
    using ISO 8859-1

All top-level, nontransient 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 containing 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 determined using the information in  the  WM_TRANSIENT_FOR
property.  The WM_CLIENT_LEADER property must:

+o   Be of type WINDOW

+o   Be of format 32

+o   Contain the window ID of the client leader window




                                [1m54[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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 identify 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:

+o   Be of type STRING

+o   Be of format 8

+o   Contain a string restricted to the XPCS  characters,  encoded
    in ISO 8859-1

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.  There-
fore, window managers should request a  second  checkpoint  phase
and save clients' state only during that phase.

The  Inter-Client  Exchange  protocol  (ICE)  defined as of X11R6
specifies a generic communication framework, independent of the X
server, for data exchange between arbitrary  clients.   ICE  also
defines  a  protocol for any two ICE clients who also have X con-
nections to the same X server to locate  (rendezvous  with)  each
other.

This protocol, called the "ICE X Rendezvous" protocol, is defined
in  the  ICE  specification,  Appendix  B,  and uses the property
ICE_PROTOCOLS plus events.  Refer to that specification for  com-
plete details.



                                [1m55[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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

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

+o   Locally active mode

+o   Globally active mode

1.   Locally  active clients should set the input focus to one of
     their windows only when it is already in one of  their  win-
     dows  or  when  they  receive a WM_TAKE_FOCUS message.  They
     should set the input field of the WM_HINTS structure to

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

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 request, not

In  general,  clients  should  not warp the pointer.  Window man-
agers, 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.

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 request set  to  one  of
     their windows.

A  client's attempt to establish a button or a key grab on a win-
dow will fail if some other client has already established a con-
flicting grab on the same  window.   The  grabs,  therefore,  are
shared resources, and their use requires conventions.

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.  Window man-
agers 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 example, a hypothetical WIN-
DOW KeySym).




                                [1m56[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


In  other  words,  window managers must provide some mechanism by
which a client can receive events from every key and button  (re-
gardless  of  modifiers) unless and until the X Consortium regis-
ters some KeySyms as being reserved for window  management  func-
tions.   Currently,  no KeySyms are registered for window manage-
ment functions.

Even so, clients are advised to allow the key and button combina-
tions 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 user to transmit events
from some keys.  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 win-
dow  and establish the grab on a proper ancestor.  In some cases,
a window manager may want to consume the event received,  placing
the  window  in  a state where a subsequent such event will go to
the client.  Examples are:

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

+o   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  re-
place,  the client's semantics for key+button combinations by al-
lowing the event to be used by the client after the  window  man-
ager  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  re-
quest 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  possible
user interface policies.  There is a trade-off here between free-
dom  for  window managers to implement their user interface poli-
cies and freedom for clients to implement theirs.  The dilemma is
resolved by:

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





                                [1m57[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   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

Section  4.1.8  prescribes conventions for clients to communicate
with the window manager about  their  colormap  needs.   If  your
clients are type applications, you should consult section 14.3 of
[4mXlib[24m  [4m-[24m  [4mC[24m  [4mLanguage[24m  [4mX[24m  [4mInterface[24m 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 follows:

l l l.  _
[1mField     Type Comments[0m
[1m_[0m
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   vi-
sual_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 sufficient
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 request with kill_id as
the argument.  If kill_id is one, the resources should  be  freed
by  issuing a 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 re-
source is  created  specifically  for  this  purpose  should  set
kill_id  to  one (and can create more than one such standard col-
ormap 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).   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 appropriate 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 col-
ormap sharing if they use the root visual.

The X server contains a table (which is read  by  requests)  that
describes  the  set of symbols appearing on the corresponding key
for each keycode generated by the server.  This  table  does  not



                                [1m58[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


affect  the  server's operations in any way; it is simply a data-
base used by clients that attempt to understand the keycodes they
receive.  Nevertheless, it is a shared resource and requires con-
ventions.

It is possible for clients to modify this table by  using  a  re-
quest.   In  general, clients should not do this.  In particular,
this is not the way in which clients should implement  key  bind-
ings or key remapping.  The conversion between a sequence of key-
codes  received  from the server and a string in a particular en-
coding is a private matter for each client (as it must  be  in  a
world where applications may be using different encodings to sup-
port different languages and fonts).  See the Xlib reference man-
ual for converting keyboard events to text.

The  only  valid  reason  for using a 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

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

User:     Confirms

Client:   Uses a request to add Pause to the keycode that already
          contains  Scroll  Lock and issues this request, "Please
          paint Pause on the Scroll Lock  key."   Clients  should
          not use requests.

If  a client succeeds in changing the keyboard mapping table, all
clients will receive events.  There is no mechanism to avoid  re-
ceiving these events.  Clients receiving events should update any
internal keycode translation tables they are using.

X  Version 11 supports 8 modifier bits of which 3 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 ta-
ble  accessed  by  and 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 correctly
to  control  these  modifiers.   The  Lock  modifier  should   be



                                [1m59[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


interpreted  as Caps Lock or Shift Lock according as the keycodes
in its controlling set  include  XK_Caps_Lock  or  XK_Shift_Lock.
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:

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

+o   If  there is no existing modifier controlled by  XK_Meta_L or
    XK_Meta_R, it should select an unused modifier 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 mod-
         ifier.

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

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

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

1.   Clients needing a modifier not currently in use  should  as-
     sign  keycodes  carrying suitable KeySyms to an unused modi-
     fier 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 request returns a status.

There is no good solution to the problem  of  reclaiming  assign-
ments  to  the  five  nonpreassigned  modifiers  when they are no
longer being used.  The user must use or some  other  utility  to
deassign obsolete modifier mappings by hand.

When  a client succeeds in performing a request, all clients will
receive events.  There  is  no  mechanism  for  preventing  these
events  from  being received.  A client that uses one of the non-
preassigned modifiers that receives one of these events should do
a request to discover the new mapping, and if the modifier it  is
using has been cleared, it should reinstall the modifier.

Note  that  a  request must be used to make the and pair in these
transactions atomic.





                                [1m60[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


                            delim @@
define oc % "\fR{\fP" %
define cc % "\fR}\fP" %

The X protocol provides explicit Red, Green, and Blue (RGB)  val-
ues, which are used to directly drive a monitor, and color names.
RGB  values  provide a mechanism for accessing the full capabili-
ties 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.  Un-
fortunately,  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 de-
vice capabilities (gamut compression) and to enable the user  in-
terface  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 system
should use a standard mechanism for naming the colors, be able to
provide names for existing colors, and provide means by which un-
reachable 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 perceiv-
able color is specified as a triplet of numbers.  Other appropri-
ate device-independent color models do exist, but  most  of  them
are directly traceable back to this original work.

X device color characterization provides device-independent color
spaces to X clients.  It does this by providing the barest possi-
ble 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  be-
tween CIE XYZ space and linear RGB device space (such as standard
CRTs).  Linear RGB devices require just two pieces of information
to completely characterize them:

+o    A  @3  times 3@ matrix @M@ and its inverse @M sup -1@, which
     convert between XYZ and RGB intensity (@RGB sub intensity@):





                                [1m61[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


                RGB sub intensity ~ = ~ M ~ times ~ XYZ

            XYZ ~ = ~ M sup -1 ~ times ~ RGB sub intensity

+o    A way of mapping between  RGB  intensity  and  RGB  protocol
     value.   XDCCC  supports three mechanisms which will be out-
     lined later.

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

Because  of  the limited dynamic range of both XYZ and RGB inten-
sity, these matrices will be encoded using a  fixed-point  repre-
sentation  of  a  32-bit two's complement number scaled by @2 sup
27@, giving a range of @-16@ to @16 - epsilon@, where @epsilon  ~
= ~ 2 sup -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 (format  =  32)  on  the
root  window  of  each  screen, using values appropriate for that
screen.

This will be encoded as shown in the following table:

center; c s s c c c l l  l.   XDCCC_LINEAR_RGB_MATRICES  property
contents
_
[1mField     Type Comments[0m
_
@M  sub  0,0@    INT32     Interpreted  as  a  fixed-point number
@-16~<=~x~<~16@   @M   sub   0,1@    INT32        ...    @M   sub
3,3@    INT32       @{M  sup  -1} sub 0,0@     INT32      @{M sup
-1}   sub   0,1@   INT32         ...     @{M    sup    -1}    sub
3,3@     INT32
_

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

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

In both cases, the relevant data will be stored in the XDCCC_LIN-
EAR_RGB_CORRECTION properties on the root window of each  screen,
using values appropriate for that screen, in whatever format pro-
vides adequate resolution.  Each property can consist of multiple
entries  concatenated  together,  if  different  visuals  for the
screen require different conversion data.  An entry with a  Visu-
alID  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



                                [1m62[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


converting, the client must linearly interpolate between adjacent
entries  in  the table to compute the desired value.  This allows
the server to perform gamma correction  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 be-
tween  0 and 1 (inclusive).  The precision of this value will de-
pend 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 prop-
erty by:

RGB sub value ~ = ~ { Property ~ Value ~ times ~ 65535 } over 255

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.  There-
fore, 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:

center;  c s s c c c l l l.  XDCCC_LINEAR_RGB_CORRECTION Property
Contents for Type 0 Correction
_
[1mField     Type Comments[0m
_
VisualID0 CARD Most  significant  portion   of   VisualID   Visu-
alID1 CARD Exists  if  and only if the property format is 8 Visu-
alID2 CARD Exists if and only if the property format is  8  Visu-
alID3 CARD T{  Least  significant  portion, exists if and only if
the property format is 8 or 16 T} type CARD 0 for  this  type  of
correction count     CARD Number of tables following (either 1 or
3)  length    CARD Number  of  pairs  - 1 following in this table
value     CARD X Protocol RGB value intensity CARD Interpret as a
number @0~<=~intensity~<=~1@ ...  ...  Total of [4mlength+1[24m pairs of
value/intensity values lengthg   CARD T{ Number of pairs - 1 fol-
lowing  in  this  table  (if  and  only  if  [4mcount[24m   is   3)   T}
value     CARD X Protocol RGB value intensity CARD Interpret as a
number  @0~<=~intensity~<=~1@  ...  ...  Total of [4mlengthg+1[24m pairs
of value/intensity values lengthb   CARD T{ Number of pairs  -  1
following  in  this  table  (if  and  only  if  [4mcount[24m  is  3)  T}
value     CARD X Protocol RGB value intensity CARD Interpret as a
number @0~<=~intensity~<=~1@ ...  ...  Total of  [4mlengthb+1[24m  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.



                                [1m63[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


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):

   RGB sub value ~ = ~ { Array ~ Index ~ times ~ 65535 } over
{ Array ~ Size ~ - ~ 1 }

When  converting, the client may linearly interpolate between en-
tries 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:

center;  c s s c c c l l l.  XDCCC_LINEAR_RGB_CORRECTION Property
Contents for Type 1 Correction
_
[1mField     Type Comments[0m
_
VisualID0 CARD Most  significant  portion   of   VisualID   Visu-
alID1 CARD Exists  if  and only if the property format is 8 Visu-
alID2 CARD Exists if and only if the property format is  8  Visu-
alID3 CARD T{  Least  significant  portion, exists if and only if
the property format is 8 or 16 T} 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~<=~intensity~<=~1@
...  ... Total  of  [4mlength+1[24m intensity elements lengthg   CARD T{
Number of elements - 1 following in this table (if  and  only  if
[4mcount[24m  is 3) T} intensity CARD Interpret as a number @0~<=~inten-
sity~<=~1@  ...  ...  Total  of  [4mlengthg+1[24m   intensity   elements
lengthb   CARD T{  Number of elements - 1 following in this table
(if and only if [4mcount[24m is 3) T} intensity CARD Interpret as a num-
ber @0~<=~intensity~<=~1@ ...  ...  Total of [4mlengthb+1[24m  intensity
elements
_

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 interoper-
ability conventions only for the X Version 11 protocol.   Clients
should be aware of other protocols that should be used for better
interoperation in the X environment.  The reader is referred to [4mX[0m
[4mSession[24m  [4mManagement[24m  [4mProtocol[24m  for information on session manage-
ment, and to [4mInter-Client[24m [4mExchange[24m [4mProtocol[24m  for  information  on
general-purpose communication among clients.

The X Consortium maintains a registry of certain X-related items,
to aid in avoiding conflicts and in sharing of such items.  Read-
ers  are  encouraged  to  use the registry.  The classes of items
kept in the registry that are relevant to the ICCCM include prop-
erty names, property types, selection names,  selection  targets,



                                [1m64[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


WM_PROTOCOLS protocols, types, and application classes.  Requests
to register items, or questions about registration, should be ad-
dressed to

                            delim off

          xregistry@x.org

or to

          Registry
          X Consortium
          201 Broadway
          Cambridge, MA 02139-1955
          USA

Electronic  mail will be acknowledged upon receipt.  Please allow
up to 4 weeks for a  formal  response  to  registration  and  in-
quiries.

The  registry is published as part of the X software distribution
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 postal address of where to
write to obtain the document.
































                                [1m65[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m




                           [1mAppendix A[0m


This appendix describes the revision history of this document and
summarizes the incompatibilities between this  and  earlier  ver-
sions.

The  February  25,  1988, draft that was distributed as part of X
Version 11, Release 2, was clearly labeled as such, and many  ar-
eas  were  explicitly labeled as liable to change.  Nevertheless,
in the revision work done 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.

The Consortium review was based on a draft dated July  27,  1988.
This draft included several areas in which incompatibilities with
the X11R2 draft were necessary:

+o   The use of property in 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.

+o   The protocol for INCREMENTAL  type  properties  as  selection
    replies  has  changed, and the name has been changed to INCR.
    Selection requestors are free to implement the earlier proto-
    col if they receive properties of type INCREMENTAL.

+o   The  protocol  for  INDIRECT  type  properties  as  selection
    replies  has changed, and the name has been changed to MULTI-
    PLE.  Selection requestors are free to implement the  earlier
    protocol if they receive properties of type INDIRECT.

+o   The  protocol  for  the special CLIPBOARD client has changed.
    The earlier protocol is subject to race conditions and should
    not be used.

+o   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 values sensibly.

+o   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.

+o   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.





                                [1m66[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   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.

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.

+o   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 man-
    agers can provide a backwards compatibility mode.

+o   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  prop-
    erty.  Clients that use the earlier mechanism can be detected
    by the WM_COLORMAPS property they set on their top-level win-
    dow, but providing a reliable backwards compatibility mode is
    not possible.

+o   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  nonwin-
    dow manager clients, there is no incompatibility.

+o   The  pseudoroot  facility  in  the earlier draft has been re-
    moved.  Although it has  been  successfully  implemented,  it
    turns out to be inadequate to support the uses envisaged.  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 mecha-
    nism was invisible to clients and no  incompatibility  should
    result.

+o   The addition of the WM_DELETE_WINDOW protocol (which prevents
    the  danger that multi-window clients may be terminated unex-
    pectedly) has meant some changes in the WM_SAVE_YOURSELF pro-
    tocol, to ensure  that  the  two  protocols  are  orthogonal.
    Clients  using  the  earlier  protocol  can  be detected (see
    WM_PROTOCOLS above) and supported in a backwards  compatibil-
    ity mode.

+o   The conventions in Section 14.3.1. of [4mXlib[24m [4m-[24m [4mC[24m [4mLanguage[24m [4mX[24m [4mIn-[0m
    [4mterface[24m  regarding properties of type RGB_COLOR_MAP have been
    changed, but clients that use the earlier conventions can  be
    detected because their properties are 4 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.



                                [1m67[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


The public review resulted in a set of mostly editorial  changes.
The  changes in version 1.0 that introduced some degree of incom-
patibility with the earlier drafts are:

+o   A new section (6.3) was added covering the  window  manager's
    use of Grabs.  The restrictions it imposes should affect only
    window managers.

+o   The  TARGETS  selection target has been clarified, and it may
    be necessary  for  clients  to  add  some  entries  to  their
    replies.

+o   A  selection  owner  using INCR transfer should no longer re-
    place targets in a MULTIPLE property with the atom INCR.

+o   The contents of the 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.

+o   The border-width in synthetic events is  now  specified,  but
    this should not cause any incompatibility.

+o   Clients are now asked to set a border-width on all requests.

+o   Window  manager  properties  on  icon windows now will be ig-
    nored, but there should be no incompatibility  because  there
    was no specification that they be obeyed previously.

+o   The  ordering  of real and synthetic events is now specified,
    but any incompatibility should affect only window managers.

+o   The semantics of WM_SAVE_YOURSELF have been clarified and re-
    stricted 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.

+o   A  kill_id  field has been added to RGB_COLOR_MAP properties.
    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.

Version  1.1 was released with X11R5 in September 1991.  In addi-
tion to some minor editorial changes, there were a  few  semantic
changes since Version 1.0:

+o   The section on Device Color Characterization was added.

+o   The meaning of the NULL property type was clarified.

+o   Appropriate references to Compound Text were added.

The  following changes have been made in preparing the public re-
view draft for Version 2.0.



                                [1m68[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   [P01] Addition of advice to clients on how to keep track of a
    top-level window's absolute position on the screen.

+o   [P03] A technique for clients to detect when it  is  safe  to
    reuse a top-level window has been added.

+o   [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.

+o   [P08] The LENGTH target has been deprecated.

+o   [P11] The manager selections facility was added.

+o   [P17] The definition  of  the  aspect  ratio  fields  of  the
    WM_NORMAL_HINTS property has been changed to include the base
    size.

+o   [P19]  has  been  added to the list of values allowed for the
    win_gravity field of the WM_HINTS property.  The  meaning  of
    the value has been clarified.

+o   [P20] A means for clients to query the ICCCM compliance level
    of the window manager has been added.

+o   [P22]  The  definition  of  the MULTIPLE selection target has
    been clarified.

+o   [P25] A definition of "top-level window" has been added.  The
    WM_STATE property has been defined and exposed to clients.

+o   [P26] The definition of window states has been clarified  and
    the wording regarding window state changes has been made more
    consistent.

+o   [P27]  Clarified the rules governing when window managers are
    required to send synthetic events.

+o   [P28] Added a recommended technique for setting the input fo-
    cus to a window as soon as it is mapped.

+o   [P29] The required lifetime of resource IDs named  in  window
    manager properties has been specified.

+o   [P30]  Advice  for dealing with keystrokes and override-redi-
    rect windows has been added.

+o   [P31] A statement on the ownership of  resources  transferred
    through the selection mechanism has been added.

+o   [P32]  The  definition  of  the CLIENT_WINDOW target has been
    clarified.





                                [1m69[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   [P33] A rule about requiring the selection owner to reacquire
    the selection under certain circumstances has been added.

+o   [P42] Added several new selection targets.

+o   [P44] Ambiguous wording regarding the withdrawal of top-level
    windows has been removed.

+o   [P45] A facility for requestors to pass parameters  during  a
    selection request has been added.

+o   [P49] A convention on discrimated names has been added.

+o   [P57] The C_STRING property type was added.

+o   [P62]  An  ordering  requirement  on processing selection re-
    quests was added.

+o   [P63] The flag was added.

+o   [P64] The session management  section  has  been  updated  to
    align with the new session management protocol.  The old ses-
    sion management conventions have been moved to Appendix C.

+o   References  to  the never-forthcoming [4mWindow[24m [4mand[24m [4mSession[24m [4mMan-[0m
    [4mager[24m [4mConventions[24m [4mManual[24m have been removed.

+o   Information on the X Registry and references to  the  session
    management and ICE documents have been added.

+o   Numerous  editorial  and typographical improvements have been
    made.

The following changes have been made in preparation for releasing
the final edition of Version 2.0 with X11R6.

+o   The PIXMAP selection target has  been  revised  to  return  a
    property of type PIXMAP instead of type DRAWABLE.

+o   The  session  management section has been revised slightly to
    correspond with the changes to the [4mX[24m [4mSession[24m [4mManagement[24m  [4mPro-[0m
    [4mtocol[24m.

+o   Window  managers are now prohibited from placing in the time-
    stamp field of WM_TAKE_FOCUS messages.

+o   In the WM_HINTS property, the flag has been  renamed  to  Its
    semantics have also been defined more thoroughly.

+o   Additional  editorial  and  typographical  changes  have been
    made.






                                [1m70[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m




                             [1mAppendix B[0m


During the development of these conventions, a number  of  inade-
quacies  have been discovered in the core X11 protocol.  They are
summarized here as input to an eventual protocol revision  design
process:

+o   There  is  no way for anyone to find out the last-change time
    of a selection.  The request should be changed to return  the
    last-change time as well as the owner.

+o   There  is  no  way  for  a client to find out which selection
    atoms are valid.

+o   There would be no need for WM_TAKE_FOCUS if  the  event  con-
    tained  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.

+o   There is a race condition in the request.  It does not take a
    timestamp and may be executed after  the  top-level  colormap
    has been uninstalled.  The next protocol revision should pro-
    vide  the  timestamp  in  the requests and in the 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  instal-
    lation to the window manager.

+o   The protocol needs to be changed to provide some way of iden-
    tifying the Visual and the Screen of a colormap.

+o   There  should  be some way to reclaim assignments to the five
    nonpreassigned modifiers when they are no longer needed.  The
    manual method is unpleasantly low-tech.



















                                [1m71[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m




                             [1mAppendix C[0m


This appendix contains obsolete conventions for  session  manage-
ment  using X properties and messages.  The conventions described
here are deprecated and are described only for historical  inter-
est.   For  further information on session management, see [4mX[24m [4mSes-[0m
[4msion[24m [4mManagement[24m [4mProtocol.[0m

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.

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 de-
pend 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:

+o   Be of type STRING

+o   Contain a list of null-terminated strings

+o   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-sepa-
rated.  This inconsistency is necessary for backwards compatibil-
ity.

A client with multiple top-level windows should ensure  that  ex-
actly  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.

This property is described in section 4.1.2.9.




                                [1m72[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


Because they communicate by means of unreliable  network  connec-
tions,  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.

Clients may need to respond to session  manager  actions  in  two
ways:

+o   Saving their internal state

+o   Deleting a window

Clients  that  want  to  be warned when the session manager feels
that they should save their internal  state  (for  example,  when
termination  impends) should include the atom WM_SAVE_YOURSELF in
the WM_PROTOCOLS property on their top-level windows to  partici-
pate in the WM_SAVE_YOURSELF protocol.  They will receive a 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 themselves  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 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
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 session 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 updat-
ing WM_COMMAND, the client should not change its  state  (in  the
sense  of  doing  anything that would require a change to WM_COM-
MAND) 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 dan-
ger 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:



                                [1m73[0m





[1mInter-Client Communication Conventions           X11, Release 6.4[0m


+o   Only  one  of  their  top-level  windows has a nonzero-length
    WM_COMMAND property.

+o   They respond to a WM_SAVE_YOURSELF message by:

    -    First, updating the nonzero-length WM_COMMAND  property,
         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 com-
mand to save the entire client state.[16]

Windows are deleted using the WM_DELETE_WINDOW protocol, which is
described in section 4.2.8.1.

The session manager properties are listed in the following table:

l l n c.  _
[1mName Type Format    See Section[0m
[1m_[0m
WM_CLIENT_MACHINE   TEXT      4.1.2.9                     WM_COM-
MAND     TEXT      C.1.1 WM_STATE  WM_STATE  32   4.1.3.1
_



















-----------
  [16] This convention has changed since earlier drafts  be-
cause  of  the introduction of the protocol in the next sec-
tion.  In the public review draft, there was ambiguity as to
whether WM_SAVE_YOURSELF was a checkpoint or a shutdown  fa-
cility.  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.



                                [1m74[0m


