Page:   1 2 3 4 5 6 7 8 9 10 11

Chapter 3


Inter-Client Communication Conventions Manual

Version 1.1

MIT X Consortium Standard

X Version 11, Release 6

David Rosenthal

Sun Microsystems, Inc.

Version2 edited by Stuart W. Marks

Sun Soft, Inc.

X Window System is a trademark of X Consortium, Inc.

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.

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 this document. This documentation is provided as is without express or implied warranty.


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

Home

3.1 INTRODUCTION

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:

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.

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

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

3.1.2.1 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 comment in the protocol specification for InternAtom that ISO Latin-l encoding should be used is in the nature of a convention; the server treats the string as a byte sequence.)

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

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

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

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

3.1.2.5 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_EDIT,...

3.1.2.6 Discriminated Names

Sometimes a protocol requires there to be an arbitrary number of similar objects which need unique names (usually because the objects are created dynamically, so that name 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 letter, 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 name (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_UI BAR_U1...)
if they come in sets (here there are two sets, name "FOO" and "BAR").; The stand-alone Ud form should only be used 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 which 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 from 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.

Home

3.2 COMMUNICATION BY MEANS OF 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. Section 3.2.6 discusses the choice of an atom. Each selection is owned by a client and is attached to a window.

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

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

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, and so on) is permitted only if both clients specifically agree.

3.2.1 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) At present, no pan of the protocol requires requestors to send events to the owner of a selection. This restriction is imposed to prepare for possible future extensions.)

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.

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

Selection Request
owner: WINDOW
selection: ATOM
target: ATOM
property: ATOM or None
requestor: W1NDOW
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 Section 3.2.5.

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 Section 3.2.4) or in properties with type MULTIPLE.

A selection owner will often need confirmation that the data comprising the selection has actually been transferred. (For example, if the operation has side effects on the owner's internal data structures, these should not take place until the requestor has indicated that it has successfully received the data.) Owners should express interest in PropertyNotify events for the specified requestor window and wait until the property in the SelectionNotify even 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, the owner should take no action. (The division between these two cases is a matter of judgment on the part of the software developer)

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

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

3.2.3.2 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 Selection Clear event. For the definition of a Selection Clear event, see Section 3.2.2.

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.

3.2.4 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 Section 3.2.6. 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. The exception to this rule is when the requestor intends to pass parameter with the request.

(This requirement is new in vermin 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.)

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 requesters can pass parameters along with the request. If the requestor wishes to provided 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
  1. Requestors should not use None for the property argument of a ConvertSelection request.
  2. 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 Section 3.2.2.

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 LISToflNT16 or LISTofINT32

When using 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 Section 3.2.5). If the returned value of bytes-after is zero, the whole property has been transferred.

Once all the data in the selection has been retrieved (which may require getting the values of several properties-see Section 3.2.7), 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 Section 3.2.5.

3.2.5 Large Data Transfers

Selections can get large, which poses two problems:

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

Conventions

Advice to Implementors

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

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

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

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

3.2.6.1.2 The SECONDARY Selection

The selection named by the atom SECONDARY is used:

3.2.6.1.3 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 or copied, and then pasted. Whenever a client wants to transfer 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:

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:

The reasons not to run the clipboard client include:

3.2.6.2 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
CLASS TEXT (see Section 3.4.1.2.5)
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 Section 3.2.6.3.1)
DRAWABLE DRAWABLE A list of drawable IDs
ENCAPSULATED_POSTS CRIPT    
  STRING [3], Appendix H6)
ENCAPSULATED_POSTSCRIPT_INTERCHANGE    
  STRING [3], Appendix H6)
FILE_NAME TEXT The full path name of a file
FOREGROUND PIXEL A list of pixel values
HOST_NAME TEXT (see Section 3.4.1.2.9)
INSERT_PROPERTY NULL (see Section 3.2.6.3.3)
INSERT_SELECTION NULL (see Section 3.2.6.3.2)
LENGTH INTEGER The number of bytes in the selection7)
LINE_NUMBER SPAN The start and end line numbers
LIST_LENGTH INTEGER Thc number of disjoint parts of the selection
MODULE TEXT The name of the selected procedure
MULTlPLE ATOM_PAIR (see the discussion that follows)
NAME TEXT (see Section 3.4.1.2.1)
ODIF TEXT ISO Office Document Interchange Format
OWNER_OS TEXT The operating system of the owner client
PIXMAP5) Pixmap5) 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-l (+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

References (print-only documents):

  1. Adobe Systems, incorporated. Portable Document Format Reference Manual. AddisonWesley, ISBN 0-201-62628-4.
  2. Apple Computer, Incorporated. Inside Macintosh, Volume V. Chapter 4, "Color Quick-Draw," Color Picture Format. ISBN0-201-17719-6.
  3. Adobe Systems, Incorporated. PostScript Language Reference Manual. Addison-Wesley, ISBN 0-20l - 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.

3.2.6.3 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 zerolength 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
  1. Targets with side effects should return no information (that is, they should have a zero-length property of type NULL).
  2. The side effect of a target must be performed before the conversion is accepted.
  3. If the side effect of a target cannot be performed, the corresponding conversion request must be refused.

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

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

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

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

3.2.7 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 property 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. For variable-length items such as text, the separators are listed in the following table:

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.

3.2.7.1 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 Section 3.2.6.2, the word TEXT (in the Type column) is used to indicate one of the registered encoding names. The type would not actually be TEXT; it would be STRING or some other ATOM naming the encoding chosen by the owner.

STRING as a type or a target specifies the ISO Latin-l 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 nay byte value is forbidden or that any two differing sequences are equivalent8). 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 and COMPOUND_TEXT properties will consist of a list of elements separated by null characters; other encodings will need to specify an appropriate list format.

