














       IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss MMaannuuaall

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

                   XX CCoonnssoorrttiiuumm SSttaannddaarrdd

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






                      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










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



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

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

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

Stuart W. Marks
December 1993

























                             vii










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



David Rosenthal had overall architectural responsibility for
the conventions defined in this document; he wrote  most  of
the  text  and  edited the document, but its 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
Fulton                    Bob        Scheifler         Hania
Gajewska                Ralph          Swick          Jordan
Hubbard                Mike           Wexler           Kerry
Kimbrough               Glenn         Widener         Audrey
Ishizaki

For the Device Color Characterization section: Keith Packard

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

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






                            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  _X  _W_i_n_d_o_w
_S_y_s_t_e_m  _P_r_o_t_o_c_o_l, _V_e_r_s_i_o_n _1_1 may operate correctly in isola-
tion but may not coexist properly with  others  sharing  the
same server.

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

+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
operations 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 _I_n_t_e_r_-_C_l_i_e_n_t _C_o_m_-
_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l (ICCCM) covers only a  minimal
set  of  required  conventions.   These  conventions will be
added to and updated as appropriate, based  on  the  experi-
ences of the X Consortium.

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

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



                              11





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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

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
appear on the wire have a fixed size (in fact, 32 bytes) and
that  because some events contain atoms, a fixed-size repre-
sentation for them was needed.

To allow a fixed-size representation, a protocol request 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
results  of  the requests, which require a handshake, can be
-----------
  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.



                              22





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


assumed _a _p_r_i_o_r_i.

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

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

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

The core protocol imposes no semantics on  atoms  except  as
they  are used in FONTPROP structures.  For further informa-
tion on FONTPROP semantics, see the _X _L_o_g_i_c_a_l _F_o_n_t  _D_e_s_c_r_i_p_-
_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s.

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

l l lw(3.6i).  _
SSppaaccee     BBrriieeffllyy   EExxaammpplleess
__
Property  name  Name WM_HINTS,  WM_NAME,  RGB_BEST_MAP,  ...
Property  type     Type WM_HINTS, CURSOR, RGB_COLOR_MAP, ...
Selection  name  Selection PRIMARY,   SECONDARY,   CLIPBOARD
Selection     target     Target    FILE_NAME,    POSTSCRIPT,
PIXMAP, ...  Font property       QUAD_WIDTH, POINT_SIZE, ...
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



                              33





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


by some entity. This entity can be:

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


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

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

lB lB lB l l l .  _
Name Discriminated by    Form Example
_
screen            number  _n_a_m_e_S_d   WM_COMMS_S2            X
resource     _n_a_m_e_R_x   GROUP_LEADER_R1234ABCD
_


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

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

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


if the names stand totally alone, and the form:

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


if  they  come in sets (here there are two sets, named "FOO"
and "BAR").  The stand-alone U_d form should 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:





                              44





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


         FOO_R12345678_U23

Existing protocols will not be changed to use  these  naming
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
defines for the exchange of information between clients, for
example,  by cutting and pasting between windows.  Note that
there can be an arbitrary number of selections  (each  named
by an atom) and that they are global to the server.  Section
2.6 discusses the choice of  an  atom.   Each  selection  is
owned by a client and is attached to a window.

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

+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
requestor must usually go by means of the  server  in  an  X
Version 11 environment.  A client cannot assume that another
client can open the same files or even communicate directly.
The  other client may be talking to the server by means of a
completely different networking mechanism (for example,  one
client might be DECnet and the other TCP/IP).  Thus, passing



                              55





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


indirect references to  data  (such  as,  file  names,  host
names,  and  port numbers) is permitted only if both clients
specifically agree.

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


  _s_e_l_e_c_t_i_o_n: ATOM
  _o_w_n_e_r: WINDOW or
  _t_i_m_e: 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
selection.2  Clients  attempting to acquire a selection must
set the time value of the request to the  timestamp  of  the
event  triggering  the  acquisition  attempt, not to A zero-
length append to a property is a way to obtain  a  timestamp
for  this  purpose;  the  timestamp  is in the corresponding
event.

If the time in the request is in the future relative to  the
server's current time or is in the past relative to the last
time the specified  selection  changed  hands,  the  request
appears to the client to succeed, but ownership is not 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:


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

->

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



                              66





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


  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:

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:


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


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

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

