Inter-Client Communication Conventions Manual

X Consortium Standard

David Rosenthal

Sun Microsystems, Inc.

Edited by

Stuart W. Marks

SunSoft, Inc.

X Version 11, Release 7.7

Version 2.0

Copyright © 1988, 1991, 1993, 1994 X Consortium

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation 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 PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X
CONSORTIUM 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 Consortium 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.

X Window System is a trademark of The Open Group.

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

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

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents

Preface to Version 2.0
Preface to Version 1.1
1. Introduction
    Evolution of the Conventions
    Atoms
        What Are Atoms?
        Predefined Atoms
        Naming Conventions
        Semantics
        Name Spaces
        Discriminated Names
2. Peer-to-Peer Communication by Means of Selections
    Acquiring Selection Ownership
    Responsibilities of the Selection Owner
    Giving Up Selection Ownership
        Voluntarily Giving Up Selection Ownership
        Forcibly Giving Up Selection Ownership
    Requesting a Selection
    Large Data Transfers
    Use of Selection Atoms
        Selection Atoms
        Target Atoms
        Selection Targets with Side Effects
    Use of Selection Properties
        TEXT Properties
        INCR Properties
        DRAWABLE Properties
        SPAN Properties
    Manager Selections
3. Peer-to-Peer Communication by Means of Cut Buffers
4. Client-to-Window-Manager Communication
    Client's Actions
        Creating a Top-Level Window
        Client Properties
        Window Manager Properties
        Changing Window State
        Configuring the Window
        Changing Window Attributes
        Input Focus
        Colormaps
        Icons
        Pop-up Windows
        Window Groups
    Client Responses to Window Manager Actions
        Reparenting
        Redirection of Operations
        Window Move
        Window Resize
        Iconify and Deiconify
        Colormap Change
        Input Focus
        ClientMessage Events
        Redirecting Requests
    Communication with the Window Manager by Means of Selections
    Summary of Window Manager Property Types
5. Session Management and Additional Inter-Client Exchanges
    Client Support for Session Management
    Window Manager Support for Session Management
    Support for ICE Client Rendezvous
6. Manipulation of Shared Resources
    The Input Focus
    The Pointer
    Grabs
    Colormaps
    The Keyboard Mapping
    The Modifier Mapping
7. Device Color Characterization
    XYZ <-> RGB Conversion Matrices
    Intensity (dA RGB Value Conversion
8. Conclusion
    The X Registry
A. Revision History
    The X11R2 Draft
    The July 27, 1988, Draft
    The Public Review Drafts
    Version 1.0, July 1989
    Version 1.1
    Public Review Draft, December 1993
    Version 2.0, April 1994
B. Suggested Protocol Revisions
C. Obsolete Session Manager Conventions
    Properties
        WM_COMMAND Property
        WM_CLIENT_MACHINE Property
    Termination
    Client Responses to Session Manager Actions
        Saving Client State
        Window Deletion
    Summary of Session Manager Property Types

Preface to Version 2.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 members of the X Consortium's
wmtalk working group. The following 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

Preface to Version 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 wmtalk 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

Chapter 1. Introduction

Table of Contents

Evolution of the Conventions
Atoms
    What Are Atoms?
    Predefined Atoms
    Naming Conventions
    Semantics
    Name Spaces
    Discriminated Names

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 Window System Protocol, Version 11 may operate correctly in
isolation but may not coexist properly with others sharing the same server.

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

  • Selection mechanism

  • Cut buffers

  • Window manager

  • Session manager

  • Manipulation of shared resources

  • Device color characterization

This document proposes suitable conventions without attempting to enforce any
particular user interface. To permit clients written in different languages to
communicate, these conventions are expressed solely in terms of protocol
operations, 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 documents.

Evolution of the Conventions

In the interests of timely acceptance, the Inter-Client Communication
Conventions Manual (ICCCM) covers only a minimal set of required conventions.
These conventions will be added to and updated as appropriate, based on the
experiences of the X Consortium.

As far as possible, these conventions are upwardly compatible with those in the
February 25, 1988, draft that was distributed with the X Version 11, Release 2,
of the software. In some 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 incorporating these changes
is undertaken, it is anticipated that the ICCCM will need to be revised.
Because it is difficult to ensure that clients and servers are upgraded
simultaneously, 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 conventions appropriate to protocol minor
revision n + 1 if the server supports both.

Atoms

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.

What Are Atoms?

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

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

To allow a fixed-size representation, a protocol request ( InternAtom ) 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 ( GetAtomName ).

Predefined Atoms

The protocol specifies a number of atoms as being predefined:

    Predefined atoms are not strictly necessary and may not be useful in all
    environments, but they will eliminate many InternAtom 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 InternAtom requests, which require a
handshake, can be assumed a priori.

Language interfaces should probably cache the atom-name mappings 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.

Naming Conventions

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

Semantics

The core protocol imposes no semantics on atoms except as they are used in
FONTPROP structures. For further information on FONTPROP semantics, see the X
Logical Font Description Conventions.

Name Spaces

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.

┌──────────────────┬─────────┬───────────────────────────────────────┐
│Space             │Briefly  │Examples                               │
├──────────────────┼─────────┼───────────────────────────────────────┤
│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, ...            │
├──────────────────┼─────────┼───────────────────────────────────────┤
│ClientMessage type│         │WM_SAVE_YOURSELF, _DEC_SAVE_EDITS, &...│
└──────────────────┴─────────┴───────────────────────────────────────┘

Discriminated Names

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

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

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

If name is a descriptive portion for the name, d is a decimal 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:

┌─────────────────────┬───────┬──────────────────────┐
│Name Discriminated by│Form   │Example               │
├─────────────────────┼───────┼──────────────────────┤
│screen number        │name_Sd│WM_COMMS_S2           │
├─────────────────────┼───────┼──────────────────────┤
│X resource           │name_Rx│GROUP_LEADER_R1234ABCD│
└─────────────────────┴───────┴──────────────────────┘

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

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

Ud     (e.g.,  U0  U1  U2  U3  ...)

if the names stand totally alone, and the form:

name_Ud     (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 Ud 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 window is almost certainly not.)

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

    FOO_R12345678_U23

    Rationale

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


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

^[1] The comment in the protocol specification for InternAtom that ISO Latin-1
encoding should be used is in the nature of a convention; the server treats the
string as a byte sequence.

Chapter 2. Peer-to-Peer Communication by Means of Selections

Table of Contents

Acquiring Selection Ownership
Responsibilities of the Selection Owner
Giving Up Selection Ownership
    Voluntarily Giving Up Selection Ownership
    Forcibly Giving Up Selection Ownership
Requesting a Selection
Large Data Transfers
Use of Selection Atoms
    Selection Atoms
    Target Atoms
    Selection Targets with Side Effects
Use of Selection Properties
    TEXT Properties
    INCR Properties
    DRAWABLE Properties
    SPAN Properties
Manager Selections

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. Use of Selection Atoms.
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 selection, and the requestor receives it. A
requestor wishing to obtain the value of a selection provides the following:

  • The name of the selection

  • The name of a property

  • A window

  • The atom representing the data type required

  • Optionally, some parameters for the request

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

  • Convert the contents of the selection to the requested data type

  • Place this data in the named property on the named window

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

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

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

Acquiring Selection Ownership

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

SetSelectionOwner

selection: ATOM
owner: WINDOW or None
time: TIMESTAMP or CurrentTime

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 CurrentTime, 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]

    Convention

    Clients attempting to acquire a selection must set the time value of the
    SetSelectionOwner request to the timestamp of the event triggering the
    acquisition attempt, not to CurrentTime. A zero-length append to a property
    is a way to obtain a timestamp for this purpose; the timestamp is in the
    corresponding PropertyNotify event.

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

Because clients cannot name other clients directly, the specified owner window
is used to refer to the owning client in the replies to GetSelectionOwner, in
SelectionRequest and SelectionClear 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 GetSelectionOwner, which is
defined as follows:

GetSelectionOwner

selection: ATOM
->
owner: WINDOW or None

    Convention

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

Responsibilities of the Selection Owner

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

SelectionRequest

owner: WINDOW
selection: ATOM
selection: ATOM
target: ATOM
property: ATOM or None
requestor: WINDOW
time: TIMESTAMP or CurrentTime

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

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

If the specified property is None, 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 parameters 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 dependent upon the definition of the target.
If the target is not defined to have parameters, the owner should ignore the
property if it is present. If the selection cannot be converted into a form
based on the target (and parameters, if any), the owner should refuse the
SelectionRequest as previously described.

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

    Convention

    All properties used to reply to SelectionRequest 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 SelectionRequest, as previously described.
See also Large Data Transfers.

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

SelectionNotify

requestor: WINDOW
selection, target: ATOM
property: ATOM or None
time: TIMESTAMP or CurrentTime

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

    Convention

    The selection, target, time, and property arguments in the SelectionNotify
    event should be set to the values received in the SelectionRequest event.

If the owner receives more than one SelectionRequest event with the same
requestor, selection, target, and timestamp it must respond to them in the same
order in which they were received.

    Rationale

    It is possible for a requestor to have multiple outstanding requests that
    use the same requestor window, selection, target, and timestamp, and that
    differ only in the property. If this occurs, and one of the conversion
    requests fails, the resulting SelectionNotify event will have its property
    argument set to None. This may make it impossible for the requestor to
    determine which conversion request had failed, unless the requests are
    responded to in order.

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

    Convention

    Selection requestors are responsible for deleting properties whose names
    they receive in SelectionNotify events (See Requesting a Selection ) or in
    properties with type MULTIPLE.

A selection owner will often need confirmation that the data comprising the
selection has actually been transferred. (For example, if the operation has
side effects on the owner's internal data structures, these should not take
place until the requestor has indicated that it has successfully received the
data.) Owners should express interest in PropertyNotify events for the
specified requestor window and wait until the property in the SelectionNotify
event has been deleted before assuming that the selection data has been
transferred. For the MULTIPLE request, if the different conversions require
separate confirmation, the selection owner can also watch for the deletion of
the individual properties named in the property in the SelectionNotify event.

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

SelectionClear

owner: WINDOW
selection: ATOM
time: TIMESTAMP

The timestamp argument is the time at which the ownership changed hands, and
the owner argument is the window the previous owner specified in its
SetSelectionOwner 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
xterm as before), then the client should reacquire the selection ownership as
if it were not the owner, providing a new timestamp. If the selection value is
modified, but can still reasonably be viewed as the same selected object, ^[3]
the owner should take no action.

Giving Up Selection Ownership

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

Voluntarily Giving Up Selection Ownership

