














          [1mInter-Client Communication Conventions Manual[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}
_

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 WINDOW    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 (octal 11) and NEWLINE (octal
12).   The  spacing  interpretation  of TAB is context dependent.
Other ASCII control characters are  explicitly  not  included  in
STRING at the present time.

COMPOUND_TEXT  as  a type or a target specifies the Compound Text
interchange format; see the [4mCompound[24m [4mText[24m [4mEncoding[24m.

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, and C_STRING properties will consist
of a list of elements separated by null characters; other  encod-
ings 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
the owner will send the actual data incrementally.  The  contents
of the INCR property will be an integer, which represents a lower
-----------
  [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
name has changed to avoid confusion.



                                [1m19[0m





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


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

+o   Background pixel

+o   Colormap ID





                                [1m20[0m





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


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.

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



                                [1m21[0m





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


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

The cut buffers consist of eight properties on the root of screen
zero, named by the predefined atoms CUT_BUFFER0  to  CUT_BUFFER7.
-----------
  [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


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.

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



                                [1m23[0m





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


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

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,



                                [1m24[0m





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


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



                                [1m25[0m





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


representing private protocols (see section 4.1.2.7).

The  next  sections  describe  each of the properties the clients
need to set, in turn.  They are summarized in the table  in  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