If  the  specified  property is 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
parameters in the property named in the  selection  request.
The  type,  format, and contents of this property are depen-
dent upon the definition of the target.  If  the  target  is
not  defined to have parameters, the owner should ignore the
property if it is present.  If the selection cannot be  con-
verted  into  a form based on the target (and parameters, if



                              77





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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


  _r_e_q_u_e_s_t_o_r: WINDOW
  _s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t: ATOM
  _p_r_o_p_e_r_t_y: ATOM or
  _t_i_m_e: 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
requestor,  selection, target, and timestamp it must respond
to them in the same order in which they were  received.   It
is  possible  for  a  requestor to have multiple outstanding
requests that use the same requestor window, selection, 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
doing 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



                              88





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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


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


The  timestamp  argument  is the time at which the ownership
changed hands, and the owner argument is the window the pre-
vious owner specified in its request.

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

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

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

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

Alternatively, the client may destroy the window used as the
owner value of the request, or the client may terminate.  In
both cases, the ownership of  the  selection  involved  will
-----------
  3 The division between these two cases is a mat-
ter of judgment on the part of the software devel-
oper.



                              99





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


revert to

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

The timestamp is the time the selection changed hands.   The
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:


  _s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t: ATOM
  _p_r_o_p_e_r_t_y: ATOM or
  _r_e_q_u_e_s_t_o_r: WINDOW
  _t_i_m_e: 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
request to be made.

The  requestor  should set the property argument to the name
of a property that the owner can use to report the value  of
the  selection.   Requestors  should  ensure  that the named
property does not exist on the  window  before  issuing  the
request.4  The  exception to this rule is when the requestor
intends to pass parameters with the request (see below).  It
is  necessary  for  requestors to delete the property before
issuing the request so that the target can later be extended
to  take  parameters without introducing an incompatibility.
Also note that the requestor of a selection  need  not  know
the  client  that owns the selection nor the window on which
the selection was acquired.
-----------
  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



                             1100





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


Some  targets  may  be defined such that requestors can pass
parameters along with the request.  If the requestor  wishes
to provide parameters to a request, they should be placed in
the specified property on the requestor  window  before  the
requestor  issues  the  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
exist  on  the requestor window.  The value of the selection
can be retrieved from this property by  using  the  request,
which is defined as follows:


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

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



                             1111





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


->

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


When  using  to retrieve the value of a selection, the prop-
erty argument should be set to the  corresponding  value  in
the  event.   Because  the  requestor  has no way of knowing
beforehand what type the selection owner will use, the  type
argument  should be set to Several requests may be needed to
retrieve all the data in the selection; each should set  the
long-offset  argument to the amount of data received so far,
and the size argument to some reasonable  buffer  size  (see
section 2.5).  If the returned value of bytes-after is zero,
the whole property has been transferred.

Once all the data in the selection has been retrieved (which
may  require getting the values of several properties -- see
section 2.7), the requestor should delete  the  property  in
the  request by using a request with the delete argument set
to As previously discussed, the owner has no way of  knowing
when  the  data has been transferred to the requestor unless
the property is removed.   The  requestor  must  delete  the
property  named in the once all the data has been retrieved.
The requestor should invoke either or after it has  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
    expensive.

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




                             1122





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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

5.   If  an error occurs during the storing of the selection
     data, all properties stored for this  selection  should
     be  deleted and the request should be refused (see 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,
reducing  the  need  for  newly minted atoms is an important
goal for the use of the selection atoms.

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

+o   PRIMARY

+o   SECONDARY

+o   CLIPBOARD

Other  selections  may be used freely for private 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
    selection and the user does not want to disturb it




                             1133





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

+o   It should assert ownership of the CLIPBOARD.

+o   If it succeeds in acquiring ownership, it should be 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
request the contents of the CLIPBOARD selection in the usual
way.

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

+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
         selection by using the same timestamp.

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




                             1144





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

A  special  CLIPBOARD client is not necessary.  The protocol
used by the cutting client and the  pasting  client  is  the
same  whether  the  CLIPBOARD client is running or not.  The
reasons for running the special client include:

+o   Stability - If the cutting client were to crash or  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
    retain  it for so long, thus reducing the chance of race
    conditions causing problems.

The reasons not to run the clipboard client include:

+o   Performance - Data is transferred only if it is actually
    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
request 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 sug-
gested so far.

lw(1.8i) lw(1i) lw(3i) .  _
AAttoomm TTyyppee      DDaattaa RReecceeiivveedd
_
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}
BACKGROUND     PIXEL     A    list    of    pixel     values
BITMAP    BITMAP    A      list      of      bitmap      IDs
CHARACTER_POSITION  SPAN T{ The start and end of the  selec-
tion   in  bytes  T}  CLASS     TEXT (see  section  4.1.2.5)
CLIENT_WINDOW  WINDOW    T{ Any top-level  window  owned  by
the  selection  owner  T} COLORMAP  COLORMAP  A list of col-
ormap IDs COLUMN_NUMBER  SPAN T{ The start  and  end  column
numbers   T}   COMPOUND_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}



                             1155





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


lw(1.8i) lw(1i) lw(3i) .  _
AAttoomm TTyyppee      DDaattaa RReecceeiivveedd
_
FILE_NAME TEXT The    full    path    name    of    a   file
FOREGROUND     PIXEL     T{  A  list  of  pixel  values   T}
HOST_NAME TEXT (see             section             4.1.2.9)
INSERT_PROPERTY     NULL (see        section        2.6.3.3)
INSERT_SELECTION    NULL (see        section        2.6.3.2)
LENGTH    INTEGER   T{ The number of bytes in the selection6
T}  LINE_NUMBER    SPAN T{ The start and end line numbers T}
LIST_LENGTH    INTEGER   T{ The number of disjoint parts  of
the  selection T} MODULE    TEXT T{ The name of the selected
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
TARGETS   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.  _P_o_r_t_a_b_l_e _D_o_c_u_m_e_n_t  _F_o_r_m_a_t
     _R_e_f_e_r_e_n_c_e  _M_a_n_u_a_l_.   Reading,  MA, Addison-Wesley, ISBN
-----------
  5 Earlier versions of this document  erroneously
specified  that  conversion  of  the PIXMAP target
returns a property of  type  DRAWABLE  instead  of
PIXMAP.   Implementors should be aware of this and
may want to support the DRAWABLE type as  well  to
allow for compatibility with older clients.
  6 The targets ENCAPSULATED_POSTSCRIPT and 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
requestor has no way of knowing which, if any,  of
these targets corresponds to the result of LENGTH.
Clients are advised that no guarantees can be made
about  the  result  of a conversion to LENGTH; its
use is thus deprecated.



                             1166





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


     0-201-62628-4.

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

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

It is expected that this table will grow over time.

Selection owners are required to support the following  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
         requested conversions have been performed.

    -    If the owner fails to convert the target  named  by
         an atom in the MULTIPLE property, it should replace
         that atom in the property with
    The entries in a MULTIPLE property must be processed  in
    the  order  they  appear  in  the property.  For further
    information, see section 2.6.3.

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

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



                             1177





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


    targets:  a  data  target  and  the  DELETE target.  The
    DELETE target will still be processed even if  the  con-
    version 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
    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
accepted.  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



                             1188





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


doing so means for its internal data structures).

