1056N/AInter-Client Communication Conventions Manual
1056N/ACopyright © 1988, 1991, 1993, 1994 X Consortium
1056N/APermission is hereby granted, free of charge, to any person obtaining a copy of
1056N/Athis software and associated documentation files (the "Software"), to deal in
1056N/Athe Software without restriction, including without limitation the rights to
1056N/Ause, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies
1056N/Aof the Software, and to permit persons to whom the Software is furnished to do
1056N/Aso, subject to the following conditions:
1056N/AThe above copyright notice and this permission notice shall be included in all
1056N/Acopies or substantial portions of the Software.
1276N/ATHE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1056N/AIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1056N/AFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X
1056N/ACONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
1056N/AACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
1056N/AWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1056N/AExcept as contained in this notice, the name of the X Consortium shall not be
1056N/Aused in advertising or otherwise to promote the sale, use or other dealings in
1056N/Athis Software without prior written authorization from the X Consortium.
1276N/AX Window System is a trademark of The Open Group.
1056N/ACopyright © 1987, 1988, 1989, 1993, 1994 Sun Microsystems, Inc
1056N/APermission to use, copy, modify, and distribute this documentation for any
1056N/Apurpose and without fee is hereby granted, provided that the above copyright
1056N/Anotice and this permission notice appear in all copies. Sun Microsystems makes
1056N/Ano representations about the suitability for any purpose of the information in
1056N/Athis document. This documentation is provided as is without express or implied
1056N/A━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1056N/A Evolution of the Conventions
1056N/A2. Peer-to-Peer Communication by Means of Selections
1056N/A Acquiring Selection Ownership
1056N/A Responsibilities of the Selection Owner
1056N/A Giving Up Selection Ownership
1056N/A Voluntarily Giving Up Selection Ownership
1056N/A Forcibly Giving Up Selection Ownership
1056N/A Selection Targets with Side Effects
1056N/A Use of Selection Properties
1056N/A3. Peer-to-Peer Communication by Means of Cut Buffers
1056N/A4. Client-to-Window-Manager Communication
1056N/A Creating a Top-Level Window
1056N/A Client Responses to Window Manager Actions
1056N/A Communication with the Window Manager by Means of Selections
1056N/A Summary of Window Manager Property Types
1056N/A5. Session Management and Additional Inter-Client Exchanges
1056N/A Client Support for Session Management
1056N/A Window Manager Support for Session Management
1056N/A Support for ICE Client Rendezvous
1056N/A6. Manipulation of Shared Resources
1056N/A7. Device Color Characterization
1056N/A XYZ <-> RGB Conversion Matrices
1056N/A Intensity (dA RGB Value Conversion
1056N/A Public Review Draft, December 1993
1056N/AB. Suggested Protocol Revisions
1056N/AC. Obsolete Session Manager Conventions
1056N/A Client Responses to Session Manager Actions
1056N/A Summary of Session Manager Property Types
1056N/AThe goal of the ICCCM Version 2.0 effort was to add new facilities, to fix
1056N/Aproblems with earlier drafts, and to improve readability and understandability,
1056N/Awhile maintaining compatibility with the earlier versions. This document is the
1056N/Aproduct of over two years of discussion among the members of the X Consortium's
1056N/Awmtalk working group. The following people deserve thanks for their
1056N/ASusan Dahlberg Bob Scheifler
1056N/AAndrew deBlois Jim VanGilder
1056N/AIt has been a privilege for me to work with this fine group of people.
1056N/ADavid Rosenthal had overall architectural responsibility for the conventions
1056N/Adefined in this document; he wrote most of the text and edited the document,
1056N/Abut its development has been a communal effort. The details were thrashed out
1056N/Ain meetings at the January 1988 MIT X Conference and at the 1988 Summer Usenix
1056N/Aconference, and through months (and megabytes) of argument on the wmtalk mail
1056N/Aalias. Thanks are due to everyone who contributed, and especially to the
1056N/AFor the Window and Session Manager sections:
1056N/AKerry Kimbrough Glenn Widener
1056N/AFor the Device Color Characterization section:
1056N/AIn addition, thanks are due to those who contributed to the public review:
1056N/AEvolution of the Conventions
1056N/AIt was an explicit design goal of X Version 11 to specify mechanism, not
1056N/Apolicy. As a result, a client that converses with the server using the protocol
1056N/Adefined by the X Window System Protocol, Version 11 may operate correctly in
1056N/Aisolation but may not coexist properly with others sharing the same server.
1056N/ABeing a good citizen in the X Version 11 world involves adhering to conventions
1056N/Athat govern inter-client communications in the following areas:
1056N/A ● Manipulation of shared resources
1056N/A ● Device color characterization
1056N/AThis document proposes suitable conventions without attempting to enforce any
1056N/Aparticular user interface. To permit clients written in different languages to
1056N/Acommunicate, these conventions are expressed solely in terms of protocol
1056N/Aoperations, not in terms of their associated Xlib interfaces, which are
1056N/Aprobably more familiar. The binding of these operations to the Xlib interface
1056N/Afor C and to the equivalent interfaces for other languages is the subject of
1056N/AEvolution of the Conventions
1056N/AIn the interests of timely acceptance, the Inter-Client Communication
1056N/AConventions Manual (ICCCM) covers only a minimal set of required conventions.
1056N/AThese conventions will be added to and updated as appropriate, based on the
1056N/Aexperiences of the X Consortium.
1056N/AAs far as possible, these conventions are upwardly compatible with those in the
1056N/AFebruary 25, 1988, draft that was distributed with the X Version 11, Release 2,
1056N/Aof the software. In some areas, semantic problems were discovered with those
1056N/Aconventions, and, thus, complete upward compatibility could not be assured.
1056N/AThese areas are noted in the text and are summarized in Appendix A.
1056N/AIn the course of developing these conventions, a number of minor changes to the
1056N/Aprotocol were identified as desirable. They also are identified in the text,
1056N/Aare summarized in Appendix B, and are offered as input to a future protocol
1056N/Arevision process. If and when a protocol revision incorporating these changes
1056N/Ais undertaken, it is anticipated that the ICCCM will need to be revised.
1056N/ABecause it is difficult to ensure that clients and servers are upgraded
1056N/Asimultaneously, clients using the revised conventions should examine the minor
1056N/Aprotocol revision number and be prepared to use the older conventions when
1056N/Acommunicating with an older server.
1056N/AIt is expected that these revisions will ensure that clients using the
1056N/Aconventions appropriate to protocol minor revision n will interoperate
1056N/Acorrectly with those that use the conventions appropriate to protocol minor
1056N/Arevision n + 1 if the server supports both.
1056N/AMany of the conventions use atoms. To assist the reader, the following sections
1056N/Aattempt to amplify the description of atoms that is provided in the protocol
1056N/AAt the conceptual level, atoms are unique names that clients can use to
1056N/Acommunicate information to each other. They can be thought of as a bundle of
1056N/Aoctets, like a string but without an encoding being specified. The elements are
1056N/Anot necessarily ASCII characters, and no case folding happens. ^[1]
1056N/AThe protocol designers felt that passing these sequences of bytes back and
1056N/Aforth across the wire would be too costly. Further, they thought it important
1056N/Athat events as they appear on the wire have a fixed size (in fact, 32 bytes)
1056N/Aand that because some events contain atoms, a fixed-size representation for
1056N/ATo allow a fixed-size representation, a protocol request ( InternAtom ) was
1056N/Aprovided to register a byte sequence with the server, which returns a 32-bit
1056N/Avalue (with the top three bits zero) that maps to the byte sequence. The
1056N/Ainverse operator is also available ( GetAtomName ).
1056N/AThe protocol specifies a number of atoms as being predefined:
1056N/A Predefined atoms are not strictly necessary and may not be useful in all
1056N/A environments, but they will eliminate many InternAtom requests in most
1056N/A applications. Note that they are predefined only in the sense of having
1056N/A numeric values, not in the sense of having required semantics.
1056N/APredefined atoms are an implementation trick to avoid the cost of interning
1056N/Amany of the atoms that are expected to be used during the startup phase of all
1056N/Aapplications. The results of the InternAtom requests, which require a
1056N/Ahandshake, can be assumed a priori.
1056N/ALanguage interfaces should probably cache the atom-name mappings and get them
1056N/Aonly when required. The CLX interface, for instance, makes no distinction
1056N/Abetween predefined atoms and other atoms; all atoms are viewed as symbols at
1056N/Athe interface. However, a CLX implementation will typically keep a symbol or
1056N/Aatom cache and will typically initialize this cache with the predefined atoms.
1056N/AThe built-in atoms are composed of uppercase ASCII characters with the logical
1056N/Awords separated by an underscore character (_), for example, WM_ICON_NAME. The
1056N/Aprotocol specification recommends that atoms used for private vendor-specific
1056N/Areasons should begin with an underscore. To prevent conflicts among
1056N/Aorganizations, additional prefixes should be chosen (for example,
1056N/A_DEC_WM_DECORATION_GEOMETRY).
1056N/AThe names were chosen in this fashion to make it easy to use them in a natural
1056N/Away within LISP. Keyword constructors allow the programmer to specify the atoms
1056N/Aas LISP atoms. If the atoms were not all uppercase, special quoting conventions
1056N/AThe core protocol imposes no semantics on atoms except as they are used in
1056N/AFONTPROP structures. For further information on FONTPROP semantics, see the X
1056N/ALogical Font Description Conventions.
1056N/AThe protocol defines six distinct spaces in which atoms are interpreted. Any
1056N/Aparticular atom may or may not have some valid interpretation with respect to
1276N/A┌──────────────────┬─────────┬───────────────────────────────────────┐
1276N/A├──────────────────┼─────────┼───────────────────────────────────────┤
1276N/A│Property name │Name │WM_HINTS, WM_NAME, RGB_BEST_MAP, ... │
1276N/A├──────────────────┼─────────┼───────────────────────────────────────┤
1276N/A│Property type │Type │WM_HINTS, CURSOR, RGB_COLOR_MAP, ... │
1276N/A├──────────────────┼─────────┼───────────────────────────────────────┤
1276N/A│Selection name │Selection│PRIMARY, SECONDARY, CLIPBOARD │
1276N/A├──────────────────┼─────────┼───────────────────────────────────────┤
1276N/A│Selection target │Target │FILE_NAME, POSTSCRIPT, PIXMAP, ... │
1276N/A├──────────────────┼─────────┼───────────────────────────────────────┤
1276N/A│Font property │ │QUAD_WIDTH, POINT_SIZE, ... │
1276N/A├──────────────────┼─────────┼───────────────────────────────────────┤
1276N/A│ClientMessage type│ │WM_SAVE_YOURSELF, _DEC_SAVE_EDITS, &...│
1276N/A└──────────────────┴─────────┴───────────────────────────────────────┘
1056N/ASometimes a protocol requires an arbitrary number of similar objects that need
1056N/Aunique names (usually because the objects are created dynamically, so that
1056N/Anames cannot be invented in advance). For example, a colormap-generating
1056N/Aprogram might use the selection mechanism to offer colormaps for each screen
1056N/Aand so needs a selection name for each screen. Such names are called
1056N/A"discriminated names" and are discriminated by some entity. This entity can be:
1056N/A An X resource (a window, a colormap, a visual, etc.)
1056N/AIf it is only necessary to generate a fixed set of names for each value of the
1056N/Adiscriminating entity, then the discriminated names are formed by suffixing an
1056N/Aordinary name according to the value of the entity.
1056N/AIf name is a descriptive portion for the name, d is a decimal number with no
1056N/Aleading zeroes, and x is a hexadecimal number with exactly 8 digits, and using
1056N/Auppercase letters, then such discriminated names shall have the form:
1276N/A┌─────────────────────┬───────┬──────────────────────┐
1276N/A│Name Discriminated by│Form │Example │
1276N/A├─────────────────────┼───────┼──────────────────────┤
1276N/A│screen number │name_Sd│WM_COMMS_S2 │
1276N/A├─────────────────────┼───────┼──────────────────────┤
1276N/A│X resource │name_Rx│GROUP_LEADER_R1234ABCD│
1276N/A└─────────────────────┴───────┴──────────────────────┘
1056N/ATo discriminate a name by client, use an X resource ID created by that client.
1056N/AThis resource can be of any type.
1056N/ASometimes it is simply necessary to generate a unique set of names (for
1056N/Aexample, for the properties on a window used by a MULTIPLE selection). These
1056N/Aif the names stand totally alone, and the form:
1056N/Aif they come in sets (here there are two sets, named "FOO" and "BAR"). The
1056N/Astand-alone Ud form should be used only if it is clear that the module using it
1056N/Ahas complete control over the relevant namespace or has the active cooperation
1056N/Aof all other entities that might also use these names. (Naming properties on a
1056N/Awindow created specifically for a particular selection is such a use; naming
1056N/Aproperties on the root window is almost certainly not.)
1056N/AIn a particularly difficult case, it might be necessary to combine both forms
1056N/Aof discrimination. If this happens, the U form should come after the other
1056N/A Existing protocols will not be changed to use these naming conventions,
1056N/A because doing so will cause too much disruption. However, it is expected
1056N/A that future protocols -- both standard and private -- will use these
1056N/A^[1] The comment in the protocol specification for InternAtom that ISO Latin-1
1056N/Aencoding should be used is in the nature of a convention; the server treats the
1056N/AChapter 2. Peer-to-Peer Communication by Means of Selections
1056N/AAcquiring Selection Ownership
1056N/AResponsibilities of the Selection Owner
1056N/AGiving Up Selection Ownership
1056N/A Voluntarily Giving Up Selection Ownership
1056N/A Forcibly Giving Up Selection Ownership
1056N/A Selection Targets with Side Effects
1056N/ASelections are the primary mechanism that X Version 11 defines for the exchange
1056N/Aof information between clients, for example, by cutting and pasting between
1056N/Awindows. Note that there can be an arbitrary number of selections (each named
1276N/Aby an atom) and that they are global to the server. Use of Selection Atoms.
1276N/Adiscusses the choice of an atom. Each selection is owned by a client and is
1056N/ASelections communicate between an owner and a requestor. The owner has the data
1056N/Arepresenting the value of its selection, and the requestor receives it. A
1056N/Arequestor wishing to obtain the value of a selection provides the following:
1056N/A ● The name of the selection
1056N/A ● The atom representing the data type required
1056N/A ● Optionally, some parameters for the request
1056N/AIf the selection is currently owned, the owner receives an event and is
1056N/Aexpected to do the following:
1056N/A ● Convert the contents of the selection to the requested data type
1056N/A ● Place this data in the named property on the named window
1056N/A ● Send the requestor an event to let it know the property is available
1056N/AClients are strongly encouraged to use this mechanism. In particular,
1056N/Adisplaying text in a permanent window without providing the ability to select
1056N/Aand convert it into a string is definitely considered antisocial.
1056N/ANote that all data transferred between an owner and a requestor must usually go
1056N/Aby means of the server in an X Version 11 environment. A client cannot assume
1056N/Athat another client can open the same files or even communicate directly. The
1056N/Aother client may be talking to the server by means of a completely different
1056N/Anetworking mechanism (for example, one client might be DECnet and the other TCP
1056N/A/IP). Thus, passing indirect references to data (such as, file names, host
1056N/Anames, and port numbers) is permitted only if both clients specifically agree.
1056N/AAcquiring Selection Ownership
1056N/AA client wishing to acquire ownership of a particular selection should call
1056N/ASetSelectionOwner, which is defined as follows:
1056N/Atime: TIMESTAMP or CurrentTime
1056N/AThe client should set the specified selection to the atom that represents the
1056N/Aselection, set the specified owner to some window that the client created, and
1056N/Aset the specified time to some time between the current last-change time of the
1056N/Aselection concerned and the current server time. This time value usually will
1056N/Abe obtained from the timestamp of the event that triggers the acquisition of
1056N/Athe selection. Clients should not set the time value to CurrentTime, because if
1056N/Athey do so, they have no way of finding when they gained ownership of the
1056N/Aselection. Clients must use a window they created so that requestors can route
1056N/Aevents to the owner of the selection.^[2]
1056N/A Clients attempting to acquire a selection must set the time value of the
1056N/A SetSelectionOwner request to the timestamp of the event triggering the
1056N/A acquisition attempt, not to CurrentTime. A zero-length append to a property
1056N/A is a way to obtain a timestamp for this purpose; the timestamp is in the
1056N/A corresponding PropertyNotify event.
1056N/AIf the time in the SetSelectionOwner request is in the future relative to the
1056N/Aserver's current time or is in the past relative to the last time the specified
1056N/Aselection changed hands, the SetSelectionOwner request appears to the client to
1056N/Asucceed, but ownership is not actually transferred.
1056N/ABecause clients cannot name other clients directly, the specified owner window
1056N/Ais used to refer to the owning client in the replies to GetSelectionOwner, in
1056N/ASelectionRequest and SelectionClear events, and possibly as a place to put
1056N/Aproperties describing the selection in question. To discover the owner of a
1056N/Aparticular selection, a client should invoke GetSelectionOwner, which is
1056N/A Clients are expected to provide some visible confirmation of selection
1056N/A ownership. To make this feedback reliable, a client must perform a sequence
1056N/ASetSelectionOwner(selection=PRIMARY, owner=Window, time=timestamp)
1056N/Aowner = GetSelectionOwner(selection=PRIMARY)
1056N/Aif (owner != Window) Failure
1056N/AIf the SetSelectionOwner request succeeds (not merely appears to succeed), the
1056N/Aclient that issues it is recorded by the server as being the owner of the
1056N/Aselection for the time period starting at the specified time.
1056N/AResponsibilities of the Selection Owner
1056N/AWhen a requestor wants the value of a selection, the owner receives a
1056N/ASelectionRequest event, which is defined as follows:
1056N/Atime: TIMESTAMP or CurrentTime
1056N/AThe specified owner and selection will be the values that were specified in the
1056N/ASetSelectionOwner request. The owner should compare the timestamp with the
1056N/Aperiod it has owned the selection and, if the time is outside, refuse the
1056N/ASelectionRequest by sending the requestor window a SelectionNotify event with
1056N/Athe property set to None (by means of a SendEvent request with an empty event
1056N/AMore advanced selection owners are free to maintain a history of the value of
1056N/Athe selection and to respond to requests for the value of the selection during
1056N/Aperiods they owned it even though they do not own it now.
1056N/AIf the specified property is None, the requestor is an obsolete client. Owners
1056N/Aare encouraged to support these clients by using the specified target atom as
1056N/Athe property name to be used for the reply.
1056N/AOtherwise, the owner should use the target to decide the form into which the
1056N/Aselection should be converted. Some targets may be defined such that requestors
1056N/Acan pass parameters along with the request. The owner will find these
1056N/Aparameters in the property named in the selection request. The type, format,
1056N/Aand contents of this property are dependent upon the definition of the target.
1056N/AIf the target is not defined to have parameters, the owner should ignore the
1056N/Aproperty if it is present. If the selection cannot be converted into a form
1056N/Abased on the target (and parameters, if any), the owner should refuse the
1056N/ASelectionRequest as previously described.
1056N/AIf the specified property is not None, the owner should place the data
1056N/Aresulting from converting the selection into the specified property on the
1056N/Arequestor window and should set the property's type to some appropriate value,
1056N/Awhich need not be the same as the specified target.
1056N/A All properties used to reply to SelectionRequest events must be placed on
1056N/AIn either case, if the data comprising the selection cannot be stored on the
1056N/Arequestor window (for example, because the server cannot provide sufficient
1056N/Amemory), the owner must refuse the SelectionRequest, as previously described.
1276N/ASee also Large Data Transfers.
1056N/AIf the property is successfully stored, the owner should acknowledge the
1056N/Asuccessful conversion by sending the requestor window a SelectionNotify event
1056N/A(by means of a SendEvent request with an empty mask). SelectionNotify is
1056N/Atime: TIMESTAMP or CurrentTime
1056N/AThe owner should set the specified selection, target, time, and property
1056N/Aarguments to the values received in the SelectionRequest event. (Note that
1056N/Asetting the property argument to None indicates that the conversion requested
1056N/A The selection, target, time, and property arguments in the SelectionNotify
1056N/A event should be set to the values received in the SelectionRequest event.
1056N/AIf the owner receives more than one SelectionRequest event with the same
1056N/Arequestor, selection, target, and timestamp it must respond to them in the same
1056N/Aorder in which they were received.
1056N/A It is possible for a requestor to have multiple outstanding requests that
1056N/A use the same requestor window, selection, target, and timestamp, and that
1056N/A differ only in the property. If this occurs, and one of the conversion
1056N/A requests fails, the resulting SelectionNotify event will have its property
1056N/A argument set to None. This may make it impossible for the requestor to
1056N/A determine which conversion request had failed, unless the requests are
1056N/AThe data stored in the property must eventually be deleted. A convention is
1056N/Aneeded to assign the responsibility for doing so.
1056N/A Selection requestors are responsible for deleting properties whose names
1276N/A they receive in SelectionNotify events (See Requesting a Selection ) or in
1276N/A properties with type MULTIPLE.
1056N/AA selection owner will often need confirmation that the data comprising the
1056N/Aselection has actually been transferred. (For example, if the operation has
1056N/Aside effects on the owner's internal data structures, these should not take
1056N/Aplace until the requestor has indicated that it has successfully received the
1056N/Adata.) Owners should express interest in PropertyNotify events for the
1056N/Aspecified requestor window and wait until the property in the SelectionNotify
1056N/Aevent has been deleted before assuming that the selection data has been
1056N/Atransferred. For the MULTIPLE request, if the different conversions require
1056N/Aseparate confirmation, the selection owner can also watch for the deletion of
1056N/Athe individual properties named in the property in the SelectionNotify event.
1056N/AWhen some other client acquires a selection, the previous owner receives a
1056N/ASelectionClear event, which is defined as follows:
1056N/AThe timestamp argument is the time at which the ownership changed hands, and
1056N/Athe owner argument is the window the previous owner specified in its
1056N/AIf an owner loses ownership while it has a transfer in progress (that is,
1056N/Abefore it receives notification that the requestor has received all the data),
1056N/Ait must continue to service the ongoing transfer until it is complete.
1056N/AIf the selection value completely changes, but the owner happens to be the same
1056N/Aclient (for example, selecting a totally different piece of text in the same
1056N/Axterm as before), then the client should reacquire the selection ownership as
1056N/Aif it were not the owner, providing a new timestamp. If the selection value is
1056N/Amodified, but can still reasonably be viewed as the same selected object, ^[3]
1056N/Athe owner should take no action.
1056N/AGiving Up Selection Ownership
1056N/AClients may either give up selection ownership voluntarily or lose it forcibly
1056N/Aas the result of some other client's actions.
1056N/AVoluntarily Giving Up Selection Ownership
1056N/ATo relinquish ownership of a selection voluntarily, a client should execute a
1056N/ASetSelectionOwner request for that selection atom, with owner specified as None
1056N/Aand the time specified as the timestamp that was used to acquire the selection.
1056N/AAlternatively, the client may destroy the window used as the owner value of the
1056N/ASetSelectionOwner request, or the client may terminate. In both cases, the
1056N/Aownership of the selection involved will revert to None.
1056N/AForcibly Giving Up Selection Ownership
1056N/AIf a client gives up ownership of a selection or if some other client executes
1056N/Aa SetSelectionOwner for it and thus reassigns it forcibly, the previous owner
1056N/Awill receive a SelectionClear event. For the definition of a SelectionClear
1276N/Aevent, see Responsibilities of the Selection Owner
1056N/AThe timestamp is the time the selection changed hands. The specified owner is
1056N/Athe window that was specified by the current owner in its SetSelectionOwner
1056N/AA client that wishes to obtain the value of a selection in a particular form
1056N/A(the requestor) issues a ConvertSelection request, which is defined as follows:
1056N/Atime: TIMESTAMP or CurrentTime
1056N/AThe selection argument specifies the particular selection involved, and the
1056N/Atarget argument specifies the required form of the information. For information
1276N/Aabout the choice of suitable atoms to use, see Use of Selection Atoms The
1276N/Arequestor should set the requestor argument to a window that it created; the
1276N/Aowner will place the reply property there. The requestor should set the time
1276N/Aargument to the timestamp on the event that triggered the request for the
1276N/Aselection value. Note that clients should not specify CurrentTime.
1056N/A Clients should not use CurrentTime for the time argument of a
1056N/A ConvertSelection request. Instead, they should use the timestamp of the
1056N/A event that caused the request to be made.
1056N/AThe requestor should set the property argument to the name of a property that
1056N/Athe owner can use to report the value of the selection. Requestors should
1056N/Aensure that the named property does not exist on the window before issuing the
1056N/AConvertSelection request.^[4] The exception to this rule is when the requestor
1056N/Aintends to pass parameters with the request (see below).
1056N/A It is necessary for requestors to delete the property before issuing the
1056N/A request so that the target can later be extended to take parameters without
1056N/A introducing an incompatibility. Also note that the requestor of a selection
1056N/A need not know the client that owns the selection nor the window on which
1056N/A the selection was acquired.
1056N/ASome targets may be defined such that requestors can pass parameters along with
1056N/Athe request. If the requestor wishes to provide parameters to a request, they
1056N/Ashould be placed in the specified property on the requestor window before the
1056N/Arequestor issues the ConvertSelection request, and this property should be
1056N/ASome targets may be defined so that parameters are optional. If no parameters
1056N/Aare to be supplied with the request of such a target, the requestor must ensure
1056N/Athat the property does not exist before issuing the ConvertSelection request.
1056N/AThe protocol allows the property field to be set to None, in which case the
1056N/Aowner is supposed to choose a property name. However, it is difficult for the
1056N/Aowner to make this choice safely.
1056N/A ● Requestors should not use None for the property argument of a
1056N/A ● Owners receiving ConvertSelection requests with a property argument of None
1056N/A are talking to an obsolete client. They should choose the target atom as
1056N/A the property name to be used for the reply.
1056N/AThe result of the ConvertSelection request is that a SelectionNotify event will
1276N/Abe received. For the definition of a SelectionNotify event, see
1276N/AResponsibilities of the Selection Owner.
1056N/AThe requestor, selection, time, and target arguments will be the same as those
1056N/Aon the ConvertSelection request.
1056N/AIf the property argument is None, the conversion has been refused. This can
1056N/Amean either that there is no owner for the selection, that the owner does not
1056N/Asupport the conversion implied by the target, or that the server did not have
1056N/Asufficient space to accommodate the data.
1056N/AIf the property argument is not None, then that property will exist on the
1056N/Arequestor window. The value of the selection can be retrieved from this
1056N/Aproperty by using the GetProperty request, which is defined as follows:
1056N/Atype: ATOM or AnyPropertyType
1056N/Along-offset, long-length: CARD32
1056N/Avalue: LISTofINT8 or LISTofINT16 or LISTofINT32
1056N/AGetProperty to retrieve the value of a selection, the property argument should
1056N/Abe set to the corresponding value in the SelectionNotify event. Because the
1056N/Arequestor has no way of knowing beforehand what type the selection owner will
1056N/Ause, the type argument should be set to AnyPropertyType. Several GetProperty
1056N/Arequests may be needed to retrieve all the data in the selection; each should
1056N/Aset the long-offset argument to the amount of data received so far, and the
1276N/Asize argument to some reasonable buffer size (see Large Data Transfers. ). If
1276N/Athe returned value of bytes-after is zero, the whole property has been
1056N/AOnce all the data in the selection has been retrieved (which may require
1276N/Agetting the values of several properties -- see Use of Selection Properties. ),
1276N/Athe requestor should delete the property in the SelectionNotify request by
1276N/Ausing a GetProperty request with the delete argument set to True. As previously
1276N/Adiscussed, the owner has no way of knowing when the data has been transferred
1276N/Ato the requestor unless the property is removed.
1056N/A The requestor must delete the property named in the SelectionNotify once
1056N/A all the data has been retrieved. The requestor should invoke either
1056N/A DeleteProperty or GetProperty (delete==True) after it has successfully
1276N/A retrieved all the data in the selection. For further information, see Large
1056N/ASelections can get large, which poses two problems:
1056N/A ● Transferring large amounts of data to the server is expensive.
1056N/A ● All servers will have limits on the amount of data that can be stored in
1056N/A properties. Exceeding this limit will result in an Alloc error on the
1056N/A ChangeProperty request that the selection owner uses to store the data.
1056N/AThe problem of limited server resources is addressed by the following
1056N/A ● Selection owners should transfer the data describing a large selection
1056N/A (relative to the maximum-request-size they received in the connection
1276N/A handshake) using the INCR property mechanism (see INCR Properties. ).
1056N/A ● Any client using SetSelectionOwner to acquire selection ownership should
1056N/A arrange to process Alloc errors in property change requests. For clients
1056N/A using Xlib, this involves using the XSetErrorHandler function to override
1056N/A ● A selection owner must confirm that no Alloc error occurred while storing
1056N/A the properties for a selection before replying with a confirming
1056N/A ● When storing large amounts of data (relative to maximum-request-size),
1056N/A clients should use a sequence of ChangeProperty (mode==Append) requests for
1056N/A reasonable quantities of data. This avoids locking servers up and limits
1056N/A the waste of data an Alloc error would cause.
1056N/A ● If an Alloc error occurs during the storing of the selection data, all
1056N/A properties stored for this selection should be deleted and the
1276N/A ConvertSelection request should be refused (see Responsibilities of the
1056N/A ● To avoid locking servers up for inordinate lengths of time, requestors
1056N/A retrieving large quantities of data from a property should perform a series
1056N/A of GetProperty requests, each asking for a reasonable amount of data.
1056N/A Single-threaded servers should take care to avoid locking up during large
1056N/ADefining a new atom consumes resources in the server that are not released
1056N/Auntil the server reinitializes. Thus, reducing the need for newly minted atoms
1056N/Ais an important goal for the use of the selection atoms.
1056N/AThere can be an arbitrary number of selections, each named by an atom. To
1056N/Aconform with the inter-client conventions, however, clients need deal with only
1056N/AOther selections may be used freely for private communication among related
1056N/AThe selection named by the atom PRIMARY is used for all commands that take only
1056N/Aa single argument and is the principal means of communication between clients
1056N/Athat use the selection mechanism.
1056N/AThe selection named by the atom SECONDARY is used:
1056N/A ● As the second argument to commands taking two arguments (for example,
1056N/A "exchange primary and secondary selections")
1056N/A ● As a means of obtaining data when there is a primary selection and the user
1056N/A does not want to disturb it
1056N/AThe selection named by the atom CLIPBOARD is used to hold data that is being
1056N/Atransferred between clients, that is, data that usually is being cut and then
1056N/Apasted or copied and then pasted. Whenever a client wants to transfer data to
1056N/A ● It should assert ownership of the CLIPBOARD.
1056N/A ● If it succeeds in acquiring ownership, it should be prepared to respond to
1056N/A a request for the contents of the CLIPBOARD in the usual way (retaining the
1056N/A data to be able to return it). The request may be generated by the
1056N/A clipboard client described below.
1056N/A ● If it fails to acquire ownership, a cutting client should not actually
1056N/A perform the cut or provide feedback that would suggest that it has actually
1056N/A transferred data to the clipboard.
1056N/AThe owner should repeat this process whenever the data to be transferred would
1056N/AClients wanting to paste data from the clipboard should request the contents of
1056N/Athe CLIPBOARD selection in the usual way.
1056N/AExcept while a client is actually deleting or copying data, the owner of the
1056N/ACLIPBOARD selection may be a single, special client implemented for the
1056N/Apurpose. This client maintains the content of the clipboard up-to-date and
1056N/Aresponds to requests for data from the clipboard as follows:
1056N/A ● It should assert ownership of the CLIPBOARD selection and reassert it any
1056N/A time the clipboard data changes.
1056N/A ● If it loses the selection (because another client has some new data for the
1056N/A ○ Obtain the contents of the selection from the new owner by using the
1056N/A timestamp in the SelectionClear event.
1056N/A ○ Attempt to reassert ownership of the CLIPBOARD selection by using the
1056N/A ○ Restart the process using a newly acquired timestamp if this attempt
1056N/A fails. This timestamp should be obtained by asking the current owner of
1056N/A the CLIPBOARD selection to convert it to a TIMESTAMP. If this
1056N/A conversion is refused or if the same timestamp is received twice, the
1056N/A clipboard client should acquire a fresh timestamp in the usual way (for
1056N/A example by a zero-length append to a property).
1056N/A ● It should respond to requests for the CLIPBOARD contents in the usual way.
1056N/AA special CLIPBOARD client is not necessary. The protocol used by the cutting
1056N/Aclient and the pasting client is the same whether the CLIPBOARD client is
1056N/Arunning or not. The reasons for running the special client include:
1056N/A ● Stability - If the cutting client were to crash or terminate, the clipboard
1056N/A value would still be available.
1056N/A ● Feedback - The clipboard client can display the contents of the clipboard.
1056N/A ● Simplicity - A client deleting data does not have to retain it for so long,
1056N/A thus reducing the chance of race conditions causing problems.
1056N/AThe reasons not to run the clipboard client include:
1056N/A ● Performance - Data is transferred only if it is actually required (that is,
1056N/A when some client actually wants the data).
1056N/A ● Flexibility - The clipboard data may be available as more than one target.
1056N/AThe atom that a requestor supplies as the target of a ConvertSelection request
1056N/Adetermines the form of the data supplied. The set of such atoms is extensible,
1056N/Abut a generally accepted base set of target atoms is needed. As a starting
1056N/Apoint for this, the following table contains those that have been suggested so
1276N/A┌────────────────────────────────────┬─────────────┬──────────────────────────┐
1276N/A│Atom │Type │Data Received │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│ADOBE_PORTABLE_DOCUMENT_FORMAT │STRING │[1] │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│APPLE_PICT │APPLE_PICT │[2] │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│BACKGROUND │PIXEL │A list of pixel values │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│BITMAP │BITMAP │A list of bitmap IDs │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│CHARACTER_POSITION │SPAN │The start and end of the │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│CLASS │TEXT │(see WM_CLASS Property. ) │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│CLIENT_WINDOW │WINDOW │Any top-level window owned│
1276N/A│ │ │by the selection owner │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│COLORMAP │COLORMAP │A list of colormap IDs │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│COLUMN_NUMBER │SPAN │The start and end column │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│COMPOUND_TEXT │COMPOUND_TEXT│Compound Text │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│DELETE │NULL │(see DELETE. ) │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│DRAWABLE │DRAWABLE │A list of drawable IDs │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│ENCAPSULATED_POSTSCRIPT │STRING │[3], Appendix H ^[a] │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│ENCAPSULATED_POSTSCRIPT_INTERCHANGE│STRING │[3], Appendix H │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│FILE_NAME │TEXT │The full path name of a │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│FOREGROUND │PIXEL │A list of pixel values │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│HOST_NAME │TEXT │(see WM_CLIENT_MACHINE │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│INSERT_PROPERTY │NULL │(see INSERT_PROPERTY. ) │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│INSERT_SELECTION │NULL │(see INSERT_SELECTION. ) │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│LENGTH │INTEGER │The number of bytes in the│
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│LINE_NUMBER │SPAN │The start and end line │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│LIST_LENGTH │INTEGER │The number of disjoint │
1276N/A│ │ │parts of the selection │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│MODULE │TEXT │The name of the selected │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│MULTIPLE │ATOM_PAIR │(see the discussion that │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│NAME │TEXT │(see WM_NAME Property. ) │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│ODIF │TEXT │ISO Office Document │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│OWNER_OS │TEXT │The operating system of │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│PIXMAP │PIXMAP ^[c] │A list of pixmap IDs │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│PROCEDURE │TEXT │The name of the selected │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│PROCESS │INTEGER, TEXT│The process ID of the │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│STRING │STRING │ISO Latin-1 (+TAB+NEWLINE)│
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│TARGETS │ATOM │A list of valid target │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│TASK │INTEGER, TEXT│The task ID of the owner │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│TEXT │TEXT │The text in the owner's │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│TIMESTAMP │INTEGER │The timestamp used to │
1276N/A│ │ │acquire the selection │
1276N/A├────────────────────────────────────┼─────────────┼──────────────────────────┤
1276N/A│USER │TEXT │The name of the user │
1276N/A├────────────────────────────────────┴─────────────┴──────────────────────────┤
1276N/A│^[a] Earlier versions of this document erroneously specified that conversion │
1276N/A│of the PIXMAP target returns a property of type DRAWABLE instead of PIXMAP. │
1276N/A│Implementors should be aware of this and may want to support the DRAWABLE │
1276N/A│type as well to allow for compatibility with older clients. │
1276N/A│^[b] The targets ENCAPSULATED_POSTSCRIPT and │
1276N/A│ENCAPSULATED_POSTSCRIPT_INTERCHANGE are equivalent to the targets _ADOBE_EPS │
1276N/A│and _ADOBE_EPSI (respectively) that appear in the selection targets registry.│
1276N/A│The _ADOBE_ targets are deprecated, but clients are encouraged to continue to│
1276N/A│support them for backward compatibility. │
1276N/A│^[c] This definition is ambiguous, as the selection may be converted into any│
1276N/A│of several targets that may return differing amounts of data. The requestor │
1276N/A│has no way of knowing which, if any, of these targets corresponds to the │
1276N/A│result of LENGTH. Clients are advised that no guarantees can be made about │
1276N/A│the result of a conversion to LENGTH; its use is thus deprecated. │
1276N/A└─────────────────────────────────────────────────────────────────────────────┘
1056N/A 1. Adobe Systems, Incorporated. Portable Document Format Reference Manual.
1056N/A Reading, MA, Addison-Wesley, ISBN 0-201-62628-4.
1056N/A 2. Apple Computer, Incorporated. Inside Macintosh, Volume V. Chapter 4, "Color
1056N/A QuickDraw," Color Picture Format. ISBN 0-201-17719-6.
1056N/A 3. Adobe Systems, Incorporated. PostScript Language Reference Manual. Reading,
1056N/A MA, Addison-Wesley, ISBN 0-201-18127-4.
1056N/AIt is expected that this table will grow over time.
1056N/ASelection owners are required to support the following targets. All other
1056N/A ● TARGETS - The owner should return a list of atoms that represent the
1056N/A targets for which an attempt to convert the current selection will succeed
1056N/A (barring unforseeable problems such as Alloc errors). This list should
1056N/A include all the required atoms.
1056N/A ● MULTIPLE - The MULTIPLE target atom is valid only when a property is
1056N/A specified on the ConvertSelection request. If the property argument in the
1056N/A SelectionRequest event is None and the target is MULTIPLE, it should be
1056N/A When a selection owner receives a SelectionRequest (target==MULTIPLE)
1056N/A request, the contents of the property named in the request will be a list
1056N/A of atom pairs: the first atom naming a target and the second naming a
1056N/A property ( None is not valid here). The effect should be as if the owner
1056N/A had received a sequence of SelectionRequest events (one for each atom pair)
1056N/A ○ The owner should reply with a SelectionNotify only when all the
1056N/A requested conversions have been performed.
1056N/A ○ If the owner fails to convert the target named by an atom in the
1056N/A MULTIPLE property, it should replace that atom in the property with
1056N/A The entries in a MULTIPLE property must be processed in the order they
1276N/A appear in the property. For further information, see Selection Targets
1056N/A The requestor should delete each individual property when it has copied the
1056N/A data from that conversion, and the property specified in the MULTIPLE
1056N/A request when it has copied all the data.
1056N/A The requests are otherwise to be processed independently, and they should
1056N/A succeed or fail independently. The MULTIPLE target is an optimization that
1056N/A reduces the amount of protocol traffic between the owner and the requestor;
1056N/A it is not a transaction mechanism. For example, a client may issue a
1056N/A MULTIPLE request with two targets: a data target and the DELETE target. The
1056N/A DELETE target will still be processed even if the conversion of the data
1056N/A ● TIMESTAMP - To avoid some race conditions, it is important that requestors
1056N/A be able to discover the timestamp the owner used to acquire ownership.
1056N/A Until and unless the protocol is changed so that a GetSelectionOwner
1056N/A request returns the timestamp used to acquire ownership, selection owners
1056N/A must support conversion to TIMESTAMP, returning the timestamp they used to
1056N/ASelection Targets with Side Effects
1056N/ASome targets (for example, DELETE) have side effects. To render these targets
1056N/Aunambiguous, the entries in a MULTIPLE property must be processed in the order
1056N/Athat they appear in the property.
1056N/AIn general, targets with side effects will return no information, that is, they
1056N/Awill return a zero length property of type NULL. (Type NULL means the result of
1056N/AInternAtom on the string "NULL", not the value zero.) In all cases, the
1056N/Arequested side effect must be performed before the conversion is accepted. If
1056N/Athe requested side effect cannot be performed, the corresponding conversion
1056N/A ● Targets with side effects should return no information (that is, they
1056N/A should have a zero-length property of type NULL).
1056N/A ● The side effect of a target must be performed before the conversion is
1056N/A ● If the side effect of a target cannot be performed, the corresponding
1056N/A conversion request must be refused.
1056N/A The need to delay responding to the ConvertSelection request until a
1056N/A further conversion has succeeded poses problems for the Intrinsics
1056N/A interface that need to be addressed.
1056N/AThese side-effect targets are used to implement operations such as "exchange
1056N/APRIMARY and SECONDARY selections."
1056N/AWhen the owner of a selection receives a request to convert it to DELETE, it
1056N/Ashould delete the corresponding selection (whatever doing so means for its
1056N/Ainternal data structures) and return a zero-length property of type NULL if the
1056N/AWhen the owner of a selection receives a request to convert it to
1056N/AINSERT_SELECTION, the property named will be of type ATOM_PAIR. The first atom
1056N/Awill name a selection, and the second will name a target. The owner should use
1056N/Athe selection mechanism to convert the named selection into the named target
1056N/Aand should insert it at the location of the selection for which it got the
1056N/AINSERT_SELECTION request (whatever doing so means for its internal data
1056N/AWhen the owner of a selection receives a request to convert it to
1056N/AINSERT_PROPERTY, it should insert the property named in the request at the
1056N/Alocation of the selection for which it got the INSERT_SELECTION request
1056N/A(whatever doing so means for its internal data structures).
1056N/AThe names of the properties used in selection data transfer are chosen by the
1056N/Arequestor. The use of None property fields in ConvertSelection requests (which
1056N/Arequest the selection owner to choose a name) is not permitted by these
1056N/AThe selection owner always chooses the type of the property in the selection
1056N/Adata transfer. Some types have special semantics assigned by convention, and
1056N/Athese are reviewed in the following sections.
1056N/AIn all cases, a request for conversion to a target should return either a
1056N/Aproperty of one of the types listed in the previous table for that target or a
1056N/Aproperty of type INCR and then a property of one of the listed types.
1056N/ACertain selection properties may contain resource IDs. The selection owner
1056N/Ashould ensure that the resource is not destroyed and that its contents are not
1056N/Achanged until after the selection transfer is complete. Requestors that rely on
1056N/Athe existence or on the proper contents of a resource must operate on the
1056N/Aresource (for example, by copying the contents of a pixmap) before deleting the
1056N/AThe selection owner will return a list of zero or more items of the type
1056N/Aindicated by the property type. In general, the number of items in the list
1056N/Awill correspond to the number of disjoint parts of the selection. Some targets
1056N/A(for example, side-effect targets) will be of length zero irrespective of the
1056N/Anumber of disjoint selection parts. In the case of fixed-size items, the
1056N/Arequestor may determine the number of items by the property size. Selection
1056N/Aproperty types are listed in the table below. For variable-length items such as
1056N/Atext, the separators are also listed.
1276N/A┌─────────────┬──────┬───────────┐
1276N/A│Type Atom │Format│Separator │
1276N/A├─────────────┼──────┼───────────┤
1276N/A│APPLE_PICT │8 │Self-sizing│
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A│ATOM_PAIR │32 │Fixed-size │
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A├─────────────┼──────┼───────────┤
1276N/A└─────────────┴──────┴───────────┘
1056N/AIt is expected that this table will grow over time.
1056N/AIn general, the encoding for the characters in a text string property is
1056N/Aspecified by its type. It is highly desirable for there to be a simple,
1056N/Ainvertible mapping between string property types and any character set names
1056N/Aembedded within font names in any font naming standard adopted by the
1056N/AThe atom TEXT is a polymorphic target. Requesting conversion into TEXT will
1056N/Aconvert into whatever encoding is convenient for the owner. The encoding chosen
1056N/Awill be indicated by the type of the property returned. TEXT is not defined as
1056N/Aa type; it will never be the returned type from a selection conversion request.
1056N/AIf the requestor wants the owner to return the contents of the selection in a
1056N/Aspecific encoding, it should request conversion into the name of that encoding.
1276N/AIn the table in Target Atoms, the word TEXT (in the Type column) is used to
1276N/Aindicate one of the registered encoding names. The type would not actually be
1276N/ATEXT; it would be STRING or some other ATOM naming the encoding chosen by the
1056N/ASTRING as a type or a target specifies the ISO Latin-1 character set plus the
1056N/Acontrol characters TAB (octal 11) and NEWLINE (octal 12). The spacing
1056N/Ainterpretation of TAB is context dependent. Other ASCII control characters are
1056N/Aexplicitly not included in STRING at the present time.
1056N/ACOMPOUND_TEXT as a type or a target specifies the Compound Text interchange
1056N/Aformat; see the Compound Text Encoding.
1056N/AThere are some text objects where the source or intended user, as the case may
1056N/Abe, does not have a specific character set for the text, but instead merely
1056N/Arequires a zero-terminated sequence of bytes with no other restriction; no
1056N/Aelement of the selection mechanism may assume that any byte value is forbidden
1056N/Aor that any two differing sequences are equivalent. ^[5] For these objects, the
1056N/Atype C_STRING should be used.
1056N/A An example of the need for C_STRING is to transmit the names of files; many
1056N/A operating systems do not interpret filenames as having a character set. For
1056N/A example, the same character string uses a different sequence of bytes in
1056N/A ASCII and EBCDIC, and so most operating systems see these as different
1056N/A filenames and offer no way to treat them as the same. Thus no character-set
1056N/A based property type is suitable.
1056N/AType STRING, COMPOUND_TEXT, and C_STRING properties will consist of a list of
1056N/Aelements separated by null characters; other encodings will need to specify an
1056N/ARequestors may receive a property of type INCR ^[6] in response to any target
1056N/Athat results in selection data.
1056N/AThis indicates that the owner will send the actual data incrementally. The
1056N/Acontents of the INCR property will be an integer, which represents a lower
1056N/Abound on the number of bytes of data in the selection. The requestor and the
1056N/Aselection owner transfer the data in the selection in the following manner.
1056N/AThe selection requestor starts the transfer process by deleting the (type==
1056N/AINCR) property forming the reply to the selection.
1056N/A ● Appends the data in suitable-size chunks to the same property on the same
1056N/A window as the selection reply with a type corresponding to the actual type
1056N/A of the converted selection. The size should be less than the
1056N/A maximum-request-size in the connection handshake.
1056N/A ● Waits between each append for a PropertyNotify (state==Deleted) event that
1056N/A shows that the requestor has read the data. The reason for doing this is to
1056N/A limit the consumption of space in the server.
1056N/A ● Waits (after the entire data has been transferred to the server) until a
1056N/A PropertyNotify (state==Deleted) event that shows that the data has been
1056N/A read by the requestor and then writes zero-length data to the property.
1056N/A ● Waits for the SelectionNotify event.
1056N/A ○ Retrieving data using GetProperty with the delete argument True.
1056N/A ○ Waiting for a PropertyNotify with the state argument NewValue.
1056N/A ● Waits until the property named by the PropertyNotify event is zero-length.
1056N/A ● Deletes the zero-length property.
1056N/AThe type of the converted selection is the type of the first partial property.
1056N/AThe remaining partial properties must have the same type.
1056N/ARequestors may receive properties of type PIXMAP, BITMAP, DRAWABLE, or WINDOW,
1056N/Awhich contain an appropriate ID. While information about these drawables is
1056N/Aavailable from the server by means of the GetGeometry request, the following
1056N/AIn general, requestors converting into targets whose returned type in the table
1276N/Ain Target Atoms is one of the DRAWABLE types should expect to convert also into
1276N/Athe following targets (using the MULTIPLE mechanism):
1056N/A ● FOREGROUND returns a PIXEL value.
1056N/A ● BACKGROUND returns a PIXEL value.
1056N/A ● COLORMAP returns a colormap ID.
1056N/AProperties with type SPAN contain a list of cardinal-pairs with the length of
1056N/Athe cardinals determined by the format. The first specifies the starting
1056N/Aposition, and the second specifies the ending position plus one. The base is
1056N/Azero. If they are the same, the span is zero-length and is before the specified
1056N/Aposition. The units are implied by the target atom, such as LINE_NUMBER or
1056N/ACertain clients, often called managers, take on responsibility for managing
1056N/Ashared resources. A client that manages a shared resource should take ownership
1276N/Aof an appropriate selection, named using the conventions described in Naming
1276N/AConventions and Discriminated Names. A client that manages multiple shared
1276N/Aresources (or groups of resources) should take ownership of a selection for
1056N/AThe manager may support conversion of various targets for that selection.
1056N/AManagers are encouraged to use this technique as the primary means by which
1056N/Aclients interact with the managed resource. Note that the conventions for
1056N/Ainteracting with the window manager predate this section; as a result many
1056N/Ainteractions with the window manager use other techniques.
1056N/ABefore a manager takes ownership of a manager selection, it should use the
1056N/AGetSelectionOwner request to check whether the selection is already owned by
1056N/Aanother client, and, where appropriate, it should ask the user if the new
1056N/Amanager should replace the old one. If so, it may then take ownership of the
1056N/Aselection. Managers should acquire the selection using a window created
1056N/Aexpressly for this purpose. Managers must conform to the rules for selection
1276N/Aowners described in Acquiring Selection Ownership and Responsibilities of the
1276N/ASelection Owner , and they must also support the required targets listed in Use
1056N/AIf a manager loses ownership of a manager selection, this means that a new
1056N/Amanager is taking over its responsibilities. The old manager must release all
1056N/Aresources it has managed and must then destroy the window that owned the
1056N/Aselection. For example, a window manager losing ownership of WM_S2 must
1056N/Adeselect from SubstructureRedirect on the root window of screen 2 before
1056N/Adestroying the window that owned WM_S2.
1056N/AWhen the new manager notices that the window owning the selection has been
1056N/Adestroyed, it knows that it can successfully proceed to control the resource it
1056N/Ais planning to manage. If the old manager does not destroy the window within a
1056N/Areasonable time, the new manager should check with the user before destroying
1056N/Athe window itself or killing the old manager.
1056N/AIf a manager wants to give up, on its own, management of a shared resource
1056N/Acontrolled by a selection, it must do so by releasing the resources it is
1056N/Amanaging and then by destroying the window that owns the selection. It should
1056N/Anot first disown the selection, since this introduces a race condition.
1056N/AClients who are interested in knowing when the owner of a manager selection is
1056N/Ano longer managing the corresponding shared resource should select for
1056N/AStructureNotify on the window owning the selection so they can be notified when
1056N/Athe window is destroyed. Clients are warned that after doing a
1056N/AGetSelectionOwner and selecting for StructureNotify, they should do a
1056N/AGetSelectionOwner again to ensure that the owner did not change after initially
1056N/Agetting the selection owner and before selecting for StructureNotify.
1056N/AImmediately after a manager successfully acquires ownership of a manager
1056N/Aselection, it should announce its arrival by sending a ClientMessage event.
1056N/AThis event should be sent using the SendEvent protocol request with the
1276N/A┌────────────┬────────────────────────────────────────────────────────────────┐
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A│ │the root window of screen 0, or the root window of the │
1276N/A│destination:│appropriate screen if the manager is managing a screen-specific │
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A│event-mask: │StructureNotify │
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A│ data │manager selection atom │
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A│ data │the window owning the selection │
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A│ data │manager-selection-specific data │
1276N/A├────────────┼────────────────────────────────────────────────────────────────┤
1276N/A│ data │manager-selection-specific data │
1276N/A├────────────┴────────────────────────────────────────────────────────────────┤
1276N/A│^[a] We use the notation data[n] to indicate the n ^th element of the │
1276N/A│LISTofINT8, LISTofINT16, or LISTofINT32 in the data field of the │
1276N/A│ClientMessage, according to the format field. The list is indexed from zero. │
1276N/A└─────────────────────────────────────────────────────────────────────────────┘
1056N/AClients that wish to know when a specific manager has started should select for
1056N/AStructureNotify on the appropriate root window and should watch for the
1056N/Aappropriate MANAGER ClientMessage.
1056N/A^[2] At present, no part of the protocol requires requestors to send events to
1056N/Athe owner of a selection. This restriction is imposed to prepare for possible
1056N/A^[3] The division between these two cases is a matter of judgment on the part
1056N/A^[4] This requirement is new in version 2.0, and, in general, existing clients
1056N/Ado not conform to this requirement. To prevent these clients from breaking, no
1056N/Aexisting targets should be extended to take parameters until sufficient time
1056N/Ahas passed for clients to be updated. Note that the MULTIPLE target was defined
1056N/Ato take parameters in version 1.0 and its definition is not changing. There is
1056N/Athus no conformance problem with MULTIPLE.
1056N/A^[5] Note that this is different from STRING, where many byte values are
1056N/Aforbidden, and from COMPOUND_TEXT, where, for example, inserting the sequence
1056N/A27,\ 40,\ 66 (designate ASCII into GL) at the start does not alter the meaning.
1056N/A^[6] These properties were called INCREMENTAL in an earlier draft. The protocol
1056N/Afor using them has changed, and so the name has changed to avoid confusion.
1056N/AChapter 3. Peer-to-Peer Communication by Means of Cut Buffers
1056N/AThe cut buffer mechanism is much simpler but much less powerful than the
1056N/Aselection mechanism. The selection mechanism is active in that it provides a
1056N/Alink between the owner and requestor clients. The cut buffer mechanism is
1056N/Apassive; an owner places data in a cut buffer from which a requestor retrieves
1056N/Athe data at some later time.
1056N/AThe cut buffers consist of eight properties on the root of screen zero, named
1056N/Aby the predefined atoms CUT_BUFFER0 to CUT_BUFFER7. These properties must, at
1056N/Apresent, have type STRING and format 8. A client that uses the cut buffer
1056N/Amechanism must initially ensure that all eight properties exist by using
1056N/AChangeProperty requests to append zero-length data to each.
1056N/AA client that stores data in the cut buffers (an owner) first must rotate the
1056N/Aring of buffers by plus 1 by using RotateProperties requests to rename each
1056N/Abuffer; that is, CUT_BUFFER0 to CUT_BUFFER1, CUT_BUFFER1 to CUT_BUFFER2, ...,
1056N/Aand CUT_BUFFER7 to CUT_BUFFER0. It then must store the data into CUT_BUFFER0 by
1056N/Ausing a ChangeProperty request in mode Replace.
1056N/AA client that obtains data from the cut buffers should use a GetProperty
1056N/Arequest to retrieve the contents of CUT_BUFFER0.
1056N/AIn response to a specific user request, a client may rotate the cut buffers by
1056N/Aminus 1 by using RotateProperties requests to rename each buffer; that is,
1056N/ACUT_BUFFER7 to CUT_BUFFER6, CUT_BUFFER6 to CUT_BUFFER5, ..., and CUT_BUFFER0 to
1056N/AData should be stored to the cut buffers and the ring rotated only when
1056N/Arequested by explicit user action. Users depend on their mental model of cut
1056N/Abuffer operation and need to be able to identify operations that transfer data
1056N/AChapter 4. Client-to-Window-Manager Communication
1056N/A Creating a Top-Level Window
1056N/AClient Responses to Window Manager Actions
1056N/ACommunication with the Window Manager by Means of Selections
1056N/ASummary of Window Manager Property Types
1056N/ATo permit window managers to perform their role of mediating the competing
1056N/Ademands for resources such as screen space, the clients being managed must
1056N/Aadhere to certain conventions and must expect the window managers to do
1056N/Alikewise. These conventions are covered here from the client's point of view.
1056N/AIn general, these conventions are somewhat complex and will undoubtedly change
1056N/Aas new window management paradigms are developed. Thus, there is a strong bias
1056N/Atoward defining only those conventions that are essential and that apply
1056N/Agenerally to all window management paradigms. Clients designed to run with a
1056N/Aparticular window manager can easily define private protocols to add to these
1056N/Aconventions, but they must be aware that their users may decide to run some
1056N/Aother window manager no matter how much the designers of the private protocol
1056N/Aare convinced that they have seen the "one true light" of user interfaces.
1056N/AIt is a principle of these conventions that a general client should neither
1056N/Aknow nor care which window manager is running or, indeed, if one is running at
1056N/Aall. The conventions do not support all client functions without a window
1056N/Amanager running; for example, the concept of Iconic is not directly supported
1056N/Aby clients. If no window manager is running, the concept of Iconic does not
1056N/Aapply. A goal of the conventions is to make it possible to kill and restart
1056N/Awindow managers without loss of functionality.
1056N/AEach window manager will implement a particular window management policy; the
1056N/Achoice of an appropriate window management policy for the user's circumstances
1056N/Ais not one for an individual client to make but will be made by the user or the
1056N/Auser's system administrator. This does not exclude the possibility of writing
1056N/Aclients that use a private protocol to restrict themselves to operating only
1056N/Aunder a specific window manager. Rather, it merely ensures that no claim of
1056N/Ageneral utility is made for such programs.
1056N/AFor example, the claim is often made: "The client I'm writing is important, and
1056N/Ait needs to be on top." Perhaps it is important when it is being run in
1056N/Aearnest, and it should then be run under the control of a window manager that
1056N/Arecognizes "important" windows through some private protocol and ensures that
1056N/Athey are on top. However, imagine, for example, that the "important" client is
1056N/Abeing debugged. Then, ensuring that it is always on top is no longer the
1056N/Aappropriate window management policy, and it should be run under a window
1056N/Amanager that allows other windows (for example, the debugger) to appear on top.
1056N/AIn general, the object of the X Version 11 design is that clients should, as
1056N/Afar as possible, do exactly what they would do in the absence of a window
1056N/Amanager, except for the following:
1056N/A ● Hinting to the window manager about the resources they would like to obtain
1056N/A ● Cooperating with the window manager by accepting the resources they are
1056N/A allocated even if they are not those requested
1056N/A ● Being prepared for resource allocations to change at any time
1056N/AA client's top-level window is a window whose override-redirect attribute is
1056N/AFalse. It must either be a child of a root window, or it must have been a child
1056N/Aof a root window immediately prior to having been reparented by the window
1056N/Amanager. If the client reparents the window away from the root, the window is
1056N/Ano longer a top-level window; but it can become a top-level window again if the
1056N/Aclient reparents it back to the root.
1056N/AA client usually would expect to create its top-level windows as children of
1056N/Aone or more of the root windows by using some boilerplate like the following:
1056N/AIf a particular one of the root windows was required, however, it could use
1056N/Asomething like the following:
1056N/AIdeally, it should be possible to override the choice of a root window and
1056N/Aallow clients (including window managers) to treat a nonroot window as a
1056N/Apseudo-root. This would allow, for example, the testing of window managers and
1056N/Athe use of application-specific window managers to control the subwindows owned
1056N/Aby the members of a related suite of clients. Doing so properly requires an
1056N/Aextension, the design of which is under study.
1056N/AFrom the client's point of view, the window manager will regard its top-level
1056N/Awindow as being in one of three states:
1056N/ANewly created windows start in the Withdrawn state. Transitions between states
1056N/Ahappen when the top-level window is mapped and unmapped and when the window
1276N/Amanager receives certain messages. For further details, see WM_HINTS Property.
1056N/AOnce the client has one or more top-level windows, it should place properties
1056N/Aon those windows to inform the window manager of the behavior that the client
1056N/Adesires. Window managers will assume values they find convenient for any of
1056N/Athese properties that are not supplied; clients that depend on particular
1056N/Avalues must explicitly supply them. The window manager will not change
1056N/Aproperties written by the client.
1056N/AThe window manager will examine the contents of these properties when the
1056N/Awindow makes the transition from the Withdrawn state and will monitor some
1056N/Aproperties for changes while the window is in the Iconic or Normal state. When
1056N/Athe client changes one of these properties, it must use Replace mode to
1056N/Aoverwrite the entire property with new data; the window manager will retain no
1056N/Amemory of the old value of the property. All fields of the property must be set
1056N/Ato suitable values in a single Replace mode ChangeProperty request. This
1056N/Aensures that the full contents of the property will be available to a new
1056N/Awindow manager if the existing one crashes, if it is shut down and restarted,
1056N/Aor if the session needs to be shut down and restarted by the session manager.
1056N/A Clients writing or rewriting window manager properties must ensure that the
1056N/A entire content of each property remains valid at all times.
1056N/ASome of these properties may contain the IDs of resources, such as windows or
1056N/Apixmaps. Clients should ensure that these resources exist for at least as long
1056N/Aas the window on which the property resides.
1056N/AIf these properties are longer than expected, clients should ignore the
1056N/Aremainder of the property. Extending these properties is reserved to the X
1056N/AConsortium; private extensions to them are forbidden. Private additional
1056N/Acommunication between clients and window managers should take place using
1056N/Aseparate properties. The only exception to this rule is the WM_PROTOCOLS
1056N/Aproperty, which may be of arbitrary length and which may contain atoms
1276N/Arepresenting private protocols (see WM_PROTOCOLS Property ).
1056N/AThe next sections describe each of the properties the clients need to set, in
1276N/Aturn. They are summarized in the table in Summary of Window Manager Property
1056N/AThe WM_NAME property is an uninterpreted string that the client wants the
1056N/Awindow manager to display in association with the window (for example, in a
1056N/AThe encoding used for this string (and all other uninterpreted string
1056N/Aproperties) is implied by the type of the property. The type atoms to be used
1276N/Afor this purpose are described in TEXT Properties.
1056N/AWindow managers are expected to make an effort to display this information.
1056N/ASimply ignoring WM_NAME is not acceptable behavior. Clients can assume that at
1056N/Aleast the first part of this string is visible to the user and that if the
1056N/Ainformation is not visible to the user, it is because the user has taken an
1056N/Aexplicit action to make it invisible.
1056N/AOn the other hand, there is no guarantee that the user can see the WM_NAME
1056N/Astring even if the window manager supports window headlines. The user may have
1056N/Aplaced the headline off-screen or have covered it by other windows. WM_NAME
1056N/Ashould not be used for application-critical information or to announce
1056N/Aasynchronous changes of an application's state that require timely user
1056N/Aresponse. The expected uses are to permit the user to identify one of a number
1056N/Aof instances of the same client and to provide the user with noncritical state
1056N/AEven window managers that support headline bars will place some limit on the
1056N/Alength of the WM_NAME string that can be visible; brevity here will pay
1056N/AThe WM_ICON_NAME property is an uninterpreted string that the client wants to
1056N/Abe displayed in association with the window when it is iconified (for example,
1056N/Ain an icon label). In other respects, including the type, it is similar to
1056N/AWM_NAME. For obvious geometric reasons, fewer characters will normally be
1056N/Avisible in WM_ICON_NAME than WM_NAME.
1056N/AClients should not attempt to display this string in their icon pixmaps or
1056N/Awindows; rather, they should rely on the window manager to do so.
1056N/AThe type of the WM_NORMAL_HINTS property is WM_SIZE_HINTS. Its contents are as
1276N/A┌───────────┬─────────────┬──────────────────────────────┐
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│flags │CARD32 │(see the next table) │
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│pad │4*CARD32 │For backwards compatibility │
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│min_width │INT32 │If missing, assume base_width │
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│min_height │INT32 │If missing, assume base_height│
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│min_aspect │(INT32,INT32)│ │
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│max_aspect │(INT32,INT32)│ │
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│base_width │INT32 │If missing, assume min_width │
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│base_height│INT32 │If missing, assume min_height │
1276N/A├───────────┼─────────────┼──────────────────────────────┤
1276N/A│win_gravity│INT32 │If missing, assume NorthWest │
1276N/A└───────────┴─────────────┴──────────────────────────────┘
1276N/A┌───────────┬─────┬───────────────────────────────────────────┐
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│USPosition │1 │User-specified x, y │
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│USSize │2 │User-specified width, height │
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│PPosition │4 │Program-specified position │
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│PSize │8 │Program-specified size │
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│PMinSize │16 │Program-specified minimum size │
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│PMaxSize │32 │Program-specified maximum size │
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│PResizeInc │64 │Program-specified resize increments │
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│PAspect │128 │Program-specified min and max aspect ratios│
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│PBaseSize │256 │Program-specified base size │
1276N/A├───────────┼─────┼───────────────────────────────────────────┤
1276N/A│PWinGravity│512 │Program-specified window gravity │
1276N/A└───────────┴─────┴───────────────────────────────────────────┘
1056N/ATo indicate that the size and position of the window (when a transition from
1056N/Athe Withdrawn state occurs) was specified by the user, the client should set
1056N/Athe USPosition and USSize flags, which allow a window manager to know that the
1056N/Auser specifically asked where the window should be placed or how the window
1056N/Ashould be sized and that further interaction is superfluous. To indicate that
1056N/Ait was specified by the client without any user involvement, the client should
1056N/AThe size specifiers refer to the width and height of the client's window
1056N/AThe win_gravity may be any of the values specified for WINGRAVITY in the core
1056N/Aprotocol except for Unmap: NorthWest (1), North (2), NorthEast (3), West (4),
1056N/ACenter (5), East (6), SouthWest (7), South (8), and SouthEast (9). It specifies
1056N/Ahow and whether the client window wants to be shifted to make room for the
1056N/AIf the win_gravity is Static, the window manager frame is positioned so that
1056N/Athe inside border of the client window inside the frame is in the same position
1056N/Aon the screen as it was when the client requested the transition from Withdrawn
1056N/Astate. Other values of win_gravity specify a window reference point. For
1056N/ANorthWest, NorthEast, SouthWest, and SouthEast the reference point is the
1056N/Aspecified outer corner of the window (on the outside border edge). For North,
1056N/ASouth, East and West the reference point is the center of the specified outer
1056N/Aedge of the window border. For Center the reference point is the center of the
1056N/Awindow. The reference point of the window manager frame is placed at the
1056N/Alocation on the screen where the reference point of the client window was when
1056N/Athe client requested the transition from Withdrawn state.
1056N/AThe min_width and min_height elements specify the minimum size that the window
1056N/Acan be for the client to be useful. The max_width and max_height elements
1056N/Aspecify the maximum size. The base_width and base_height elements in
1056N/Aconjunction with width_inc and height_inc define an arithmetic progression of
1056N/Apreferred window widths and heights for non-negative integers i and j:
1056N/Awidth = base_width + ( i x width_inc )
1056N/Aheight = base_height + ( j x height_inc )
1056N/AWindow managers are encouraged to use i and j instead of width and height in
1056N/Areporting window sizes to users. If a base size is not provided, the minimum
1056N/Asize is to be used in its place and vice versa.
1056N/AThe min_aspect and max_aspect fields are fractions with the numerator first and
1056N/Athe denominator second, and they allow a client to specify the range of aspect
1056N/Aratios it prefers. Window managers that honor aspect ratios should take into
1056N/Aaccount the base size in determining the preferred window size. If a base size
1056N/Ais provided along with the aspect ratio fields, the base size should be
1056N/Asubtracted from the window size prior to checking that the aspect ratio falls
1056N/Ain range. If a base size is not provided, nothing should be subtracted from the
1056N/Awindow size. (The minimum size is not to be used in place of the base size for
1056N/AThe WM_HINTS property (whose type is WM_HINTS) is used to communicate to the
1056N/Awindow manager. It conveys the information the window manager needs other than
1056N/Athe window geometry, which is available from the window itself; the constraints
1056N/Aon that geometry, which is available from the WM_NORMAL_HINTS structure; and
1056N/Avarious strings, which need separate properties, such as WM_NAME. The contents
1056N/Aof the properties are as follows:
1276N/A┌─────────────┬──────┬─────────────────────────────────┐
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A│flags │CARD32│(see the next table) │
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A│input │CARD32│The client's input model │
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A│initial_state│CARD32│The state when first mapped │
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A│icon_pixmap │PIXMAP│The pixmap for the icon image │
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A│icon_window │WINDOW│The window for the icon image │
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A│icon_x │INT32 │The icon location │
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A│icon_mask │PIXMAP│The mask for the icon shape │
1276N/A├─────────────┼──────┼─────────────────────────────────┤
1276N/A│window_group │WINDOW│The ID of the group leader window│
1276N/A└─────────────┴──────┴─────────────────────────────────┘
1276N/A┌────────────────┬─────┬──────────────────────┐
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A│StateHint │2 │initial_state │
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A│IconPixmapHint │4 │icon_pixmap │
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A│IconWindowHint │8 │icon_window │
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A│IconPositionHint│16 │icon_x & icon_y │
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A│IconMaskHint │32 │icon_mask │
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A│WindowGroupHint │64 │window_group │
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A│MessageHint │128 │(this bit is obsolete)│
1276N/A├────────────────┼─────┼──────────────────────┤
1276N/A│UrgencyHint │256 │urgency │
1276N/A└────────────────┴─────┴──────────────────────┘
1056N/AWindow managers are free to assume convenient values for all fields of the
1056N/AWM_HINTS property if a window is mapped without one.
1056N/AThe input field is used to communicate to the window manager the input focus
1276N/Amodel used by the client (see Input Focus ).
1056N/AClients with the Globally Active and No Input models should set the input flag
1056N/Ato False. Clients with the Passive and Locally Active models should set the
1056N/AFrom the client's point of view, the window manager will regard the client's
1056N/Atop-level window as being in one of three states:
1276N/AThe semantics of these states are described in Changing Window State. Newly
1276N/Acreated windows start in the Withdrawn state. Transitions between states happen
1276N/Awhen a top-level window is mapped and unmapped and when the window manager
1056N/AThe value of the initial_state field determines the state the client wishes to
1056N/Abe in at the time the top-level window is mapped from the Withdrawn state, as
1056N/Ashown in the following table:
1276N/A┌───────────┬─────┬─────────────────────┐
1276N/A├───────────┼─────┼─────────────────────┤
1276N/A│NormalState│1 │The window is visible│
1276N/A├───────────┼─────┼─────────────────────┤
1276N/A│IconicState│3 │The icon is visible │
1276N/A└───────────┴─────┴─────────────────────┘
1056N/AThe icon_pixmap field may specify a pixmap to be used as an icon. This pixmap
1056N/A ● One of the sizes specified in the WM_ICON_SIZE property on the root if it
1276N/A exists (see WM_ICON_SIZE Property ).
1056N/A ● 1-bit deep. The window manager will select, through the defaults database,
1056N/A suitable background (for the 0 bits) and foreground (for the 1 bits)
1056N/A colors. These defaults can, of course, specify different colors for the
1056N/A icons of different clients.
1056N/AThe icon_mask specifies which pixels of the icon_pixmap should be used as the
1056N/Aicon, allowing for icons to appear nonrectangular.
1056N/AThe icon_window field is the ID of a window the client wants used as its icon.
1056N/AMost, but not all, window managers will support icon windows. Those that do not
1056N/Aare likely to have a user interface in which small windows that behave like
1056N/Aicons are completely inappropriate. Clients should not attempt to remedy the
1056N/Aomission by working around it.
1056N/AClients that need more capabilities from the icons than a simple 2-color bitmap
1276N/Ashould use icon windows. Rules for clients that do are set out in Icons.
1056N/AThe (icon_x,icon_y) coordinate is a hint to the window manager as to where it
1056N/Ashould position the icon. The policies of the window manager control the
1056N/Apositioning of icons, so clients should not depend on attention being paid to
1056N/AThe window_group field lets the client specify that this window belongs to a
1056N/Agroup of windows. An example is a single client manipulating multiple children
1056N/A ● The window_group field should be set to the ID of the group leader. The
1056N/A window group leader may be a window that exists only for that purpose;
1056N/A a placeholder group leader of this kind would never be mapped either by
1056N/A the client or by the window manager.
1056N/A ● The properties of the window group leader are those for the group as a
1056N/A whole (for example, the icon to be shown when the entire group is
1056N/AWindow managers may provide facilities for manipulating the group as a whole.
1056N/AClients, at present, have no way to operate on the group as a whole.
1056N/AThe messages bit, if set in the flags field, indicates that the client is using
1056N/Aan obsolete window manager communication protocol, ^[7] rather than the
1276N/AWM_PROTOCOLS mechanism of WM_PROTOCOLS Property
1056N/AThe UrgencyHint flag, if set in the flags field, indicates that the client
1056N/Adeems the window contents to be urgent, requiring the timely response of the
1056N/Auser. The window manager must make some effort to draw the user's attention to
1056N/Athis window while this flag is set. The window manager must also monitor the
1056N/Astate of this flag for the entire time the window is in the Normal or Iconic
1056N/Astate and must take appropriate action when the state of the flag changes. The
1056N/Aflag is otherwise independent of the window's state; in particular, the window
1056N/Amanager is not required to deiconify the window if the client sets the flag on
1056N/Aan Iconic window. Clients must provide some means by which the user can cause
1056N/Athe UrgencyHint flag to be set to zero or the window to be withdrawn. The
1056N/Auser's action can either mitigate the actual condition that made the window
1056N/Aurgent, or it can merely shut off the alarm.
1056N/A This mechanism is useful for alarm dialog boxes or reminder windows, in
1056N/A cases where mapping the window is not enough (
e.g., in the presence of
1056N/A multi-workspace or virtual desktop window managers), and where using an
1056N/A override-redirect window is too intrusive. For example, the window manager
1056N/A may attract attention to an urgent window by adding an indicator to its
1056N/A title bar or its icon. Window managers may also take additional action for
1056N/A a window that is newly urgent, such as by flashing its icon (if the window
1056N/A is iconic) or by raising it to the top of the stack.
1056N/AThe WM_CLASS property (of type STRING without control characters) contains two
1056N/Aconsecutive null-terminated strings. These specify the Instance and Class names
1056N/Ato be used by both the client and the window manager for looking up resources
1056N/Afor the application or as identifying information. This property must be
1056N/Apresent when the window leaves the Withdrawn state and may be changed only
1056N/Awhile the window is in the Withdrawn state. Window managers may examine the
1056N/Aproperty only when they start up and when the window leaves the Withdrawn
1056N/Astate, but there should be no need for a client to change its state
1056N/AThe two strings, respectively, are:
1056N/A ● A string that names the particular instance of the application to which the
1056N/A client that owns this window belongs. Resources that are specified by
1056N/A instance name override any resources that are specified by class name.
1056N/A Instance names can be specified by the user in an operating-system specific
1056N/A manner. On POSIX-conformant systems, the following conventions are used:
1056N/A ○ If "-name NAME" is given on the command line, NAME is used as the
1056N/A ○ Otherwise, if the environment variable RESOURCE_NAME is set, its value
1056N/A will be used as the instance name.
1056N/A ○ Otherwise, the trailing part of the name used to invoke the program
1056N/A (argv[0] stripped of any directory names) is used as the instance name.
1056N/A ● A string that names the general class of applications to which the client
1056N/A that owns this window belongs. Resources that are specified by class apply
1056N/A to all applications that have the same class name. Class names are
1056N/A specified by the application writer. Examples of commonly used class names
1056N/A include: "Emacs", "XTerm", "XClock", "XLoad", and so on.
1056N/ANote that WM_CLASS strings are null-terminated and, thus, differ from the
1056N/Ageneral conventions that STRING properties are null-separated. This
1056N/Ainconsistency is necessary for backwards compatibility.
1056N/AThe WM_TRANSIENT_FOR property (of type WINDOW) contains the ID of another
1056N/Atop-level window. The implication is that this window is a pop-up on behalf of
1056N/Athe named window, and window managers may decide not to decorate transient
1056N/Awindows or may treat them differently in other ways. In particular, window
1056N/Amanagers should present newly mapped WM_TRANSIENT_FOR windows without requiring
1056N/Aany user interaction, even if mapping top-level windows normally does require
1056N/Ainteraction. Dialogue boxes, for example, are an example of windows that should
1056N/AIt is important not to confuse WM_TRANSIENT_FOR with override-redirect.
1056N/AWM_TRANSIENT_FOR should be used in those cases where the pointer is not grabbed
1056N/Awhile the window is mapped (in other words, if other windows are allowed to be
1056N/Aactive while the transient is up). If other windows must be prevented from
1056N/Aprocessing input (for example, when implementing pop-up menus), use
1056N/Aoverride-redirect and grab the pointer while the window is mapped.
1056N/AThe WM_PROTOCOLS property (of type ATOM) is a list of atoms. Each atom
1056N/Aidentifies a communication protocol between the client and the window manager
1056N/Ain which the client is willing to participate. Atoms can identify both standard
1056N/Aprotocols and private protocols specific to individual window managers.
1056N/AAll the protocols in which a client can volunteer to take part involve the
1056N/Awindow manager sending the client a ClientMessage event and the client taking
1276N/Aappropriate action. For details of the contents of the event, see ClientMessage
1276N/AEvents In each case, the protocol transactions are initiated by the window
1056N/AThe WM_PROTOCOLS property is not required. If it is not present, the client
1056N/Adoes not want to participate in any window manager protocols.
1056N/AThe X Consortium will maintain a registry of protocols to avoid collisions in
1056N/Athe name space. The following table lists the protocols that have been defined
1276N/A┌────────────────┬───────────────┬──────────────────────────────────────┐
1276N/A│Protocol │Section │Purpose │
1276N/A├────────────────┼───────────────┼──────────────────────────────────────┤
1276N/A│WM_TAKE_FOCUS │Input Focus │Assignment of input focus │
1276N/A├────────────────┼───────────────┼──────────────────────────────────────┤
1276N/A│WM_SAVE_YOURSELF│Appendix C │Save client state request (deprecated)│
1276N/A├────────────────┼───────────────┼──────────────────────────────────────┤
1276N/A│WM_DELETE_WINDOW│Window Deletion│Request to delete top-level window │
1276N/A└────────────────┴───────────────┴──────────────────────────────────────┘
1056N/AIt is expected that this table will grow over time.
1056N/AWM_COLORMAP_WINDOWS Property
1056N/AThe WM_COLORMAP_WINDOWS property (of type WINDOW) on a top-level window is a
1056N/Alist of the IDs of windows that may need colormaps installed that differ from
1056N/Athe colormap of the top-level window. The window manager will watch this list
1056N/Aof windows for changes in their colormap attributes. The top-level window is
1056N/Aalways (implicitly or explicitly) on the watch list. For the details of this
1056N/AThe client should set the WM_CLIENT_MACHINE property (of one of the TEXT types)
1056N/Ato a string that forms the name of the machine running the client as seen from
1056N/Athe machine running the server.
1056N/AThe properties that were described in the previous section are those that the
1056N/Aclient is responsible for maintaining on its top-level windows. This section
1056N/Adescribes the properties that the window manager places on client's top-level
1056N/AThe window manager will place a WM_STATE property (of type WM_STATE) on each
1056N/Atop-level client window that is not in the Withdrawn state. Top-level windows
1056N/Ain the Withdrawn state may or may not have the WM_STATE property. Once the
1056N/Atop-level window has been withdrawn, the client may re-use it for another
1056N/Apurpose. Clients that do so should remove the WM_STATE property if it is still
1056N/ASome clients (such as xprop) will ask the user to click over a window on which
1056N/Athe program is to operate. Typically, the intent is for this to be a top-level
1056N/Awindow. To find a top-level window, clients should search the window hierarchy
1056N/Abeneath the selected location for a window with the WM_STATE property. This
1056N/Asearch must be recursive in order to cover all window manager reparenting
1056N/Apossibilities. If no window with a WM_STATE property is found, it is
1056N/Arecommended that programs use a mapped child-of-root window if one is present
1056N/Abeneath the selected location.
1056N/AThe contents of the WM_STATE property are defined as follows:
1276N/A┌─────┬──────┬────────────────────┐
1276N/A├─────┼──────┼────────────────────┤
1276N/A│state│CARD32│(see the next table)│
1276N/A├─────┼──────┼────────────────────┤
1276N/A│icon │WINDOW│ID of icon window │
1276N/A└─────┴──────┴────────────────────┘
1056N/AAdding other fields to this property is reserved to the X Consortium. Values
1056N/Afor the state field other than those defined in the above table are reserved
1056N/Afor use by the X Consortium.
1056N/AThe state field describes the window manager's idea of the state the window is
1056N/Ain, which may not match the client's idea as expressed in the initial_state
1056N/Afield of the WM_HINTS property (for example, if the user has asked the window
1056N/Amanager to iconify the window). If it is NormalState, the window manager
1056N/Abelieves the client should be animating its window. If it is IconicState, the
1056N/Aclient should animate its icon window. In either state, clients should be
1056N/Aprepared to handle exposure events from either window.
1056N/AWhen the window is withdrawn, the window manager will either change the state
1056N/Afield's value to WithdrawnState or it will remove the WM_STATE property
1056N/AThe icon field should contain the window ID of the window that the window
1056N/Amanager uses as the icon for the window on which this property is set. If no
1056N/Asuch window exists, the icon field should be None. Note that this window could
1056N/Abe but is not necessarily the same window as the icon window that the client
1056N/Amay have specified in its WM_HINTS property. The WM_STATE icon may be a window
1056N/Athat the window manager has supplied and that contains the client's icon
1056N/Apixmap, or it may be an ancestor of the client's icon window.
1056N/AA window manager that wishes to place constraints on the sizes of icon pixmaps
1056N/Aand/or windows should place a property called WM_ICON_SIZE on the root. The
1056N/Acontents of this property are listed in the following table.
1276N/A┌──────────┬──────┬─────────────────────────────────┐
1276N/A├──────────┼──────┼─────────────────────────────────┤
1276N/A│min_width │CARD32│The data for the icon size series│
1276N/A├──────────┼──────┼─────────────────────────────────┤
1276N/A├──────────┼──────┼─────────────────────────────────┤
1276N/A├──────────┼──────┼─────────────────────────────────┤
1276N/A├──────────┼──────┼─────────────────────────────────┤
1276N/A├──────────┼──────┼─────────────────────────────────┤
1276N/A└──────────┴──────┴─────────────────────────────────┘
1056N/AFor more details see section 14.1.12 in Xlib - C Language X Interface.
1056N/AFrom the client's point of view, the window manager will regard each of the
1056N/Aclient's top-level windows as being in one of three states, whose semantics are
1056N/A ● NormalState - The client's top-level window is viewable.
1056N/A ● IconicState - The client's top-level window is iconic (whatever that means
1056N/A for this window manager). The client can assume that its top-level window
1056N/A is not viewable, its icon_window (if any) will be viewable and, failing
1056N/A that, its icon_pixmap (if any) or its WM_ICON_NAME will be displayed.
1056N/A ● WithdrawnState - Neither the client's top-level window nor its icon is
1056N/AIn fact, the window manager may implement states with semantics other than
1056N/Athose described above. For example, a window manager might implement a concept
1056N/Aof an "inactive" state in which an infrequently used client's window would be
1056N/Arepresented as a string in a menu. But this state is invisible to the client,
1056N/Awhich would see itself merely as being in the Iconic state.
1056N/ANewly created top-level windows are in the Withdrawn state. Once the window has
1056N/Abeen provided with suitable properties, the client is free to change its state
1056N/A ● Withdrawn -> Normal - The client should map the window with
1056N/A ● Withdrawn -> Iconic - The client should map the window with
1056N/A ● Normal -> Iconic - The client should send a ClientMessage event as
1056N/A described later in this section.
1056N/A ● Normal -> Withdrawn - The client should unmap the window and follow it with
1056N/A a synthetic UnmapNotify event as described later in this section.
1056N/A ● Iconic -> Normal - The client should map the window. The contents of
1056N/A ● Iconic -> Withdrawn - The client should unmap the window and follow it with
1056N/A a synthetic UnmapNotify event as described later in this section.
1056N/AOnly the client can effect a transition into or out of the Withdrawn state.
1056N/AOnce a client's window has left the Withdrawn state, the window will be mapped
1056N/Aif it is in the Normal state and the window will be unmapped if it is in the
1056N/AIconic state. Reparenting window managers must unmap the client's window when
1056N/Ait is in the Iconic state, even if an ancestor window being unmapped renders
1056N/Athe client's window unviewable. Conversely, if a reparenting window manager
1056N/Arenders the client's window unviewable by unmapping an ancestor, the client's
1056N/Awindow is by definition in the Iconic state and must also be unmapped.
1056N/A Clients can select for StructureNotify on their top-level windows to track
1056N/A transitions between Normal and Iconic states. Receipt of a MapNotify event
1056N/A will indicate a transition to the Normal state, and receipt of an
1056N/A UnmapNotify event will indicate a transition to the Iconic state.
1056N/AWhen changing the state of the window to Withdrawn, the client must (in
1056N/Aaddition to unmapping the window) send a synthetic UnmapNotify event by using a
1056N/ASendEvent request with the following arguments:
1276N/A┌───────────────────────────┬─────────────────────────────────────────┐
1276N/A├───────────────────────────┼─────────────────────────────────────────┤
1276N/A├───────────────────────────┼─────────────────────────────────────────┤
1276N/A├───────────────────────────┼─────────────────────────────────────────┤
1276N/A│event-mask │(SubstructureRedirect|SubstructureNotify)│
1276N/A├───────────────────────────┼─────────────────────────────────────────┤
1276N/A│event: an UnmapNotify with:│ │
1276N/A├───────────────────────────┼─────────────────────────────────────────┤
1276N/A├───────────────────────────┼─────────────────────────────────────────┤
1276N/A│ window: │The window itself │
1276N/A├───────────────────────────┼─────────────────────────────────────────┤
1276N/A└───────────────────────────┴─────────────────────────────────────────┘
1056N/A The reason for requiring the client to send a synthetic UnmapNotify event
1056N/A is to ensure that the window manager gets some notification of the client's
1056N/A desire to change state, even though the window may already be unmapped when
1056N/A For compatibility with obsolete clients, window managers should trigger the
1056N/A transition to the Withdrawn state on the real UnmapNotify rather than
1056N/A waiting for the synthetic one. They should also trigger the transition if
1056N/A they receive a synthetic UnmapNotify on a window for which they have not
1056N/A yet received a real UnmapNotify.
1056N/AWhen a client withdraws a window, the window manager will then update or remove
1276N/Athe WM_STATE property as described in WM_STATE Property. Clients that want to
1276N/Are-use a client window (
e.g., by mapping it again or reparenting it elsewhere)
1276N/Aafter withdrawing it must wait for the withdrawal to be complete before
1276N/Aproceeding. The preferred method for doing this is for clients to wait for the
1276N/Awindow manager to update or remove the WM_STATE property. ^[8]
1056N/AIf the transition is from the Normal to the Iconic state, the client should
1056N/Asend a ClientMessage event to the root with:
1056N/A ● Window == the window to be iconified
1056N/A ● Type ^[9] == the atom WM_CHANGE_STATE
1056N/A The format of this ClientMessage event does not match the format of
1276N/A ClientMessages in ClientMessage Events. This is because they are sent by
1276N/A the window manager to clients, and this message is sent by clients to the
1056N/AOther values of data[0] are reserved for future extensions to these
1056N/Aconventions. The parameters of the SendEvent request should be those described
1056N/Afor the synthetic UnmapNotify event.
1056N/A Clients can also select for VisibilityChange events on their top-level or
1056N/A icon windows. They will then receive a VisibilityNotify (state==
1056N/A FullyObscured) event when the window concerned becomes completely obscured
1056N/A even though mapped (and thus, perhaps a waste of time to update) and a
1056N/A VisibilityNotify (state!=FullyObscured) event when it becomes even partly
1056N/A When a window makes a transition from the Normal state to either the Iconic
1056N/A or the Withdrawn state, clients should be aware that the window manager may
1056N/A make transients for this window inaccessible. Clients should not rely on
1056N/A transient windows being available to the user when the transient owner
1056N/A window is not in the Normal state. When withdrawing a window, clients are
1056N/A advised to withdraw transients for the window.
1056N/AClients can resize and reposition their top-level windows by using the
1056N/AConfigureWindow request. The attributes of the window that can be altered with
1056N/Athis request are as follows:
1056N/A ● The [x,y] location of the window's upper left-outer corner
1056N/A ● The [width,height] of the inner region of the window (excluding borders)
1056N/A ● The border width of the window
1056N/A ● The window's position in the stack
1056N/AThe coordinate system in which the location is expressed is that of the root
1056N/A(irrespective of any reparenting that may have occurred). The border width to
1056N/Abe used and win_gravity position hint to be used are those most recently
1056N/Arequested by the client. Client configure requests are interpreted by the
1056N/Awindow manager in the same manner as the initial window geometry mapped from
1276N/Athe Withdrawn state, as described in WM_NORMAL_HINTS Property Clients must be
1276N/Aaware that there is no guarantee that the window manager will allocate them the
1276N/Arequested size or location and must be prepared to deal with any size and
1276N/Alocation. If the window manager decides to respond to a ConfigureRequest
1056N/A ● Not changing the size, location, border width, or stacking order of the
1056N/A A client will receive a synthetic ConfigureNotify event that describes the
1056N/A (unchanged) geometry of the window. The (x,y) coordinates will be in the
1056N/A root coordinate system, adjusted for the border width the client requested,
1056N/A irrespective of any reparenting that has taken place. The border_width will
1056N/A be the border width the client requested. The client will not receive a
1056N/A real ConfigureNotify event because no change has actually taken place.
1056N/A ● Moving or restacking the window without resizing it or changing its border
1056N/A A client will receive a synthetic ConfigureNotify event following the
1056N/A change that describes the new geometry of the window. The event's (x,y)
1056N/A coordinates will be in the root coordinate system adjusted for the border
1056N/A width the client requested. The border_width will be the border width the
1056N/A client requested. The client may not receive a real ConfigureNotify event
1056N/A that describes this change because the window manager may have reparented
1056N/A the top-level window. If the client does receive a real event, the
1056N/A synthetic event will follow the real one.
1056N/A ● Resizing the window or changing its border width (regardless of whether the
1056N/A window was also moved or restacked).
1056N/A A client that has selected for StructureNotify events will receive a real
1056N/A ConfigureNotify event. Note that the coordinates in this event are relative
1056N/A to the parent, which may not be the root if the window has been reparented.
1056N/A The coordinates will reflect the actual border width of the window (which
1056N/A the window manager may have changed). The TranslateCoordinates request can
1056N/A be used to convert the coordinates if required.
1056N/AThe general rule is that coordinates in real ConfigureNotify events are in the
1056N/Aparent's space; in synthetic events, they are in the root space.
1056N/A Clients cannot distinguish between the case where a top-level window is
1056N/A resized and moved from the case where the window is resized but not moved,
1056N/A since a real ConfigureNotify event will be received in both cases. Clients
1056N/A that are concerned with keeping track of the absolute position of a
1056N/A top-level window should keep a piece of state indicating whether they are
1056N/A certain of its position. Upon receipt of a real ConfigureNotify event on
1056N/A the top-level window, the client should note that the position is unknown.
1056N/A Upon receipt of a synthetic ConfigureNotify event, the client should note
1056N/A the position as known, using the position in this event. If the client
1056N/A receives a KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
1056N/A EnterNotify or LeaveNotify event on the window (or on any descendant), the
1056N/A client can deduce the top-level window's position from the difference
1056N/A between the (event-x, event-y) and (root-x, root-y) coordinates in these
1056N/A events. Only when the position is unknown does the client need to use the
1056N/A TranslateCoordinates request to find the position of a top-level window.
1056N/AClients should be aware that their borders may not be visible. Window managers
1056N/Aare free to use reparenting techniques to decorate client's top-level windows
1056N/Awith borders containing titles, controls, and other details to maintain a
1056N/Aconsistent look-and-feel. If they do, they are likely to override the client's
1056N/Aattempts to set the border width and set it to zero. Clients, therefore, should
1056N/Anot depend on the top-level window's border being visible or use it to display
1056N/Aany critical information. Other window managers will allow the top-level
1056N/Awindows border to be visible.
1056N/A Clients should set the desired value of the border-width attribute on all
1056N/A ConfigureWindow requests to avoid a race condition.
1056N/AClients that change their position in the stack must be aware that they may
1056N/Ahave been reparented, which means that windows that used to be siblings no
1056N/Alonger are. Using a nonsibling as the sibling parameter on a ConfigureWindow
1056N/Arequest will cause an error.
1056N/A Clients that use a ConfigureWindow request to request a change in their
1056N/A position in the stack should do so using None in the sibling field.
1056N/AClients that must position themselves in the stack relative to some window that
1056N/Awas originally a sibling must do the ConfigureWindow request (in case they are
1056N/Arunning under a nonreparenting window manager), be prepared to deal with a
1056N/Aresulting error, and then follow with a synthetic ConfigureRequest event by
1056N/Ainvoking a SendEvent request with the following arguments:
1276N/A┌──────────────────────────────┬──────────────────────────────────────────────┐
1276N/A├──────────────────────────────┼──────────────────────────────────────────────┤
1276N/A├──────────────────────────────┼──────────────────────────────────────────────┤
1276N/A├──────────────────────────────┼──────────────────────────────────────────────┤
1276N/A│event-mask │(SubstructureRedirect|SubstructureNotify) │
1276N/A├──────────────────────────────┼──────────────────────────────────────────────┤
1276N/A│event: an ConfigureRequest │ │
1276N/A├──────────────────────────────┼──────────────────────────────────────────────┤
1276N/A├──────────────────────────────┼──────────────────────────────────────────────┤
1276N/A│ window: │The window itself │
1276N/A├──────────────────────────────┼──────────────────────────────────────────────┤
1276N/A│ ... │Other parameters from the ConfigureWindow │
1276N/A└──────────────────────────────┴──────────────────────────────────────────────┘
1056N/AWindow managers are in any case free to position windows in the stack as they
1056N/Asee fit, and so clients should not rely on receiving the stacking order they
1056N/Ahave requested. Clients should ignore the above-sibling field of both real and
1056N/Asynthetic ConfigureNotify events received on their top-level windows because
1056N/Athis field may not contain useful information.
1056N/AThe attributes that may be supplied when a window is created may be changed by
1056N/Ausing the ChangeWindowAttributes request. The window attributes are listed in
1276N/A┌──────────────────────┬─────────────────┐
1276N/A│Attribute │Private to Client│
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A│Do-not-propagate mask │Yes │
1276N/A├──────────────────────┼─────────────────┤
1276N/A│Override-redirect flag│No │
1276N/A├──────────────────────┼─────────────────┤
1276N/A├──────────────────────┼─────────────────┤
1276N/A└──────────────────────┴─────────────────┘
1056N/AMost attributes are private to the client and will never be interfered with by
1056N/Athe window manager. For the attributes that are not private to the client:
1056N/A ● The window manager is free to override the window gravity; a reparenting
1056N/A window manager may want to set the top-level window's window gravity for
1056N/A ● Clients are free to set the save-under hint on their top-level windows, but
1056N/A they must be aware that the hint may be overridden by the window manager.
1056N/A ● Windows, in effect, have per-client event masks, and so, clients may select
1056N/A for whatever events are convenient irrespective of any events the window
1056N/A manager is selecting for. There are some events for which only one client
1056N/A at a time may select, but the window manager should not select for them on
1056N/A any of the client's windows.
1056N/A ● Clients can set override-redirect on top-level windows but are encouraged
1276N/A not to do so except as described in Pop-up Windows. and Redirecting
1056N/AThere are four models of input handling:
1056N/A ● No Input - The client never expects keyboard input. An example would be
1056N/A xload or another output-only client.
1056N/A ● Passive Input - The client expects keyboard input but never explicitly sets
1056N/A the input focus. An example would be a simple client with no subwindows,
1056N/A which will accept input in PointerRoot mode or when the window manager sets
1056N/A the input focus to its top-level window (in click-to-type mode).
1056N/A ● Locally Active Input - The client expects keyboard input and explicitly
1056N/A sets the input focus, but it only does so when one of its windows already
1056N/A has the focus. An example would be a client with subwindows defining
1056N/A various data entry fields that uses Next and Prev keys to move the input
1056N/A focus between the fields. It does so when its top-level window has acquired
1056N/A the focus in PointerRoot mode or when the window manager sets the input
1056N/A focus to its top-level window (in click-to-type mode).
1056N/A ● Globally Active Input - The client expects keyboard input and explicitly
1056N/A sets the input focus, even when it is in windows the client does not own.
1056N/A An example would be a client with a scroll bar that wants to allow users to
1056N/A scroll the window without disturbing the input focus even if it is in some
1056N/A other window. It wants to acquire the input focus when the user clicks in
1056N/A the scrolled region but not when the user clicks in the scroll bar itself.
1056N/A Thus, it wants to prevent the window manager from setting the input focus
1056N/AThe four input models and the corresponding values of the input field and the
1056N/Apresence or absence of the WM_TAKE_FOCUS atom in the WM_PROTOCOLS property are
1056N/Alisted in the following table:
1276N/A┌───────────────┬───────────┬─────────────┐
1276N/A│Input Model │Input Field│WM_TAKE_FOCUS│
1276N/A├───────────────┼───────────┼─────────────┤
1276N/A├───────────────┼───────────┼─────────────┤
1276N/A├───────────────┼───────────┼─────────────┤
1276N/A│Locally Active │True │Present │
1276N/A├───────────────┼───────────┼─────────────┤
1276N/A│Globally Active│False │Present │
1276N/A└───────────────┴───────────┴─────────────┘
1056N/APassive and Locally Active clients set the input field of WM_HINTS to True,
1056N/Awhich indicates that they require window manager assistance in acquiring the
1056N/Ainput focus. No Input and Globally Active clients set the input field to False,
1056N/Awhich requests that the window manager not set the input focus to their
1056N/AClients that use a SetInputFocus request must set the time field to the
1056N/Atimestamp of the event that caused them to make the attempt. This cannot be a
1056N/AFocusIn event because they do not have timestamps. Clients may also acquire the
1056N/Afocus without a corresponding EnterNotify. Note that clients must not use
1056N/ACurrentTime in the time field.
1056N/AClients using the Globally Active model can only use a SetInputFocus request to
1056N/Aacquire the input focus when they do not already have it on receipt of one of
1056N/A ● Passive-grabbed KeyRelease
1056N/AIn general, clients should avoid using passive-grabbed key events for this
1056N/Apurpose, except when they are unavoidable (as, for example, a selection tool
1056N/Athat establishes a passive grab on the keys that cut, copy, or paste).
1056N/AThe method by which the user commands the window manager to set the focus to a
1056N/Awindow is up to the window manager. For example, clients cannot determine
1056N/Awhether they will see the click that transfers the focus.
1056N/AWindows with the atom WM_TAKE_FOCUS in their WM_PROTOCOLS property may receive
1276N/Aa ClientMessage event from the window manager (as described in ClientMessage
1276N/AEvents. ) with WM_TAKE_FOCUS in its data[0] field and a valid timestamp (
i.e.,
1276N/Anot CurrentTime) in its data[1] field. If they want the focus, they should
1276N/Arespond with a SetInputFocus request with its window field set to the window of
1276N/Atheirs that last had the input focus or to their default input window, and the
1276N/Atime field set to the timestamp in the message. For further information, see
1056N/AA client could receive WM_TAKE_FOCUS when opening from an icon or when the user
1056N/Ahas clicked outside the top-level window in an area that indicates to the
1056N/Awindow manager that it should assign the focus (for example, clicking in the
1056N/Aheadline bar can be used to assign the focus).
1056N/AThe goal is to support window managers that want to assign the input focus to a
1056N/Atop-level window in such a way that the top-level window either can assign it
1056N/Ato one of its subwindows or can decline the offer of the focus. For example, a
1056N/Aclock or a text editor with no currently open frames might not want to take
1056N/Afocus even though the window manager generally believes that clients should
1056N/Atake the input focus after being deiconified or raised.
1056N/AClients that set the input focus need to decide a value for the revert-to field
1056N/Aof the SetInputFocus request. This determines the behavior of the input focus
1056N/Aif the window the focus has been set to becomes not viewable. The value can be
1056N/A ● Parent - In general, clients should use this value when assigning focus to
1056N/A one of their subwindows. Unmapping the subwindow will cause focus to revert
1056N/A to the parent, which is probably what you want.
1056N/A ● PointerRoot - Using this value with a click-to-type focus management policy
1056N/A leads to race conditions because the window becoming unviewable may
1056N/A coincide with the window manager deciding to move the focus elsewhere.
1056N/A ● None - Using this value causes problems if the window manager reparents the
1056N/A window, as most window managers will, and then crashes. The input focus
1056N/A will be None, and there will probably be no way to change it.
1056N/ANote that neither PointerRoot nor None is really safe to use.
1056N/A Clients that invoke a SetInputFocus request should set the revert-to
1056N/AA convention is also required for clients that want to give up the input focus.
1056N/AThere is no safe value set for them to set the input focus to; therefore, they
1056N/Ashould ignore input material.
1056N/A Clients should not give up the input focus of their own volition. They
1056N/A should ignore input that they receive instead.
1056N/AThe window manager is responsible for installing and uninstalling colormaps on
1056N/Abehalf of clients with top-level windows that the window manager manages.
1056N/AClients provide the window manager with hints as to which colormaps to install
1056N/Aand uninstall. Clients must not install or uninstall colormaps themselves
1056N/A(except under the circumstances noted below). When a client's top-level window
1056N/Agets the colormap focus (as a result of whatever colormap focus policy is
1056N/Aimplemented by the window manager), the window manager will ensure that one or
1056N/Amore of the client's colormaps are installed.
1056N/AClients whose top-level windows and subwindows all use the same colormap should
1056N/Aset its ID in the colormap field of the top-level window's attributes. They
1056N/Ashould not set a WM_COLORMAP_WINDOWS property on the top-level window. If they
1056N/Awant to change the colormap, they should change the top-level window's colormap
1056N/Aattribute. The window manager will track changes to the window's colormap
1056N/Aattribute and install colormaps as appropriate.
1056N/AClients that create windows can use the value CopyFromParent to inherit their
1056N/Aparent's colormap. Window managers will ensure that the root window's colormap
1056N/Afield contains a colormap that is suitable for clients to inherit. In
1056N/Aparticular, the colormap will provide distinguishable colors for BlackPixel and
1056N/ATop-level windows that have subwindows or override-redirect pop-up windows
1056N/Awhose colormap requirements differ from the top-level window should have a
1056N/AWM_COLORMAP_WINDOWS property. This property contains a list of IDs for windows
1056N/Awhose colormaps the window manager should attempt to have installed when, in
1056N/Athe course of its individual colormap focus policy, it assigns the colormap
1276N/Afocus to the top-level window (see WM_COLORMAP_WINDOWS Property ). The list is
1276N/Aordered by the importance to the client of having the colormaps installed. The
1276N/Awindow manager will track changes to this property and will track changes to
1276N/Athe colormap attribute of the windows in the property.
1056N/AIf the relative importance of colormaps changes, the client should update the
1056N/AWM_COLORMAP_WINDOWS property to reflect the new ordering. If the top-level
1056N/Awindow does not appear in the list, the window manager will assume it to be of
1056N/Ahigher priority than any window in the list.
1056N/AWM_TRANSIENT_FOR windows can either have their own WM_COLORMAP_WINDOWS property
1056N/Aor appear in the property of the window they are transient for, as appropriate.
1056N/A An alternative design was considered for how clients should hint to the
1056N/A window manager about their colormap requirements. This alternative design
1056N/A specified a list of colormaps instead of a list of windows. The current
1056N/A design, a list of windows, was chosen for two reasons. First, it allows
1056N/A window managers to find the visuals of the colormaps, thus permitting
1056N/A visual-dependent colormap installation policies. Second, it allows window
1056N/A managers to select for VisibilityChange events on the windows concerned and
1056N/A to ensure that colormaps are only installed if the windows that need them
1056N/A are visible. The alternative design allows for neither of these policies.
1056N/A Clients should be aware of the min-installed-maps and max-installed-maps
1056N/A fields of the connection setup information, and the effect that the minimum
1056N/A value has on the "required list" defined by the Protocol in the description
1056N/A of the InstallColormap request. Briefly, the min-installed-maps most
1056N/A recently installed maps are guaranteed to be installed. This value is often
1056N/A one; clients needing multiple colormaps should beware.
1056N/AWhenever possible, clients should use the mechanisms described above and let
1056N/Athe window manager handle colormap installation. However, clients are permitted
1056N/Ato perform colormap installation on their own while they have the pointer
1056N/Agrabbed. A client performing colormap installation must notify the window
1056N/Amanager prior to the first installation. When the client has finished its
1056N/Acolormap installation, it must also notify the window manager. The client
1056N/Anotifies the window manager by issuing a SendEvent request with the following
1276N/A┌─────────────────┬───────────────────────────────────────────────────────────┐
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│destination │The root window of the screen on which the colormap is │
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│event-mask │ColormapChange │
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│ window: │The root window, as above │
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│ type: │WM_COLORMAP_NOTIFY │
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│ data[0] │the timestampe of the event that caused the client to start│
1276N/A│ │or stop installing colormaps │
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│ data[1] │1 if the client is starting colormap installation, 0 if the│
1276N/A│ │client is finished with colormap installation │
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│ data[2] │reserved, must be zero │
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│ data[3] │reserved, must be zero │
1276N/A├─────────────────┼───────────────────────────────────────────────────────────┤
1276N/A│ data[4] │reserved, must be zero │
1276N/A└─────────────────┴───────────────────────────────────────────────────────────┘
1056N/AThis feature was introduced in version 2.0 of this document, and there will be
1056N/Aa significant period of time before all window managers can be expected to
1056N/Aimplement this feature. Before using this feature, clients must check the
1276N/Acompliance level of the window manager (using the mechanism described in
1276N/ACommunication with the Window Manager by Means of Selections ) to verify that
1276N/Ait supports this feature. This is necessary to prevent colormap installation
1276N/Aconflicts between clients and older window managers.
1056N/AWindow managers should refrain from installing colormaps while a client has
1056N/Arequested control of colormap installation. The window manager should continue
1056N/Ato track the set of installed colormaps so that it can reinstate its colormap
1056N/Afocus policy when the client has finished colormap installation.
1056N/AThis technique has race conditions that may result in the colormaps continuing
1056N/Ato be installed even after a client has issued its notification message. For
1056N/Aexample, the window manager may have issued some InstallColormap requests that
1056N/Aare not executed until after the client's SendEvent and InstallColormap
1056N/Arequests, thus uninstalling the client's colormaps. If this occurs while the
1056N/Aclient still has the pointer grabbed and before the client has issued the
1056N/A"finished" message, the client may reinstall the desired colormaps.
1056N/A Clients are expected to use this mechanism for things such as pop-up
1056N/A windows and for animations that use override-redirect windows.
1056N/A If a client fails to issue the "finished" message, the window manager may
1056N/A be left in a state where its colormap installation policy is suspended.
1056N/A Window manager implementors may want to implement a feature that resets
1056N/A colormap installation policy in response to a command from the user.
1056N/AA client can hint to the window manager about the desired appearance of its
1056N/A ● A string in WM_ICON_NAME.
1056N/A ● All clients should do this because it provides a fallback for window
1056N/A managers whose ideas about icons differ widely from those of the client.
1056N/A A Pixmap into the icon_pixmap field of the WM_HINTS property and possibly
1056N/A another into the icon_mask field.
1056N/A ● The window manager is expected to display the pixmap masked by the mask.
1056N/A The pixmap should be one of the sizes found in the WM_ICON_SIZE property on
1056N/A the root. If this property is not found, the window manager is unlikely to
1056N/A display icon pixmaps. Window managers usually will clip or tile pixmaps
1056N/A that do not match WM_ICON_SIZE.
1056N/A ● A window into the icon_window field of the WM_HINTS property.
1056N/A The window manager is expected to map that window whenever the client is in
1056N/A the Iconic state. In general, the size of the icon window should be one of
1056N/A those specified in WM_ICON_SIZE on the root, if it exists. Window managers
1056N/A are free to resize icon windows.
1056N/AIn the Iconic state, the window manager usually will ensure that:
1056N/A ● Otherwise, the window's WM_ICON_NAME string is visible.
1056N/AClients should observe the following conventions about their icon windows:
1056N/A ● The icon window should be an InputOutput child of the root.
1056N/A ● The icon window should be one of the sizes specified in the
1056N/A WM_ICON_SIZE property on the root.
1056N/A ● The icon window should use the root visual and default colormap for the
1056N/A ● Clients should not map their icon windows.
1056N/A ● Clients should not unmap their icon windows.
1056N/A ● Clients should not configure their icon windows.
1056N/A ● Clients should not set override-redirect on their icon windows or
1056N/A select for ResizeRedirect events on them.
1056N/A ● Clients must not depend on being able to receive input events by means
1056N/A ● Clients must not manipulate the borders of their icon windows.
1056N/A ● Clients must select for Exposure events on their icon window and
1056N/AWindow managers will differ as to whether they support input events to client's
1056N/Aicon windows; most will allow the client to receive some subset of the keys and
1056N/AWindow managers will ignore any WM_NAME, WM_ICON_NAME, WM_NORMAL_HINTS,
1056N/AWM_HINTS, WM_CLASS, WM_TRANSIENT_FOR, WM_PROTOCOLS, WM_COLORMAP_WINDOWS,
1056N/AWM_COMMAND, or WM_CLIENT_MACHINE properties they find on icon windows.
1056N/AClients that wish to pop up a window can do one of three things:
1056N/A ● They can create and map another normal top-level window, which will get
1056N/A decorated and managed as normal by the window manager. See the discussion
1056N/A of window groups that follows.
1056N/A ● If the window will be visible for a relatively short time and deserves a
1056N/A somewhat lighter treatment, they can set the WM_TRANSIENT_FOR property.
1056N/A They can expect less decoration but can set all the normal window manager
1056N/A properties on the window. An example would be a dialog box.
1056N/A ● If the window will be visible for a very short time and should not be
1056N/A decorated at all, the client can set override-redirect on the window. In
1056N/A general, this should be done only if the pointer is grabbed while the
1056N/A window is mapped. The window manager will never interfere with these
1056N/A windows, which should be used with caution. An example of an appropriate
1056N/A The user will not be able to move, resize, restack, or transfer the input
1056N/A focus to override-redirect windows, since the window manager is not
1056N/A managing them. If it is necessary for a client to receive keystrokes on an
1056N/A override-redirect window, either the client must grab the keyboard or the
1056N/A client must have another top-level window that is not override-redirect and
1056N/A that has selected the Locally Active or Globally Active focus model. The
1056N/A client may set the focus to the override-redirect window when the other
1276N/A window receives a WM_TAKE_FOCUS message or one of the events listed in
1276N/A Input Focus in the description of the Globally Active focus model.
1056N/AWindow managers are free to decide if WM_TRANSIENT_FOR windows should be
1056N/Aiconified when the window they are transient for is. Clients displaying
1056N/AWM_TRANSIENT_FOR windows that have (or request to have) the window they are
1056N/Atransient for iconified do not need to request that the same operation be
1056N/Aperformed on the WM_TRANSIENT_FOR window; the window manager will change its
1056N/Astate if that is the policy it wishes to enforce.
1056N/AA set of top-level windows that should be treated from the user's point of view
1056N/Aas related (even though they may belong to a number of clients) should be
1056N/Alinked together using the window_group field of the WM_HINTS structure.
1056N/AOne of the windows (that is, the one the others point to) will be the group
1056N/Aleader and will carry the group as opposed to the individual properties. Window
1056N/Amanagers may treat the group leader differently from other windows in the
1056N/Agroup. For example, group leaders may have the full set of decorations, and
1056N/Aother group members may have a restricted set.
1056N/AIt is not necessary that the client ever map the group leader; it may be a
1056N/Awindow that exists solely as a placeholder.
1056N/AIt is up to the window manager to determine the policy for treating the windows
1056N/Ain a group. At present, there is no way for a client to request a group, as
1056N/Aopposed to an individual, operation.
1056N/AClient Responses to Window Manager Actions
1056N/AThe window manager performs a number of operations on client resources,
1056N/Aprimarily on their top-level windows. Clients must not try to fight this but
1056N/Amay elect to receive notification of the window manager's operations.
1056N/AClients must be aware that some window managers will reparent their top-level
1056N/Awindows so that a window that was created as a child of the root will be
1056N/Adisplayed as a child of some window belonging to the window manager. The
1056N/Aeffects that this reparenting will have on the client are as follows:
1056N/A ● The parent value returned by a QueryTree request will no longer be the
1056N/A value supplied to the CreateWindow request that created the reparented
1056N/A window. There should be no need for the client to be aware of the identity
1056N/A of the window to which the top-level window has been reparented. In
1056N/A particular, a client that wishes to create further top-level windows should
1056N/A continue to use the root as the parent for these new windows.
1056N/A ● The server will interpret the (x,y) coordinates in a ConfigureWindow
1056N/A request in the new parent's coordinate space. In fact, they usually will
1056N/A not be interpreted by the server because a reparenting window manager
1276N/A usually will have intercepted these operations (see Redirection of
1276N/A Operations ). Clients should use the root coordinate space for these
1276N/A requests (see Configuring the Window ).
1056N/A ● ConfigureWindow requests that name a specific sibling window may fail
1056N/A because the window named, which used to be a sibling, no longer is after
1276N/A the reparenting operation (see Configuring the Window ).
1056N/A ● The (x,y) coordinates returned by a GetGeometry request are in the parent's
1056N/A coordinate space and are thus not directly useful after a reparent
1056N/A ● A background of ParentRelative will have unpredictable results.
1056N/A ● A cursor of None will have unpredictable results.
1056N/AClients that want to be notified when they are reparented can select for
1056N/AStructureNotify events on their top-level window. They will receive a
1056N/AReparentNotify event if and when reparenting takes place. When a client
1056N/Awithdraws a top-level window, the window manager will reparent it back to the
1056N/Aroot window if the window had been reparented elsewhere.
1056N/AIf the window manager reparents a client's window, the reparented window will
1056N/Abe placed in the save-set of the parent window. This means that the reparented
1056N/Awindow will not be destroyed if the window manager terminates and will be
1056N/Aremapped if it was unmapped. Note that this applies to all client windows the
1056N/Awindow manager reparents, including transient windows and client icon windows.
1056N/AClients must be aware that some window managers will arrange for some client
1056N/Arequests to be intercepted and redirected. Redirected requests are not
1056N/Aexecuted; they result instead in events being sent to the window manager, which
1056N/Amay decide to do nothing, to alter the arguments, or to perform the request on
1056N/AThe possibility that a request may be redirected means that a client cannot
1056N/Aassume that any redirectable request is actually performed when the request is
1056N/Aissued or is actually performed at all. The requests that may be redirected are
1056N/AMapWindow, ConfigureWindow, and CirculateWindow.
1056N/A The following is incorrect because the MapWindow request may be intercepted
1056N/A and the PolyLine output made to an unmapped window:
1056N/A PolyLine A GC <point> <point> ...
1276N/A The client must wait for an Expose event before drawing in the window. ^
1056N/A This next example incorrectly assumes that the ConfigureWindow request is
1056N/A actually executed with the arguments supplied:
1056N/A ConfigureWindow width=N height=M
1056N/A <output assuming window is N by M>
1056N/A The client should select for StructureNotify on its window and monitor the
1056N/A window's size by tracking ConfigureNotify events.
1056N/A Clients must be especially careful when attempting to set the focus to a
1056N/A window that they have just mapped. This sequence may result in an X
1056N/A If the MapWindow request has been intercepted, the window will still be
1056N/A unmapped, causing the SetInputFocus request to generate the error. The
1056N/A solution to this problem is for clients to select for VisibilityChange on
1056N/A the window and to delay the issuance of the SetInputFocus request until
1056N/A they have received a VisibilityNotify event indicating that the window is
1056N/A This technique does not guarantee correct operation. The user may have
1056N/A iconified the window by the time the SetInputFocus request reaches the
1056N/A server, still causing an error. Or the window manager may decide to map the
1056N/A window into Iconic state, in which case the window will not be visible.
1056N/A This will delay the generation of the VisibilityNotify event indefinitely.
1056N/A Clients must be prepared to handle these cases.
1056N/AA window with the override-redirect bit set is immune from redirection, but the
1056N/Abit should be set on top-level windows only in cases where other windows should
1056N/Abe prevented from processing input while the override-redirect window is mapped
1276N/A(see Pop-up Windows ) and while responding to ResizeRequest events (see
1056N/AClients that have no non-Withdrawn top-level windows and that map an
1056N/Aoverride-redirect top-level window are taking over total responsibility for the
1056N/Astate of the system. It is their responsibility to:
1056N/A ● Prevent any preexisting window manager from interfering with their
1056N/A ● Restore the status quo exactly after they unmap the window so that any
1056N/A preexisting window manager does not get confused
1056N/AIn effect, clients of this kind are acting as temporary window managers. Doing
1056N/Aso is strongly discouraged because these clients will be unaware of the user
1056N/Ainterface policies the window manager is trying to maintain and because their
1056N/Auser interface behavior is likely to conflict with that of less demanding
1056N/AIf the window manager moves a top-level window without changing its size, the
1056N/Aclient will receive a synthetic ConfigureNotify event following the move that
1056N/Adescribes the new location in terms of the root coordinate space. Clients must
1056N/Anot respond to being moved by attempting to move themselves to a better
1056N/AAny real ConfigureNotify event on a top-level window implies that the window's
1056N/Aposition on the root may have changed, even though the event reports that the
1056N/Awindow's position in its parent is unchanged because the window may have been
1056N/Areparented. Note that the coordinates in the event will not, in this case, be
1056N/AThe window manager will send these events by using a SendEvent request with the
1276N/A┌───────────┬───────────────────┐
1276N/A├───────────┼───────────────────┤
1276N/A│destination│The client's window│
1276N/A├───────────┼───────────────────┤
1276N/A├───────────┼───────────────────┤
1276N/A│event-mask │StructureNotify │
1276N/A└───────────┴───────────────────┘
1056N/AThe client can elect to receive notification of being resized by selecting for
1056N/AStructureNotify events on its top-level windows. It will receive a
1056N/AConfigureNotify event. The size information in the event will be correct, but
1056N/Athe location will be in the parent window (which may not be the root).
1056N/AThe response of the client to being resized should be to accept the size it has
1056N/Abeen given and to do its best with it. Clients must not respond to being
1056N/Aresized by attempting to resize themselves to a better size. If the size is
1056N/Aimpossible to work with, clients are free to request to change to the Iconic
1056N/AA top-level window that is not Withdrawn will be in the Normal state if it is
1056N/Amapped and in the Iconic state if it is unmapped. This will be true even if the
1056N/Awindow has been reparented; the window manager will unmap the window as well as
1056N/Aits parent when switching to the Iconic state.
1056N/AThe client can elect to be notified of these state changes by selecting for
1056N/AStructureNotify events on the top-level window. It will receive a UnmapNotify
1056N/Aevent when it goes Iconic and a MapNotify event when it goes Normal.
1056N/AClients that wish to be notified of their colormaps being installed or
1056N/Auninstalled should select for ColormapNotify events on their top-level windows
1056N/Aand on any windows they have named in WM_COLORMAP_WINDOWS properties on their
1056N/Atop-level windows. They will receive ColormapNotify events with the new field
1056N/AFALSE when the colormap for that window is installed or uninstalled.
1056N/AClients can request notification that they have the input focus by selecting
1056N/Afor FocusChange events on their top-level windows; they will receive FocusIn
1056N/Aand FocusOut events. Clients that need to set the input focus to one of their
1056N/Asubwindows should not do so unless they have set WM_TAKE_FOCUS in their
1056N/AWM_PROTOCOLS property and have done one of the following:
1056N/A ● Set the input field of WM_HINTS to True and actually have the input focus
1056N/A in one of their top-level windows
1056N/A ● Set the input field of WM_HINTS to False and have received a suitable event
1276N/A as described in Input Focus.
1276N/A ● Have received a WM_TAKE_FOCUS message as described in Input Focus.
1056N/AClients should not warp the pointer in an attempt to transfer the focus; they
1056N/Ashould set the focus and leave the pointer alone. For further information, see
1056N/AOnce a client satisfies these conditions, it may transfer the focus to another
1056N/Aof its windows by using the SetInputFocus request, which is defined as follows:
1056N/Afocus: WINDOW or PointerRoot or None
1056N/Arevert-to: { Parent, PointerRoot, None }
1056N/Atime: TIMESTAMP or CurrentTime
1056N/A ● Clients that use a SetInputFocus request must set the time argument to
1056N/A the timestamp of the event that caused them to make the attempt. This
1056N/A cannot be a FocusIn event because they do not have timestamps. Clients
1056N/A may also acquire the focus without a corresponding EnterNotify event.
1056N/A Clients must not use CurrentTime for the time argument.
1056N/A ● Clients that use a SetInputFocus request to set the focus to one of
1056N/A their windows must set the revert-to field to Parent.
1056N/AThere is no way for clients to prevent themselves being sent ClientMessage
1056N/ATop-level windows with a WM_PROTOCOLS property may be sent ClientMessage events
1276N/Aspecific to the protocols named by the atoms in the property (see WM_PROTOCOLS
1276N/AProperty ). For all protocols, the ClientMessage events have the following:
1056N/A ● WM_PROTOCOLS as the type field
1056N/A ● The atom that names their protocol in the data[0] field
1056N/A ● A timestamp in their data[1] field
1056N/AThe remaining fields of the event, including the window field, are determined
1056N/AThese events will be sent by using a SendEvent request with the following
1276N/A┌───────────┬────────────────────────────┐
1276N/A├───────────┼────────────────────────────┤
1276N/A│destination│The client's window │
1276N/A├───────────┼────────────────────────────┤
1276N/A├───────────┼────────────────────────────┤
1276N/A├───────────┼────────────────────────────┤
1276N/A│event │As specified by the protocol│
1276N/A└───────────┴────────────────────────────┘
1056N/AClients, usually those with multiple top-level windows, whose server connection
1056N/Amust survive the deletion of some of their top-level windows, should include
1056N/Athe atom WM_DELETE_WINDOW in the WM_PROTOCOLS property on each such window.
1056N/AThey will receive a ClientMessage event as described above whose data[0] field
1056N/AClients receiving a WM_DELETE_WINDOW message should behave as if the user
1056N/Aselected "delete window" from a hypothetical menu. They should perform any
1056N/Aconfirmation dialog with the user and, if they decide to complete the deletion,
1276N/A ● Either change the window's state to Withdrawn (as described in Changing
1276N/A Window State ) or destroy the window.
1056N/A ● Destroy any internal state associated with the window.
1056N/AIf the user aborts the deletion during the confirmation dialog, the client
1056N/AClients are permitted to interact with the user and ask, for example, whether a
1056N/Afile associated with the window to be deleted should be saved or the window
1056N/Adeletion should be cancelled. Clients are not required to destroy the window
1056N/Aitself; the resource may be reused, but all associated state (for example,
1056N/Abacking store) should be released.
1056N/AIf the client aborts a destroy and the user then selects DELETE WINDOW again,
1056N/Athe window manager should start the WM_DELETE_WINDOW protocol again. Window
1056N/Amanagers should not use DestroyWindow requests on a window that has
1056N/AWM_DELETE_WINDOW in its WM_PROTOCOLS property.
1056N/AClients that choose not to include WM_DELETE_WINDOW in the WM_PROTOCOLS
1056N/Aproperty may be disconnected from the server if the user asks for one of the
1056N/Aclient's top-level windows to be deleted.
1056N/ANormal clients can use the redirection mechanism just as window managers do by
1056N/Aselecting for SubstructureRedirect events on a parent window or ResizeRedirect
1056N/Aevents on a window itself. However, at most, one client per window can select
1056N/Afor these events, and a convention is needed to avoid clashes.
1056N/A Clients (including window managers) should select for SubstructureRedirect
1056N/A and ResizeRedirect events only on windows that they own.
1056N/AIn particular, clients that need to take some special action if they are
1056N/Aresized can select for ResizeRedirect events on their top-level windows. They
1056N/Awill receive a ResizeRequest event if the window manager resizes their window,
1056N/Aand the resize will not actually take place. Clients are free to make what use
1056N/Athey like of the information that the window manager wants to change their
1056N/Asize, but they must configure the window to the width and height specified in
1056N/Athe event in a timely fashion. To ensure that the resize will actually happen
1056N/Aat this stage instead of being intercepted and executed by the window manager
1056N/A(and thus restarting the process), the client needs temporarily to set
1056N/Aoverride-redirect on the window.
1056N/A Clients receiving ResizeRequest events must respond by doing the following:
1056N/A ● Setting override-redirect on the window specified in the event
1056N/A ● Configuring the window specified in the event to the width and height
1056N/A specified in the event as soon as possible and before making any other
1056N/A ● Clearing override-redirect on the window specified in the event
1056N/AIf a window manager detects that a client is not obeying this convention, it is
1056N/Afree to take whatever measures it deems appropriate to deal with the client.
1056N/ACommunication with the Window Manager by Means of Selections
1056N/AFor each screen they manage, window managers will acquire ownership of a
1276N/Aselection named WM_Sn, where n is the screen number, as described in
1276N/ADiscriminated Names Window managers should comply with the conventions for
1276N/A"Manager Selections" described in Manager Selections. The intent is for clients
1276N/Ato be able to request a variety of information or services by issuing
1276N/Aconversion requests on this selection. Window managers should support
1276N/Aconversion of the following target on their manager selection:
1276N/A┌───────┬───────┬─────────────────────────────────────────────────────────────┐
1276N/A│Atom │Type │Data Received │
1276N/A├───────┼───────┼─────────────────────────────────────────────────────────────┤
1276N/A│ │ │Two integers, which are the major and minor release numbers │
1276N/A│VERSION│INTEGER│(respectively) of the ICCCM with which the window manager │
1276N/A│ │ │complies. For this version of the ICCCM, the numbers are 2 │
1276N/A├───────┴───────┴─────────────────────────────────────────────────────────────┤
1276N/A│^[a] As a special case, clients not wishing to implement a selection request │
1276N/A│may simply issue a GetSelectionOwner request on the appropriate WM_Sn │
1276N/A│selection. If this selection is owned, clients may assume that the window │
1276N/A│manager complies with ICCCM version 2.0 or later. │
1276N/A└─────────────────────────────────────────────────────────────────────────────┘
1056N/ASummary of Window Manager Property Types
1056N/AThe window manager properties are summarized in the following table (see also
1056N/Asection 14.1 of Xlib - C Language X Interface).
1276N/A┌───────────────────┬─────────────┬──────┬────────────────────────────┐
1276N/A│Name │Type │Format│See Section │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_CLASS │STRING │8 │WM_CLASS Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_CLIENT_MACHINE │TEXT │ │WM_CLIENT_MACHINE Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_COLORMAP_WINDOWS│WINDOW │32 │WM_COLORMAP_WINDOWS Property│
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_HINTS │WM_HINTS │32 │WM_HINTS Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_ICON_NAME │TEXT │ │WM_ICON_NAME Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_ICON_SIZE │WM_ICON_SIZE │32 │WM_ICON_SIZE Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_NAME │TEXT │ │WM_NAME Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_NORMAL_HINTS │WM_SIZE_HINTS│32 │WM_NORMAL_HINTS Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_PROTOCOLS │ATOM │32 │WM_PROTOCOLS Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_STATE │WM_STATE │32 │WM_STATE Property │
1276N/A├───────────────────┼─────────────┼──────┼────────────────────────────┤
1276N/A│WM_TRANSIENT_FOR │WINDOW │32 │WM_TRANSIENT_FOR Property │
1276N/A└───────────────────┴─────────────┴──────┴────────────────────────────┘
1056N/A^[7] This obsolete protocol was described in the July 27, 1988, draft of the
1056N/AICCCM. Windows using it can also be detected because their WM_HINTS properties
1056N/Aare 4 bytes longer than expected. Window managers are free to support clients
1056N/Ausing the obsolete protocol in a backwards compatibility mode.
1056N/A^[8] Earlier versions of these conventions prohibited clients from reading the
1056N/AWM_STATE property. Clients operating under the earlier conventions used the
1056N/Atechnique of tracking ReparentNotify events to wait for the top-level window to
1056N/Abe reparented back to the root window. This is still a valid technique;
1056N/Ahowever, it works only for reparenting window managers, and the WM_STATE
1056N/Atechnique is to be preferred.
1056N/A^[9] The type field of the ClientMessage event (called the message_type field
1056N/Aby Xlib) should not be confused with the code field of the event itself, which
1056N/Awill have the value 33 ( ClientMessage).
1056N/A^[10] This is true even if the client set the backing-store attribute to
1056N/AAlways. The backing-store attribute is a only a hint, and the server may stop
1056N/Amaintaining backing store contents at any time.
1056N/AChapter 5. Session Management and Additional Inter-Client Exchanges
1056N/AClient Support for Session Management
1056N/AWindow Manager Support for Session Management
1056N/ASupport for ICE Client Rendezvous
1056N/AThis section contains some conventions for clients that participate in session
1056N/Amanagement. See X Session Management Protocol for further details. Clients that
1056N/Ado not support this protocol cannot expect their window state (
e.g., WM_STATE,
1056N/Aposition, size, and stacking order) to be preserved across sessions.
1056N/AClient Support for Session Management
1056N/AEach session participant will obtain a unique client identifier (client-ID)
1056N/Afrom the session manager. The client must identify one top-level window as the
1056N/A"client leader." This window must be created by the client. It may be in any
1056N/Astate, including the Withdrawn state. The client leader window must have a
1056N/ASM_CLIENT_ID property, which contains the client-ID obtained from the session
1056N/Amanagement protocol. That property must:
1056N/A ● Contain the client-ID as a string of XPCS characters encoded using ISO
1056N/AAll top-level, nontransient windows created by a client on the same display as
1056N/Athe client leader must have a WM_CLIENT_LEADER property. This property contains
1056N/Aa window ID that identifies the client leader window. The client leader window
1056N/Amust have a WM_CLIENT_LEADER property containing its own window ID (
i.e., the
1056N/Aclient leader window is pointing to itself). Transient windows need not have a
1056N/AWM_CLIENT_LEADER property if the client leader can be determined using the
1056N/Ainformation in the WM_TRANSIENT_FOR property. The WM_CLIENT_LEADER property
1056N/A ● Contain the window ID of the client leader window
1056N/AA client must withdraw all of its top-level windows on the same display before
1056N/Amodifiying either the WM_CLIENT_LEADER or the SM_CLIENT_ID property of its
1056N/AIt is necessary that other clients be able to uniquely identify a window
1056N/A(across sessions) among all windows related to the same client-ID. For example,
1056N/Aa window manager can require this unique ID to restore geometry information
1056N/Afrom a previous session, or a workspace manager could use it to restore
1056N/Ainformation about which windows are in which workspace. A client may optionally
1056N/Aprovide a WM_WINDOW_ROLE property to uniquely identify a window within the
1056N/Ascope specified above. The combination of SM_CLIENT_ID and WM_WINDOW_ROLE can
1056N/Abe used by other clients to uniquely identify a window across sessions.
1056N/AIf the WM_WINDOW_ROLE property is not specified on a top-level window, a client
1056N/Athat needs to uniquely identify that window will try to use instead the values
1056N/Aof WM_CLASS and WM_NAME. If a client has multiple windows with identical
1056N/AWM_CLASS and WM_NAME properties, then it should provide a WM_WINDOW_ROLE
1056N/AThe client must set the WM_WINDOW_ROLE property to a string that uniquely
1056N/Aidentifies that window among all windows that have the same client leader
1056N/A ● Contain a string restricted to the XPCS characters, encoded in ISO 8859-1
1056N/AWindow Manager Support for Session Management
1056N/AA window manager supporting session management must register with the session
1056N/Amanager and obtain its own client-ID. The window manager should save and
1056N/Arestore information such as the WM_STATE, the layout of windows on the screen,
1056N/Aand their stacking order for every client window that has a valid SM_CLIENT_ID
1056N/Aproperty (on itself, or on the window named by WM_CLIENT_LEADER) and that can
1056N/Abe uniquely identified. Clients are allowed to change this state during the
1056N/Afirst phase of the session checkpoint process. Therefore, window managers
1056N/Ashould request a second checkpoint phase and save clients' state only during
1056N/ASupport for ICE Client Rendezvous
1056N/AThe Inter-Client Exchange protocol (ICE) defined as of X11R6 specifies a
1056N/Ageneric communication framework, independent of the X server, for data exchange
1056N/Abetween arbitrary clients. ICE also defines a protocol for any two ICE clients
1056N/Awho also have X connections to the same X server to locate (rendezvous with)
1056N/AThis protocol, called the "ICE X Rendezvous" protocol, is defined in the ICE
1056N/Aspecification, Appendix B, and uses the property ICE_PROTOCOLS plus
1056N/AClientMessage events. Refer to that specification for complete details.
1056N/AChapter 6. Manipulation of Shared Resources
1056N/AX Version 11 permits clients to manipulate a number of shared resources, for
1056N/Aexample, the input focus, the pointer, and colormaps. Conventions are required
1056N/Aso that clients share resources in an orderly fashion.
1056N/AClients that explicitly set the input focus must observe one of two modes:
1056N/A ● Locally active clients should set the input focus to one of their
1056N/A windows only when it is already in one of their windows or when they
1056N/A receive a WM_TAKE_FOCUS message. They should set the input field of the
1056N/A WM_HINTS structure to True.
1056N/A ● Globally active clients should set the input focus to one of their
1056N/A windows only when they receive a button event and a passive-grabbed key
1056N/A event, or when they receive a WM_TAKE_FOCUS message. They should set
1056N/A the input field of the WM_HINTS structure to False.
1056N/A ● In addition, clients should use the timestamp of the event that caused
1056N/A them to attempt to set the input focus as the time field on the
1056N/A SetInputFocus request, not CurrentTime.
1056N/AIn general, clients should not warp the pointer. Window managers, however, may
1056N/Ado so (for example, to maintain the invariant that the pointer is always in the
1056N/Awindow with the input focus). Other window managers may want to preserve the
1056N/Aillusion that the user is in sole control of the pointer.
1056N/A ● Clients should not warp the pointer.
1056N/A ● Clients that insist on warping the pointer should do so only with the
1056N/A src-window argument of the WarpPointer request set to one of their
1056N/AA client's attempt to establish a button or a key grab on a window will fail if
1056N/Asome other client has already established a conflicting grab on the same
1056N/Awindow. The grabs, therefore, are shared resources, and their use requires
1056N/AIn conformance with the principle that clients should behave, as far as
1056N/Apossible, when a window manager is running as they would when it is not, a
1056N/Aclient that has the input focus may assume that it can receive all the
1056N/A Window managers should ensure that they provide some mechanism for their
1056N/A clients to receive events from all keys and all buttons, except for events
1056N/A involving keys whose KeySyms are registered as being for window management
1056N/A functions (for example, a hypothetical WINDOW KeySym).
1056N/AIn other words, window managers must provide some mechanism by which a client
1056N/Acan receive events from every key and button (regardless of modifiers) unless
1056N/Aand until the X Consortium registers some KeySyms as being reserved for window
1056N/Amanagement functions. Currently, no KeySyms are registered for window
1056N/AEven so, clients are advised to allow the key and button combinations used to
1056N/Aelicit program actions to be modified, because some window managers may choose
1056N/Anot to observe this convention or may not provide a convenient method for the
1056N/Auser to transmit events from some keys.
1056N/A Clients should establish button and key grabs only on windows that they
1056N/AIn particular, this convention means that a window manager that wishes to
1056N/Aestablish a grab over the client's top-level window should either establish the
1056N/Agrab on the root or reparent the window and establish the grab on a proper
1056N/Aancestor. In some cases, a window manager may want to consume the event
1056N/Areceived, placing the window in a state where a subsequent such event will go
1056N/Ato the client. Examples are:
1056N/A ● Clicking in a window to set focus with the click not being offered to the
1056N/A ● Clicking in a buried window to raise it, again, with the click not offered
1056N/AMore typically, a window manager should add to, rather than replace, the
1056N/Aclient's semantics for key+button combinations by allowing the event to be used
1056N/Aby the client after the window manager is done with it. To ensure this, the
1056N/Awindow manager should establish the grab on the parent by using the following:
1056N/AThen, the window manager should release the grab by using an AllowEvents
1056N/Arequest with the following specified:
1056N/AIn this way, the client will receive the events as if they had not been
1056N/AObviously, these conventions place some constraints on possible user interface
1056N/Apolicies. There is a trade-off here between freedom for window managers to
1056N/Aimplement their user interface policies and freedom for clients to implement
1056N/Atheirs. The dilemma is resolved by:
1056N/A ● Allowing window managers to decide if and when a client will receive an
1056N/A event from any given key or button
1056N/A ● Placing a requirement on the window manager to provide some mechanism,
1056N/A perhaps a "Quote" key, by which the user can send an event from any key or
1276N/AColormaps prescribes conventions for clients to communicate with the window
1276N/Amanager about their colormap needs. If your clients are DirectColor type
1276N/Aapplications, you should consult section 14.3 of Xlib - C Language X Interface
1276N/Afor conventions connected with sharing standard colormaps. They should look for
1276N/Aand create the properties described there on the root window of the appropriate
1056N/AThe contents of the RGB_COLOR_MAP type property are as follows:
1276N/A┌──────────┬────────┬────────────────────────────────┐
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A│colormap │COLORMAP│ID of the colormap described │
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A│red_max │CARD32 │Values for pixel calculations │
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A│visual_id │VISUALID│Visual to which colormap belongs│
1276N/A├──────────┼────────┼────────────────────────────────┤
1276N/A│kill_id │CARD32 │ID for destroying the resources │
1276N/A└──────────┴────────┴────────────────────────────────┘
1056N/AWhen deleting or replacing an RGB_COLOR_MAP, it is not sufficient to delete the
1056N/Aproperty; it is important to free the associated colormap resources as well. If
1056N/Akill_id is greater than one, the resources should be freed by issuing a
1056N/AKillClient request with kill_id as the argument. If kill_id is one, the
1056N/Aresources should be freed by issuing a FreeColormap request with colormap as
1056N/Athe colormap argument. If kill_id is zero, no attempt should be made to free
1056N/Athe resources. A client that creates an RGB_COLOR_MAP for which the colormap
1056N/Aresource is created specifically for this purpose should set kill_id to one
1056N/A(and can create more than one such standard colormap using a single
1056N/Aconnection). A client that creates an RGB_COLOR_MAP for which the colormap
1056N/Aresource is shared in some way (for example, is the default colormap for the
1056N/Aroot window) should create an arbitrary resource and use its resource ID for
1056N/Akill_id (and should create no other standard colormaps on the connection).
1056N/A If an RGB_COLOR_MAP property is too short to contain the visual_id field,
1056N/A it can be assumed that the visual_id is the root visual of the appropriate
1056N/A screen. If an RGB_COLOR_MAP property is too short to contain the kill_id
1056N/A field, a value of zero can be assumed.
1056N/ADuring the connection handshake, the server informs the client of the default
1056N/Acolormap for each screen. This is a colormap for the root visual, and clients
1056N/Acan use it to improve the extent of colormap sharing if they use the root
1056N/AThe X server contains a table (which is read by GetKeyboardMapping requests)
1056N/Athat describes the set of symbols appearing on the corresponding key for each
1056N/Akeycode generated by the server. This table does not affect the server's
1056N/Aoperations in any way; it is simply a database used by clients that attempt to
1056N/Aunderstand the keycodes they receive. Nevertheless, it is a shared resource and
1056N/AIt is possible for clients to modify this table by using a
1056N/AChangeKeyboardMapping request. In general, clients should not do this. In
1056N/Aparticular, this is not the way in which clients should implement key bindings
1056N/Aor key remapping. The conversion between a sequence of keycodes received from
1056N/Athe server and a string in a particular encoding is a private matter for each
1056N/Aclient (as it must be in a world where applications may be using different
1056N/Aencodings to support different languages and fonts). See the Xlib reference
1056N/Amanual for converting keyboard events to text.
1056N/AThe only valid reason for using a ChangeKeyboardMapping request is when the
1056N/Asymbols written on the keys have changed as, for example, when a Dvorak key
1056N/Aconversion kit or a set of APL keycaps has been installed. Of course, a client
1056N/Amay have to take the change to the keycap on trust.
1056N/AThe following illustrates a permissible interaction between a client and a
1056N/A ● "You just started me on a server without a Pause key. Please choose a key
1056N/A to be the Pause key and press it now."
1056N/A ● Presses the Scroll Lock key
1056N/A ● "Adding Pause to the symbols on the Scroll Lock key: Confirm or Abort."
1056N/A ● Uses a ChangeKeyboardMapping request to add Pause to the keycode that
1056N/A already contains Scroll Lock and issues this request, "Please paint Pause
1056N/A on the Scroll Lock key." Clients should not use ChangeKeyboardMapping
1056N/AIf a client succeeds in changing the keyboard mapping table, all clients will
1056N/Areceive MappingNotify (request==Keyboard) events. There is no mechanism to
1056N/Aavoid receiving these events.
1056N/A Clients receiving MappingNotify (request==Keyboard) events should update
1056N/A any internal keycode translation tables they are using.
1056N/AX Version 11 supports 8 modifier bits of which 3 are preassigned to Shift,
1056N/ALock, and Control. Each modifier bit is controlled by the state of a set of
1056N/Akeys, and these sets are specified in a table accessed by GetModifierMapping
1056N/Aand SetModifierMapping requests. This table is a shared resource and requires
1056N/AA client that needs to use one of the preassigned modifiers should assume that
1056N/Athe modifier table has been set up correctly to control these modifiers. The
1056N/ALock modifier should be interpreted as Caps Lock or Shift Lock according as the
1056N/Akeycodes in its controlling set include XK_Caps_Lock or XK_Shift_Lock.
1056N/A Clients should determine the meaning of a modifier bit from the KeySyms
1056N/AA client that needs to use an extra modifier (for example, META) should do the
1056N/A ● Scan the existing modifier mappings. If it finds a modifier that contains a
1056N/A keycode whose set of KeySyms includes XK_Meta_L or XK_Meta_R, it should use
1056N/A ● If there is no existing modifier controlled by XK_Meta_L or XK_Meta_R, it
1056N/A should select an unused modifier bit (one with an empty controlling set)
1056N/A ○ If there is a keycode with XL_Meta_L in its set of KeySyms, add that
1056N/A keycode to the set for the chosen modifier.
1056N/A ○ If there is a keycode with XL_Meta_R in its set of KeySyms, add that
1056N/A keycode to the set for the chosen modifier.
1056N/A ○ If the controlling set is still empty, interact with the user to select
1056N/A one or more keys to be META.
1056N/A ● If there are no unused modifier bits, ask the user to take corrective
1056N/A ○ Clients needing a modifier not currently in use should assign
1056N/A keycodes carrying suitable KeySyms to an unused modifier bit.
1056N/A ○ Clients assigning their own modifier bits should ask the user
1056N/A politely to remove his or her hands from the key in question if
1056N/A their SetModifierMapping request returns a Busy status.
1056N/AThere is no good solution to the problem of reclaiming assignments to the five
1056N/Anonpreassigned modifiers when they are no longer being used.
1056N/A The user must use xmodmap or some other utility to deassign obsolete
1056N/AWhen a client succeeds in performing a SetModifierMapping request, all clients
1056N/Awill receive MappingNotify (request==Modifier) events. There is no mechanism
1056N/Afor preventing these events from being received. A client that uses one of the
1056N/Anonpreassigned modifiers that receives one of these events should do a
1056N/AGetModifierMapping request to discover the new mapping, and if the modifier it
1056N/Ais using has been cleared, it should reinstall the modifier.
1056N/ANote that a GrabServer request must be used to make the GetModifierMapping and
1056N/ASetModifierMapping pair in these transactions atomic.
1056N/AChapter 7. Device Color Characterization
1056N/AXYZ <-> RGB Conversion Matrices
1056N/AIntensity (dA RGB Value Conversion
1056N/AThe X protocol provides explicit Red, Green, and Blue (RGB) values, which are
1056N/Aused to directly drive a monitor, and color names. RGB values provide a
1056N/Amechanism for accessing the full capabilities of the display device, but at the
1056N/Aexpense of having the color perceived by the user remain unknowable through the
1056N/Aprotocol. Color names were originally designed to provide access to a
1056N/Adevice-independent color database by having the server vendor tune the
1056N/Adefinitions of the colors in that textual database. Unfortunately, this still
1056N/Adoes not provide the client any way of using an existing device-independent
1056N/Acolor, nor for the client to get device-independent color information back
1056N/Aabout colors that it has selected.
1056N/AFurthermore, the client must be able to discover which set of colors are
1056N/Adisplayable by the device (the device gamut), both to allow colors to be
1056N/Aintelligently modified to fit within the device capabilities (gamut
1056N/Acompression) and to enable the user interface to display a representation of
1056N/Athe reachable color space to the user (gamut display).
1056N/ATherefore, a system is needed that will provide full access to
1056N/Adevice-independent color spaces for X clients. This system should use a
1056N/Astandard mechanism for naming the colors, be able to provide names for existing
1056N/Acolors, and provide means by which unreachable colors can be modified to fall
1056N/AWe are fortunate in this area to have a seminal work, the 1931 CIE color
1056N/Astandard, which is nearly universally agreed upon as adequate for describing
1056N/Acolors on CRT devices. This standard uses a tri-stimulus model called CIE XYZ
1056N/Ain which each perceivable color is specified as a triplet of numbers. Other
1056N/Aappropriate device-independent color models do exist, but most of them are
1056N/Adirectly traceable back to this original work.
1056N/AX device color characterization provides device-independent color spaces to X
1056N/Aclients. It does this by providing the barest possible amount of information to
1056N/Athe client that allows the client to construct a mapping between CIE XYZ and
1056N/Athe regular X RGB color descriptions.
1056N/ADevice color characterization is defined by the name and contents of two window
1056N/Aproperties that, together, permit converting between CIE XYZ space and linear
1056N/ARGB device space (such as standard CRTs). Linear RGB devices require just two
1056N/Apieces of information to completely characterize them:
1056N/A ● A 3 x 3 matrix M and its inverse M^-1, which convert between XYZ and RGB
1056N/A intensity (RGB[intensity]):
1056N/A XYZ = M^-1 x RGB[intensity]
1056N/A ● A way of mapping between RGB intensity and RGB protocol value. XDCCC
1056N/A supports three mechanisms which will be outlined later.
1056N/AIf other device types are eventually necessary, additional properties will be
1056N/AXYZ <-> RGB Conversion Matrices
1056N/ABecause of the limited dynamic range of both XYZ and RGB intensity, these
1056N/Amatrices will be encoded using a fixed-point representation of a 32-bit two's
1056N/Acomplement number scaled by 2^27, giving a range of -16 to 16 - Ε, where Ε = 2^
1056N/AThese matrices will be packed into an 18-element list of 32-bit values, XYZ ->
1056N/ARGB matrix first, in row major order and stored in the
1056N/AXDCCC_LINEAR_RGB_MATRICES properties (format = 32) on the root window of each
1056N/Ascreen, using values appropriate for that screen.
1056N/AThis will be encoded as shown in the following table:
1276N/A┌─────────┬─────┬────────────────────────────────────────────────┐
1276N/A├─────────┼─────┼────────────────────────────────────────────────┤
1276N/A│M[0,0] │INT32│Interpreted as a fixed-point number -16 ≤ x < 16│
1276N/A├─────────┼─────┼────────────────────────────────────────────────┤
1276N/A├─────────┼─────┼────────────────────────────────────────────────┤
1276N/A├─────────┼─────┼────────────────────────────────────────────────┤
1276N/A├─────────┼─────┼────────────────────────────────────────────────┤
1276N/A├─────────┼─────┼────────────────────────────────────────────────┤
1276N/A├─────────┼─────┼────────────────────────────────────────────────┤
1276N/A├─────────┼─────┼────────────────────────────────────────────────┤
1276N/A└─────────┴─────┴────────────────────────────────────────────────┘
1056N/AIntensity (dA RGB Value Conversion
1056N/AXDCCC provides two representations for describing the conversion between RGB
1056N/Aintensity and the actual X protocol RGB values:
1056N/AIn both cases, the relevant data will be stored in the
1056N/AXDCCC_LINEAR_RGB_CORRECTION properties on the root window of each screen, using
1056N/Avalues appropriate for that screen, in whatever format provides adequate
1056N/Aresolution. Each property can consist of multiple entries concatenated
1056N/Atogether, if different visuals for the screen require different conversion
1056N/Adata. An entry with a VisualID of 0 specifies data for all visuals of the
1056N/Ascreen that are not otherwise explicitly listed.
1056N/Athe RGB values in strictly increasing order. When converting, the client must
1056N/Alinearly interpolate between adjacent entries in the table to compute the
1056N/Adesired value. This allows the server to perform gamma correction itself and
1056N/Aencode that fact in a short two-element correction table. The intensity will be
1056N/Aencoded as an unsigned number to be interpreted as a value between 0 and 1
1056N/A(inclusive). The precision of this value will depend on the format of the
1056N/Aproperty in which it is stored (8, 16, or 32 bits). For 16-bit and 32-bit
1056N/Aformats, the RGB value will simply be the value stored in the property. When
1056N/Astored in 8-bit format, the RGB value can be computed from the value in the
1056N/ARGB sub value ~ = ~ { Property ~ Value ~ times ~ 65535 } over 255
1056N/ABecause the three electron guns in the device may not be exactly alike in
1056N/Aresponse characteristics, it is necessary to allow for three separate tables,
1056N/Aone each for red, green, and blue. Therefore, each table will be preceded by
1056N/Athe number of entries in that table, and the set of tables will be preceded by
1056N/Athe number of tables. When three tables are provided, they will be in red,
1056N/AThis will be encoded as shown in the following table:
1056N/AXDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 0 Correction
1276N/A┌─────────┬────┬──────────────────────────────────────────────────────────────┐
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│VisualID0│CARD│Most significant portion of VisualID │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│VisualID1│CARD│Exists if and only if the property format is 8 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│VisualID2│CARD│Exists if and only if the property format is 8 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│VisualID3│CARD│Least significant portion, exists if and only if the property │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│type │CARD│0 for this type of correction │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│count │CARD│Number of tables following (either 1 or 3) │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│length │CARD│Number of pairs -1 following in this table │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│value │CARD│X Protocol RBG value │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│intensity│CARD│Interpret as number 0 ≤ intensity ≤ 1 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│lengthg │CARD│Number of pairs -1 following in this table (if and only if │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│value │CARD│X Protocol RBG value │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│intensity│CARD│Interpret as a number 0 ≤ intensity ≤ 1 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│lengthb │CARD│Number of pairs -1 following in this table (if and only if │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│value │CARD│X Protocol RBG value │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│intensity│CARD│Interpret as a number 0 ≤ intensity ≤ 1 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A└─────────┴────┴──────────────────────────────────────────────────────────────┘
1056N/AThe VisualID is stored in 4, 2, or 1 pieces, depending on whether the property
1056N/Aformat is 8, 16, or 32, respectively. The VisualID is always stored most
1056N/Asignificant piece first. Note that the length fields are stored as one less
1056N/Athan the actual length, so 256 entries can be stored in format 8.
1056N/AThe second representation is a simple array of intensities for a linear subset
1056N/Aof RGB values. The expected size of this table is the bits-per-rgb-value of the
1056N/Ascreen, but it can be any length. This is similar to the first mechanism,
1056N/Aexcept that the RGB value numbers are implicitly defined by the index in the
1056N/A RGB sub value ~ = ~ { Array ~ Index ~ times ~ 65535 } over { Array ~ Size ~
1056N/AWhen converting, the client may linearly interpolate between entries in this
1056N/Atable. The intensity values will be encoded just as in the first
1056N/AThis will be encoded as shown in the following table:
1056N/AXDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 1 Correction
1276N/A┌─────────┬────┬──────────────────────────────────────────────────────────────┐
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│VisualID0│CARD│Most significant portion of VisualID │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│VisualID1│CARD│Exists if and only if the property format is 8 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│VisualID2│CARD│Exists if and only if the property format is 8 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│VisualID3│CARD│Least significant portion, exists if and only if the property │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│type │CARD│1 for this type of correction │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│count │CARD│Number of tables following (either 1 or 3) │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│length │CARD│Number of pairs -1 following in this table │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│intensity│CARD│Interpret as number 0 ≤ intensity ≤ 1 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│lengthg │CARD│Number of pairs -1 following in this table (if and only if │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│intensity│CARD│Interpret as a number 0 ≤ intensity ≤ 1 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│lengthb │CARD│Number of pairs -1 following in this table (if and only if │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A│intensity│CARD│Interpret as a number 0 ≤ intensity ≤ 1 │
1276N/A├─────────┼────┼──────────────────────────────────────────────────────────────┤
1276N/A└─────────┴────┴──────────────────────────────────────────────────────────────┘
1056N/AThis document provides the protocol-level specification of the minimal
1056N/Aconventions needed to ensure that X Version 11 clients can interoperate
1056N/Aproperly. This document specifies interoperability conventions only for the X
1056N/AVersion 11 protocol. Clients should be aware of other protocols that should be
1056N/Aused for better interoperation in the X environment. The reader is referred to
1056N/AX Session Management Protocol for information on session management, and to
1056N/AInter-Client Exchange Protocol for information on general-purpose communication
1056N/AThe X Consortium maintains a registry of certain X-related items, to aid in
1056N/Aavoiding conflicts and in sharing of such items. Readers are encouraged to use
1056N/Athe registry. The classes of items kept in the registry that are relevant to
1056N/Athe ICCCM include property names, property types, selection names, selection
1056N/Atargets, WM_PROTOCOLS protocols, ClientMessage types, and application classes.
1056N/ARequests to register items, or questions about registration, should be
1056N/AElectronic mail will be acknowledged upon receipt. Please allow up to 4 weeks
1056N/Afor a formal response to registration and inquiries.
1056N/AThe registry is published as part of the X software distribution from the
X.Org 1056N/AFoundation. All registered items must have the postal address of someone
1056N/Aresponsible for the item or a reference to a document describing the item and
1056N/Athe postal address of where to write to obtain the document.
1056N/AAppendix A. Revision History
1056N/APublic Review Draft, December 1993
1056N/AThis appendix describes the revision history of this document and summarizes
1056N/Athe incompatibilities between this and earlier versions.
1056N/AThe February 25, 1988, draft that was distributed as part of X Version 11,
1056N/ARelease 2, was clearly labeled as such, and many areas were explicitly labeled
1056N/Aas liable to change. Nevertheless, in the revision work done since then, we
1056N/Ahave been very careful not to introduce gratuitous incompatibility. As far as
1056N/Apossible, we have tried to ensure that clients obeying the conventions in the
1056N/AX11R2 draft would still work.
1056N/AThe Consortium review was based on a draft dated July 27, 1988. This draft
1056N/Aincluded several areas in which incompatibilities with the X11R2 draft were
1056N/A ● The use of property None in ConvertSelection requests is no longer allowed.
1056N/A Owners that receive them are free to use the target atom as the property to
1056N/A respond with, which will work in most cases.
1056N/A ● The protocol for INCREMENTAL type properties as selection replies has
1056N/A changed, and the name has been changed to INCR. Selection requestors are
1056N/A free to implement the earlier protocol if they receive properties of type
1056N/A ● The protocol for INDIRECT type properties as selection replies has changed,
1056N/A and the name has been changed to MULTIPLE. Selection requestors are free to
1056N/A implement the earlier protocol if they receive properties of type INDIRECT.
1056N/A ● The protocol for the special CLIPBOARD client has changed. The earlier
1056N/A protocol is subject to race conditions and should not be used.
1056N/A values that are still valid are unchanged. Window managers should treat the
1056N/A ● The methods an application uses to change the state of its top-level window
1056N/A have changed but in such a way that cases that used to work will still
1056N/A ● The x, y, width, and height fields have been removed from the
1056N/A WM_NORMAL_HINTS property and replaced by pad fields. Values set into these
1056N/A fields will be ignored. The position and size of the window should be set
1056N/A by setting the appropriate window attributes.
1056N/A ● A pair of base fields and a win_gravity field have been added to the
1056N/A WM_NORMAL_HINTS property. Window managers will assume values for these
1056N/A fields if the client sets a short property.
1056N/AThe Consortium review resulted in several incompatible changes. These changes
1056N/Awere included in drafts that were distributed for public review during the
1056N/A ● The messages field of the WM_HINTS property was found to be unwieldy and
1056N/A difficult to evolve. It has been replaced by the WM_PROTOCOLS property, but
1056N/A clients that use the earlier mechanism can be detected because they set the
1056N/A messages bit in the flags field of the WM_HINTS property, and window
1056N/A managers can provide a backwards compatibility mode.
1056N/A ● The mechanism described in the earlier draft by which clients installed
1056N/A their own subwindow colormaps could not be made to work reliably and
1056N/A mandated some features of the look and feel. It has been replaced by the
1056N/A WM_COLORMAP_WINDOWS property. Clients that use the earlier mechanism can be
1056N/A detected by the WM_COLORMAPS property they set on their top-level window,
1056N/A but providing a reliable backwards compatibility mode is not possible.
1056N/A ● The recommendations for window manager treatment of top-level window
1056N/A borders have been changed as those in the earlier draft produced problems
1056N/A with Visibility events. For nonwindow manager clients, there is no
1056N/A ● The pseudoroot facility in the earlier draft has been removed. Although it
1056N/A has been successfully implemented, it turns out to be inadequate to support
1056N/A the uses envisaged. An extension will be required to support these uses
1056N/A fully, and it was felt that the maximum freedom should be left to the
1056N/A designers of the extension. In general, the previous mechanism was
1056N/A invisible to clients and no incompatibility should result.
1056N/A ● The addition of the WM_DELETE_WINDOW protocol (which prevents the danger
1056N/A that multi-window clients may be terminated unexpectedly) has meant some
1056N/A changes in the WM_SAVE_YOURSELF protocol, to ensure that the two protocols
1056N/A are orthogonal. Clients using the earlier protocol can be detected (see
1056N/A WM_PROTOCOLS above) and supported in a backwards compatibility mode.
1056N/A ● The conventions in Section 14.3.1. of Xlib - C Language X Interface
1056N/A regarding properties of type RGB_COLOR_MAP have been changed, but clients
1056N/A that use the earlier conventions can be detected because their properties
1056N/A are 4 bytes shorter. These clients will work correctly if the server
1056N/A supports only a single Visual or if they use only the Visual of the root.
1056N/A These are the only cases in which they would have worked, anyway.
1056N/AThe public review resulted in a set of mostly editorial changes. The changes in
1056N/Aversion 1.0 that introduced some degree of incompatibility with the earlier
1276N/A ● A new section ( Grabs ) was added covering the window manager's use of
1276N/A Grabs. The restrictions it imposes should affect only window managers.
1056N/A ● The TARGETS selection target has been clarified, and it may be necessary
1056N/A for clients to add some entries to their replies.
1056N/A ● A selection owner using INCR transfer should no longer replace targets in a
1056N/A MULTIPLE property with the atom INCR.
1056N/A ● The contents of the ClientMessage event sent by a client to iconify itself
1056N/A has been clarified, but there should be no incompatibility because the
1056N/A earlier contents would not in fact have worked.
1056N/A ● The border-width in synthetic ConfigureNotify events is now specified, but
1056N/A this should not cause any incompatibility.
1056N/A ● Clients are now asked to set a border-width on all ConfigureWindow
1056N/A ● Window manager properties on icon windows now will be ignored, but there
1056N/A should be no incompatibility because there was no specification that they
1056N/A ● The ordering of real and synthetic ConfigureNotify events is now specified,
1056N/A but any incompatibility should affect only window managers.
1056N/A ● The semantics of WM_SAVE_YOURSELF have been clarified and restricted to be
1056N/A a checkpoint operation only. Clients that were using it as part of a
1056N/A shutdown sequence may need to be modified, especially if they were
1056N/A interacting with the user during the shutdown.
1056N/A ● A kill_id field has been added to RGB_COLOR_MAP properties. Clients using
1056N/A earlier conventions can be detected by the size of their RGB_COLOR_MAP
1056N/A properties, and the cases that would have worked will still work.
1056N/AVersion 1.1 was released with X11R5 in September 1991. In addition to some
1056N/Aminor editorial changes, there were a few semantic changes since Version 1.0:
1056N/A ● The section on Device Color Characterization was added.
1056N/A ● The meaning of the NULL property type was clarified.
1056N/A ● Appropriate references to Compound Text were added.
1056N/APublic Review Draft, December 1993
1056N/AThe following changes have been made in preparing the public review draft for
1056N/A ● [P01] Addition of advice to clients on how to keep track of a top-level
1056N/A window's absolute position on the screen.
1056N/A ● [P03] A technique for clients to detect when it is safe to reuse a
1056N/A top-level window has been added.
1276N/A ● [P06] Colormaps , on colormaps, has been rewritten. A new feature that
1276N/A allows clients to install their own colormaps has also been added.
1056N/A ● [P08] The LENGTH target has been deprecated.
1056N/A ● [P11] The manager selections facility was added.
1056N/A ● [P17] The definition of the aspect ratio fields of the WM_NORMAL_HINTS
1056N/A property has been changed to include the base size.
1056N/A ● [P19] StaticGravity has been added to the list of values allowed for the
1056N/A win_gravity field of the WM_HINTS property. The meaning of the
1056N/A CenterGravity value has been clarified.
1056N/A ● [P20] A means for clients to query the ICCCM compliance level of the window
1056N/A ● [P22] The definition of the MULTIPLE selection target has been clarified.
1056N/A ● [P25] A definition of "top-level window" has been added. The WM_STATE
1056N/A property has been defined and exposed to clients.
1056N/A ● [P26] The definition of window states has been clarified and the wording
1056N/A regarding window state changes has been made more consistent.
1056N/A ● [P27] Clarified the rules governing when window managers are required to
1056N/A send synthetic ConfigureNotify events.
1056N/A ● [P28] Added a recommended technique for setting the input focus to a window
1056N/A ● [P29] The required lifetime of resource IDs named in window manager
1056N/A properties has been specified.
1056N/A ● [P30] Advice for dealing with keystrokes and override-redirect windows has
1056N/A ● [P31] A statement on the ownership of resources transferred through the
1056N/A selection mechanism has been added.
1056N/A ● [P32] The definition of the CLIENT_WINDOW target has been clarified.
1056N/A ● [P33] A rule about requiring the selection owner to reacquire the selection
1056N/A under certain circumstances has been added.
1056N/A ● [P42] Added several new selection targets.
1056N/A ● [P44] Ambiguous wording regarding the withdrawal of top-level windows has
1056N/A ● [P45] A facility for requestors to pass parameters during a selection
1056N/A ● [P49] A convention on discrimated names has been added.
1056N/A ● [P57] The C_STRING property type was added.
1056N/A ● [P62] An ordering requirement on processing selection requests was added.
1056N/A ● [P63] The VisibleHint flag was added.
1056N/A ● [P64] The session management section has been updated to align with the new
1056N/A session management protocol. The old session management conventions have
1056N/A ● References to the never-forthcoming Window and Session Manager Conventions
1056N/A ● Information on the X Registry and references to the session management and
1056N/A ICE documents have been added.
1056N/A ● Numerous editorial and typographical improvements have been made.
1056N/AThe following changes have been made in preparation for releasing the final
1056N/Aedition of Version 2.0 with X11R6.
1056N/A ● The PIXMAP selection target has been revised to return a property of type
1056N/A PIXMAP instead of type DRAWABLE.
1056N/A ● The session management section has been revised slightly to correspond with
1056N/A the changes to the X Session Management Protocol.
1056N/A ● Window managers are now prohibited from placing CurrentTime in the
1056N/A timestamp field of WM_TAKE_FOCUS messages.
1056N/A ● In the WM_HINTS property, the VisibleHint flag has been renamed to
1056N/A UrgencyHint. Its semantics have also been defined more thoroughly.
1056N/A ● Additional editorial and typographical changes have been made.
1056N/AAppendix B. Suggested Protocol Revisions
1056N/ADuring the development of these conventions, a number of inadequacies have been
1056N/Adiscovered in the core X11 protocol. They are summarized here as input to an
1056N/Aeventual protocol revision design process:
1056N/A ● There is no way for anyone to find out the last-change time of a selection.
1056N/A The GetSelectionOwner request should be changed to return the last-change
1056N/A ● There is no way for a client to find out which selection atoms are valid.
1056N/A ● There would be no need for WM_TAKE_FOCUS if the FocusIn event contained a
1056N/A timestamp and a previous-focus field. This could avoid the potential race
1056N/A condition. There is space in the event for this information; it should be
1056N/A added at the next protocol revision.
1056N/A ● There is a race condition in the InstallColormap request. It does not take
1056N/A a timestamp and may be executed after the top-level colormap has been
1056N/A uninstalled. The next protocol revision should provide the timestamp in the
1056N/A InstallColormap, UninstallColormap, ListInstalledColormaps requests and in
1056N/A the ColormapNotify event. The timestamp should be used in a similar way to
1056N/A the last-focus-change time for the input focus. The lack of timestamps in
1056N/A these packets is the reason for restricting colormap installation to the
1056N/A ● The protocol needs to be changed to provide some way of identifying the
1056N/A Visual and the Screen of a colormap.
1056N/A ● There should be some way to reclaim assignments to the five nonpreassigned
1056N/A modifiers when they are no longer needed. The manual method is unpleasantly
1056N/AAppendix C. Obsolete Session Manager Conventions
1056N/AClient Responses to Session Manager Actions
1056N/ASummary of Session Manager Property Types
1056N/AThis appendix contains obsolete conventions for session management using X
1056N/Aproperties and messages. The conventions described here are deprecated and are
1056N/Adescribed only for historical interest. For further information on session
1056N/Amanagement, see X Session Management Protocol.
1056N/AThe client communicates with the session manager by placing two properties
1056N/A(WM_COMMAND and WM_CLIENT_MACHINE) on its top-level window. If the client has a
1056N/Agroup of top-level windows, these properties should be placed on the group
1056N/AThe window manager is responsible for placing a WM_STATE property on each
1056N/Atop-level client window for use by session managers and other clients that need
1056N/Ato be able to identify top-level client windows and their state.
1056N/AThe WM_COMMAND property represents the command used to start or restart the
1056N/Aclient. By updating this property, clients should ensure that it always
1056N/Areflects a command that will restart them in their current state. The content
1056N/Aand type of the property depend on the operating system of the machine running
1056N/Athe client. On POSIX-conformant systems using ISO Latin-1 characters for their
1056N/Acommand lines, the property should:
1056N/A ● Contain a list of null-terminated strings
1056N/A Other systems will need to set appropriate conventions for the type and
1056N/A contents of WM_COMMAND properties. Window and session managers should not
1056N/A assume that STRING is the type of WM_COMMAND or that they will be able to
1056N/A understand or display its contents.
1056N/ANote that WM_COMMAND strings are null-terminated and differ from the general
1056N/Aconventions that STRING properties are null-separated. This inconsistency is
1056N/Anecessary for backwards compatibility.
1056N/AA client with multiple top-level windows should ensure that exactly one of them
1056N/Ahas a WM_COMMAND with nonzero length. Zero-length WM_COMMAND properties can be
1056N/Aused to reply to WM_SAVE_YOURSELF messages on other top-level windows but will
1276N/AThis property is described in WM_CLIENT_MACHINE Property.
1056N/ABecause they communicate by means of unreliable network connections, clients
1056N/Amust be prepared for their connection to the server to be terminated at any
1056N/Atime without warning. They cannot depend on getting notification that
1056N/Atermination is imminent or on being able to use the server to negotiate with
1056N/Athe user about their fate. For example, clients cannot depend on being able to
1056N/ASimilarly, clients may terminate at any time without notice to the session
1056N/Amanager. When a client terminates itself rather than being terminated by the
1056N/Asession manager, it is viewed as having resigned from the session in question,
1056N/Aand it will not be revived if the session is revived.
1056N/AClient Responses to Session Manager Actions
1056N/AClients may need to respond to session manager actions in two ways:
1056N/A ● Saving their internal state
1056N/AClients that want to be warned when the session manager feels that they should
1056N/Asave their internal state (for example, when termination impends) should
1056N/Ainclude the atom WM_SAVE_YOURSELF in the WM_PROTOCOLS property on their
1056N/Atop-level windows to participate in the WM_SAVE_YOURSELF protocol. They will
1276N/Areceive a ClientMessage event as described in ClientMessage Events with the
1276N/Aatom WM_SAVE_YOURSELF in its data[0] field.
1056N/AClients that receive WM_SAVE_YOURSELF should place themselves in a state from
1056N/Awhich they can be restarted and should update WM_COMMAND to be a command that
1056N/Awill restart them in this state. The session manager will be waiting for a
1056N/APropertyNotify event on WM_COMMAND as a confirmation that the client has saved
1056N/Aits state. Therefore, WM_COMMAND should be updated (perhaps with a zero-length
1056N/Aappend) even if its contents are correct. No interactions with the user are
1056N/Apermitted during this process.
1056N/AOnce it has received this confirmation, the session manager will feel free to
1056N/Aterminate the client if that is what the user asked for. Otherwise, if the user
1056N/Aasked for the session to be put to sleep, the session manager will ensure that
1056N/Athe client does not receive any mouse or keyboard events.
1056N/AAfter receiving a WM_SAVE_YOURSELF, saving its state, and updating WM_COMMAND,
1056N/Athe client should not change its state (in the sense of doing anything that
1056N/Awould require a change to WM_COMMAND) until it receives a mouse or keyboard
1056N/Aevent. Once it does so, it can assume that the danger is over. The session
1056N/Amanager will ensure that these events do not reach clients until the danger is
1056N/Aover or until the clients have been killed.
1056N/AIrrespective of how they are arranged in window groups, clients with multiple
1056N/Atop-level windows should ensure the following:
1056N/A ● Only one of their top-level windows has a nonzero-length WM_COMMAND
1056N/A ● They respond to a WM_SAVE_YOURSELF message by:
1056N/A ○ First, updating the nonzero-length WM_COMMAND property, if necessary
1056N/A ○ Second, updating the WM_COMMAND property on the window for which they
1056N/A received the WM_SAVE_YOURSELF message if it was not updated in the
1056N/AReceiving WM_SAVE_YOURSELF on a window is, conceptually, a command to save the
1056N/AWindows are deleted using the WM_DELETE_WINDOW protocol, which is described in
1056N/ASummary of Session Manager Property Types
1056N/AThe session manager properties are listed in the following table:
1276N/A┌─────────────────┬────────┬──────┬──────────────────────────┐
1276N/A│Name │Type │Format│See Section │
1276N/A├─────────────────┼────────┼──────┼──────────────────────────┤
1276N/A│WM_CLIENT_MACHINE│TEXT │ │WM_CLIENT_MACHINE Property│
1276N/A├─────────────────┼────────┼──────┼──────────────────────────┤
1276N/A│WM_COMMAND │TEXT │ │WM_COMMAND Property │
1276N/A├─────────────────┼────────┼──────┼──────────────────────────┤
1276N/A│WM_STATE │WM_STATE│32 │WM_STATE Property │
1276N/A└─────────────────┴────────┴──────┴──────────────────────────┘
1056N/A^[11] This convention has changed since earlier drafts because of the
1056N/Aintroduction of the protocol in the next section. In the public review draft,
1056N/Athere was ambiguity as to whether WM_SAVE_YOURSELF was a checkpoint or a
1056N/Ashutdown facility. It is now unambiguously a checkpoint facility; if a shutdown
1056N/Afacility is judged to be necessary, a separate WM_PROTOCOLS protocol will be
1056N/Adeveloped and registered with the X Consortium.