To relinquish ownership of a selection voluntarily, a client should execute a
SetSelectionOwner request for that selection atom, with owner specified as None
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
SetSelectionOwner request, or the client may terminate. In both cases, the
ownership of the selection involved will revert to None.

Forcibly Giving Up Selection Ownership

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

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

Requesting a Selection

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

ConvertSelection

selection, target: ATOM
property: ATOM or None
requestor: WINDOW
time: TIMESTAMP or CurrentTime

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 Use of Selection Atoms The
requestor should set the requestor argument to a window that it created; the
owner will place the reply property there. The requestor should set the time
argument to the timestamp on the event that triggered the request for the
selection value. Note that clients should not specify CurrentTime.

    Convention

    Clients should not use CurrentTime for the time argument of a
    ConvertSelection 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
ConvertSelection request.^[4] The exception to this rule is when the requestor
intends to pass parameters with the request (see below).

    Rationale

    It is necessary for requestors to delete the property before issuing the
    request so that the target can later be extended to take parameters without
    introducing an incompatibility. Also note that the requestor of a selection
    need not know the client that owns the selection nor the window on which
    the selection was acquired.

Some targets may be defined such that requestors can pass parameters along with
the request. If the requestor wishes to provide parameters to a request, they
should be placed in the specified property on the requestor window before the
requestor issues the ConvertSelection 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 ConvertSelection request.

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

Conventions

  • Requestors should not use None for the property argument of a
    ConvertSelection request.

  • Owners receiving ConvertSelection requests with a property argument of None
    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 ConvertSelection request is that a SelectionNotify event will
be received. For the definition of a SelectionNotify event, see
Responsibilities of the Selection Owner.

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

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

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

GetProperty

window: WINDOW
property: ATOM
type: ATOM or AnyPropertyType
long-offset, long-length: CARD32
delete: BOOL
->
type: ATOM or None
format: {0, 8, 16, 32}
bytes-after: CARD32
value: LISTofINT8 or LISTofINT16 or LISTofINT32

GetProperty to retrieve the value of a selection, the property argument should
be set to the corresponding value in the SelectionNotify event. Because the
requestor has no way of knowing beforehand what type the selection owner will
use, the type argument should be set to AnyPropertyType. Several GetProperty
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 Large Data Transfers. ). 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 Use of Selection Properties. ),
the requestor should delete the property in the SelectionNotify request by
using a GetProperty request with the delete argument set to True. As previously
discussed, the owner has no way of knowing when the data has been transferred
to the requestor unless the property is removed.

    Convention

    The requestor must delete the property named in the SelectionNotify once
    all the data has been retrieved. The requestor should invoke either
    DeleteProperty or GetProperty (delete==True) after it has successfully
    retrieved all the data in the selection. For further information, see Large
    Data Transfers.

Large Data Transfers

Selections can get large, which poses two problems:

  • Transferring large amounts of data to the server is expensive.

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

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

Conventions

  • 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 INCR Properties. ).

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

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

  • When storing large amounts of data (relative to maximum-request-size),
    clients should use a sequence of ChangeProperty (mode==Append) requests for
    reasonable quantities of data. This avoids locking servers up and limits
    the waste of data an Alloc error would cause.

  • If an Alloc error occurs during the storing of the selection data, all
    properties stored for this selection should be deleted and the
    ConvertSelection request should be refused (see Responsibilities of the
    Selection Owner. ).

  • To avoid locking servers up for inordinate lengths of time, requestors
    retrieving large quantities of data from a property should perform a series
    of GetProperty requests, each asking for a reasonable amount of data.

    Advice to Implementors

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

Use of Selection Atoms

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.

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:

  • PRIMARY

  • SECONDARY

  • CLIPBOARD

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

The PRIMARY Selection

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

The SECONDARY Selection

The selection named by the atom SECONDARY is used:

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

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

The CLIPBOARD Selection

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:

  • It should assert ownership of the CLIPBOARD.

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

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

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

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

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

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

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

      □ Obtain the contents of the selection from the new owner by using the
        timestamp in the SelectionClear event.

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

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

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

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

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

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

The reasons not to run the clipboard client include:

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

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

Target Atoms

The atom that a requestor supplies as the target of a ConvertSelection 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 suggested so
far.

┌───────────────────────────────────┬─────────────┬───────────────────────────┐
│Atom                               │Type         │Data Received              │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│ADOBE_PORTABLE_DOCUMENT_FORMAT     │STRING       │[1]                        │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│APPLE_PICT                         │APPLE_PICT   │[2]                        │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│BACKGROUND                         │PIXEL        │A list of pixel values     │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│BITMAP                             │BITMAP       │A list of bitmap IDs       │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│CHARACTER_POSITION                 │SPAN         │The start and end of the   │
│                                   │             │selection in bytes         │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│CLASS                              │TEXT         │(see WM_CLASS Property. )  │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│CLIENT_WINDOW                      │WINDOW       │Any top-level window owned │
│                                   │             │by the selection owner     │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│COLORMAP                           │COLORMAP     │A list of colormap IDs     │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│COLUMN_NUMBER                      │SPAN         │The start and end column   │
│                                   │             │numbers                    │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│COMPOUND_TEXT                      │COMPOUND_TEXT│Compound Text              │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│DELETE                             │NULL         │(see DELETE. )             │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│DRAWABLE                           │DRAWABLE     │A list of drawable IDs     │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│ENCAPSULATED_POSTSCRIPT            │STRING       │[3], Appendix H ^[a]       │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│ENCAPSULATED_POSTSCRIPT_INTERCHANGE│STRING       │[3], Appendix H            │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│FILE_NAME                          │TEXT         │The full path name of a    │
│                                   │             │file                       │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│FOREGROUND                         │PIXEL        │A list of pixel values     │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│HOST_NAME                          │TEXT         │(see WM_CLIENT_MACHINE     │
│                                   │             │Property. )                │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│INSERT_PROPERTY                    │NULL         │(see INSERT_PROPERTY. )    │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│INSERT_SELECTION                   │NULL         │(see INSERT_SELECTION. )   │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│LENGTH                             │INTEGER      │The number of bytes in the │
│                                   │             │selection ^[b]             │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│LINE_NUMBER                        │SPAN         │The start and end line     │
│                                   │             │numbers                    │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│LIST_LENGTH                        │INTEGER      │The number of disjoint     │
│                                   │             │parts of the selection     │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│MODULE                             │TEXT         │The name of the selected   │
│                                   │             │procedure                  │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│MULTIPLE                           │ATOM_PAIR    │(see the discussion that   │
│                                   │             │follows)                   │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│NAME                               │TEXT         │(see WM_NAME Property. )   │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│ODIF                               │TEXT         │ISO Office Document        │
│                                   │             │Interchange Format         │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│OWNER_OS                           │TEXT         │The operating system of the│
│                                   │             │owner client               │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│PIXMAP                             │PIXMAP ^[c]  │A list of pixmap IDs       │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│POSTSCRIPT                         │STRING       │[3]                        │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│PROCEDURE                          │TEXT         │The name of the selected   │
│                                   │             │procedure                  │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│PROCESS                            │INTEGER, TEXT│The process ID of the owner│
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│STRING                             │STRING       │ISO Latin-1 (+TAB+NEWLINE) │
│                                   │             │text                       │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│TARGETS                            │ATOM         │A list of valid target     │
│                                   │             │atoms                      │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│TASK                               │INTEGER, TEXT│The task ID of the owner   │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│TEXT                               │TEXT         │The text in the owner's    │
│                                   │             │choice of encoding         │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│TIMESTAMP                          │INTEGER      │The timestamp used to      │
│                                   │             │acquire the selection      │
├───────────────────────────────────┼─────────────┼───────────────────────────┤
│USER                               │TEXT         │The name of the user       │
│                                   │             │running the owner          │
├───────────────────────────────────┴─────────────┴───────────────────────────┤
│^[a] 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.                  │
│                                                                             │
│^[b] The targets ENCAPSULATED_POSTSCRIPT and                                 │
│ENCAPSULATED_POSTSCRIPT_INTERCHANGE are equivalent to the targets _ADOBE_EPS │
│and _ADOBE_EPSI (respectively) that appear in the selection targets registry.│
│The _ADOBE_ targets are deprecated, but clients are encouraged to continue to│
│support them for backward compatibility.                                     │
│                                                                             │
│^[c] 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.            │
└─────────────────────────────────────────────────────────────────────────────┘

References:

 1. Adobe Systems, Incorporated. Portable Document Format Reference Manual.
    Reading, MA, Addison-Wesley, ISBN 0-201-62628-4.

 2. Apple Computer, Incorporated. Inside Macintosh, Volume V. Chapter 4, "Color
    QuickDraw," Color Picture Format. ISBN 0-201-17719-6.

 3. Adobe Systems, Incorporated. PostScript Language Reference Manual. Reading,
    MA, Addison-Wesley, ISBN 0-201-18127-4.

It is expected that this table will grow over time.

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

  • 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 Alloc errors). This list should
    include all the required atoms.

  • MULTIPLE - The MULTIPLE target atom is valid only when a property is
    specified on the ConvertSelection request. If the property argument in the
    SelectionRequest event is None and the target is MULTIPLE, it should be
    refused.

    When a selection owner receives a SelectionRequest (target==MULTIPLE)
    request, the contents of the property named in the request will be a list
    of atom pairs: the first atom naming a target and the second naming a
    property ( None is not valid here). The effect should be as if the owner
    had received a sequence of SelectionRequest events (one for each atom pair)
    except that:

      □ The owner should reply with a SelectionNotify 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
        None.

        Convention

        The entries in a MULTIPLE property must be processed in the order they
        appear in the property. For further information, see Selection Targets
        with Side Effects.

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

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

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

Selection Targets with Side Effects

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