When  the owner of a selection receives a request to convert
it to INSERT_PROPERTY, it should insert the  property  named
in the 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
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
semantics assigned by convention, and these are reviewed  in
the following sections.

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

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

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

l c l.  _
TTyyppee AAttoomm FFoorrmmaatt    SSeeppaarraattoorr
_
APPLE_PICT     8    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
WINDOW    32   Fixed-size
_



                             1199





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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.

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

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

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

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

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

There  are  some  text  objects where the source or intended
user, as the case may be, does not have a specific character
set  for the text, but instead merely requires a zero-termi-
nated sequence of bytes with no other restriction;  no  ele-
ment  of  the  selection  mechanism may assume that any byte
value is forbidden or that any two differing  sequences  are
equivalent.8  For these objects, the type C_STRING should be
used.  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.
-----------
  8 Note that this is different from STRING, where
many  byte  values  are  forbidden,  and from COM-
POUND_TEXT,  where,  for  example,  inserting  the
sequence  27, 40, 66  (designate ASCII into GL) at
the start does not alter the meaning.



                             2200





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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
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-
    request-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.
-----------
  9 These properties were called INCREMENTAL in an
earlier  draft.   The  protocol for using them has
changed, and so the name has changed to avoid con-
fusion.



                             2211





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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
returned  type  in  the table in section 2.6.2 is one of the
DRAWABLE types should expect to convert also into  the  fol-
lowing targets (using the MULTIPLE mechanism):

+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
selection, named using the conventions described in sections
1.2.3  and  1.2.6.   A  client  that manages multiple shared
resources (or groups of resources) should take ownership  of
a selection for each one.

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

Before  a manager takes ownership of a manager selection, it
should use the request to check  whether  the  selection  is



                             2222





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


already  owned by another client, and, where appropriate, it
should ask the user if the new manager  should  replace  the
old  one.   If  so, it may then take ownership of the 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
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
selection.  For example, a window manager  losing  ownership
of  WM_S2  must deselect from on the root window of screen 2
before destroying the window that owned WM_S2.

When the new manager notices  that  the  window  owning  the
selection  has been destroyed, it knows that it can 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
destroyed.   Clients  are  warned  that  after  doing  a and
selecting for they should do a  again  to  ensure  that  the
owner  did  not change after initially getting the selection
owner and before selecting for

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

l lw(4.5i) .  _
AArrgguummeenntt  VVaalluuee
_
destination:   T{  the  root window of screen 0, or the root
window of the appropriate screen if the manager is  managing
a    screen-specific    resource   T}   propagate:     False
event-mask:    T{  T}  event:    T{   T}       type: MANAGER
    format:    32     T{        data[0]:10    T}   timestamp



                             2233





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


    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
_


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
retrieves the data at some later time.

The cut buffers consist of eight properties on the  root  of
screen  zero,  named  by the predefined atoms CUT_BUFFER0 to
CUT_BUFFER7.  These properties must, at present,  have  type
STRING  and  format  8.   A  client that uses the cut buffer
mechanism must initially ensure that  all  eight  properties
exist  by using requests to append zero-length data to each.

A client that stores data in  the  cut  buffers  (an  owner)
first  must  rotate  the  ring of buffers by plus 1 by using
requests to rename each  buffer;  that  is,  CUT_BUFFER0  to
CUT_BUFFER1,    CUT_BUFFER1   to   CUT_BUFFER2,   ...,   and
CUT_BUFFER7 to CUT_BUFFER0.  It then  must  store  the  data
into CUT_BUFFER0 by using a request in mode

A client that obtains data from the cut buffers should use a
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
rotated only when requested by explicit user action.   Users
depend  on  their  mental  model of cut buffer operation and
need to be able to identify operations that transfer data to
and fro.

To permit window managers to perform their role of mediating
the competing demands for resources such  as  screen  space,
the clients being managed must adhere to certain conventions
-----------
  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.



                             2244





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


and must expect the window managers to do  likewise.   These
conventions  are  covered  here  from  the client's point of
view.

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

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

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

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

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:





                             2255





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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

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

A client's _t_o_p_-_l_e_v_e_l _w_i_n_d_o_w is a window whose override-redi-
rect attribute is 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
regard its top-level window as being in one of three states:

+o   Normal

+o   Iconic

+o   Withdrawn

