














       [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
obtaining a copy of this software and associated  documenta-
tion files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons  to  whom
the Software is furnished to do so, subject to the following
conditions:

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

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

Except  as  contained in this notice, the name of the X Con-
sortium shall not be used in  advertising  or  otherwise  to
promote  the  sale,  use  or other dealings in this Software
without prior written authorization from the X Consortium.



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

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



                             ii

































































                             vi










                   [1mPreface to Version 2.0[0m



The  goal of the ICCCM Version 2.0 effort was to add new fa-
cilities, to fix problems with earlier drafts,  and  to  im-
prove  readability  and understandability, while maintaining
compatibility with the earlier versions.  This  document  is
the  product  of over two years of discussion among the mem-
bers of the X Consortium's [1mwmtalk [22mworking group.   The  fol-
lowing 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       Hub-
bard                Mike       Wexler       Kerry       Kim-
brough               Glenn           Widener          Audrey
Ishizaki

For the Device Color Characterization section: Keith Packard

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

Gary      Combs                    John      Irwin     Errol
Crary                   Vania         Joloboff         Nancy
Cyprych                 John      Laporta      John     Dia-
mant                  Ken             Lee              Clive
Feather                 Stuart          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
mechanism, not policy.  As a result, a client that converses
with  the  server using the protocol defined by the [4mX[24m [4mWindow[0m
[4mSystem[24m [4mProtocol[24m, [4mVersion[24m [4m11[24m may operate correctly in  isola-
tion  but  may  not coexist properly with others sharing the
same server.

Being a good citizen in the X Version 11 world involves  ad-
hering  to  conventions  that govern inter-client communica-
tions 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 attempt-
ing  to  enforce  any  particular user interface.  To permit
clients written in different languages to communicate, these
conventions are expressed solely in terms of protocol opera-
tions, not in terms of  their  associated  Xlib  interfaces,
which  are probably more familiar.  The binding of these op-
erations to the Xlib interface for C and to  the  equivalent
interfaces for other languages is the subject of other docu-
ments.

In the interests of timely acceptance, the [4mInter-Client[24m [4mCom-[0m
[4mmunication[24m  [4mConventions[24m [4mManual[24m (ICCCM) covers only a minimal
set of required  conventions.   These  conventions  will  be
added  to  and  updated as appropriate, based on the experi-
ences of the X Consortium.

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

In the course of developing these conventions, a  number  of
minor  changes to the protocol were identified as desirable.
They also are identified in the text, are summarized in  Ap-
pendix  B, and are offered as input to a future protocol re-
vision process.  If and when a protocol revision incorporat-
ing  these changes is undertaken, it is anticipated that the
ICCCM will need to be revised.  Because it is  difficult  to



                              [1m1[0m





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


ensure that clients and servers are upgraded simultaneously,
clients using the revised conventions should examine the mi-
nor  protocol  revision  number  and  be prepared to use the
older conventions when communicating with an older server.

It is expected that these revisions will ensure that clients
using the conventions appropriate to protocol minor revision
[4mn[24m will interoperate correctly with those that use  the  con-
ventions appropriate 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 with-
out  an encoding being specified.  The elements are not nec-
essarily ASCII characters, and no case folding happens.1

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

To allow a fixed-size representation, a protocol request was
provided  to register a byte sequence with the server, which
returns a 32-bit value (with the top three bits  zero)  that
maps  to  the  byte  sequence.  The inverse operator is also
available

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

     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  re-
sults of the requests, which require a handshake, can be as-
sumed [4ma[24m [4mpriori[24m.
-----------
  1 The comment in the protocol specification  for
that ISO Latin-1 encoding should be used is in the
nature of a  convention;  the  server  treats  the
string as a byte sequence.



                              [1m2[0m





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


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

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

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

The core protocol imposes no semantics on  atoms  except  as
they  are used in FONTPROP structures.  For further informa-
tion on FONTPROP semantics, see the [4mX[24m [4mLogical[24m [4mFont[24m  [4mDescrip-[0m
[4mtion[24m [4mConventions[24m.

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

l l lw(3.6i).  _
[1mSpace     Briefly   Examples[0m
[1m_[0m
Property  name  Name WM_HINTS,  WM_NAME,  RGB_BEST_MAP,  ...
Property  type     Type WM_HINTS, CURSOR, RGB_COLOR_MAP, ...
Selection name  Selection PRIMARY, SECONDARY, CLIPBOARD  Se-
lection target  Target    FILE_NAME, POSTSCRIPT, PIXMAP, ...
Font property         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
objects that need unique names (usually because the  objects
are created dynamically, so that names cannot be invented in
advance). 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:





                              [1m3[0m





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


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


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

If  [4mname[24m is a descriptive portion for the name, [4md[24m is a deci-
mal number with no leading zeroes, and [4mx[24m  is  a  hexadecimal
number  with  exactly 8 digits, and using uppercase letters,
then such discriminated 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 cre-
ated by that client.  This resource can be of any type.

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

     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 relevant namespace or has the active cooperation of
all other entities 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  win-
dow is almost certainly not.)

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

         FOO_R12345678_U23

Existing  protocols  will not be changed to use these naming



                              [1m4[0m





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


conventions, because doing so will cause  too  much  disrup-
tion.  However, it is expected that future protocols -- both
standard and private -- will use these conventions.

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

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

+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 win-
    dow

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

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

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



                              [1m5[0m





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


A client wishing to acquire ownership of a particular selec-
tion 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 and the current server  time.   This
time  value  usually  will be obtained from the timestamp of
the event that triggers the acquisition  of  the  selection.
Clients  should not set the time value to 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  selec-
tion.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 ap-
pend  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  ap-
pears  to  the client to succeed, but ownership is not actu-
ally 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  describing  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
selection ownership.  To  make  this  feedback  reliable,  a
client must perform a sequence like the following:
-----------
  2 At  present,  no part of the protocol requires
requestors to send events to the owner of a selec-
tion.   This restriction is imposed to prepare for
possible future extensions.



                              [1m6[0m





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


SetSelectionOwner(selection=PRIMARY,           owner=Window,
time=timestamp) 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
specified time.

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


  [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 re-
quest with an empty event mask).

More advanced selection owners are free to maintain  a  his-
tory  of  the  value  of the selection and to respond to re-
quests 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  specified target atom as the property name to be
used for the reply.

Otherwise, the owner should use the  target  to  decide  the
form  into  which  the  selection should be converted.  Some
targets may be defined such that requestors can pass parame-
ters  along with the request.  The owner will find these pa-
rameters in the property named  in  the  selection  request.
The  type,  format, and contents of this property are depen-
dent upon the definition of the target.  If  the  target  is
not  defined to have parameters, the owner should ignore the
property if it is present.  If the selection cannot be  con-
verted  into  a form based on the target (and parameters, if
any), the owner should refuse the as previously described.

If the specified property is not the owner should place  the
data resulting from converting the selection into the speci-
fied property on the requestor window  and  should  set  the
property's type to some appropriate value, which need not be



                              [1m7[0m





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


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 ac-
knowledge the successful conversion by sending the requestor
window a event (by means of a request with an  empty  mask).
is defined as follows:


  [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 conversion 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 re-
quests that use the same requestor window,  selection,  tar-
get,  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 requestor  to  determine
which conversion request had failed, unless the requests are
responded to in order.

The data stored in the property must eventually be  deleted.
A  convention is needed to assign the responsibility for do-
ing so.  Selection requestors are responsible  for  deleting
properties  whose  names they receive in events (see section
2.4) or in properties with type MULTIPLE.

A selection owner will often need confirmation that the data
comprising  the  selection  has  actually  been transferred.
(For example, if the  operation  has  side  effects  on  the
owner's  internal  data  structures,  these  should not take
place until the requestor has indicated that it has success-
fully received the data.)  Owners should express interest in
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



                              [1m8[0m





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


request,  if the different conversions require separate con-
firmation, the selection owner can also watch for the  dele-
tion  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 pre-
vious owner 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 to-
tally 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  modified,  but can still reasonably be
viewed as the same selected object,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 ac-
tions.

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 re-
vert 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  previous owner will receive a event. For the
definition of a event, see section 2.2.
-----------
  3 The division between these two cases is a mat-
ter of judgment on the part of the software devel-
oper.



                              [1m9[0m





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


The timestamp is the time the selection changed hands.   The
specified owner is the window that was specified by the cur-
rent owner in its request.

A client that wishes to obtain the value of a selection in a
particular  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
involved,  and  the  target  argument specifies the required
form of the information.  For information about  the  choice
of  suitable  atoms  to use, see section 2.6.  The requestor
should set the requestor argument to a window that  it  cre-
ated;  the  owner  will place the reply property there.  The
requestor should set the time argument to the  timestamp  on
the  event  that  triggered  the  request  for the selection
value.  Note that clients should not specify Clients  should
not  use  for the time argument of a request.  Instead, they
should use the timestamp of the event that  caused  the  re-
quest to be made.

The  requestor  should set the property argument to the name
of a property that the owner can use to report the value  of
the  selection.   Requestors  should  ensure  that the named
property does not exist on the window before issuing the re-
quest.4 The exception to this rule is when the requestor in-
tends 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
parameters along with the request.  If the requestor  wishes
-----------
  4 This requirement is new in version  2.0,  and,
in  general,  existing  clients  do not conform to
this requirement.  To prevent these  clients  from
breaking,  no  existing targets should be extended
to  take  parameters  until  sufficient  time  has
passed  for  clients to be updated.  Note that the
MULTIPLE target was defined to take parameters  in
version  1.0  and  its definition is not changing.
There is thus no conformance problem  with  MULTI-
PLE.



                             [1m10[0m





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


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 target, 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.   How-
ever,  it  is  difficult  for  the owner to make this choice
safely.

1.   Requestors should not use for the property argument  of
     a request.

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

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

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 selec-
tion, that the owner does not support the conversion implied
by  the  target,  or that the server did not have sufficient
space to accommodate the data.

If the property argument is not then that property will  ex-
ist on the requestor window.  The value of the selection can
be retrieved 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




                             [1m11[0m





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


When  using  to retrieve the value of a selection, the prop-
erty argument should be set to the  corresponding  value  in
the  event.  Because the requestor has no way of knowing be-
forehand 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  success-
fully  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  ex-
    pensive.

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

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

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

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

4.   When  storing  large amounts of data (relative to maxi-
     mum-request-size), clients should use a sequence of re-
     quests  for reasonable quantities of data.  This avoids
     locking servers up and limits  the  waste  of  data  an



                             [1m12[0m





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


     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 sec-
     tion 2.2).

6.   To avoid locking servers up for inordinate  lengths  of
     time,  requestors  retrieving  large quantities of data
     from a property should perform a  series  of  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,  re-
ducing  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  communica-
tion among related groups of clients.

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

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 selec-
    tions")

+o   As a means of obtaining data when there is a primary se-
    lection 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.




                             [1m13[0m





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


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

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

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

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

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

+o   It  should  assert  ownership of the CLIPBOARD selection
    and reassert 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  se-
         lection by using the same timestamp.

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

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




                             [1m14[0m





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


+o   Stability  - If the cutting client were to crash or ter-
    minate, 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 re-
    tain 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
    required (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  re-
quest  determines 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 contains 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    BIT-
MAP    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  WIN-
DOW    T{  Any top-level window owned by the selection owner
T} COLORMAP  COLORMAP  A list of  colormap  IDs  COLUMN_NUM-
BER  SPAN T{  The  start  and  end  column  numbers  T} COM-
POUND_TEXT  COMPOUND_TEXT  Compound Text DELETE    NULL (see
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 H5 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_SELEC-
TION    NULL (see  section  2.6.3.2)  LENGTH    INTEGER   T{
The  number  of  bytes  in  the  selection6   T}   LINE_NUM-
BER    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 selected



                             [1m15[0m





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


lw(1.8i) lw(1i) lw(3i) .  _
[1mAtom Type      Data Received[0m
_
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
operating system of the owner client T} PIXMAP    T{ PIXMAP7
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[0m
     [4mReference[24m  [4mManual.[24m   Reading,  MA, Addison-Wesley, ISBN
     0-201-62628-4.

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

[3]  Adobe Systems, Incorporated.  [4mPostScript[24m [4mLanguage[24m  [4mRef-[0m
     [4merence[24m   [4mManual.[24m   Reading,  MA,  Addison-Wesley,  ISBN
     0-201-18127-4.
-----------
  5 Earlier versions of this document  erroneously
specified that conversion of the PIXMAP target re-
turns a  property  of  type  DRAWABLE  instead  of
PIXMAP.   Implementors should be aware of this and
may want to support the DRAWABLE type as  well  to
allow for compatibility with older clients.
  6 The targets ENCAPSULATED_POSTSCRIPT and ENCAP-
SULATED_POSTSCRIPT_INTERCHANGE are  equivalent  to
the  targets  _ADOBE_EPS  and _ADOBE_EPSI (respec-
tively) that appear in the selection targets  reg-
istry.   The  _ADOBE_  targets are deprecated, but
clients are encouraged to continue to support them
for backward compatibility.
  7 This definition is ambiguous, as the selection
may be converted into any of several targets  that
may  return  differing  amounts  of data.  The re-
questor 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.



                             [1m16[0m





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


It is expected that this table will grow over time.

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

+o   TARGETS  -  The owner should return a list of atoms that
    represent the targets for which an  attempt  to  convert
    the current selection will succeed (barring unforseeable
    problems such as 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
    argument  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  sec-
    ond  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 in-
    formation, 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 indepen-
    dently, and they should succeed or  fail  independently.
    The  MULTIPLE target is an optimization that reduces the
    amount of protocol traffic between the owner and the re-
    questor;  it  is not a transaction mechanism.  For exam-
    ple, a client may issue a MULTIPLE request with two tar-
    gets:  a  data target and the DELETE target.  The DELETE
    target will still be processed even if the conversion of
    the data target fails.

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



                             [1m17[0m





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


    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  infor-
mation,  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  ac-
cepted.   If  the requested side effect cannot be performed,
the corresponding conversion request 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
     corresponding conversion request must be refused.   The
     need to delay responding to the request until a further
     conversion has succeeded poses problems for the Intrin-
     sics 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 dele-
tion 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 selec-
tion mechanism to convert the named selection into the named
target and should insert it at the location of the selection
for which it got the INSERT_SELECTION request (whatever  do-
ing 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 request at the location of the selection for which it
got the INSERT_SELECTION request (whatever  doing  so  means
for its internal data structures).

The  names of the properties used in selection data transfer
are chosen by the requestor.  The use of property fields  in



                             [1m18[0m





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


requests  (which  request  the  selection  owner to choose a
name) is not permitted by these conventions.

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

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

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

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

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}
COMPOUND_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        WIN-
DOW    32   Fixed-size
_


It is expected that this table will grow over time.

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



                             [1m19[0m





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


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

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

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

STRING as a type or a target specifies the ISO Latin-1 char-
acter  set  plus  the  control characters TAB (octal 11) and
NEWLINE (octal 12).  The spacing interpretation  of  TAB  is
context  dependent.   Other ASCII control characters are ex-
plicitly 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-termi-
nated sequence of bytes with no other restriction;  no  ele-
ment  of  the  selection  mechanism may assume that any byte
value is forbidden or that any two differing  sequences  are
equivalent.8  For these objects, the type C_STRING should be
used.  An example of the need for C_STRING  is  to  transmit
the  names of files; many operating systems do not interpret
filenames as having a character set. For example,  the  same
character string uses a different sequence of bytes in ASCII
and EBCDIC, and so most operating systems see these as  dif-
ferent filenames and offer no way to treat them as the same.
Thus no character-set based property type is suitable.

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

Requestors  may receive a property of type INCR9 in response

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



                             [1m20[0m





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


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

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

The selection owner then:

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

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

+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
partial property.  The  remaining  partial  properties  must
have the same type.


-----------
  9 These properties were called INCREMENTAL in an
earlier  draft.   The  protocol for using them has
changed, and so the name has changed to avoid con-
fusion.



                             [1m21[0m





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


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

+o   Foreground pixel

+o   Background pixel

+o   Colormap ID

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

+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 position.  The units are implied by the target
atom, such as LINE_NUMBER or CHARACTER_POSITION.

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

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

Before  a manager takes ownership of a manager selection, it
should use the request to check whether the selection is al-
ready  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 selec-
tion.  Managers should acquire the selection using a  window
created  expressly  for this purpose.  Managers must conform
to the rules for selection owners described in sections  2.1



                             [1m22[0m





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


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 responsibili-
ties.  The old manager must release  all  resources  it  has
managed  and must then destroy the window that owned the se-
lection.  For example, a window manager losing ownership  of
WM_S2  must deselect from on the root window of screen 2 be-
fore destroying the window that owned WM_S2.

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

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

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  de-
stroyed.   Clients are warned that after doing a and select-
ing 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 proto-
col 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      for-
mat:    32       T{           data[0]:10      T}   timestamp
    data[1]:   manager  selection  atom       data[2]:   the
window  owning  the  selection     data[3]:   manager-selec-
tion-specific data     data[4]:   manager-selection-specific
data
_




                             [1m23[0m





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


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  pow-
erful 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 re-
trieves the data at some later time.

The  cut  buffers consist of eight properties on the root of
screen zero, named by the predefined  atoms  CUT_BUFFER0  to
CUT_BUFFER7.   These  properties must, at present, have type
STRING and format 8.  A client  that  uses  the  cut  buffer
mechanism  must  initially  ensure that all eight properties
exist by using 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 re-
quests to  rename  each  buffer;  that  is,  CUT_BUFFER0  to
CUT_BUFFER1,  CUT_BUFFER1  to CUT_BUFFER2, ..., and CUT_BUF-
FER7 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
request to retrieve the contents of CUT_BUFFER0.

In response to a specific user request, a client may  rotate
the  cut buffers by minus 1 by using 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 ro-
tated 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  covered  here  from  the client's point of
view.

In general, these conventions are somewhat complex and  will
undoubtedly  change  as  new window management paradigms are
developed.  Thus, there is a  strong  bias  toward  defining
-----------
  10 We  use  the notation data[n] to indicate the
nth element of  the  LISTofINT8,  LISTofINT16,  or
LISTofINT32  in the data field of the according to
the format field.  The list is indexed from zero.



                             [1m24[0m





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


only  those  conventions  that  are essential and that apply
generally to all window management paradigms.   Clients  de-
signed  to  run  with a particular window manager can easily
define private protocols to add to  these  conventions,  but
they  must  be aware that their users may decide to run some
other window manager no matter how much the designers of the
private  protocol are convinced that they have seen the "one
true light" of user interfaces.

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

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

For example, the claim is often made: "The client I'm  writ-
ing is important, and it needs to be on top."  Perhaps it is
important when it is being run in  earnest,  and  it  should
then  be run under the control of a window manager that rec-
ognizes "important" windows through  some  private  protocol
and ensures that they are on top.  However, imagine, for ex-
ample, that the "important" client is being debugged.  Then,
ensuring that it is always on top is no longer the appropri-
ate window management policy, and it should be run  under  a
window  manager  that allows other windows (for example, 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
    requested





                             [1m25[0m





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


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

A client's [4mtop-level[24m [4mwindow[24m is a window whose override-redi-
rect attribute is It must either be a child of a  root  win-
dow,  or  it must have been a child of a root window immedi-
ately prior to having been reparented by the window manager.
If  the  client reparents the window away from the root, the
window is no longer a top-level window; but it can become  a
top-level  window  again  if the client reparents it back to
the root.

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

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

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

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

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

From the client's point of view, the window manager will re-
gard 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.  Transi-
tions between states happen when  the  top-level  window  is
mapped  and  unmapped  and  when the window manager receives
certain messages.  For further details, see sections 4.1.2.4
and 4.1.4.

Once the client has one or more top-level windows, it should
place properties on those windows to inform the window  man-
ager  of  the  behavior  that  the  client  desires.  Window



                             [1m26[0m





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


managers will assume values they find convenient for any  of
these  properties that are not supplied; clients that depend
on particular values must explicitly supply them.  The  win-
dow  manager  will  not  change  properties  written  by the
client.

The window manager will examine the contents of these  prop-
erties  when  the window makes the transition from the With-
drawn state and will monitor  some  properties  for  changes
while the window is in the Iconic or Normal state.  When the
client changes one of these properties, it must use mode  to
overwrite the entire property with new data; the window man-
ager 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  man-
ager  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 resources exist for at least as long as the window  on
which the property resides.

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

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

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

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

Window managers are expected to make an  effort  to  display
this information.  Simply ignoring WM_NAME is not acceptable
behavior.  Clients can assume that at least the  first  part
of  this  string  is  visible  to  the  user and that if the



                             [1m27[0m





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


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 response.  The expected uses are to
permit the user to identify one of a number of instances  of
the  same  client  and  to provide the user with noncritical
state information.

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

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

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

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

lw(1i) lw(1i) lw(2i).  _
[1mField     Type Comments[0m
[1m_[0m
flags     CARD32    (see the next table)  pad  4*CARD32  For
backwards  compatibility min_width INT32     If missing, as-
sume base_width min_height     INT32     If missing,  assume
base_height       max_width INT32       max_height     INT32
width_inc INT32         height_inc     INT32         min_as-
pect     (INT32,INT32)          max_aspect     (INT32,INT32)
base_width     INT32     If   missing,   assume    min_width
base_height    INT32     If   missing,   assume   min_height
win_gravity    INT32     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{



                             [1m28[0m





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


lw(1i) nw(.5i) lw(3i).  _
[1mName Value     Field[0m
[1m_[0m
T}   8    Program-specified size T{ T}   16   Program-speci-
fied  minimum  size  T{  T}   32   Program-specified maximum
size T{  T}   64   Program-specified  resize  increments  T{
T}   128  Program-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 further interaction  is  superfluous.   To
indicate  that  it  was  specified 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 window 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 requested the transition  from  Withdrawn  state.
Other  values  of  win_gravity  specify  a  window reference
point.  For and the reference 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 reference point is the
center of the window.  The reference  point  of  the  window
manager  frame is placed at the location on the screen where
the reference point of the client window was when the client
requested the transition from Withdrawn state.

The  min_width  and  min_height elements specify the minimum
size that the window can be for the  client  to  be  useful.
The  max_width  and  max_height elements specify the maximum
size.  The base_width and base_height elements  in  conjunc-
tion with width_inc and height_inc define an arithmetic pro-
gression of preferred window widths and heights for non-neg-
ative integers [4mi[24m and [4mj[24m:






                             [1m29[0m





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


   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
numerator first and the denominator second, and they allow a
client to specify the range of  aspect  ratios  it  prefers.
Window  managers  that  honor aspect ratios should take into
account the base size in determining  the  preferred  window
size.   If a base size is provided along with the aspect ra-
tio fields, the base size should be subtracted from the win-
dow  size  prior  to checking that the aspect ratio falls in
range.  If a base size is not provided,  nothing  should  be
subtracted  from  the window size.  (The minimum size is not
to be used in place of the base size for this purpose.)

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

l l l.  _
[1mField     Type Comments[0m
[1m_[0m
flags     CARD32    (see     the     next     table)     in-
put     CARD32    The    client's    input    model     ini-
tial_state  CARD32    The    state    when    first   mapped
icon_pixmap    PIXMAP    The  pixmap  for  the  icon   image
icon_window    WINDOW    The   window  for  the  icon  image
icon_x    INT32     The   icon   location    icon_y    INT32
icon_mask PIXMAP    The   mask   for  the  icon  shape  win-
dow_group   WINDOW    The ID of the group leader window
_


The WM_HINTS.flags bit definitions are as follows:

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{



                             [1m30[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}   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 with-
out one.

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

Clients with the Globally Active and No Input models  should
set  the  input flag to 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 re-
gard  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  unmapped  and  when the window manager receives
certain messages.

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

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



                             [1m31[0m





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


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

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

The icon_window field is the ID of a window the client wants
used  as  its icon.  Most, but not all, window managers will
support icon windows.  Those that do not are likely to  have
a  user  interface  in  which small windows that behave like
icons are completely inappropriate.  Clients should not  at-
tempt 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 man-
ager as to where it should position the icon.  The  policies
of  the  window manager control the positioning of icons, so
clients should not depend on attention being  paid  to  this
hint.

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

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

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

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

The messages bit, if set in the flags field, indicates  that
the client is using an obsolete window manager communication
protocol,11 rather than the WM_PROTOCOLS mechanism  of  sec-
tion 4.1.2.7.
-----------
  11 This  obsolete  protocol was described in the
July 27, 1988, draft of the ICCCM.  Windows  using
it  can  also  be  detected because their WM_HINTS



                             [1m32[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  response  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 moni-
tor the state of this flag for the entire time the window is
in  the Normal or Iconic state and must take appropriate ac-
tion when the state of the flag changes.  The flag is other-
wise  independent  of the window's state; in particular, the
window manager is not required to deiconify  the  window  if
the  client sets the flag on an Iconic window.  Clients must
provide some means by which the user can cause the  flag  to
be  set  to  zero or the window to be withdrawn.  The user's
action can either mitigate the actual  condition  that  made
the  window  urgent,  or  it  can merely shut off the alarm.
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 win-
dow is too intrusive.  For example, the window  manager  may
attract attention to an urgent window by adding an indicator
to its title bar or its icon.  Window managers may also take
additional action for a window that is newly urgent, such as
by flashing its icon (if the window is iconic) or by raising
it to the top of the stack.

The  WM_CLASS property (of type STRING without control char-
acters) contains two  consecutive  null-terminated  strings.
These  specify  the  Instance  and Class names to be used by
both the client and the window manager for  looking  up  re-
sources  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 ap-
    plication to which the client that owns this window  be-
    longs.   Resources  that  are specified by instance name
    override any resources that are specified by class name.
    Instance  names can be specified by the user in an oper-
    ating-system specific manner.  On POSIX-conformant  sys-
    tems, the following conventions are used:


-----------
properties are 4 bytes longer than expected.  Win-
dow managers are free to support clients using the
obsolete protocol  in  a  backwards  compatibility
mode.



                             [1m33[0m





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


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

    -    Otherwise,  if   the   environment   variable   RE-
         SOURCE_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 direc-
         tory names) is used as the instance name.

+o   A string that names the general class of applications to
    which  the  client  that  owns this window belongs.  Re-
    sources that are specified by class apply to all  appli-
    cations  that have the same class name.  Class names are
    specified by the application writer.  Examples  of  com-
    monly   used  class  names  include:  "Emacs",  "XTerm",
    "XClock", "XLoad", and so on.

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

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

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

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

All the protocols in which a client can  volunteer  to  take
part  involve  the window manager sending the client a event
and the client taking appropriate action.   For  details  of



                             [1m34[0m





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


the contents of the event, see section 4.2.8.  In each case,
the protocol transactions are initiated by the  window  man-
ager.

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

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

l c l.  _
[1mProtocol  Section   Purpose[0m
[1m_[0m
WM_TAKE_FOCUS  4.1.7     Assignment     of    input    focus
WM_SAVE_YOURSELF    Appendix  C Save  client  state  request
(deprecated) WM_DELETE_WINDOW    4.2.8.1   Request to delete
top-level window
_

It is expected that this table will grow over time.

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

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



                             [1m35[0m





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


level window, clients should search the window hierarchy be-
neath the selected location for a window with  the  WM_STATE
property.   This  search must be recursive in order to cover
all window manager reparenting possibilities.  If no  window
with  a  WM_STATE  property is found, it is recommended that
programs use a mapped child-of-root window if one is present
beneath the selected location.

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

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


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
Consortium.  Values for the state field other than those de-
fined  in the above table are reserved for use by the X Con-
sortium.

The state field describes the window manager's idea  of  the
state  the  window  is  in, which may not match the client's
idea as expressed in the initial_state field of the WM_HINTS
property (for example, if the user has asked the window man-
ager to iconify the window).  If it is  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 handle 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



                             [1m36[0m





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


supplied  and  that contains the client's icon pixmap, or it
may be an ancestor of the client's icon window.

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

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[0m
[4mInterface[24m.

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

+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_win-
    dow  (if  any)  will  be viewable and, failing that, its
    icon_pixmap (if any) or its WM_ICON_NAME  will  be  dis-
    played.

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

In fact, the window manager may implement states with seman-
tics  other than those described above.  For example, a win-
dow manager might implement a concept of an "inactive" state
in  which an infrequently used client's window would be rep-
resented 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




                             [1m37[0m





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


+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
Withdrawn state.  Once a client's window has left the  With-
drawn  state, the window will be mapped if it is in the Nor-
mal state and the window will be unmapped if it  is  in  the
Iconic  state.   Reparenting  window managers must unmap the
client's window when it is in the Iconic state, even  if  an
ancestor  window  being unmapped renders the client's window
unviewable.  Conversely, if  a  reparenting  window  manager
renders  the  client's window unviewable by unmapping an an-
cestor, 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  Normal
and Iconic states.  Receipt of a event will indicate a tran-
sition 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 argu-
ments:

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      window:    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 notifi-
cation  of  the client's desire to change state, even though
the window may already be unmapped when the  desire  is  ex-
pressed.   For  compatibility  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



                             [1m38[0m





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


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  win-
dow  (e.g., by mapping it again or reparenting it elsewhere)
after withdrawing it must wait for the withdrawal to be com-
plete  before  proceeding.   The  preferred method for doing
this is for clients to wait for the window manager to update
or remove the WM_STATE property.12

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   Type13 == the atom WM_CHANGE_STATE

+o   Format == 32

+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 receive a event when the window concerned be-
comes completely obscured even though mapped (and thus, per-
haps 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
withdraw transients for the window.
-----------
  12 Earlier versions of these conventions prohib-
ited clients from reading the  WM_STATE  property.
Clients  operating  under  the earlier conventions
used the technique of tracking events to wait  for
the  top-level window to be reparented back to the
root window.  This is  still  a  valid  technique;
however, it works only for reparenting window man-
agers, and the WM_STATE technique is  to  be  pre-
ferred.
  13 The type field of the event (called the  mes-
sage_type  field  by  Xlib) should not be confused
with the code field of  the  event  itself,  which
will have the value 33



                             [1m39[0m





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


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

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

+o   The  [width,height]  of  the  inner region of the window
    (excluding 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 occurred).  The border width to be used and win_gravity
position  hint  to be used are those most recently requested
by the client.  Client configure requests are interpreted by
the  window manager in the same manner as the initial window
geometry mapped from the Withdrawn state,  as  described  in
section  4.1.2.3.   Clients  must  be aware that there is no
guarantee that the window manager will allocate them the re-
quested  size  or location and must be prepared to deal with
any size and location.  If the window manager decides to re-
spond to a request by:

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

    A client will receive a synthetic event  that  describes
    the (unchanged) geometry of the window.  The (x,y) coor-
    dinates will be in the root coordinate system,  adjusted
    for  the border width the client requested, irrespective
    of any reparenting  that  has  taken  place.   The  bor-
    der_width will be the border width the client requested.
    The client will not receive  a  real  event  because  no
    change has actually taken place.

+o   Moving  or  restacking the window without resizing it or
    changing 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  coor-
    dinate  system  adjusted for the border width the client
    requested.  The border_width will be  the  border  width
    the client requested.  The client may not receive a real
    event that describes this change because the window man-
    ager  may  have reparented the top-level window.  If the
    client does receive a real event,  the  synthetic  event
    will follow the real one.





                             [1m40[0m





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


+o   Resizing  the  window  or changing its border width (re-
    gardless  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  re-
    flect  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  resized  but not moved, since a real
event will be received in both cases.  Clients that are con-
cerned with keeping track of the absolute position of a top-
level window should keep a piece of state indicating whether
they  are  certain  of its 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 synthetic event,
the client should note the position as known, using the  po-
sition  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 request to find the position of a  top-level
window.

Clients  should be aware that their borders may not be visi-
ble.  Window managers are free to use reparenting techniques
to decorate client's top-level windows with borders contain-
ing titles,  controls, and other details to maintain a  con-
sistent look-and-feel.  If they do, they are likely to over-
ride the client's attempts to set the border width  and  set
it  to  zero.   Clients, therefore, should not depend on the
top-level window's border being visible or use it to display
any  critical information.  Other window managers will allow
the top-level windows border to be visible.  Clients  should
set  the  desired value of the border-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 sib-
ling field.





                             [1m41[0m





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


Clients that must position themselves in the stack  relative
to some window that was originally a sibling must do the re-
quest (in case they are running under a nonreparenting  win-
dow  manager),  be  prepared to deal with a resulting error,
and then follow with a synthetic event by invoking 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:   a    with:    T}   T{    T}
    event:     The  root     window:    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
receiving the stacking order they have  requested.   Clients
should  ignore the above-sibling field of both real and syn-
thetic 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
gravity No  Backing-store  hint  Yes  Save-under hint     No
Event mask   No Do-not-propagate mask    Yes  Override-redi-
rect flag No Colormap  Yes Cursor    Yes
_


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

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

+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
    irrespective   of  any  events  the  window  manager  is



                             [1m42[0m





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


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

+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
    example 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 simple 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 exam-
    ple  would  be a client with subwindows defining various
    data entry fields that uses Next and Prev keys  to  move
    the input focus between the fields.  It does so when its
    top-level window has acquired the focus in 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  in-
    put 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 re-
    gion  but not when the user clicks in the scroll bar it-
    self.  Thus, it wants to prevent the window manager from
    setting the input focus to any of its windows.

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

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{ Globally Active T}   T{ T}   T{ Present T}
_




                             [1m43[0m





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


Passive and Locally Active clients set the  input  field  of
WM_HINTS to which indicates that they require window manager
assistance  in acquiring the  input  focus.   No  Input  and
Globally  Active  clients  set  the input field to which re-
quests 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
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
Note that clients must not use in the time field.

Clients  using  the Globally Active model can only use a re-
quest to acquire the input focus when they  do  not  already
have it on receipt 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  example, a selection tool that establishes a pas-
sive grab on the keys that cut,  copy,  or paste).

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

Windows  with  the  atom WM_TAKE_FOCUS in their WM_PROTOCOLS
property may receive a event from the window manager (as de-
scribed  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 win-
dow  in an area that indicates to the window manager that it
should assign the focus (for example, clicking in the  head-
line bar can be used to assign the focus).

The  goal  is to support window managers that want to assign
the input focus to a top-level window in such a way that the
top-level  window  either  can  assign  it  to  one  of  its



                             [1m44[0m





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


subwindows or can decline the offer of the focus.  For exam-
ple,  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 be-
havior 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 assign-
    ing  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
    policy leads to race conditions because the  window  be-
    coming  unviewable  may coincide with the window manager
    deciding to move the focus elsewhere.

+o   - Using this value causes problems if the window manager
    reparents  the window, as most window managers will, and
    then crashes.  The input focus will be  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  re-
ceive instead.

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

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

Clients whose top-level windows and subwindows all  use  the
same colormap should set its ID in the colormap field of the
top-level  window's  attributes.   They  should  not  set  a
WM_COLORMAP_WINDOWS  property  on  the top-level window.  If



                             [1m45[0m





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


they want to change the colormap,  they  should  change  the
top-level  window's  colormap attribute.  The window manager
will track changes to the window's  colormap  attribute  and
install colormaps as appropriate.

Clients  that  create  windows  can use the value 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  col-
ormap 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  col-
ormaps  the  window manager should attempt to have installed
when, in the course of its individual colormap focus policy,
it  assigns  the colormap focus to the top-level window (see
section 4.1.2.8).  The list is ordered by the importance  to
the  client  of  having the colormaps installed.  The window
manager will track changes to this property and  will  track
changes  to  the  colormap  attribute  of the windows in the
property.

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

WM_TRANSIENT_FOR windows can either have their  own  WM_COL-
ORMAP_WINDOWS property or appear in the property of the win-
dow 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  al-
ternative  design specified a list of colormaps instead of a
list of windows.  The current design, a list of windows, was
chosen for two reasons.  First, it allows window managers to
find the visuals of the colormaps, thus  permitting  visual-
dependent colormap installation policies.  Second, it allows
window managers to select for events  on  the  windows  con-
cerned  and  to  ensure that colormaps are only installed if
the windows that need them are visible.  The alternative de-
sign  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  Protocol  in  the description of the request.  Briefly,
the min-installed-maps  most  recently  installed  maps  are
guaranteed  to  be  installed.   This  value  is  often one;
clients needing multiple colormaps should beware.

Whenever possible, clients should  use  the  mechanisms  de-
scribed  above  and  let  the window manager handle colormap



                             [1m46[0m





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


installation.  However, clients  are  permitted  to  perform
colormap  installation  on  their  own  while  they have the
pointer grabbed.  A client performing colormap  installation
must  notify the window manager prior to the first installa-
tion.  When the client has finished its  colormap  installa-
tion,  it  must  also notify the window manager.  The client
notifies the window manager by issuing a  request  with  the
following arguments:


tab(/) ; lB lB l lw(3.5i) _
Argument/Value
_ destination:/T{ the root window of the screen on which the
colormap 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  timestamp  of  the event that caused the
client  to   start   or   stop   installing   colormaps   T}
  data[1]:/T{ 1 if the client is starting colormap installa-
tion, 0 if the client is finished with colormap installation
T}    data[2]:/reserved,  must  be zero   data[3]:/reserved,
must be zero   data[4]:/reserved, must be zero
_


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

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

This technique has race conditions that may  result  in  the
colormaps continuing to be installed even after a client has
issued its notification message.  For  example,  the  window
manager  may have issued some 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 animations that use
override-redirect windows.

If a client fails  to  issue  the  "finished"  message,  the



                             [1m47[0m





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


window manager may be left in a state where its colormap in-
stallation policy is suspended.  Window manager implementors
may want to implement a feature that resets colormap instal-
lation policy in response to a command from the user.

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

+o   A string in WM_ICON_NAME.

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

+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 un-
    likely 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 when-
    ever the client is in the Iconic state.  In general, the
    size of the icon window should be one of those specified
    in WM_ICON_SIZE on the root, if it exists.  Window  man-
    agers are free to resize icon windows.

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

+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
    window'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.




                             [1m48[0m





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


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

4.   Clients should not map their icon windows.

5.   Clients should not unmap their icon windows.

6.   Clients should not configure their icon windows.

7.   Clients should not set override-redirect on their  icon
     windows or select for events on them.

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

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

10.  Clients must select for events on their icon window and
     repaint it when requested.

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

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

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

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

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

3.   If the window will be visible for a very short time and
     should  not  be  decorated  at  all, the client can set
     override-redirect on  the  window.   In  general,  this
     should be done only if the pointer is grabbed while the
     window is mapped.  The window manager will never inter-
     fere with these windows, which should be used with cau-
     tion.  An example of an appropriate  use  is  a  pop-up
     menu.   The  user  will  not  be  able to move, resize,
     restack, or  transfer  the  input  focus  to  override-



                             [1m49[0m





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


     redirect  windows, since the window manager is not man-
     aging them.  If it is necessary for a client to receive
     keystrokes  on  an override-redirect window, either the
     client must grab the keyboard or the client  must  have
     another  top-level window that is not override-redirect
     and that has selected the Locally  Active  or  Globally
     Active  focus  model.   The client may set the focus to
     the override-redirect window when the other window  re-
     ceives  a  WM_TAKE_FOCUS  message  or one of the events
     listed in section 4.1.7 in the description of the Glob-
     ally Active focus model.

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

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

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

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

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

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

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




                             [1m50[0m





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


+o   The parent value returned by a request will no longer be
    the value supplied to the request that created  the  re-
    parented 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 re-
    quest  in  the  new parent's coordinate space.  In fact,
    they usually will not be interpreted by the  server  be-
    cause a reparenting window manager usually will have in-
    tercepted these operations (see section 4.2.2).  Clients
    should  use the root coordinate 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
    parent's coordinate space and are thus not directly use-
    ful 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 select for events on their top-level window.  They  will
receive a event if and when reparenting takes place.  When a
client withdraws a top-level window, the window manager will
reparent  it  back to the root window if the window had been
reparented elsewhere.

If the window manager reparents a client's window,  the  re-
parented 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 unmapped.  Note that this applies to  all
client windows the window manager reparents, including tran-
sient windows and client icon windows.

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

The  possibility that a request may be redirected means that
a client cannot assume  that  any  redirectable  request  is



                             [1m51[0m





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


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

This next example incorrectly assumes that  the  request  is
actually 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
window's size by tracking events.

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


     MapWindow B
     SetInputFocus B


If the request has been intercepted, the window  will  still
be unmapped, 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
redirection,  but the bit should be set on top-level windows
-----------
  14 This is true even if the client set the back-
ing-store attribute to The backing-store attribute
is  a  only  a hint, and the server may stop main-
taining backing store contents at any time.



                             [1m52[0m





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


only in cases where other windows should be  prevented  from
processing  input  while  the  override-redirect  window  is
mapped (see section 4.1.10) and while responding  to  events
(see section 4.2.9).

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

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

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

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

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 coordinate space.  Clients must not respond to
being moved by attempting to move themselves to a better lo-
cation.

Any  real  event on a top-level window implies that the win-
dow's position on the root may have changed, even though the
event  reports  that  the window's position in its parent is
unchanged because the window may have been reparented.  Note
that the coordinates in the event will not, in this case, be
directly useful.

The window manager will send these events by using a 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  re-
sized  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 win-
dow (which may not be the root).



                             [1m53[0m





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


The response of the client to being resized should be to ac-
cept  the size it has been given and to do its best with it.
Clients must not respond to being resized by  attempting  to
resize themselves to a better size.  If the size is impossi-
ble 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 Nor-
mal state if it is mapped and in the Iconic state if  it  is
unmapped.  This will be true even if the window has been re-
parented; the window manager will unmap the window  as  well
as its parent when switching to the Iconic state.

The  client  can elect to be notified of these state changes
by selecting for 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
installed  or  uninstalled should select for events on their
top-level windows and on any  windows  they  have  named  in
WM_COLORMAP_WINDOWS  properties  on their top-level windows.
They will receive 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 receive and events.  Clients that need to set the
input focus to one of their subwindows should not do so  un-
less they have set WM_TAKE_FOCUS in their WM_PROTOCOLS prop-
erty and have done one of the following:

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

+o   Set  the  input field of WM_HINTS to and have received a
    suitable 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 trans-
fer the focus; they should  set  the  focus  and  leave  the
pointer alone.  For further information, see section 6.2.

Once  a  client  satisfies these conditions, it may transfer
the focus to another of its windows by  using  the  request,
which is defined as follows:


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




                             [1m54[0m





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


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  fo-
     cus  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 following:

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

These events will be sent by using a request with  the  fol-
lowing arguments:

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


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:




                             [1m55[0m





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


+o   Either change the window's state to  Withdrawn  (as  de-
    scribed 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 dia-
log, the client should ignore the message.

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

If  the  client  aborts  a destroy and the user then selects
DELETE WINDOW again, the window  manager  should  start  the
WM_DELETE_WINDOW protocol again.  Window managers should not
use 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 win-
dow or events on a window itself.   However,  at  most,  one
client per window can select for these events, and a conven-
tion is needed to avoid clashes.  Clients (including  window
managers)  should select for and events only on windows that
they own.

In particular, clients that need to take some special action
if they are resized can select for events on their top-level
windows.  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 en-
sure that the resize will actually happen at this stage  in-
stead  of  being intercepted and executed by the window man-
ager (and thus restarting the  process),  the  client  needs
temporarily to set override-redirect on the window.  Clients
receiving events must respond by doing the following:

+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  pos-
    sible and before making any other geometry requests



                             [1m56[0m





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


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

For each screen they manage, window  managers  will  acquire
ownership  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 is-
suing conversion requests on this  selection.   Window  man-
agers  should  support conversion of the following 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
minor release numbers (respectively) of the ICCCM with which
the window manager complies.  For this version of the ICCCM,
the numbers are 2 and 0.15 T}
_


The window manager properties are summarized in the  follow-
ing  table (see also section 14.1 of [4mXlib[24m [4m-[24m [4mC[24m [4mLanguage[24m [4mX[24m [4mIn-[0m
[4mterface[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
_


-----------
  15 As a special case, clients not wishing to im-
plement a selection request may simply issue a re-
quest on the appropriate WM_S[4mn[24m selection.  If this
selection is owned, clients may  assume  that  the
window  manager complies with ICCCM version 2.0 or
later.



                             [1m57[0m





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


This section contains some conventions for clients that par-
ticipate  in  session  management.  See [4mX[24m [4mSession[24m [4mManagement[0m
[4mProtocol[24m 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  pre-
served across sessions.

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

+o   Be of type STRING

+o   Be of format 8

+o   Contain the client-ID as a string of XPCS characters en-
    coded 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 contain-
ing its own window ID (i.e., the  client  leader  window  is
pointing  to  itself).   Transient  windows  need not have a
WM_CLIENT_LEADER property if the client leader can be deter-
mined  using  the  information in the WM_TRANSIENT_FOR prop-
erty.  The WM_CLIENT_LEADER property must:

+o   Be of type WINDOW

+o   Be of format 32

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

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

It is necessary that other clients be able to uniquely iden-
tify a window (across sessions) among all windows related to
the same client-ID.  For example, a window manager  can  re-
quire  this unique ID to restore geometry information from a
previous session, or a workspace manager could use it to re-
store   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



                             [1m58[0m





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


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, en-
    coded 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.  Therefore,  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 connections to the same  X  server  to  locate  (ren-
dezvous 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 specifi-
cation for complete details.

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

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

+o   Locally active mode




                             [1m59[0m





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


+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 windows or when they receive a WM_TAKE_FOCUS mes-
     sage.   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 re-
     ceive a WM_TAKE_FOCUS message.  They should set the in-
     put 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 fo-
     cus as the time field on the request, not

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

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
window will fail if some other  client  has  already  estab-
lished  a  conflicting  grab on the same window.  The grabs,
therefore, are shared resources, and their use requires con-
ventions.

In  conformance  with  the principle that clients should be-
have, 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 managers should ensure that they pro-
vide 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 WINDOW KeySym).

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




                             [1m60[0m





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


Even so, clients are advised to allow  the  key  and  button
combinations  used to elicit program actions to be modified,
because some window managers may choose not to observe  this
convention  or  may  not provide a convenient method for the
user to transmit events from some keys.  Clients should  es-
tablish 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 re-
parent the window and establish the grab on a proper  ances-
tor.   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 be-
    ing 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
replace, the client's semantics for key+button  combinations
by  allowing  the  event  to be used by the client after the
window manager is done with it.  To ensure this, the  window
manager should establish the grab on the parent by using the
following:

pointer/keyboard-mode == Synchronous

Then, the window manager should release the grab by using an
request with the following specified:

mode == ReplayPointer/Keyboard

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

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

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

+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 communi-
cate with the window manager about their colormap needs.  If
your  clients  are  type  applications,  you  should consult



                             [1m61[0m





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


section 14.3 of [4mXlib[24m [4m-[24m [4mC[24m [4mLanguage[24m [4mX[24m  [4mInterface[24m  for  conven-
tions  connected  with  sharing  standard  colormaps.   They
should look for and create the properties described there on
the root window of the appropriate screen.

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

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 vis-
ual_id VISUALID  Visual   to    which    colormap    belongs
kill_id   CARD32    ID for destroying the resources
_


When  deleting or replacing an RGB_COLOR_MAP, it is not suf-
ficient to delete the property; it is important to free  the
associated  colormap  resources  as  well.   If  kill_id  is
greater than one, the resources should be freed by issuing a
request  with  kill_id  as the argument.  If kill_id is one,
the resources should be freed by issuing a request with col-
ormap  as the colormap argument.  If kill_id is zero, no at-
tempt should be made to free the resources.  A  client  that
creates  an RGB_COLOR_MAP for which the colormap resource is
created specifically for this purpose should set kill_id  to
one (and can create more than one such standard colormap us-
ing  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 re-
source ID for kill_id (and should create no  other  standard
colormaps  on the connection).  If an RGB_COLOR_MAP property
is too short to contain the visual_id field, it can  be  as-
sumed that the visual_id is the root visual of the appropri-
ate screen.  If an RGB_COLOR_MAP property is  too  short  to
contain the kill_id field, a value of zero can be assumed.

During  the  connection  handshake,  the  server informs the
client of the default colormap for each screen.  This  is  a
colormap  for the root visual, and clients can use it to im-
prove the extent of colormap 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  corre-
sponding key for each keycode generated by the server.  This
table does not affect the server's operations in any way; it
is  simply a database used by clients that attempt to under-
stand the keycodes they  receive.   Nevertheless,  it  is  a



                             [1m62[0m





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


shared resource and requires conventions.

It  is  possible for clients to modify this table by using a
request.  In general, clients should not do this.   In  par-
ticular,  this is not the way in which clients should imple-
ment key bindings or key remapping.  The conversion  between
a sequence of keycodes received from the server and a string
in a particular encoding is a private matter for each client
(as  it  must  be in a world where applications may be using
different  encodings  to  support  different  languages  and
fonts).   See  the Xlib reference manual for converting key-
board events to text.

The only valid reason for using a request is when  the  sym-
bols  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 re-
          quest, "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  receiving  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 preas-
signed to Shift, Lock, and Control.  Each  modifier  bit  is
controlled by the state of a set of keys, and these sets are
specified in a table accessed by 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  cor-
rectly to control these modifiers.  The Lock modifier should
be interpreted as Caps Lock or Shift Lock according  as  the



                             [1m63[0m





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


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 mod-
    ifier  that  contains a keycode whose set of KeySyms in-
    cludes XK_Meta_L or XK_Meta_R, it should use that  modi-
    fier bit.

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

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

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

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

+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
     assign keycodes carrying suitable KeySyms to an  unused
     modifier bit.

2.   Clients  assigning  their  own modifier bits should ask
     the user politely to remove his or her hands  from  the
     key in question if their request returns a status.

There  is  no good solution to the problem of reclaiming as-
signments to the five nonpreassigned modifiers when they are
no longer being used.  The user must use or some other util-
ity 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  nonpreassigned  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 re-
install the modifier.





                             [1m64[0m





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


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


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

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

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

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

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

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

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



                             [1m65[0m





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


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

             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
     outlined later.

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

Because of the limited dynamic range of both XYZ and RGB in-
tensity, these matrices will be encoded using a  fixed-point
representation 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 (for-
mat = 32) on the root window of each  screen,  using  values
appropriate for that screen.

This will be encoded as shown in the following table:

center;  c s s c c c l l l.  XDCCC_LINEAR_RGB_MATRICES prop-
erty 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  con-
version  between RGB intensity and the actual X protocol RGB
values:

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




                             [1m66[0m





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


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

The first representation is an array of RGB  value/intensity
level  pairs, with the RGB values in strictly increasing or-
der.  When 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 correc-
tion table.  The intensity will be encoded  as  an  unsigned
number  to be interpreted as a value between 0 and 1 (inclu-
sive).  The precision of this value will depend on the  for-
mat  of  the  property  in  which it is stored (8, 16, or 32
bits).  For 16-bit and 32-bit formats, the  RGB  value  will
simply  be the value stored in the property.  When stored in
8-bit format, the RGB value can be computed from  the  value
in the property by:

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


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

This will be encoded as shown in the following table:

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
VisualID2 CARD Exists if and only if the property format  is
8 VisualID3 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 fol-
lowing (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  following  in  this



                             [1m67[0m





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


table (if and only if [4mcount[24m is 3) T} value     CARD X Proto-
col RGB value intensity CARD Interpret as a number @0~<=~in-
tensity~<=~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.

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
entries in this table.  The intensity values will be encoded
just as in the first representation.

This will be encoded as shown in the following table:

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
VisualID2 CARD Exists if and only if the property format  is
8 VisualID3 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 fol-
lowing (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}  inten-
sity CARD Interpret   as   a   number  @0~<=~intensity~<=~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 Inter-
pret  as  a  number @0~<=~intensity~<=~1@ ...  ...  Total of



                             [1m68[0m





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


[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
interoperability  conventions only for the X Version 11 pro-
tocol.  Clients should be  aware  of  other  protocols  that
should  be  used for better interoperation in the X environ-
ment.  The reader is referred to [4mX[24m [4mSession[24m [4mManagement[24m [4mProto-[0m
[4mcol[24m  for  information  on  session management, and to [4mInter-[0m
[4mClient[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.   Readers  are  encouraged  to use the registry.  The
classes of items kept in the registry that are  relevant  to
the  ICCCM include property names, property types, selection
names, selection targets, WM_PROTOCOLS protocols, types, and
application  classes.   Requests to register items, or ques-
tions about registration, should be addressed 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 inquiries.

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











                             [1m69[0m





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




                         [1mAppendix A[0m


This appendix describes the revision history of  this  docu-
ment  and  summarizes the incompatibilities between this and
earlier versions.

The February 25, 1988, draft that was distributed as part of
X  Version  11,  Release 2, was clearly labeled as such, and
many areas were explicitly  labeled  as  liable  to  change.
Nevertheless,  in the revision work done since then, we have
been very careful not to introduce gratuitous  incompatibil-
ity.   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 incompati-
bilities 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  selec-
    tion  replies has changed, and the name has been changed
    to INCR.  Selection requestors are free to implement the
    earlier  protocol if they receive properties of type IN-
    CREMENTAL.

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

+o   The  protocol  for  the  special  CLIPBOARD  client  has
    changed.  The earlier protocol is subject to race condi-
    tions 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  val-
    ues 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



                             [1m70[0m





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


    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.

+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 re-
    placed by the WM_PROTOCOLS property,  but  clients  that
    use  the  earlier mechanism can be detected because they
    set the messages bit in the flags field of the  WM_HINTS
    property,  and  window  managers can provide a backwards
    compatibility mode.

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

+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 nonwindow manager clients, there is no incompatibil-
    ity.

+o   The  pseudoroot  facility  in the earlier draft has been
    removed.  Although it has been successfully implemented,
    it turns out to be inadequate to support the uses envis-
    aged.  An extension will be required  to  support  these
    uses  fully,  and  it  was felt that the maximum freedom
    should be left to the designers of  the  extension.   In
    general, the previous mechanism was invisible to clients
    and no incompatibility should result.

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





                             [1m71[0m





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


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

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

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

+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
    replace 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 incom-
    patibility  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 re-
    quests.

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

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

+o   The  semantics  of  WM_SAVE_YOURSELF have been clarified
    and  restricted  to  be  a  checkpoint  operation  only.
    Clients  that  were  using  it as part of a shutdown se-
    quence 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 proper-
    ties.  Clients using earlier conventions can be detected
    by  the  size of their RGB_COLOR_MAP properties, and the



                             [1m72[0m





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


    cases that would have worked will still work.

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

+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
review draft for Version 2.0.

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




                             [1m73[0m





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


+o   [P28] Added a recommended technique for setting the  in-
    put focus 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-
    redirect windows has been added.

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

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

+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  dur-
    ing 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
    requests 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
    session management conventions have been moved to Appen-
    dix C.

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

+o   Information on the X Registry and references to the ses-
    sion 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  re-
leasing the final edition of Version 2.0 with X11R6.





                             [1m74[0m





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


+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 [4mManage-[0m
    [4mment[24m [4mProtocol[24m.

+o   Window managers are now prohibited from placing  in  the
    timestamp 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.










































                             [1m75[0m





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




                           [1mAppendix B[0m


During the development of these conventions, a number of in-
adequacies 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
    contained a timestamp and a previous-focus field.   This
    could  avoid  the  potential  race  condition.  There is
    space in the event for this information;  it  should  be
    added at the next protocol revision.

+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 revi-
    sion should provide 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 installation to the window man-
    ager.

+o   The  protocol needs to be changed to provide some way of
    identifying 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.


















                             [1m76[0m





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




                           [1mAppendix C[0m


This appendix contains obsolete conventions for session man-
agement  using  X  properties and messages.  The conventions
described here are deprecated and  are  described  only  for
historical  interest.   For  further  information on session
management, see [4mX[24m [4mSession[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  depend on the operating system of the ma-
chine 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-separated.  This inconsistency is necessary  for  back-
wards compatibility.

A  client with multiple top-level windows should ensure that
exactly one of them has a WM_COMMAND  with  nonzero  length.
Zero-length  WM_COMMAND  properties  can be used to reply to
WM_SAVE_YOURSELF messages on  other  top-level  windows  but
will otherwise be ignored.




                             [1m77[0m





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


This property is described in section 4.1.2.9.

Because they communicate by means of unreliable network con-
nections, clients must be prepared for their  connection  to
the  server  to  be  terminated at any time without warning.
They cannot depend on getting notification that  termination
is  imminent or on being able to use the server to negotiate
with the user about their fate.  For example, clients cannot
depend on being able to put up a dialog box.

Similarly,  clients may terminate at any time without notice
to the session manager.  When  a  client  terminates  itself
rather  than  being terminated by the session manager, it is
viewed as having resigned from the session in question,  and
it will not be revived if the session is revived.

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 exam-
ple, when  termination  impends)  should  include  the  atom
WM_SAVE_YOURSELF  in the WM_PROTOCOLS property on their top-
level windows to participate in the WM_SAVE_YOURSELF  proto-
col.   They  will  receive  a  event as described in section
4.2.8 with the atom WM_SAVE_YOURSELF in its data[0] field.

Clients that receive  WM_SAVE_YOURSELF  should  place  them-
selves  in  a  state  from  which  they can be restarted and
should update WM_COMMAND to be a command that  will  restart
them in this state.  The session manager will be waiting for
a 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  ses-
sion  to  be  put  to sleep, the session manager will ensure
that the client does  not  receive  any  mouse  or  keyboard
events.

After  receiving  a  WM_SAVE_YOURSELF, saving its state, and
updating WM_COMMAND, the client should not change its  state
(in  the sense of doing anything that would require a change
to WM_COMMAND) until it receives a mouse or keyboard  event.
Once it does so, it can assume that the danger is over.  The
session manager will ensure that these events do  not  reach



                             [1m78[0m





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


clients  until  the danger is over or until the clients have
been killed.

Irrespective of how they  are  arranged  in  window  groups,
clients  with  multiple  top-level windows should ensure the
following:

+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 prop-
         erty, if necessary

    -    Second, updating the  WM_COMMAND  property  on  the
         window for which they received the WM_SAVE_YOURSELF
         message if it was not updated in the first step

Receiving WM_SAVE_YOURSELF on a window is,  conceptually,  a
command to save the entire client state.16

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 because of the introduction of the protocol
in  the next section.  In the public review draft,
there was ambiguity as to whether WM_SAVE_YOURSELF
was  a  checkpoint  or a shutdown facility.  It is
now unambiguously  a  checkpoint  facility;  if  a
shutdown  facility  is  judged  to be necessary, a
separate WM_PROTOCOLS protocol will  be  developed
and registered with the X Consortium.



                             [1m79[0m