In general, targets with side effects will return no information, that is, they
will return a zero length property of type NULL. (Type NULL means the result of
InternAtom 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.

    Conventions

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

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

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

    Problem

    The need to delay responding to the ConvertSelection request until a
    further conversion has succeeded poses problems for the Intrinsics
    interface that need to be addressed.

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

DELETE

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

INSERT_SELECTION

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

INSERT_PROPERTY

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

Use of Selection Properties

The names of the properties used in selection data transfer are chosen by the
requestor. The use of None property fields in ConvertSelection 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 contents 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.

┌─────────────┬──────┬───────────┐
│Type Atom    │Format│Separator  │
├─────────────┼──────┼───────────┤
│APPLE_PICT   │8     │Self-sizing│
├─────────────┼──────┼───────────┤
│ATOM         │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│ATOM_PAIR    │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│BITMAP       │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│C_STRING     │8     │Zero       │
├─────────────┼──────┼───────────┤
│COLORMAP     │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│COMPOUND_TEXT│8     │Zero       │
├─────────────┼──────┼───────────┤
│DRAWABLE     │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│INCR         │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│INTEGER      │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│PIXEL        │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│PIXMAP       │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│SPAN         │32    │Fixed-size │
├─────────────┼──────┼───────────┤
│STRING       │8     │Zero       │
├─────────────┼──────┼───────────┤
│WINDOW       │32    │Fixed-size │
└─────────────┴──────┴───────────┘

It is expected that this table will grow over time.

TEXT Properties

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

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

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

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

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

COMPOUND_TEXT as a type or a target specifies the Compound Text interchange
format; see the Compound Text Encoding.

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

    Rationale

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

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

INCR Properties

Requestors may receive a property of type INCR ^[6] in response to any target
that results in selection data.

This indicates that the owner will send the actual data incrementally. The
contents of the INCR property will be an integer, which represents a lower
bound on the number of bytes of data in the selection. The requestor and the
selection owner transfer the data in the selection in the following manner.

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

The selection owner then:

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

  • Waits between each append for a PropertyNotify (state==Deleted) event that
    shows that the requestor has read the data. The reason for doing this is to
    limit the consumption of space in the server.

  • Waits (after the entire data has been transferred to the server) until a
    PropertyNotify (state==Deleted) event that shows that the data has been
    read by the requestor and then writes zero-length data to the property.

The selection requestor:

  • Waits for the SelectionNotify event.

  • Loops:

      □ Retrieving data using GetProperty with the delete argument True.

      □ Waiting for a PropertyNotify with the state argument NewValue.

  • Waits until the property named by the PropertyNotify event is zero-length.

  • Deletes the zero-length property.

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

DRAWABLE Properties

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 GetGeometry request, the following
items are not:

  • Foreground pixel

  • Background pixel

  • Colormap ID

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

  • FOREGROUND returns a PIXEL value.

  • BACKGROUND returns a PIXEL value.

  • COLORMAP returns a colormap ID.

SPAN Properties

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.

Manager Selections

Certain clients, often called managers, take on responsibility for managing
shared resources. A client that manages a shared resource should take ownership
of an appropriate selection, named using the conventions described in Naming
Conventions and Discriminated Names. 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 technique as the primary means by which
clients interact with the managed resource. Note that the conventions for
interacting 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
GetSelectionOwner request to check whether the selection is already owned by
another client, and, where appropriate, it should ask the user if the new
manager should replace the old one. If so, it may then take ownership of the
selection. Managers should acquire the selection using a window created
expressly for this purpose. Managers must conform to the rules for selection
owners described in Acquiring Selection Ownership and Responsibilities of the
Selection Owner , and they must also support the required targets listed in Use
of Selection Atoms.

If a manager loses ownership of a manager selection, this means that a new
manager is taking over its responsibilities. The old manager must release all
resources it has managed and must then destroy the window that owned the
selection. For example, a window manager losing ownership of WM_S2 must
deselect from SubstructureRedirect on the root window of screen 2 before
destroying the window that owned WM_S2.

When the new manager notices that the window owning the selection has been
destroyed, it knows that it can successfully proceed to control the resource it
is planning to manage. If the old 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 destroying the window that owns the selection. It should
not first disown the selection, since this introduces a race condition.

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

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

┌────────────┬────────────────────────────────────────────────────────────────┐
│Argument    │Value                                                           │
├────────────┼────────────────────────────────────────────────────────────────┤
│            │the root window of screen 0, or the root window of the          │
│destination:│appropriate screen if the manager is managing a screen-specific │
│            │resource                                                        │
├────────────┼────────────────────────────────────────────────────────────────┤
│propogate:  │False                                                           │
├────────────┼────────────────────────────────────────────────────────────────┤
│event-mask: │StructureNotify                                                 │
├────────────┼────────────────────────────────────────────────────────────────┤
│event:      │ClientMessage                                                   │
├────────────┼────────────────────────────────────────────────────────────────┤
│     type:  │MANAGER                                                         │
├────────────┼────────────────────────────────────────────────────────────────┤
│     format:│32                                                              │
├────────────┼────────────────────────────────────────────────────────────────┤
│     data[0]│timestamp                                                       │
│^[a]        │                                                                │
├────────────┼────────────────────────────────────────────────────────────────┤
│     data   │manager selection atom                                          │
│[1]:        │                                                                │
├────────────┼────────────────────────────────────────────────────────────────┤
│     data   │the window owning the selection                                 │
│[2]:        │                                                                │
├────────────┼────────────────────────────────────────────────────────────────┤
│     data   │manager-selection-specific data                                 │
│[3]:        │                                                                │
├────────────┼────────────────────────────────────────────────────────────────┤
│     data   │manager-selection-specific data                                 │
│[4]:        │                                                                │
├────────────┴────────────────────────────────────────────────────────────────┤
│^[a] We use the notation data[n] to indicate the n ^th element of the        │
│LISTofINT8, LISTofINT16, or LISTofINT32 in the data field of the             │
│ClientMessage, according to the format field. The list is indexed from zero. │
└─────────────────────────────────────────────────────────────────────────────┘

Clients that wish to know when a specific manager has started should select for
StructureNotify on the appropriate root window and should watch for the
appropriate MANAGER ClientMessage.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

^[2] At present, no part of the protocol requires requestors to send events to
the owner of a selection. This restriction is imposed to prepare for possible
future extensions.

^[3] The division between these two cases is a matter of judgment on the part
of the software developer.

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

^[5] Note that this is different from STRING, where many byte values are
forbidden, and from COMPOUND_TEXT, where, for example, inserting the sequence
27,\ 40,\ 66 (designate ASCII into GL) at the start does not alter the meaning.

^[6] These properties were called INCREMENTAL in an earlier draft. The protocol
for using them has changed, and so the name has changed to avoid confusion.

Chapter 3. Peer-to-Peer Communication by Means of Cut Buffers

The cut buffer mechanism is much simpler but much less powerful than the
selection mechanism. The selection mechanism is active in that it provides a
link between the owner and requestor clients. The cut buffer mechanism is
passive; an owner places data in a cut buffer from which a requestor retrieves
the data at some later time.

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

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

Chapter 4. Client-to-Window-Manager Communication

Table of Contents

Client's Actions
    Creating a Top-Level Window
    Client Properties
    Window Manager Properties
    Changing Window State
    Configuring the Window
    Changing Window Attributes
    Input Focus
    Colormaps
    Icons
    Pop-up Windows
    Window Groups
Client Responses to Window Manager Actions
    Reparenting
    Redirection of Operations
    Window Move
    Window Resize
    Iconify and Deiconify
    Colormap Change
    Input Focus
    ClientMessage Events
    Redirecting Requests
Communication with the Window Manager by Means of Selections
Summary of Window Manager Property Types

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

In general, these conventions are somewhat complex and will undoubtedly change
as new window management paradigms are developed. Thus, there is a strong bias
toward defining only those conventions that are essential and that apply
generally to all window management paradigms. Clients designed to run with a
particular window manager can easily define private protocols to add to these
conventions, but they must be aware that their users may decide to run some
other window manager no matter how much the designers of the private protocol
are convinced that they have seen the "one 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 management policy; the
choice of an appropriate window management policy for the user's circumstances
is not one for an individual client to make but will be made by the user or the
user's system 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 writing is important, and
it needs to be on top." Perhaps it is important when it is being run in
earnest, and it should then be run under the control of a window manager that
recognizes "important" 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 example, the debugger) to appear on top.

Client's Actions

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

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

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

  • Being prepared for resource allocations to change at any time

Creating a Top-Level Window

A client's top-level window is a window whose override-redirect attribute is
False. It must either be a child of a root window, or it must have been a child
of a root window immediately prior to having been reparented by the window
manager. If the client reparents the window away from the root, the window is
no longer a top-level window; but it can become a top-level window again if the
client reparents it back to the root.

A client usually would expect to create its top-level windows 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, however, it could use
something like the following:

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

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

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

  • Normal

  • Iconic

  • Withdrawn

Newly created windows start in the Withdrawn state. Transitions between states
happen when the top-level window is mapped and unmapped and when the window
manager receives certain messages. For further details, see WM_HINTS Property.
and Changing Window State.

Client Properties

Once the client has one or more top-level windows, it should place properties
on those windows to inform the window manager of the behavior that the client
desires. Window managers will 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 window manager will not change
properties written by the client.

The window manager will examine the contents of these properties when the
window makes the transition from the Withdrawn state and will monitor some
properties for changes while the window is in the Iconic or Normal state. When
the client changes one of these properties, it must use Replace mode to
overwrite the entire property with new data; the window manager will retain no
memory of the old value of the property. All fields of the property must be set
to suitable values in a single Replace mode ChangeProperty request. This
ensures that the full contents of the property will be available to a new
window manager if the existing one crashes, if it is shut down and restarted,
or if the session needs to be shut down and restarted by the session manager.

    Convention

    Clients writing or rewriting window manager 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 properties is reserved to the X
Consortium; private extensions to them are forbidden. Private additional
communication between clients and window managers should take place using
separate properties. The only exception to this rule is the WM_PROTOCOLS
property, which may be of arbitrary length and which may contain atoms
representing private protocols (see WM_PROTOCOLS Property ).

The next sections describe each of the properties the clients need to set, in
turn. They are summarized in the table in Summary of Window Manager Property
Types

WM_NAME Property

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 uninterpreted string
properties) is implied by the type of the property. The type atoms to be used
for this purpose are described in TEXT Properties.

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

On the other hand, there is no guarantee that the user can see the WM_NAME
string even if the window manager supports window headlines. The user may have
placed the headline off-screen or have covered it by other windows. WM_NAME
should not be used for application-critical information or to announce
asynchronous changes of an application's state that require timely user
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.

WM_ICON_NAME Property

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.

WM_NORMAL_HINTS Property

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