8) Note that this 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.

3.2.7.2 INCR Properties

Requestors may receive a property of type INCR9) 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:

The selection requestor:

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

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

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

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

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

3.2.8 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 Sections 3.1.2.3 and 3.1.2.6. A client that manages multiple shared resources (or groups of resources) should take ownership of a selection for each one.

The manager may support conversion of various targets for that selection. Managers are encouraged to use this 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 Sections 3.2.1 and 3.2.2, and they must also support the required targets listed in Section 3.2.6.2.

If a manager loses ownership of a manager selection, this means that a new manager is taking over its responsibilities. The old manager must release all resources it has managed, and must then destroy the window that owned the selection. For example, a window manager losing ownership of WM_S2 must be select from Substructure Redirect 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 interesting 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 selection 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
destination: the root window of screen 0, or the root window of the appropriate screen if the manager is managing a screen-specific resource
propagate: False
event-mask: StructureNotify
event: ClientMessage
type: MANAGER
format: 32
data[0]: 10 timestamp
data[1]: manager selection atom
data[2]: the window owning the selection
data[3]: manager-selection-specific data
data[4]: manager-selection-specific data
10) We use the notation data[n] to indicate the nth element of the LlST of INT8, LIS of INT16, or LlSToflNT32 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 Client-Message.

Home

3.3 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_BUFFER to CUT_BUFFERI. 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 CUT_B JFFER1, CUT_BUFFER1 to CUT_BUFFER2,..., and CUT_BUFFER7 to CUT_B JFFER0. It then must store the data into CUT_BUFFER0 by using a ChangeProperty request n 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 from.

Home

3.4 CLIENT TO WINDOW MANAGER COMMUNICATION

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.

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

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

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 Sections 3.4.1.2.4 and 3.4.1.4.

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

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

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

3.4.1.2.1 WM_NAMEProperty

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

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

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

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

3.4.1.2.3 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
US Position 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 mapped from the Withdrawn state) 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 site 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 South East (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 other 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 nonnegative integers i and j:

width = base_width + ( i * width_inc)
height = base_height + ( j * 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.)

3.4.1.2.4 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
lags 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 Section 3.4.1.7).

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:

The semantics of these states are described in 3.4.1.4. Newly created windows start in the Withdrawn state. Transitions between states happen when a top-level window is mapped and unmapped and when the window manager receives certain messages.

The value of the initial_state field determines the state the client wishes to be in at the time the top-level window is mapped from the Withdrawn state, as shown in the 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:

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 two-color bitmap should use icon windows. Rules for clients that do are set out in Section 3.4.1.9.

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

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

Conventions
  1. The window_group field should be set to the ID of the group leader. The window group leader may be a window that exists only for that purpose; a placeholder group leader of this kind would never be mapped either by the client or by the window manager.
  2. The properties of the window group leader are those for the group as a whole (for example, the icon to be shown when the entire group is iconified).

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

The messages bit, if set in the flags field, indicates that the client is using an obsolete window manager communication protocols, 11) rather than the WM_PROTOCOLS mechanism of Section 3.4.1.2.7.

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 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 of 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.
11) This obsolete protocol was described in the July 27. 1988 draft of the ICCCM. Windows using it can also be detected because their WM HINTS properties are four bytes Ionger than expected. Window managers are free to support clients using the obsolete protocol in a "backwards compatibility"mode._

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

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.

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

3.4.1.2.7 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 Section 3.4.2.8. 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 4.1.7 Assignment of input focus
WM_SAVE_YOURSELF Appendix C Save client state request (deprecated)
WM_DELETE_WINDOW 4.2.8.1 Request to delete top-level window

It is expected that this table will grow over time.

3.4.1.2.8 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 Section 3.4.1.8.

3.4.1.2.9 WM CLIENT_MACHIE 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.

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

3.4.1.3.1 WM STATE Property

The window manger 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 with-drawn, 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 X Consortium.

The state field describes the window manger'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 pix-map, or it may be an ancestor of the client's icon window.


Home

Contents Previous Chapter Chapter 3, Part 2