Newly created windows start in the Withdrawn state.  Transi-
tions  between  states  happen  when the top-level window is



                             2266





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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  man-
agers  will  assume  values  they find convenient for any of
these properties that are not supplied; clients that  depend
on  particular values must explicitly supply them.  The win-
dow manager  will  not  change  properties  written  by  the
client.

The  window manager will examine the contents of these prop-
erties when the window makes the transition from  the  With-
drawn  state  and  will  monitor some properties for changes
while the window is in the Iconic or Normal state.  When the
client  changes one of these properties, it must use 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
between clients and window managers should take place  using
separate properties.  The only exception to this rule is the
WM_PROTOCOLS property, which may be of arbitrary length  and
which  may contain atoms representing private protocols (see
section 4.1.2.7).

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

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



                             2277





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


property.  The type atoms to be used for  this  purpose  are
described in section 2.7.1.

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

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

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

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).  _
FFiieelldd     TTyyppee CCoommmmeennttss
__
flags     CARD32    (see  the next table) pad  4*CARD32  For
backwards  compatibility   min_width INT32     If   missing,
assume   base_width   min_height     INT32     If   missing,
assume  base_height   max_width INT32   max_height     INT32
width_inc INT32                         height_inc     INT32
min_aspect     (INT32,INT32)    max_aspect     (INT32,INT32)
base_width     INT32     If    missing,   assume   min_width
base_height    INT32     If   missing,   assume   min_height
win_gravity    INT32     T{ If missing, assume T}
_





                             2288





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


The WM_SIZE_HINTS.flags bit definitions are as follows:

lw(1i) nw(.5i) lw(3i).  _
NNaammee VVaalluuee     FFiieelldd
__
T{ T}   1    User-specified x, y T{ T}   2    User-specified
width, height  T{  T}   4    Program-specified  position  T{
T}   8    Program-specified size T{ T}   16   Program-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-



                             2299





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


negative integers _i and _j:


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


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


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

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

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


The WM_HINTS.flags bit definitions are as follows:







                             3300





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


lw(1.5i) nw(.5i) lw(1.5i).  _
NNaammee VVaalluuee     FFiieelldd
__
T{    T}   1    input    T{    T}   2    initial_state    T{
T}   4    icon_pixmap    T{     T}   8    icon_window     T{
T}   16   icon_x   &   icon_y   T{   T}   32   icon_mask  T{
T}   64   window_group T{ T}   128  (this bit  is  obsolete)
T{ T}   256  urgency
_


Window managers are free to assume convenient values for all
fields of the WM_HINTS property if a window is mapped  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
regard the client's top-level window  as  being  in  one  of
three states:

+o   Normal

+o   Iconic

+o   Withdrawn

The  semantics  of  these  states  are  described in section
4.1.4.  Newly created windows start in the Withdrawn  state.
Transitions between states happen when a top-level window is
mapped and 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.  _
SSttaattee     VVaalluuee     CCoommmmeennttss
__
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:



                             3311





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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

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

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

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-





                             3322





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


tion 4.1.2.7.

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
action when the state of the flag changes.  The flag is oth-
erwise 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
resources for the application or as identifying information.
This  property  must  be  present when the window leaves the
Withdrawn state and may be changed only while the window  is
in  the  Withdrawn  state.   Window managers may examine the
property only when they start up and when the window  leaves
the  Withdrawn  state,  but  there  should  be no need for a
client to change its state dynamically.

The two strings, respectively, are:

+o   A string that  names  the  particular  instance  of  the
    application  to  which  the client that owns this window
    belongs.  Resources that are specified by instance  name
    override any resources that are specified by class name.
-----------
  11 This obsolete protocol was described  in  the
July  27, 1988, draft of the ICCCM.  Windows using
it can also be  detected  because  their  WM_HINTS
properties are 4 bytes longer than expected.  Win-
dow managers are free to support clients using the
obsolete  protocol  in  a  backwards compatibility
mode.



                             3333





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


    Instance names can be specified by the user in an  oper-
    ating-system  specific manner.  On POSIX-conformant sys-
    tems, the following conventions are used:

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

    -    Otherwise,     if    the    environment    variable
         RESOURCE_NAME is set, its value will be used as the
         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.
    Resources  that  are  specified  by  class  apply to all
    applications that have the same class name.  Class names
    are  specified  by  the application writer.  Examples of
    commonly used class  names  include:  "Emacs",  "XTerm",
    "XClock", "XLoad", and so on.

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

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.



                             3344





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


All  the  protocols  in which a client can volunteer to take
part involve the window manager sending the client  a  event
and  the  client  taking appropriate action.  For details of
the contents of the event, see section 4.2.8.  In each case,
the  protocol  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.  _
PPrroottooccooll  SSeeccttiioonn   PPuurrppoossee
__
WM_TAKE_FOCUS  4.1.7     Assignment    of    input     focus
WM_SAVE_YOURSELF    Appendix  C Save  client  state  request
(deprecated) WM_DELETE_WINDOW    4.2.8.1   Request to delete
top-level window
_

It is expected that this table will grow over time.

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.




                             3355





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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

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


The following table lists the WM_STATE.state values:

l n.  _
SSttaattee     VVaalluuee
_
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
defined in the above table are reserved for  use  by  the  X
Consortium.

The  state  field describes the window manager's idea of the
state the window is in, which may  not  match  the  client's
idea as 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



                             3366





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