┌───────────┬─────────────┬──────────────────────────────┐
│Field      │Type         │Comments                      │
├───────────┼─────────────┼──────────────────────────────┤
│flags      │CARD32       │(see the next table)          │
├───────────┼─────────────┼──────────────────────────────┤
│pad        │4*CARD32     │For backwards compatibility   │
├───────────┼─────────────┼──────────────────────────────┤
│min_width  │INT32        │If missing, assume base_width │
├───────────┼─────────────┼──────────────────────────────┤
│min_height │INT32        │If missing, assume base_height│
├───────────┼─────────────┼──────────────────────────────┤
│max_width  │INT32        │                              │
├───────────┼─────────────┼──────────────────────────────┤
│max_height │INT32        │                              │
├───────────┼─────────────┼──────────────────────────────┤
│width_inc  │INT32        │                              │
├───────────┼─────────────┼──────────────────────────────┤
│height_inc │INT32        │                              │
├───────────┼─────────────┼──────────────────────────────┤
│min_aspect │(INT32,INT32)│                              │
├───────────┼─────────────┼──────────────────────────────┤
│max_aspect │(INT32,INT32)│                              │
├───────────┼─────────────┼──────────────────────────────┤
│base_width │INT32        │If missing, assume min_width  │
├───────────┼─────────────┼──────────────────────────────┤
│base_height│INT32        │If missing, assume min_height │
├───────────┼─────────────┼──────────────────────────────┤
│win_gravity│INT32        │If missing, assume NorthWest  │
└───────────┴─────────────┴──────────────────────────────┘

The WM_SIZE_HINTS.flags bit definitions are as follows:

┌───────────┬─────┬───────────────────────────────────────────┐
│Name       │Value│Field                                      │
├───────────┼─────┼───────────────────────────────────────────┤
│USPosition │1    │User-specified x, y                        │
├───────────┼─────┼───────────────────────────────────────────┤
│USSize     │2    │User-specified width, height               │
├───────────┼─────┼───────────────────────────────────────────┤
│PPosition  │4    │Program-specified position                 │
├───────────┼─────┼───────────────────────────────────────────┤
│PSize      │8    │Program-specified size                     │
├───────────┼─────┼───────────────────────────────────────────┤
│PMinSize   │16   │Program-specified minimum size             │
├───────────┼─────┼───────────────────────────────────────────┤
│PMaxSize   │32   │Program-specified maximum size             │
├───────────┼─────┼───────────────────────────────────────────┤
│PResizeInc │64   │Program-specified resize increments        │
├───────────┼─────┼───────────────────────────────────────────┤
│PAspect    │128  │Program-specified min and max aspect ratios│
├───────────┼─────┼───────────────────────────────────────────┤
│PBaseSize  │256  │Program-specified base size                │
├───────────┼─────┼───────────────────────────────────────────┤
│PWinGravity│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 USPosition and USSize 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 PPosition and PSize.

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 Unmap: NorthWest (1), North (2), NorthEast (3), West (4),
Center (5), East (6), SouthWest (7), South (8), and SouthEast (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 Static, 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
NorthWest, NorthEast, SouthWest, and SouthEast the reference point is the
specified outer corner of the window (on the outside border edge). For North,
South, East and West the reference point is the center of the specified outer
edge of the window border. For Center 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
conjunction with width_inc and height_inc define an arithmetic progression of
preferred window widths and heights for non-negative integers i and j:

width = base_width + ( i x width_inc )

height = base_height + ( j x 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.)

WM_HINTS Property

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

┌─────────────┬──────┬─────────────────────────────────┐
│Field        │Type  │Comments                         │
├─────────────┼──────┼─────────────────────────────────┤
│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:

┌────────────────┬─────┬──────────────────────┐
│Name            │Value│Field                 │
├────────────────┼─────┼──────────────────────┤
│InputHint       │1    │input                 │
├────────────────┼─────┼──────────────────────┤
│StateHint       │2    │initial_state         │
├────────────────┼─────┼──────────────────────┤
│IconPixmapHint  │4    │icon_pixmap           │
├────────────────┼─────┼──────────────────────┤
│IconWindowHint  │8    │icon_window           │
├────────────────┼─────┼──────────────────────┤
│IconPositionHint│16   │icon_x & icon_y       │
├────────────────┼─────┼──────────────────────┤
│IconMaskHint    │32   │icon_mask             │
├────────────────┼─────┼──────────────────────┤
│WindowGroupHint │64   │window_group          │
├────────────────┼─────┼──────────────────────┤
│MessageHint     │128  │(this bit is obsolete)│
├────────────────┼─────┼──────────────────────┤
│UrgencyHint     │256  │urgency               │
└────────────────┴─────┴──────────────────────┘

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

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

Clients with the Globally Active and No Input models should set the input flag
to False. Clients with the Passive and Locally Active models should set the
input flag to True.

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

  • Normal

  • Iconic

  • Withdrawn

The semantics of these states are described in Changing Window State. 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 following table:

┌───────────┬─────┬─────────────────────┐
│State      │Value│Comments             │
├───────────┼─────┼─────────────────────┤
│NormalState│1    │The window is visible│
├───────────┼─────┼─────────────────────┤
│IconicState│3    │The icon is visible  │
└───────────┴─────┴─────────────────────┘

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

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

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

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

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

    Conventions

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

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

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

The messages bit, if set in the flags field, indicates that the client is using
an obsolete window manager communication protocol, ^[7] rather than the
WM_PROTOCOLS mechanism of WM_PROTOCOLS Property

The UrgencyHint 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 monitor the
state of this flag for the entire time the window is in the Normal or Iconic
state and must take appropriate action when the state of the flag changes. The
flag is otherwise independent of the window's state; in 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 UrgencyHint flag to be set to zero or the window to be withdrawn. The
user's action can either mitigate the actual condition that made the window
urgent, or it can merely shut off the alarm.

    Rationale

    This mechanism is useful for alarm dialog boxes or reminder windows, in
    cases where mapping the window is not enough (e.g., in the presence of
    multi-workspace or virtual desktop window managers), and where using an
    override-redirect window is too intrusive. For example, the 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.

WM_CLASS Property

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

The two strings, respectively, are:

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

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

      □ Otherwise, if the environment variable RESOURCE_NAME is set, its value
        will be used as the instance name.

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

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

WM_TRANSIENT_FOR Property

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 mapping top-level windows normally does require
interaction. Dialogue boxes, for example, are an example of windows that should
have WM_TRANSIENT_FOR set.

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

WM_PROTOCOLS Property

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

All the protocols in which a client can volunteer to take part involve the
window manager sending the client a ClientMessage event and the client taking
appropriate action. For details of the contents of the event, see ClientMessage
Events In each case, the protocol transactions are initiated by the window
manager.

The WM_PROTOCOLS property is not required. If it is not present, the client
does not want to participate in any window 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.

┌────────────────┬───────────────┬──────────────────────────────────────┐
│Protocol        │Section        │Purpose                               │
├────────────────┼───────────────┼──────────────────────────────────────┤
│WM_TAKE_FOCUS   │Input Focus    │Assignment of input focus             │
├────────────────┼───────────────┼──────────────────────────────────────┤
│WM_SAVE_YOURSELF│Appendix C     │Save client state request (deprecated)│
├────────────────┼───────────────┼──────────────────────────────────────┤
│WM_DELETE_WINDOW│Window Deletion│Request to delete top-level window    │
└────────────────┴───────────────┴──────────────────────────────────────┘

It is expected that this table will grow over time.

WM_COLORMAP_WINDOWS Property

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 Colormaps

WM_CLIENT_MACHINE Property

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.

Window Manager Properties

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

WM_STATE Property

The window manager will place a WM_STATE property (of type WM_STATE) on each
top-level client window that is not in the Withdrawn state. Top-level windows
in the Withdrawn state may or may not have the WM_STATE property. Once the
top-level window has been withdrawn, the client may re-use it for another
purpose. Clients that do so should remove the WM_STATE property if it is still
present.

Some clients (such as xprop) 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 follows:

┌─────┬──────┬────────────────────┐
│Field│Type  │Comments            │
├─────┼──────┼────────────────────┤
│state│CARD32│(see the next table)│
├─────┼──────┼────────────────────┤
│icon │WINDOW│ID of icon window   │
└─────┴──────┴────────────────────┘

The following table lists the WM_STATE.state values:

┌───────────────┬─────┐
│State          │Value│
├───────────────┼─────┤
│WithdrawnState │0    │
├───────────────┼─────┤
│NormalState    │1    │
├───────────────┼─────┤
│IconicState    │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
manager to iconify the window). If it is NormalState, the window manager
believes the client should be animating its window. If it is IconicState, 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 WithdrawnState 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 None. Note that this window could
be but is not necessarily the same window as the icon window that the client
may have specified in its WM_HINTS property. The WM_STATE icon may be a window
that the window manager has supplied and that contains the client's icon
pixmap, or it may be an ancestor of the client's icon window.

WM_ICON_SIZE Property

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

┌──────────┬──────┬─────────────────────────────────┐
│Field     │Type  │Comments                         │
├──────────┼──────┼─────────────────────────────────┤
│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 Xlib - C Language X Interface.

Changing Window State

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:

  • NormalState - The client's top-level window is viewable.

  • IconicState - The client's top-level window is iconic (whatever that means
    for this window manager). The client can assume that its top-level window
    is not viewable, its icon_window (if any) will be viewable and, failing
    that, its icon_pixmap (if any) or its WM_ICON_NAME will be displayed.

  • WithdrawnState - Neither the client's top-level window nor its icon is
    visible.

In fact, the window manager may implement states with semantics other than
those described above. For example, a window manager might implement a concept
of an "inactive" state in which an infrequently used client's window would be
represented as a string in a menu. But this state is invisible to the client,
which would see itself merely as being in the Iconic state.

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

  • Withdrawn -> Normal - The client should map the window with
    WM_HINTS.initial_state being NormalState.

  • Withdrawn -> Iconic - The client should map the window with
    WM_HINTS.initial_state being IconicState.

  • Normal -> Iconic - The client should send a ClientMessage event as
    described later in this section.

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

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

  • Iconic -> Withdrawn - The client should unmap the window and follow it with
    a synthetic UnmapNotify 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 Withdrawn state, the window will be mapped
if it is in the Normal state and the window will be unmapped if it is in the
Iconic state. Reparenting window managers must unmap the client's window when
it is in the Iconic state, even if an ancestor window being unmapped renders
the client's window unviewable. Conversely, if a reparenting window manager
renders the client's window unviewable by unmapping an ancestor, the client's
window is by definition in the Iconic state and must also be unmapped.

    Advice to Implementors

    Clients can select for StructureNotify on their top-level windows to track
    transitions between Normal and Iconic states. Receipt of a MapNotify event
    will indicate a transition to the Normal state, and receipt of an
    UnmapNotify 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 UnmapNotify event by using a
SendEvent request with the following arguments:

┌───────────────────────────┬─────────────────────────────────────────┐
│Argument                   │Value                                    │
├───────────────────────────┼─────────────────────────────────────────┤
│destination                │The root                                 │
├───────────────────────────┼─────────────────────────────────────────┤
│propogate                  │False                                    │
├───────────────────────────┼─────────────────────────────────────────┤
│event-mask                 │(SubstructureRedirect|SubstructureNotify)│
├───────────────────────────┼─────────────────────────────────────────┤
│event: an UnmapNotify with:│                                         │
├───────────────────────────┼─────────────────────────────────────────┤
│     event:                │The root                                 │
├───────────────────────────┼─────────────────────────────────────────┤
│     window:               │The window itself                        │
├───────────────────────────┼─────────────────────────────────────────┤
│     from-configure:       │False                                    │
└───────────────────────────┴─────────────────────────────────────────┘


    Rationale

    The reason for requiring the client to send a synthetic UnmapNotify event
    is to ensure that the window manager gets some notification of the client's
    desire to change state, even though the window may already be unmapped when
    the desire is expressed.

    Advice to Implementors

    For compatibility with obsolete clients, window managers should trigger the
    transition to the Withdrawn state on the real UnmapNotify rather than
    waiting for the synthetic one. They should also trigger the transition if
    they receive a synthetic UnmapNotify on a window for which they have not
    yet received a real UnmapNotify.

When a client withdraws a window, the window manager will then update or remove
the WM_STATE property as described in WM_STATE Property. Clients that want to
re-use a client window (e.g., by mapping it again or reparenting it elsewhere)
after withdrawing it must wait for the withdrawal to be complete before
proceeding. The preferred method for doing this is for clients to wait for the
window manager to update or remove the WM_STATE property. ^[8]

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

  • Window == the window to be iconified

  • Type ^[9] == the atom WM_CHANGE_STATE

  • Format == 32

  • Data[0] == IconicState

    Rationale

    The format of this ClientMessage event does not match the format of
    ClientMessages in ClientMessage Events. 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 SendEvent request should be those described
for the synthetic UnmapNotify event.

    Advice to Implementors

    Clients can also select for VisibilityChange events on their top-level or
    icon windows. They will then receive a VisibilityNotify (state==
    FullyObscured) event when the window concerned becomes completely obscured
    even though mapped (and thus, perhaps a waste of time to update) and a
    VisibilityNotify (state!=FullyObscured) event when it becomes even partly
    viewable.

    Advice to Implementors

    When a window makes a transition from the Normal state to either the Iconic
    or the Withdrawn state, clients should be aware that the window manager may
    make transients for this window inaccessible. Clients should not rely on
    transient windows being available to the user when the transient owner
    window is not in the Normal state. When withdrawing a window, clients are
    advised to withdraw transients for the window.

Configuring the Window

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

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

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

  • The border width of the window

  • The window's position in the stack

The coordinate system in which the location is expressed is that of the root
(irrespective of any reparenting that may have occurred). The border width to
be used and win_gravity position hint to be used are those most recently
requested by the client. Client configure requests are interpreted by the
window manager in the same manner as the initial window geometry mapped from
the Withdrawn state, as described in WM_NORMAL_HINTS Property 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 ConfigureRequest
request by:

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

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

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

    A client will receive a synthetic ConfigureNotify event following the
    change that describes the new geometry of the window. The event's (x,y)
    coordinates will be in the root coordinate system adjusted for the border
    width the client requested. The border_width will be the border width the
    client requested. The client may not receive a real ConfigureNotify event
    that describes this change because the window manager may have reparented
    the top-level window. If the client does receive a real event, the
    synthetic event will follow the real one.

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

    A client that has selected for StructureNotify events will receive a real
    ConfigureNotify 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 TranslateCoordinates request can
    be used to convert the coordinates if required.

The general rule is that coordinates in real ConfigureNotify events are in the
parent's space; in synthetic events, they are in the root space.

    Advice to Implementors

    Clients cannot distinguish between the case where a top-level window is
    resized and moved from the case where the window is resized but not moved,
    since a real ConfigureNotify event will be received in both cases. Clients
    that are concerned 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 ConfigureNotify event on
    the top-level window, the client should note that the position is unknown.
    Upon receipt of a synthetic ConfigureNotify event, the client should note
    the position as known, using the position in this event. If the client
    receives a KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
    EnterNotify or LeaveNotify 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
    TranslateCoordinates request to find the position of a top-level window.

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

    Convention

    Clients should set the desired value of the border-width attribute on all
    ConfigureWindow 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 ConfigureWindow
request will cause an error.

    Convention

    Clients that use a ConfigureWindow request to request a change in their
    position in the stack should do so using None in the sibling field.

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

┌──────────────────────────────┬──────────────────────────────────────────────┐
│Argument                      │Value                                         │
├──────────────────────────────┼──────────────────────────────────────────────┤
│destination                   │The root                                      │
├──────────────────────────────┼──────────────────────────────────────────────┤
│propogate                     │False                                         │
├──────────────────────────────┼──────────────────────────────────────────────┤
│event-mask                    │(SubstructureRedirect|SubstructureNotify)     │
├──────────────────────────────┼──────────────────────────────────────────────┤
│event: an ConfigureRequest    │                                              │
│with:                         │                                              │
├──────────────────────────────┼──────────────────────────────────────────────┤
│     event:                   │The root                                      │
├──────────────────────────────┼──────────────────────────────────────────────┤
│     window:                  │The window itself                             │
├──────────────────────────────┼──────────────────────────────────────────────┤
│     ...                      │Other parameters from the ConfigureWindow     │
│                              │request                                       │
└──────────────────────────────┴──────────────────────────────────────────────┘

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

Changing Window Attributes

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

┌──────────────────────┬─────────────────┐
│Attribute             │Private to Client│
├──────────────────────┼─────────────────┤
│Background pixmap     │Yes              │
├──────────────────────┼─────────────────┤
│Background pixel      │Yes              │
├──────────────────────┼─────────────────┤
│Border pixmap         │Yes              │
├──────────────────────┼─────────────────┤
│Border pixel          │Yes              │
├──────────────────────┼─────────────────┤
│Bit gravity           │Yes              │
├──────────────────────┼─────────────────┤
│Window gravity        │No               │
├──────────────────────┼─────────────────┤
│Backing-store hint    │Yes              │
├──────────────────────┼─────────────────┤
│Save-under hint       │No               │
├──────────────────────┼─────────────────┤
│Event Mask            │No               │
├──────────────────────┼─────────────────┤
│Do-not-propagate mask │Yes              │
├──────────────────────┼─────────────────┤
│Override-redirect flag│No               │
├──────────────────────┼─────────────────┤
│Colormap              │Yes              │
├──────────────────────┼─────────────────┤
│Cursor                │Yes              │
└──────────────────────┴─────────────────┘

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

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

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

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

  • Clients can set override-redirect on top-level windows but are encouraged
    not to do so except as described in Pop-up Windows. and Redirecting
    Requests.

Input Focus

There are four models of input handling:

  • No Input - The client never expects keyboard input. An example would be
    xload or another output-only client.

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

  • Locally Active Input - The client expects keyboard input and explicitly
    sets the input focus, but it only does so when one of its windows already
    has the focus. An example would be a client with subwindows defining
    various data entry fields that uses Next and Prev keys to move the input
    focus between the fields. It does so when its top-level window has acquired
    the focus in PointerRoot mode or when the window manager sets the input
    focus to its top-level window (in click-to-type mode).

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

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

┌───────────────┬───────────┬─────────────┐
│Input Model    │Input Field│WM_TAKE_FOCUS│
├───────────────┼───────────┼─────────────┤
│No Input       │False      │Absent       │
├───────────────┼───────────┼─────────────┤
│Passive        │True       │Absent       │
├───────────────┼───────────┼─────────────┤
│Locally Active │True       │Present      │
├───────────────┼───────────┼─────────────┤
│Globally Active│False      │Present      │
└───────────────┴───────────┴─────────────┘

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

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

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

  • ButtonPress

  • ButtonRelease

  • Passive-grabbed KeyPress

  • Passive-grabbed KeyRelease

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 passive grab on the keys that cut, copy, or paste).

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

Windows with the atom WM_TAKE_FOCUS in their WM_PROTOCOLS property may receive
a ClientMessage event from the window manager (as described in ClientMessage
Events. ) with WM_TAKE_FOCUS in its data[0] field and a valid timestamp (i.e.,
not CurrentTime) in its data[1] field. If they want the focus, they should
respond with a SetInputFocus 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
Input Focus

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

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

Clients that set the input focus need to decide a value for the revert-to field
of the SetInputFocus 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:

  • Parent - In general, clients should use this value when assigning focus to
    one of their subwindows. Unmapping the subwindow will cause focus to revert
    to the parent, which is probably what you want.

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

  • None - 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 None, and there will probably be no way to change it.

Note that neither PointerRoot nor None is really safe to use.

    Convention

    Clients that invoke a SetInputFocus request should set the revert-to
    argument to Parent.

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

    Convention

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

Colormaps

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

Clients provide the window manager with hints as to which 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 window
gets the colormap focus (as a result of whatever colormap focus policy is
implemented by the window manager), the window manager will ensure that one or
more of the client's colormaps are installed.

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

Clients that create windows can use the value CopyFromParent to inherit their
parent's colormap. Window managers will ensure that the root window's colormap
field contains a colormap that is suitable for clients to inherit. In
particular, the colormap will provide distinguishable colors for BlackPixel and
WhitePixel.

Top-level windows that have subwindows or override-redirect pop-up windows
whose colormap requirements differ from the top-level window should have a
WM_COLORMAP_WINDOWS property. This property contains a list of IDs for windows
whose colormaps the window manager should attempt to have installed when, in
the course of its individual colormap focus policy, it assigns the colormap
focus to the top-level window (see WM_COLORMAP_WINDOWS Property ). 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_COLORMAP_WINDOWS property
or appear in the property of the window they are transient for, as appropriate.

    Rationale

    An alternative design was considered for how clients should hint to the
    window manager about their colormap requirements. This alternative design
    specified a list of colormaps instead of a list of windows. The current
    design, a list of windows, was chosen for two reasons. First, it allows
    window managers to find the visuals of the colormaps, thus permitting
    visual-dependent colormap installation policies. Second, it allows window
    managers to select for VisibilityChange events on the windows concerned and
    to ensure that colormaps are only installed if the windows that need them
    are visible. The alternative design allows for neither of these policies.

    Advice to Implementors

    Clients should be aware of the min-installed-maps and max-installed-maps
    fields of the connection setup information, and the effect that the minimum
    value has on the "required list" defined by the Protocol in the description
    of the InstallColormap 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 installation. When the client has finished its
colormap installation, it must also notify the window manager. The client
notifies the window manager by issuing a SendEvent request with the following
arguments:

