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
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
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
Table of Contents
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.
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.
Many of the conventions use atoms. To assist the reader, the following sections attempt to amplify the description of atoms that is provided in the protocol specification.
At the conceptual level, atoms are unique names that clients can use to communicate information to each other. They can be thought of as a bundle of octets, like a string but without an encoding being specified. The elements are not necessarily ASCII characters, and no case folding happens. [1]
The protocol designers felt that passing these sequences of bytes back and forth across the wire would be too costly. Further, they thought it important that events as they appear on the wire have a fixed size (in fact, 32 bytes) and that because some events contain atoms, a fixed-size representation for them was needed.
To allow a fixed-size representation,
a protocol request
( 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 ).
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
InternAtomrequests 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.
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.
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.
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, &... |
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.
Table of Contents
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.
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
SetSelectionOwnerrequest to the timestamp of the event triggering the acquisition attempt, not toCurrentTime. A zero-length append to a property is a way to obtain a timestamp for this purpose; the timestamp is in the correspondingPropertyNotifyevent.
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.
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
SelectionRequestevents 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
SelectionNotifyevent should be set to the values received in theSelectionRequestevent.
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
SelectionNotifyevent will have its property argument set toNone. 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
SelectionNotifyevents (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.
Clients may either give up selection ownership voluntarily or lose it forcibly as the result of some other client's actions.
To relinquish ownership of a selection voluntarily,
a client should execute a
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.
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.
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
CurrentTimefor the time argument of aConvertSelectionrequest. 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
SelectionNotifyonce all the data has been retrieved. The requestor should invoke eitherDeletePropertyorGetProperty(delete==True) after it has successfully retrieved all the data in the selection. For further information, see 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.
Defining a new atom consumes resources in the server that are not released until the server reinitializes. Thus, reducing the need for newly minted atoms is an important goal for the use of the selection atoms.
There can be an arbitrary number of selections, each named by an atom. To conform with the inter-client conventions, however, clients need deal with only these three selections:
PRIMARY
SECONDARY
CLIPBOARD
Other selections may be used freely for private communication among related groups of clients.
The selection named by the atom PRIMARY is used for all commands that take only a single argument and is the principal means of communication between clients that use the selection mechanism.
The selection named by the atom SECONDARY is used:
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 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.
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 | ||