not  necessarily the same window as the icon window that the
client may have specified in  its  WM_HINTS  property.   The
WM_STATE  icon  may  be a window that the window manager has
supplied and that contains the client's icon pixmap,  or  it
may be an ancestor of the client's icon window.

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


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

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

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




                             3377





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

+o   Normal  ->  Iconic  -  The client should send a event as
    described 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
ancestor, the client's window is by definition in the Iconic
state and must also be unmapped.  Clients can select for  on
their  top-level windows to track transitions between Normal
and Iconic states.  Receipt of a event will indicate a tran-
sition  to  the  Normal  state, and receipt of an event will
indicate a transition to the Iconic state.

When changing the state of  the  window  to  Withdrawn,  the
client  must  (in  addition  to unmapping the window) send a
synthetic event by using a request with the following  argu-
ments:

l lw(3.5i).  _
AArrgguummeenntt  VVaalluuee
__
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
expressed.  For compatibility with obsolete clients,  window
managers  should  trigger  the  transition  to the Withdrawn



                             3388





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


state on the real rather than waiting for the synthetic one.
They  should  also  trigger the transition if they receive a
synthetic on a window for which they have not yet received a
real

When  a  client  withdraws a window, the window manager will
then update or remove the WM_STATE property as described  in
section  4.1.3.1.  Clients that want to re-use a client 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
becomes completely obscured even though  mapped  (and  thus,
perhaps  a  waste  of  time  to  update) and a event when it
becomes even partly viewable.  When a window makes a transi-
tion from the Normal state to either the Iconic or the With-
drawn 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
-----------
  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



                             3399





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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.

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
requested size or location and must be prepared to deal with
any  size  and  location.   If the window manager decides to
respond 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



                             4400





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


    client  does  receive  a real event, the synthetic event
    will follow the real one.

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

    A client that has selected for  events  will  receive  a
    real event.  Note that the coordinates in this event are
    relative to the parent, which may not be the root if the
    window   has  been  reparented.   The  coordinates  will
    reflect the actual border width of the window (which the
    window  manager  may  have changed).  The request can be
    used to convert the coordinates if required.

The general rule is that coordinates in real events  are  in
the  parent's  space;  in  synthetic events, they are in the
root space.  Clients cannot  distinguish  between  the  case
where  a top-level window is resized and moved from the case
where the window is 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
position in this event.  If the client receives a  or  event
on  the window (or on any descendant), the client can deduce
the top-level window's position from the difference  between
the  (event-x,  event-y) and (root-x, root-y) coordinates in
these events.  Only when the position is  unknown  does  the
client  need  to  use  the 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



                             4411





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


sibling field.

Clients  that must position themselves in the stack relative
to some window that was originally a  sibling  must  do  the
request  (in  case  they  are running under a nonreparenting
window manager), be prepared to deal with a resulting error,
and then follow with a synthetic event by invoking a request
with the following arguments:

l lw(3.5i).  _
AArrgguummeenntt  VVaalluuee
__
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.  _
AAttttrriibbuuttee PPrriivvaattee ttoo CClliieenntt
__
Background  pixmap   Yes  Background   pixel    Yes   Border
pixmap  Yes  Border  pixel   Yes  Bit  gravity    Yes Window
gravity No Backing-store  hint  Yes  Save-under  hint     No
Event  mask   No Do-not-propagate mask    Yes Override-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.





                             4422





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


+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 select-
    ing for.  There are  some  events  for  which  only  one
    client  at  a  time  may  select, but the window manager
    should not select for them on any of the  client's  win-
    dows.

+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
    input  and explicitly sets the input focus, even when it
    is in windows the client does not own.  An example would
    be  a client with a scroll bar that wants to allow users
    to scroll the window without disturbing the input  focus
    even if it is in some other window.  It wants to acquire
    the input focus when the user  clicks  in  the  scrolled
    region  but  not  when the user clicks in the scroll bar
    itself.  Thus, it wants to prevent  the  window  manager
    from setting the input focus to any of its windows.

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

l l l l c c.  _
IInnppuutt MMooddeell    IInnppuutt FFiieelldd    WWMM__TTAAKKEE__FFOOCCUUSS
__
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



                             4433





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


l l l l c c.  _
IInnppuutt MMooddeell    IInnppuutt FFiieelldd    WWMM__TTAAKKEE__FFOOCCUUSS
__
T} T{ Globally Active T}   T{ T}   T{ Present T}
_


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