┌─────────────────┬───────────────────────────────────────────────────────────┐
│Argument         │Value                                                      │
├─────────────────┼───────────────────────────────────────────────────────────┤
│destination      │The root window of the screen on which the colormap is     │
│                 │installed                                                  │
├─────────────────┼───────────────────────────────────────────────────────────┤
│propogate        │False                                                      │
├─────────────────┼───────────────────────────────────────────────────────────┤
│event-mask       │ColormapChange                                             │
├─────────────────┼───────────────────────────────────────────────────────────┤
│event: an        │                                                           │
│ClientMessage    │                                                           │
│with:            │                                                           │
├─────────────────┼───────────────────────────────────────────────────────────┤
│     window:     │The root window, as above                                  │
├─────────────────┼───────────────────────────────────────────────────────────┤
│     type:       │WM_COLORMAP_NOTIFY                                         │
├─────────────────┼───────────────────────────────────────────────────────────┤
│     format      │32                                                         │
├─────────────────┼───────────────────────────────────────────────────────────┤
│     data[0]     │the timestamp of the event that caused the client to start │
│                 │or stop installing colormaps                               │
├─────────────────┼───────────────────────────────────────────────────────────┤
│     data[1]     │1 if the client is starting colormap installation, 0 if the│
│                 │client is finished with colormap installation              │
├─────────────────┼───────────────────────────────────────────────────────────┤
│     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
Communication with the Window Manager by Means of Selections ) 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 installation. 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 installation.

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 InstallColormap requests that
are not executed until after the client's SendEvent and InstallColormap
requests, thus uninstalling the client's colormaps. If this occurs while the
client still has the pointer grabbed and before the client has issued the
"finished" message, the client may reinstall the desired colormaps.

    Advice to Implementors

    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 window manager may
    be left in a state where its colormap installation policy is suspended.
    Window manager implementors may want to implement a feature that resets
    colormap installation policy in response to a command from the user.

Icons

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

  • A string in WM_ICON_NAME.

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

    A Pixmap into the icon_pixmap field of the WM_HINTS property and possibly
    another into the icon_mask field.

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

  • A window into the icon_window field of the WM_HINTS property.

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

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

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

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

  • Otherwise, the window's WM_ICON_NAME string is visible.

Clients should observe the following conventions about their icon windows:

    Conventions

      □ The icon window should be an InputOutput child of the root.

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

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

      □ Clients should not map their icon windows.

      □ Clients should not unmap their icon windows.

      □ Clients should not configure their icon windows.

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

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

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

      □ Clients must select for Exposure 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.

Pop-up Windows

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

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

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

  • If the window will be visible for a very short time and should not be
    decorated at all, the client can set override-redirect on the window. In
    general, this should be done only if the pointer is grabbed while the
    window is mapped. The window manager will never interfere with these
    windows, which should be used with caution. An example of an appropriate
    use is a pop-up menu.

    Advice to Implementors

    The user will not be able to move, resize, restack, or transfer the input
    focus to override-redirect 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
    Input Focus in the description of the Globally Active focus model.

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

Window Groups

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 decorations, and
other group members may have a restricted set.

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

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

Client Responses to Window Manager Actions

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 notification of the window manager's operations.

Reparenting

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

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

  • The server will interpret the (x,y) coordinates in a ConfigureWindow
    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 Redirection of
    Operations ). Clients should use the root coordinate space for these
    requests (see Configuring the Window ).

  • ConfigureWindow 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 Configuring the Window ).

  • The (x,y) coordinates returned by a GetGeometry request are in the parent's
    coordinate space and are thus not directly useful after a reparent
    operation.

  • A background of ParentRelative will have unpredictable results.

  • A cursor of None will have unpredictable results.

Clients that want to be notified when they are reparented can select for
StructureNotify events on their top-level window. They will receive a
ReparentNotify 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 parent window. This means that the reparented
window will not be destroyed if the window manager terminates and will be
remapped if it was unmapped. Note that this applies to all client windows the
window manager reparents, including transient windows and client icon windows.

Redirection of Operations

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
MapWindow, ConfigureWindow, and CirculateWindow.

    Advice to Implementors

    The following is incorrect because the MapWindow request may be intercepted
    and the PolyLine output made to an unmapped window:

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

    The client must wait for an Expose event before drawing in the window. ^
    [10]

    This next example incorrectly assumes that the ConfigureWindow 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 StructureNotify on its window and monitor the
    window's size by tracking ConfigureNotify 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 MapWindow request has been intercepted, the window will still be
    unmapped, causing the SetInputFocus request to generate the error. The
    solution to this problem is for clients to select for VisibilityChange on
    the window and to delay the issuance of the SetInputFocus request until
    they have received a VisibilityNotify event indicating that the window is
    visible.

    This technique does not guarantee correct operation. The user may have
    iconified the window by the time the SetInputFocus 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 VisibilityNotify 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 Pop-up Windows ) and while responding to ResizeRequest events (see
Redirecting Requests ).

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

  • Prevent any preexisting window manager from interfering with their
    activities

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

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

Window Move

If the window manager moves a top-level window without changing its size, the
client will receive a synthetic ConfigureNotify 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 ConfigureNotify event on a top-level window implies that the window's
position on the root may have changed, even though the event reports that the
window's position in its parent is unchanged because the window may have been
reparented. Note that the coordinates in the event will not, in this case, be
directly useful.

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

┌───────────┬───────────────────┐
│Argument   │Value              │
├───────────┼───────────────────┤
│destination│The client's window│
├───────────┼───────────────────┤
│propagate  │False              │
├───────────┼───────────────────┤
│event-mask │StructureNotify    │
└───────────┴───────────────────┘

Window Resize

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

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

Iconify and Deiconify

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

The client can elect to be notified of these state changes by selecting for
StructureNotify events on the top-level window. It will receive a UnmapNotify
event when it goes Iconic and a MapNotify event when it goes Normal.

Colormap Change

Clients that wish to be notified of their colormaps being installed or
uninstalled should select for ColormapNotify 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 ColormapNotify events with the new field
FALSE when the colormap for that window is installed or uninstalled.

Input Focus

Clients can request notification that they have the input focus by selecting
for FocusChange events on their top-level windows; they will receive FocusIn
and FocusOut events. Clients that need to set the input focus to one of their
subwindows should not do so unless they have set WM_TAKE_FOCUS in their
WM_PROTOCOLS property and have done one of the following:

  • Set the input field of WM_HINTS to True and actually have the input focus
    in one of their top-level windows

  • Set the input field of WM_HINTS to False and have received a suitable event
    as described in Input Focus.

  • Have received a WM_TAKE_FOCUS message as described in Input Focus.

Clients should not warp the pointer in an attempt to transfer the focus; they
should set the focus and leave the pointer alone. For further information, see
The Pointer.

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

SetInputFocus

focus: WINDOW or PointerRoot or None
revert-to: { Parent, PointerRoot, None }
time: TIMESTAMP or CurrentTime

    Conventions

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

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

ClientMessage Events

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

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

  • WM_PROTOCOLS as the type field

  • Format 32

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

  • A timestamp in their data[1] field

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

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

┌───────────┬────────────────────────────┐
│Argument   │Value                       │
├───────────┼────────────────────────────┤
│destination│The client's window         │
├───────────┼────────────────────────────┤
│propagate  │False                       │
├───────────┼────────────────────────────┤
│event-mask │() empty                    │
├───────────┼────────────────────────────┤
│event      │As specified by the protocol│
└───────────┴────────────────────────────┘

Window Deletion

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

  • Either change the window's state to Withdrawn (as described in Changing
    Window State ) or destroy the window.

  • Destroy any internal state associated with the window.

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

Clients are permitted to interact with the user and ask, for 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 DestroyWindow 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.

Redirecting Requests

Normal clients can use the redirection mechanism just as window managers do by
selecting for SubstructureRedirect events on a parent window or ResizeRedirect
events on a window itself. However, at most, one client per window can select
for these events, and a convention is needed to avoid clashes.

    Convention

    Clients (including window managers) should select for SubstructureRedirect
    and ResizeRedirect events only on windows that they own.

In particular, clients that need to take some special action if they are
resized can select for ResizeRedirect events on their top-level windows. They
will receive a ResizeRequest event if the window manager resizes their window,
and the resize will not actually take place. Clients are free to make what use
they like of the information that the window manager wants to change their
size, but they must configure the window to the width and height specified in
the event in a timely fashion. To ensure that the resize will actually happen
at this stage instead of being intercepted and executed by the window manager
(and thus restarting the process), the client needs temporarily to set
override-redirect on the window.

    Convention

    Clients receiving ResizeRequest events must respond by doing the following:

      □ Setting override-redirect on the window specified in the event

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

      □ Clearing override-redirect on the window specified in the event

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

Communication with the Window Manager by Means of Selections

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

┌───────┬───────┬─────────────────────────────────────────────────────────────┐
│Atom   │Type   │Data Received                                                │
├───────┼───────┼─────────────────────────────────────────────────────────────┤
│       │       │Two integers, which are the major and minor release numbers  │
│VERSION│INTEGER│(respectively) of the ICCCM with which the window manager    │
│       │       │complies. For this version of the ICCCM, the numbers are 2   │
│       │       │and 0. ^[a]                                                  │
├───────┴───────┴─────────────────────────────────────────────────────────────┤
│^[a] As a special case, clients not wishing to implement a selection request │
│may simply issue a GetSelectionOwner request on the appropriate WM_Sn        │
│selection. If this selection is owned, clients may assume that the window    │
│manager complies with ICCCM version 2.0 or later.                            │
└─────────────────────────────────────────────────────────────────────────────┘

Summary of Window Manager Property Types

The window manager properties are summarized in the following table (see also
section 14.1 of Xlib - C Language X Interface).

┌───────────────────┬─────────────┬──────┬────────────────────────────┐
│Name               │Type         │Format│See Section                 │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_CLASS           │STRING       │8     │WM_CLASS Property           │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_CLIENT_MACHINE  │TEXT         │      │WM_CLIENT_MACHINE Property  │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_COLORMAP_WINDOWS│WINDOW       │32    │WM_COLORMAP_WINDOWS Property│
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_HINTS           │WM_HINTS     │32    │WM_HINTS Property           │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_ICON_NAME       │TEXT         │      │WM_ICON_NAME Property       │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_ICON_SIZE       │WM_ICON_SIZE │32    │WM_ICON_SIZE Property       │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_NAME            │TEXT         │      │WM_NAME Property            │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_NORMAL_HINTS    │WM_SIZE_HINTS│32    │WM_NORMAL_HINTS Property    │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_PROTOCOLS       │ATOM         │32    │WM_PROTOCOLS Property       │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_STATE           │WM_STATE     │32    │WM_STATE Property           │
├───────────────────┼─────────────┼──────┼────────────────────────────┤
│WM_TRANSIENT_FOR   │WINDOW       │32    │WM_TRANSIENT_FOR Property   │
└───────────────────┴─────────────┴──────┴────────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