Clients  that  use  a request must set the time field to the
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
request 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
described  in  section  4.2.8)  with  WM_TAKE_FOCUS  in  its
data[0] field and  a  valid  timestamp  (i.e.,  not  in  its
data[1]  field.  If they want the focus, they should respond
with a request with its window field set to  the  window  of
theirs  that  last  had  the input focus or to their default
input window, and the time field set to the timestamp in the
message.  For further information, see section 4.2.7.

A  client  could  receive WM_TAKE_FOCUS when opening from an
icon or when the user  has  clicked  outside  the  top-level



                             4444





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


window  in an area that indicates to the window manager that
it should assign the focus (for  example,  clicking  in  the
headline bar can be used to assign the focus).

The  goal  is to support window managers that want to assign
the input focus to a top-level window in such a way that the
top-level  window either can assign it to one of its subwin-
dows or can decline the offer of the focus.  For example,  a
clock  or  a text editor with no currently open frames might
not want to take focus even though the window manager gener-
ally believes that clients should take the input focus after
being deiconified or raised.

Clients that set the input focus need to decide a value  for
the  revert-to  field  of  the request.  This determines the
behavior of the input focus if the window the focus has been
set  to  becomes  not viewable.  The value can be any of the
following:

+o   - In general, clients should use this value when 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
    becoming 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
receive 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
install  or uninstall colormaps themselves (except under the
circumstances noted below).  When a client's top-level  win-
dow  gets  the  colormap focus (as a result of whatever col-
ormap focus policy is implemented by  the  window  manager),



                             4455





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


the  window  manager  will  ensure  that  one or more of the
client's colormaps are installed.

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

Clients  that  create  windows  can use the value 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
alternative  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 man-
agers 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
concerned and to ensure that colormaps are only installed if
the windows that need them  are  visible.   The  alternative
design allows for neither of these policies.  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



                             4466





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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
described  above  and let the window manager handle colormap
installation.  However, clients  are  permitted  to  perform
colormap  installation  on  their  own  while  they have the
pointer grabbed.  A client performing colormap  installation
must  notify the window manager prior to the first installa-
tion.  When the client has finished its  colormap  installa-
tion,  it  must  also notify the window manager.  The client
notifies the window manager by issuing a  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



                             4477





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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  win-
dow  manager  may  be  left  in  a  state where its colormap
installation policy is suspended.  Window manager  implemen-
tors  may  want  to implement a feature that resets colormap
installation 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
    unlikely  to display icon pixmaps.  Window managers usu-
    ally 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.





                             4488





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


Clients should observe the following conventions about their
icon windows:

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

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

3.   The  icon window should use the root visual and default
     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.





                             4499





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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-redi-
     rect  windows, since the window manager is not managing
     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
     receives  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
enforce.

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

One  of  the  windows (that is, the one the others point to)
will be the group leader and will carry the group as opposed
to the 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



                             5500





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

+o   The parent value returned by a request will no longer be
    the value supplied  to  the  request  that  created  the
    reparented  window.   There  should  be  no need for the
    client to be aware of the  identity  of  the  window  to
    which the top-level window has been reparented.  In par-
    ticular, a client that wishes  to  create  further  top-
    level  windows  should  continue  to use the root as the
    parent for these new windows.

+o   The server will interpret the  (x,y)  coordinates  in  a
    request  in the new parent's coordinate space.  In fact,
    they usually will  not  be  interpreted  by  the  server
    because  a  reparenting window manager usually will have
    intercepted  these  operations  (see   section   4.2.2).
    Clients  should  use the root coordinate 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
reparented window will be placed in the save-set of the par-
ent window.  This means that the reparented window will  not
be  destroyed  if  the window manager terminates and will be
remapped if it was unmapped.  Note that this applies to  all
client windows the window manager reparents, including tran-
sient windows and client icon windows.




                             5511





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

The  possibility that a request may be redirected means that
a client cannot assume  that  any  redirectable  request  is
actually performed when the request is issued or is actually
performed at all.  The requests that may be  redirected  are
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
window.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
sequence 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.


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



                             5522





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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:







                             5533





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


l l.  _
AArrgguummeenntt  VVaalluuee
__
destination:   The  client's  window  propagate:     T{   T}
event-mask:    T{ T}
_


The  client  can  elect  to  receive  notification  of being
resized by selecting for events on  its  top-level  windows.
It  will receive a event.  The size information in the event
will be correct, but the location will be in the parent win-
dow (which may not be the root).

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

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

The client can elect to be notified of these  state  changes
by  selecting  for  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
unless they have set  WM_TAKE_FOCUS  in  their  WM_PROTOCOLS
property and have done one of the following:

+o   Set the input field of WM_HINTS to and actually have the
    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



                             5544





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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:


  _f_o_c_u_s: WINDOW or or
  _r_e_v_e_r_t_-_t_o:
  _t_i_m_e: TIMESTAMP or


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

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

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

Top-level  windows  with a WM_PROTOCOLS property may be sent
events specific to the protocols named by the atoms  in  the
property  (see  section  4.1.2.7).   For  all protocols, the
events have the 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.  _
AArrgguummeenntt  VVaalluuee
__
destination:   The  client's  window  propagate:     T{   T}
event-mask:    () empty event:    As specified by the proto-
col
_




                             5555





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


Clients, usually  those  with  multiple  top-level  windows,
whose server connection must survive the deletion of some of
their   top-level   windows,   should   include   the   atom
WM_DELETE_WINDOW  in  the WM_PROTOCOLS property on each such
window.  They will receive a event as described above  whose
data[0] field is WM_DELETE_WINDOW.

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

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

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

If the user aborts the deletion during the confirmation 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



                             5566





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


height specified in the  event  in  a  timely  fashion.   To
ensure  that  the  resize will actually happen at this stage
instead of being intercepted and 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

+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_n, where _n is the  screen
number,  as  described  in  section  1.2.6.  Window managers
should comply with the conventions for "Manager  Selections"
described  in  section 2.8.  The intent is for clients to be
able to request a variety  of  information  or  services  by
issuing  conversion requests on this selection.  Window man-
agers should support conversion of the following  target  on
their manager selection:


l l lw(3.5i) .  _
AAttoomm TTyyppee DDaattaa RReecceeiivveedd
_
VERSION   INTEGER   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  _X_l_i_b  _-  _C  _L_a_n_g_u_a_g_e  _X
_I_n_t_e_r_f_a_c_e).


-----------
  15 As a special case,  clients  not  wishing  to
implement  a  selection request may simply issue a
request on the appropriate  WM_S_n  selection.   If
this  selection  is owned, clients may assume that
the window manager complies with ICCCM version 2.0
or later.



                             5577





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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


This section contains some conventions for clients that par-
ticipate in session management.  See  _X  _S_e_s_s_i_o_n  _M_a_n_a_g_e_m_e_n_t
_P_r_o_t_o_c_o_l  for  further details.  Clients that do not support
this  protocol  cannot  expect  their  window  state  (e.g.,
WM_STATE,  position,  size,  and  stacking order) to be 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
    encoded using ISO 8859-1

All top-level, nontransient windows created by a  client  on
the   same   display  as  the  client  leader  must  have  a
WM_CLIENT_LEADER property. This property contains  a  window
ID  that  identifies  the  client leader window.  The client
leader window must have a WM_CLIENT_LEADER property 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





                             5588





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


+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
require this unique ID to restore geometry information  from
a  previous  session, or a workspace manager could use it to
restore  information  about  which  windows  are  in   which
workspace.  A client may optionally provide a WM_WINDOW_ROLE
property to uniquely identify  a  window  within  the  scope
specified   above.   The  combination  of  SM_CLIENT_ID  and
WM_WINDOW_ROLE can be used  by  other  clients  to  uniquely
identify a window across sessions.

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

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

+o   Be of type STRING

+o   Be of format 8

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

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



                             5599





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

+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
     receive a WM_TAKE_FOCUS message.  They should  set  the
     input field of the WM_HINTS structure to

3.   In  addition,  clients  should use the timestamp of the
     event that caused them to  attempt  to  set  the  input
     focus as the time field on the request, not

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



                             6600





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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
establish button and key grabs only  on  windows  that  they
own.

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

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

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

More typically, a window manager should add to, rather  than
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




                             6611





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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  sec-
tion  14.3  of _X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e for conventions
connected with sharing standard colormaps.  They should look
for  and  create  the properties described there on the root
window of the appropriate screen.

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

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


When deleting or replacing an RGB_COLOR_MAP, it is not  suf-
ficient  to delete the property; it is important to free the
associated  colormap  resources  as  well.   If  kill_id  is
greater than one, the resources should be freed by issuing a
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
attempt should be made to free the resources.  A client that
creates an RGB_COLOR_MAP for which the colormap resource  is
created  specifically for this purpose should set kill_id to
one (and can create more than  one  such  standard  colormap
using  a  single  connection).   A  client  that  creates an
RGB_COLOR_MAP for which the colormap resource is  shared  in
some  way (for example, is the default colormap for the root
window) should create an  arbitrary  resource  and  use  its



                             6622





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


resource ID for kill_id (and should create no other standard
colormaps on the connection).  If an RGB_COLOR_MAP  property
is  too  short  to  contain  the  visual_id field, it can be
assumed that the visual_id is the root visual of the  appro-
priate screen.  If an RGB_COLOR_MAP property is too short to
contain the kill_id field, a value of zero can be assumed.

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

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



                             6633





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


          request,  "Please  paint  Pause on the Scroll Lock
          key."  Clients should not use requests.

If a client succeeds in changing the keyboard mapping table,
all  clients  will receive events.  There is no mechanism to
avoid 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
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
    includes XK_Meta_L or XK_Meta_R, it should use that mod-
    ifier 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.



                             6644





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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
assignments  to  the five nonpreassigned modifiers when they
are no longer being used.  The user must use or  some  other
utility to deassign obsolete modifier mappings by hand.

When  a client succeeds in performing a request, all clients
will receive events.  There is no mechanism  for  preventing
these events from being received.  A client that uses one of
the 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
reinstall the modifier.

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
expense of having the color perceived  by  the  user  remain
unknowable  through  the  protocol.  Color names were origi-
nally designed to provide  access  to  a  device-independent
color  database by having the server vendor tune the defini-
tions of the colors  in  that  textual  database.   Unfortu-
nately,  this  still  does not provide the client any way of
using an existing  device-independent  color,  nor  for  the
client  to  get  device-independent  color  information back
about colors that it has selected.

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

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





                             6655





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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