^[7] 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. Window managers are free to support clients
using the obsolete protocol in a backwards compatibility mode.

^[8] Earlier versions of these conventions prohibited clients from reading the
WM_STATE property. Clients operating under the earlier conventions used the
technique of tracking ReparentNotify events to wait for the top-level window to
be reparented back to the root window. This is still a valid technique;
however, it works only for reparenting window managers, and the WM_STATE
technique is to be preferred.

^[9] The type field of the ClientMessage event (called the message_type field
by Xlib) should not be confused with the code field of the event itself, which
will have the value 33 ( ClientMessage).

^[10] This is true even if the client set the backing-store attribute to
Always. The backing-store attribute is a only a hint, and the server may stop
maintaining backing store contents at any time.

Chapter 5. Session Management and Additional Inter-Client Exchanges

Table of Contents

Client Support for Session Management
Window Manager Support for Session Management
Support for ICE Client Rendezvous

This section contains some conventions for clients that participate in session
management. See X Session Management Protocol for further details. Clients that
do not support this protocol cannot expect their window state (e.g., WM_STATE,
position, size, and stacking order) to be preserved across sessions.

Client Support for Session Management

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

  • Be of type STRING

  • Be of format 8

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

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

  • Be of type WINDOW

  • Be of format 32

  • Contain the window ID of the client leader window

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

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

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

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

  • Be of type STRING

  • Be of format 8

  • Contain a string restricted to the XPCS characters, encoded in ISO 8859-1

Window Manager Support for Session Management

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.

Support for ICE Client Rendezvous

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

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

Chapter 6. Manipulation of Shared Resources

Table of Contents

The Input Focus
The Pointer
Grabs
Colormaps
The Keyboard Mapping
The Modifier Mapping

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.

The Input Focus

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

  • Locally active mode

  • Globally active mode

    Conventions

      □ 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 message. They should set the input field of the
        WM_HINTS structure to True.

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

      □ 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
        SetInputFocus request, not CurrentTime.

The Pointer

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

    Conventions

      □ Clients should not warp the pointer.

      □ Clients that insist on warping the pointer should do so only with the
        src-window argument of the WarpPointer request set to one of their
        windows.