Device  color  characterization  is  defined by the name and
contents of two window  properties  that,  together,  permit
converting between CIE XYZ space and linear RGB device space
(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
intensity,  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:






                             6666





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


center; c s s c c c l l l.  XDCCC_LINEAR_RGB_MATRICES  prop-
erty contents
_
FFiieelldd     TTyyppee CCoommmmeennttss
_
@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


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

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

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


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



                             6677





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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
_
FFiieelldd     TTyyppee CCoommmmeennttss
_
VisualID0 CARD Most    significant   portion   of   VisualID
VisualID1 CARD Exists if and only if the property format  is
8  VisualID2 CARD Exists  if and only if the property format
is 8 VisualID3 CARD T{ Least significant portion, exists  if
and  only  if  the property format is 8 or 16 T} type CARD 0
for this type of correction count     CARD Number of  tables
following (either 1 or 3) length    CARD Number of pairs - 1
following in this table value     CARD X Protocol RGB  value
intensity CARD Interpret  as  a number @0~<=~intensity~<=~1@
...  ...  Total of _l_e_n_g_t_h_+_1 pairs of value/intensity  values
lengthg   CARD T{  Number  of  pairs  -  1 following in this
table (if and only if _c_o_u_n_t is 3) T} value     CARD X Proto-
col   RGB   value   intensity CARD Interpret   as  a  number
@0~<=~intensity~<=~1@ ...  ...  Total of _l_e_n_g_t_h_g_+_1 pairs  of
value/intensity values lengthb   CARD T{ Number of pairs - 1
following in this table (if and  only  if  _c_o_u_n_t  is  3)  T}
value     CARD X Protocol RGB value intensity CARD Interpret
as  a  number   @0~<=~intensity~<=~1@   ...  ...  Total   of
_l_e_n_g_t_h_b_+_1 pairs of value/intensity values
_


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

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

 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:




                             6688





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


center; c s s c c  c  l  l  l.   XDCCC_LINEAR_RGB_CORRECTION
Property Contents for Type 1 Correction
_
FFiieelldd     TTyyppee CCoommmmeennttss
_
VisualID0 CARD Most    significant   portion   of   VisualID
VisualID1 CARD Exists if and only if the property format  is
8  VisualID2 CARD Exists  if and only if the property format
is 8 VisualID3 CARD T{ Least significant portion, exists  if
and  only  if  the property format is 8 or 16 T} type CARD 1
for this type of correction count     CARD Number of  tables
following  (either 1 or 3) length    CARD Number of elements
- 1 following in this table  intensity CARD Interpret  as  a
number  @0~<=~intensity~<=~1@  ...  ...  Total  of  _l_e_n_g_t_h_+_1
intensity elements lengthg   CARD T{ Number of elements -  1
following  in  this  table  (if  and  only if _c_o_u_n_t is 3) T}
intensity CARD Interpret as a  number  @0~<=~intensity~<=~1@
...  ...  Total     of    _l_e_n_g_t_h_g_+_1    intensity    elements
lengthb   CARD T{ Number of elements - 1 following  in  this
table  (if  and only if _c_o_u_n_t is 3) T} intensity CARD Inter-
pret as a number  @0~<=~intensity~<=~1@  ...  ...  Total  of
_l_e_n_g_t_h_b_+_1 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 _X _S_e_s_s_i_o_n _M_a_n_a_g_e_m_e_n_t _P_r_o_t_o_-
_c_o_l for information on session  management,  and  to  _I_n_t_e_r_-
_C_l_i_e_n_t  _E_x_c_h_a_n_g_e _P_r_o_t_o_c_o_l for information on general-purpose
communication among clients.

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






                             6699





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


          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.










































                             7700





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33




                         AAppppeennddiixx AA


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

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



                             7711





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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

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





                             7722





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


+o   The conventions in Section 14.3.1. of _X_l_i_b _- _C  _L_a_n_g_u_a_g_e
    _X  _I_n_t_e_r_f_a_c_e  regarding properties of type RGB_COLOR_MAP
    have been changed, but clients that use the earlier con-
    ventions  can be detected because their properties are 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
    requests.

+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
    sequence may need to be  modified,  especially  if  they
    were interacting with the user during the shutdown.

+o   A  kill_id field has been added to RGB_COLOR_MAP proper-
    ties.  Clients using earlier conventions can be detected
    by  the  size of their RGB_COLOR_MAP properties, and the



                             7733





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


    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.




                             7744





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


+o   [P28] Added a  recommended  technique  for  setting  the
    input 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
    Appendix C.

+o   References to the never-forthcoming _W_i_n_d_o_w  _a_n_d  _S_e_s_s_i_o_n
    _M_a_n_a_g_e_r _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l have been removed.

+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
releasing the final edition of Version 2.0 with X11R6.





                             7755





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


+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 _X _S_e_s_s_i_o_n  _M_a_n_a_g_e_-
    _m_e_n_t _P_r_o_t_o_c_o_l.

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










































                             7766





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33




                           AAppppeennddiixx BB


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

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


















                             7777





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33




                           AAppppeennddiixx CC


This appendix contains obsolete conventions for session man-
agement using X properties and  messages.   The  conventions
described  here  are  deprecated  and are described only for
historical interest.  For  further  information  on  session
management, see _X _S_e_s_s_i_o_n _M_a_n_a_g_e_m_e_n_t _P_r_o_t_o_c_o_l_.

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
machine  running  the  client.   On POSIX-conformant systems
using ISO Latin-1 characters for their  command  lines,  the
property should:

+o   Be of type STRING

+o   Contain a list of null-terminated strings

+o   Be initialized from argv

    Other  systems  will need to set appropriate conventions
    for the type  and  contents  of  WM_COMMAND  properties.
    Window  and  session  managers  should  not  assume that
    STRING is the type of WM_COMMAND or that  they  will  be
    able to understand or display its contents.

Note  that WM_COMMAND strings are null-terminated and differ
from the general  conventions  that  STRING  properties  are
null-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.




                             7788





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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



                             7799





IInntteerr--CClliieenntt CCoommmmuunniiccaattiioonn CCoonnvveennttiioonnss      XX1111,, RReelleeaassee 66..33


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.  _
NNaammee TTyyppee FFoorrmmaatt    SSeeee SSeeccttiioonn
__
WM_CLIENT_MACHINE   TEXT      4.1.2.9
WM_COMMAND     TEXT      C.1.1
WM_STATE  WM_STATE  32   4.1.3.1
_









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



                             8800