Grabs

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

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

    Convention

    Window managers should ensure that they provide some mechanism for their
    clients to receive events from all keys and all buttons, except for events
    involving keys whose KeySyms are registered as being for window management
    functions (for 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 button (regardless of modifiers) unless
and until the X Consortium 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.

    Convention

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

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

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

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

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

pointer/keyboard-mode == Synchronous

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

mode == ReplayPointer/Keyboard

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

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

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

  • 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

Colormaps

Colormaps prescribes conventions for clients to communicate with the window
manager about their colormap needs. If your clients are DirectColor type
applications, you should consult section 14.3 of Xlib - C Language X Interface
for conventions connected with sharing standard colormaps. They should look for
and create the properties described there on the root window of the appropriate
screen.

The contents of the RGB_COLOR_MAP type property are as follows:

┌──────────┬────────┬────────────────────────────────┐
│Field     │Type    │Comments                        │
├──────────┼────────┼────────────────────────────────┤
│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 sufficient to delete the
property; it is important to free the associated colormap resources as well. If
kill_id is greater than one, the resources should be freed by issuing a
KillClient request with kill_id as the argument. If kill_id is one, the
resources should be freed by issuing a FreeColormap request with colormap as
the colormap argument. If kill_id is zero, no attempt should be made to free
the resources. A client that creates an RGB_COLOR_MAP for which the colormap
resource is created specifically for this 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 resource ID for
kill_id (and should create no other standard colormaps on the connection).

    Convention

    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 appropriate
    screen. If an RGB_COLOR_MAP property is too short to contain the kill_id
    field, a value of zero can be assumed.

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

The Keyboard Mapping

The X server contains a table (which is read by GetKeyboardMapping requests)
that describes the set of symbols appearing on the corresponding 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
understand the keycodes they receive. Nevertheless, it is a shared resource and
requires conventions.

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

The only valid reason for using a ChangeKeyboardMapping request is when the
symbols written on the keys have changed as, for example, when a Dvorak key
conversion kit or a set of APL keycaps has been installed. Of course, a client
may have to take the change to the keycap on trust.

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

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

  • Presses the Scroll Lock key

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

  • Confirms

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

If a client succeeds in changing the keyboard mapping table, all clients will
receive MappingNotify (request==Keyboard) events. There is no mechanism to
avoid receiving these events.

    Convention

    Clients receiving MappingNotify (request==Keyboard) events should update
    any internal keycode translation tables they are using.

The Modifier Mapping

X Version 11 supports 8 modifier bits of which 3 are preassigned to Shift,
Lock, and Control. Each modifier bit is controlled by the state of a set of
keys, and these sets are specified in a table accessed by GetModifierMapping
and SetModifierMapping requests. This table is a shared resource and requires
conventions.

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

    Convention

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

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

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

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

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

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

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

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

        Conventions

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

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

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

    Convention

    The user must use xmodmap or some other utility to deassign obsolete
    modifier mappings by hand.

When a client succeeds in performing a SetModifierMapping request, all clients
will receive MappingNotify (request==Modifier) 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
GetModifierMapping request to discover the new mapping, and if the modifier it
is using has been cleared, it should reinstall the modifier.

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

Chapter 7. Device Color Characterization

Table of Contents

XYZ <-> RGB Conversion Matrices
Intensity (dA RGB Value Conversion

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 originally designed to provide access to a
device-independent color database by having the server vendor tune the
definitions of the colors in that textual database. Unfortunately, this still
does not provide the client any way of using an existing device-independent
color, nor for the client to get device-independent color information back
about colors that it has selected.

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

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

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

  • A 3 x 3 matrix M and its inverse M^-1, which convert between XYZ and RGB
    intensity (RGB[intensity]):

        RGB[intensity] = M x XYZ

        XYZ = M^-1 x RGB[intensity]

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

XYZ <-> RGB Conversion Matrices

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^27, giving a range of -16 to 16 - Ε, where Ε = 2^
-27.

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

This will be encoded as shown in the following table:

┌─────────┬─────┬────────────────────────────────────────────────┐
│Field    │Type │Comments                                        │
├─────────┼─────┼────────────────────────────────────────────────┤
│M[0,0]   │INT32│Interpreted as a fixed-point number -16 ≤ x < 16│
├─────────┼─────┼────────────────────────────────────────────────┤
│M[0,1]   │INT32│                                                │
├─────────┼─────┼────────────────────────────────────────────────┤
│...      │INT32│                                                │
├─────────┼─────┼────────────────────────────────────────────────┤
│M[3,3]   │INT32│                                                │
├─────────┼─────┼────────────────────────────────────────────────┤
│M^-1[0,0]│INT32│                                                │
├─────────┼─────┼────────────────────────────────────────────────┤
│M^-1[0,1]│INT32│                                                │
├─────────┼─────┼────────────────────────────────────────────────┤
│...      │INT32│                                                │
├─────────┼─────┼────────────────────────────────────────────────┤
│M^-1[3,3]│INT32│                                                │
└─────────┴─────┴────────────────────────────────────────────────┘

Intensity (dA RGB Value Conversion

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

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

In both cases, the relevant data will be stored in the
XDCCC_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 conversion
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 interpolate between adjacent entries in the table to compute the
desired value. This allows the server to perform gamma correction itself and
encode that fact in a short two-element correction table. The intensity will be
encoded as an unsigned number to be interpreted as a value 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 be preceded by
the number of tables. When three tables are provided, they will be in red,
green, blue order.

This will be encoded as shown in the following table:

XDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 0 Correction

┌─────────┬────┬──────────────────────────────────────────────────────────────┐
│Field    │Type│Comments                                                      │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│VisualID0│CARD│Most significant portion of VisualID                          │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│VisualID1│CARD│Exists if and only if the property format is 8                │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│VisualID2│CARD│Exists if and only if the property format is 8                │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│VisualID3│CARD│Least significant portion, exists if and only if the property │
│         │    │format is 8 or 16                                             │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│type     │CARD│0 for this type of correction                                 │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│count    │CARD│Number of tables following (either 1 or 3)                    │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│length   │CARD│Number of pairs -1 following in this table                    │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│value    │CARD│X Protocol RBG value                                          │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│intensity│CARD│Interpret as number 0 ≤ intensity ≤ 1                         │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│...      │... │Total of length+1 pairs of value/intensity values             │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│lengthg  │CARD│Number of pairs -1 following in this table (if and only if    │
│         │    │count is 3                                                    │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│value    │CARD│X Protocol RBG value                                          │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│intensity│CARD│Interpret as a number 0 ≤ intensity ≤ 1                       │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│...      │... │Total of length+1 pairs of value/intensity values             │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│lengthb  │CARD│Number of pairs -1 following in this table (if and only if    │
│         │    │count is 3                                                    │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│value    │CARD│X Protocol RBG value                                          │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│intensity│CARD│Interpret as a number 0 ≤ intensity ≤ 1                       │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│...      │... │Total of length+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:

XDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 1 Correction

┌─────────┬────┬──────────────────────────────────────────────────────────────┐
│Field    │Type│Comments                                                      │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│VisualID0│CARD│Most significant portion of VisualID                          │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│VisualID1│CARD│Exists if and only if the property format is 8                │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│VisualID2│CARD│Exists if and only if the property format is 8                │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│VisualID3│CARD│Least significant portion, exists if and only if the property │
│         │    │format is 8 or 16                                             │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│type     │CARD│1 for this type of correction                                 │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│count    │CARD│Number of tables following (either 1 or 3)                    │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│length   │CARD│Number of pairs -1 following in this table                    │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│intensity│CARD│Interpret as number 0 ≤ intensity ≤ 1                         │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│...      │... │Total of length+1 pairs of value/intensity values             │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│lengthg  │CARD│Number of pairs -1 following in this table (if and only if    │
│         │    │count is 3                                                    │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│intensity│CARD│Interpret as a number 0 ≤ intensity ≤ 1                       │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│...      │... │Total of length+1 pairs of value/intensity values             │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│lengthb  │CARD│Number of pairs -1 following in this table (if and only if    │
│         │    │count is 3                                                    │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│intensity│CARD│Interpret as a number 0 ≤ intensity ≤ 1                       │
├─────────┼────┼──────────────────────────────────────────────────────────────┤
│...      │... │Total of length+1 pairs of value/intensity values             │
└─────────┴────┴──────────────────────────────────────────────────────────────┘

Chapter 8. Conclusion

Table of Contents

The X Registry

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 protocol. Clients should be aware of other protocols that should be
used for better interoperation in the X environment. The reader is referred to 
X Session Management Protocol for information on session management, and to 
Inter-Client Exchange Protocol for information on general-purpose communication
among clients.

The X Registry

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, ClientMessage types, and application classes.
Requests to register items, or questions about registration, should be
addressed to


     xregistry@x.org
  

or to


        The X.Org Foundation -- X11 Registry
        c/o Alan Coopersmith
        Oracle Corporation
        M/S SCA17-3824
        4170 Network Circle
        Santa Clara, CA 95054
        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 distribution from the X.Org
Foundation. 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.

Appendix A. Revision History

Table of Contents

The X11R2 Draft
The July 27, 1988, Draft
The Public Review Drafts
Version 1.0, July 1989
Version 1.1
Public Review Draft, December 1993
Version 2.0, April 1994

This appendix describes the revision history of this document and summarizes
the incompatibilities between this and earlier versions.

The X11R2 Draft

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 incompatibility. As far as
possible, we have tried to ensure that clients obeying the conventions in the
X11R2 draft would still work.

The July 27, 1988, Draft

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

  • The use of property None in ConvertSelection requests is no longer allowed.
    Owners that receive them are free to use the target atom as the property to
    respond with, which will work in most cases.

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

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

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

  • The set of state values in WM_HINTS.initial_state has been reduced, but the
    values that are still valid are unchanged. Window managers should treat the
    other values sensibly.

  • The methods an application uses to change the state of its top-level window
    have changed but in such a way that cases that used to work will still
    work.

  • The x, y, width, and height fields have been removed from the
    WM_NORMAL_HINTS property and replaced by pad fields. Values set into these
    fields will be ignored. The position and size of the window should be set
    by setting the appropriate window attributes.

  • A pair of base fields and a win_gravity field have been added to the
    WM_NORMAL_HINTS property. Window managers will assume values for these
    fields if the client sets a short property.

The Public Review Drafts

The Consortium review resulted in several incompatible changes. These changes
were included in drafts that were distributed for public review during the
first half of 1989.

  • The messages field of the WM_HINTS property was found to be unwieldy and
    difficult to evolve. It has been replaced by the WM_PROTOCOLS property, but
    clients that use the earlier mechanism can be detected because they set the
    messages bit in the flags field of the WM_HINTS property, and window
    managers can provide a backwards compatibility mode.

  • The mechanism described in the earlier draft by which clients installed
    their own subwindow colormaps could not be made to work reliably and
    mandated some features of the look and feel. It has been replaced by the
    WM_COLORMAP_WINDOWS property. Clients that use the earlier mechanism can be
    detected by the WM_COLORMAPS property they set on their top-level window,
    but providing a reliable backwards compatibility mode is not possible.

  • The recommendations for window manager treatment of top-level window
    borders have been changed as those in the earlier draft produced problems
    with Visibility events. For nonwindow manager clients, there is no
    incompatibility.

  • 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 envisaged. An extension will be required to support these uses
    fully, and it was felt that the maximum freedom should be left to the
    designers of the extension. In general, the previous mechanism was
    invisible to clients and no incompatibility should result.

  • 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 protocols
    are orthogonal. Clients using the earlier protocol can be detected (see
    WM_PROTOCOLS above) and supported in a backwards compatibility mode.

  • The conventions in Section 14.3.1. of Xlib - C Language X Interface
    regarding properties of type RGB_COLOR_MAP have been changed, but clients
    that use the earlier conventions can be detected because their properties
    are 4 bytes shorter. These clients will work correctly if the server
    supports only a single Visual or if they use only the Visual of the root.
    These are the only cases in which they would have worked, anyway.

Version 1.0, July 1989

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

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

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

  • A selection owner using INCR transfer should no longer replace targets in a
    MULTIPLE property with the atom INCR.

  • The contents of the ClientMessage event sent by a client to iconify itself
    has been clarified, but there should be no incompatibility because the
    earlier contents would not in fact have worked.

  • The border-width in synthetic ConfigureNotify events is now specified, but
    this should not cause any incompatibility.

  • Clients are now asked to set a border-width on all ConfigureWindow
    requests.

  • Window manager properties on icon windows now will be ignored, but there
    should be no incompatibility because there was no specification that they
    be obeyed previously.

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

  • The semantics of WM_SAVE_YOURSELF have been clarified and restricted to be
    a checkpoint operation only. Clients that were using it as part of a
    shutdown sequence may need to be modified, especially if they were
    interacting with the user during the shutdown.

  • A kill_id field has been added to RGB_COLOR_MAP properties. Clients using
    earlier conventions can be detected by the size of their RGB_COLOR_MAP
    properties, and the cases that would have worked will still work.

Version 1.1

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

  • The section on Device Color Characterization was added.

  • The meaning of the NULL property type was clarified.

  • Appropriate references to Compound Text were added.

Public Review Draft, December 1993

The following changes have been made in preparing the public review draft for
Version 2.0.

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

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

  • [P06] Colormaps , on colormaps, has been rewritten. A new feature that
    allows clients to install their own colormaps has also been added.

  • [P08] The LENGTH target has been deprecated.

  • [P11] The manager selections facility was added.

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

  • [P19] StaticGravity has been added to the list of values allowed for the
    win_gravity field of the WM_HINTS property. The meaning of the
    CenterGravity value has been clarified.

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

  • [P22] The definition of the MULTIPLE selection target has been clarified.

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

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

  • [P27] Clarified the rules governing when window managers are required to
    send synthetic ConfigureNotify events.

  • [P28] Added a recommended technique for setting the input focus to a window
    as soon as it is mapped.

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

  • [P30] Advice for dealing with keystrokes and override-redirect windows has
    been added.

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

  • [P32] The definition of the CLIENT_WINDOW target has been clarified.

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

  • [P42] Added several new selection targets.

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

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

  • [P49] A convention on discriminated names has been added.

  • [P57] The C_STRING property type was added.

  • [P62] An ordering requirement on processing selection requests was added.

  • [P63] The VisibleHint flag was added.

  • [P64] The session management section has been updated to align with the new
    session management protocol. The old session management conventions have
    been moved to Appendix C.

  • References to the never-forthcoming Window and Session Manager Conventions
    Manual have been removed.

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

  • Numerous editorial and typographical improvements have been made.

Version 2.0, April 1994

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

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

  • The session management section has been revised slightly to correspond with
    the changes to the X Session Management Protocol.

  • Window managers are now prohibited from placing CurrentTime in the
    timestamp field of WM_TAKE_FOCUS messages.

  • In the WM_HINTS property, the VisibleHint flag has been renamed to
    UrgencyHint. Its semantics have also been defined more thoroughly.

  • Additional editorial and typographical changes have been made.

Appendix B. Suggested Protocol Revisions

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

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

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

  • There would be no need for WM_TAKE_FOCUS if the FocusIn event contained a
    timestamp and a previous-focus field. This could avoid the potential race
    condition. There is space in the event for this information; it should be
    added at the next protocol revision.

  • There is a race condition in the InstallColormap request. It does not take
    a timestamp and may be executed after the top-level colormap has been
    uninstalled. The next protocol revision should provide the timestamp in the
    InstallColormap, UninstallColormap, ListInstalledColormaps requests and in
    the ColormapNotify event. The timestamp should be used in a similar way to
    the last-focus-change time for the input focus. The lack of timestamps in
    these packets is the reason for restricting colormap installation to the
    window manager.

  • The protocol needs to be changed to provide some way of identifying the
    Visual and the Screen of a colormap.

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

Appendix C. Obsolete Session Manager Conventions

Table of Contents

Properties
    WM_COMMAND Property
    WM_CLIENT_MACHINE Property
Termination
Client Responses to Session Manager Actions
    Saving Client State
    Window Deletion
Summary of Session Manager Property Types

This appendix contains obsolete conventions for session management 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 Session Management Protocol.

Properties

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.

WM_COMMAND Property

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:

  • Be of type STRING

  • Contain a list of null-terminated strings

  • Be initialized from argv

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

Note that WM_COMMAND strings are null-terminated and differ from the general
conventions that STRING properties are null-separated. This inconsistency is
necessary for backwards 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.

WM_CLIENT_MACHINE Property

This property is described in WM_CLIENT_MACHINE Property.

Termination

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

Client Responses to Session Manager Actions

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

  • Saving their internal state

  • Deleting a window

Saving Client State

Clients that want to be warned when the session manager feels that they should
save their internal state (for example, when termination impends) should
include the atom WM_SAVE_YOURSELF in the WM_PROTOCOLS property on their
top-level windows to participate in the WM_SAVE_YOURSELF protocol. They will
receive a ClientMessage event as described in ClientMessage Events with the
atom WM_SAVE_YOURSELF in its data[0] field.

Clients that receive WM_SAVE_YOURSELF should place themselves in a state from
which they can be restarted and should update WM_COMMAND to be a command that
will restart them in this state. The session manager will be waiting for a
PropertyNotify event on WM_COMMAND as a confirmation that the client has saved
its state. Therefore, WM_COMMAND should be updated (perhaps with a zero-length
append) even if its contents are correct. No interactions with the user are
permitted during this process.

Once it has received this confirmation, the session manager will feel free to
terminate the client if that is what the user asked for. Otherwise, if the user
asked for the session to be put to sleep, the session manager will ensure that
the client does not receive any mouse or keyboard events.

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

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

  • Only one of their top-level windows has a nonzero-length WM_COMMAND
    property.

  • They respond to a WM_SAVE_YOURSELF message by:

      □ First, updating the nonzero-length WM_COMMAND property, if necessary

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

Receiving WM_SAVE_YOURSELF on a window is, conceptually, a command to save the
entire client state. ^[11]

Window Deletion

Windows are deleted using the WM_DELETE_WINDOW protocol, which is described in
Window Deletion.

Summary of Session Manager Property Types

The session manager properties are listed in the following table:

┌─────────────────┬────────┬──────┬──────────────────────────┐
│Name             │Type    │Format│See Section               │
├─────────────────┼────────┼──────┼──────────────────────────┤
│WM_CLIENT_MACHINE│TEXT    │      │WM_CLIENT_MACHINE Property│
├─────────────────┼────────┼──────┼──────────────────────────┤
│WM_COMMAND       │TEXT    │      │WM_COMMAND Property       │
├─────────────────┼────────┼──────┼──────────────────────────┤
│WM_STATE         │WM_STATE│32    │WM_STATE Property         │
└─────────────────┴────────┴──────┴──────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

^[11] 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.

