1mInter-Client Communication Conventions Manual0m 1mVersion 2.0.xf86.10m 1mXFree86 4.0.20m 1mXFree86, Inc.0m 4mbased24m 4mon0m 1mVersion 2.00m 1mX Consortium Standard0m 1mX Version 11, Release 6.40m David Rosenthal Sun Microsystems, Inc. Version 2 edited by Stuart W. Marks SunSoft, Inc. X Window System is a trademark of X Consortium, Inc. Copyright © 1988, 1991, 1993, 1994 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documenta- tion files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR- POSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSOR- TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of the X Con- sortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. Copyright © 1987, 1988, 1989, 1993, 1994 Sun Microsystems, Inc. Permission to use, copy, modify, and distribute this docu- mentation for any purpose and without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. Sun Microsystems makes no rep- resentations about the suitability for any purpose of the information in this document. This documentation is pro- vided as is without express or implied warranty. ii vi 1mPreface to Version 2.00m The goal of the ICCCM Version 2.0 effort was to add new facilities, to fix problems with earlier drafts, and to improve readability and understandability, while maintaining compatibility with the earlier versions. This document is the product of over two years of discussion among the mem- bers of the X Consortium's 1mwmtalk 22mworking group. The fol- lowing people deserve thanks for their contributions: Gabe Beged-Dov Bill Janssen Chan Benson Vania Joloboff Jordan Brown Phil Karlton Larry Cable Kaleb Keithley Ellis Cohen Mark Manasse Donna Converse Ralph Mor Brian Cripe Todd Newman Susan Dahlberg Bob Scheifler Peter Daifuku Keith Taylor Andrew deBlois Jim VanGilder Clive Feather Mike Wexler Stephen Gildea Michael Yee Christian Jacobi It has been a privilege for me to work with this fine group of people. Stuart W. Marks December 1993 vii 1mPreface to Version 1.10m David Rosenthal had overall architectural responsibility for the conventions defined in this document; he wrote most of the text and edited the document, but its development has been a communal effort. The details were thrashed out in meetings at the January 1988 MIT X Conference and at the 1988 Summer Usenix conference, and through months (and megabytes) of argument on the 4mwmtalk24m mail alias. Thanks are due to everyone who contributed, and especially to the fol- lowing people. For the Selection section: Jerry Farrell Phil Karlton Loretta Guarino Reid Mark Manasse Bob Scheifler For the Cut-Buffer section: Andrew Palay For the Window and Session Manager sections: Todd Brunhoff Matt Landau Ellis Cohen Mark Manasse Jim Fulton Bob Scheifler Hania Gajewska Ralph Swick Jordan Hubbard Mike Wexler Kerry Kimbrough Glenn Widener Audrey Ishizaki For the Device Color Characterization section: Keith Packard In addition, thanks are due to those who contributed to the public review: Gary Combs John Irwin viii Errol Crary Vania Joloboff Nancy Cyprych John Laporta John Diamant Ken Lee Clive Feather Stuart Marks Burns Fisher Alan Mimms Richard Greco Colas Nahaboo Tim Greenwood Mark Patrick Kee Hinckley Steve Pitschke Brian Holt Brad Reed John Interrante John Thomas ix 1m1. Introduction0m It was an explicit design goal of X Version 11 to specify mechanism, not policy. As a result, a client that converses with the server using the protocol defined by the 4mX24m 4mWindow0m 4mSystem24m 4mProtocol24m, 4mVersion24m 4m1124m may operate correctly in isola- tion but may not coexist properly with others sharing the same server. Being a good citizen in the X Version 11 world involves adhering to conventions that govern inter-client communica- tions in the following areas: · Selection mechanism · Cut buffers · Window manager · Session manager · Manipulation of shared resources · Device color characterization This document proposes suitable conventions without attempt- ing to enforce any particular user interface. To permit clients written in different languages to communicate, these conventions are expressed solely in terms of protocol opera- tions, not in terms of their associated Xlib interfaces, which are probably more familiar. The binding of these operations to the Xlib interface for C and to the equivalent interfaces for other languages is the subject of other docu- ments. 1m1.1. Evolution of the Conventions0m In the interests of timely acceptance, the 4mInter-Client24m 4mCom-0m 4mmunication24m 4mConventions24m 4mManual24m (ICCCM) covers only a minimal set of required conventions. These conventions will be added to and updated as appropriate, based on the experi- ences of the X Consortium. As far as possible, these conventions are upwardly compati- ble with those in the February 25, 1988, draft that was dis- tributed with the X Version 11, Release 2, of the software. In some areas, semantic problems were discovered with those conventions, and, thus, complete upward compatibility could not be assured. These areas are noted in the text and are summarized in Appendix A. In the course of developing these conventions, a number of minor changes to the protocol were identified as desirable. They also are identified in the text, are summarized in 1m10m 1mInter-Client Communication Conventions X11, Release 6.40m Appendix B, and are offered as input to a future protocol revision process. If and when a protocol revision incorpo- rating these changes is undertaken, it is anticipated that the ICCCM will need to be revised. Because it is difficult to ensure that clients and servers are upgraded simultane- ously, clients using the revised conventions should examine the minor protocol revision number and be prepared to use the older conventions when communicating with an older server. It is expected that these revisions will ensure that clients using the conventions appropriate to protocol minor revision 4mn24m will interoperate correctly with those that use the con- ventions appropriate to protocol minor revision 4mn24m + 1 if the server supports both. 1m1.2. Atoms0m Many of the conventions use atoms. To assist the reader, the following sections attempt to amplify the description of atoms that is provided in the protocol specification. 1m1.2.1. What Are Atoms?0m At the conceptual level, atoms are unique names that clients can use to communicate information to each other. They can be thought of as a bundle of octets, like a string but with- out an encoding being specified. The elements are not nec- essarily ASCII characters, and no case folding happens.1 The protocol designers felt that passing these sequences of bytes back and forth across the wire would be too costly. Further, they thought it important that events as they appear on the wire have a fixed size (in fact, 32 bytes) and that because some events contain atoms, a fixed-size repre- sentation for them was needed. To allow a fixed-size representation, a protocol request (4mInternAtom24m) was provided to register a byte sequence with the server, which returns a 32-bit value (with the top three bits zero) that maps to the byte sequence. The inverse operator is also available (4mGetAtomName24m). 1m1.2.2. Predefined Atoms0m The protocol specifies a number of atoms as being prede- fined: ----------- 1 The comment in the protocol specification for 4mInternAtom24m that ISO Latin-1 encoding should be used is in the nature of a convention; the server treats the string as a byte sequence. 1m20m 1mInter-Client Communication Conventions X11, Release 6.40m Predefined atoms are not strictly necessary and may not be useful in all environments, but they will eliminate many 4mInternAtom24m requests in most applications. Note that they are predefined only in the sense of having numeric values, not in the sense of having required semantics. Predefined atoms are an implementation trick to avoid the cost of interning many of the atoms that are expected to be used during the startup phase of all applications. The results of the 4mInternAtom24m requests, which require a hand- shake, can be assumed 4ma24m 4mpriori24m. Language interfaces should probably cache the atom-name map- pings and get them only when required. The CLX interface, for instance, makes no distinction between predefined atoms and other atoms; all atoms are viewed as symbols at the interface. However, a CLX implementation will typically keep a symbol or atom cache and will typically initialize this cache with the predefined atoms. 1m1.2.3. Naming Conventions0m The built-in atoms are composed of uppercase ASCII charac- ters with the logical words separated by an underscore char- acter (_), for example, WM_ICON_NAME. The protocol specifi- cation recommends that atoms used for private vendor-spe- cific reasons should begin with an underscore. To prevent conflicts among organizations, additional prefixes should be chosen (for example, _DEC_WM_DECORATION_GEOMETRY). The names were chosen in this fashion to make it easy to use them in a natural way within LISP. Keyword constructors allow the programmer to specify the atoms as LISP atoms. If the atoms were not all uppercase, special quoting conven- tions would have to be used. 1m1.2.4. Semantics0m The core protocol imposes no semantics on atoms except as they are used in FONTPROP structures. For further informa- tion on FONTPROP semantics, see the 4mX24m 4mLogical24m 4mFont24m 4mDescrip-0m 4mtion24m 4mConventions24m. 1m1.2.5. Name Spaces0m The protocol defines six distinct spaces in which atoms are interpreted. Any particular atom may or may not have some valid interpretation with respect to each of these name spa- ces. 1m30m 1mInter-Client Communication Conventions X11, Release 6.40m -------------------------------------------------------------------- 1mSpace Briefly Examples0m -------------------------------------------------------------------- Property name Name WM_HINTS, WM_NAME, RGB_BEST_MAP, ... Property type Type WM_HINTS, CURSOR, RGB_COLOR_MAP, ... Selection name Selection PRIMARY, SECONDARY, CLIPBOARD Selection target Target FILE_NAME, POSTSCRIPT, PIXMAP, ... Font property QUAD_WIDTH, POINT_SIZE, ... 4mClientMessage24m WM_SAVE_YOURSELF, _DEC_SAVE_EDITS, type ... -------------------------------------------------------------------- 1m1.2.6. Discriminated Names0m Sometimes a protocol requires an arbitrary number of similar objects that need unique names (usually because the objects are created dynamically, so that names cannot be invented in advance). For example, a colormap-generating program might use the selection mechanism to offer colormaps for each screen and so needs a selection name for each screen. Such names are called "discriminated names" and are discriminated by some entity. This entity can be: A screen An X resource (a window, a colormap, a visual, etc.) A client If it is only necessary to generate a fixed set of names for each value of the discriminating entity, then the discrimi- nated names are formed by suffixing an ordinary name accord- ing to the value of the entity. If 4mname24m is a descriptive portion for the name, 4md24m is a deci- mal number with no leading zeroes, and 4mx24m is a hexadecimal number with exactly 8 digits, and using uppercase letters, then such discriminated names shall have the form: --------------------------------------------------------- 1mName Discriminated by Form Example0m --------------------------------------------------------- screen number 4mname24m_S4md24m WM_COMMS_S2 X resource 4mname24m_R4mx24m GROUP_LEADER_R1234ABCD --------------------------------------------------------- To discriminate a name by client, use an X resource ID cre- ated by that client. This resource can be of any type. Sometimes it is simply necessary to generate a unique set of names (for example, for the properties on a window used by a MULTIPLE selection). These names should have the form: 1m40m 1mInter-Client Communication Conventions X11, Release 6.40m U4md24m (e.g., U0 U1 U2 U3 ...) if the names stand totally alone, and the form: 4mname24m_U4md24m (e.g., FOO_U0 BAR_U0 FOO_U1 BAR_U1 ...) if they come in sets (here there are two sets, named "FOO" and "BAR"). The stand-alone U4md24m form should be used only if it is clear that the module using it has complete control over the relevant namespace or has the active cooperation of all other entities that might also use these names. (Naming properties on a window created specifically for a particular selection is such a use; naming properties on the root win- dow is almost certainly not.) In a particularly difficult case, it might be necessary to combine both forms of discrimination. If this happens, the U form should come after the other form, thus: FOO_R12345678_U23 Rationale Existing protocols will not be changed to use these naming conventions, because doing so will cause too much disruption. However, it is expected that future protocols -- both standard and private -- will use these conventions. 1m2. Peer-to-Peer Communication by Means of Selections0m Selections are the primary mechanism that X Version 11 defines for the exchange of information between clients, for example, by cutting and pasting between windows. Note that there can be an arbitrary number of selections (each named by an atom) and that they are global to the server. Section 2.6 discusses the choice of an atom. Each selection is owned by a client and is attached to a window. Selections communicate between an owner and a requestor. The owner has the data representing the value of its selec- tion, and the requestor receives it. A requestor wishing to obtain the value of a selection provides the following: · The name of the selection · The name of a property · A window 1m50m 1mInter-Client Communication Conventions X11, Release 6.40m · The atom representing the data type required · Optionally, some parameters for the request If the selection is currently owned, the owner receives an event and is expected to do the following: · Convert the contents of the selection to the requested data type · Place this data in the named property on the named win- dow · Send the requestor an event to let it know the property is available Clients are strongly encouraged to use this mechanism. In particular, displaying text in a permanent window without providing the ability to select and convert it into a string is definitely considered antisocial. Note that all data transferred between an owner and a requestor must usually go by means of the server in an X Version 11 environment. A client cannot assume that another client can open the same files or even communicate directly. The other client may be talking to the server by means of a completely different networking mechanism (for example, one client might be DECnet and the other TCP/IP). Thus, passing indirect references to data (such as, file names, host names, and port numbers) is permitted only if both clients specifically agree. 1m2.1. Acquiring Selection Ownership0m A client wishing to acquire ownership of a particular selec- tion should call 4mSetSelectionOwner,24m which is defined as fol- lows: __ | 4mSetSelectionOwner0m 4mselection24m: ATOM 4mowner24m: WINDOW or 4mNone0m 4mtime24m: TIMESTAMP or 4mCurrentTime0m |__ The client should set the specified selection to the atom that represents the selection, set the specified owner to some window that the client created, and set the specified time to some time between the current last-change time of the selection concerned and the current server time. This time value usually will be obtained from the timestamp of the event that triggers the acquisition of the selection. 1m60m 1mInter-Client Communication Conventions X11, Release 6.40m Clients should not set the time value to 4mCurrentTime24m, because if they do so, they have no way of finding when they gained ownership of the selection. Clients must use a win- dow they created so that requestors can route events to the owner of the selection.2 Convention Clients attempting to acquire a selection must set the time value of the 4mSetSelectionOwner24m request to the timestamp of the event triggering the acquisi- tion attempt, not to 4mCurrentTime24m. A zero-length append to a property is a way to obtain a time- stamp for this purpose; the timestamp is in the corresponding 4mPropertyNotify24m event. If the time in the 4mSetSelectionOwner24m request is in the future relative to the server's current time or is in the past relative to the last time the specified selection changed hands, the 4mSetSelectionOwner24m request appears to the client to succeed, but ownership is not actually trans- ferred. Because clients cannot name other clients directly, the specified owner window is used to refer to the owning client in the replies to 4mGetSelectionOwner24m, in 4mSelectionRequest24m and 4mSelectionClear24m events, and possibly as a place to put prop- erties describing the selection in question. To discover the owner of a particular selection, a client should invoke 4mGetSelectionOwner24m, which is defined as follows: __ | 4mGetSelectionOwner0m 4mselection24m: ATOM -> owner: WINDOW or 4mNone0m |__ Convention Clients are expected to provide some visible con- firmation of selection ownership. To make this feedback reliable, a client must perform a sequence like the following: ----------- 2 At present, no part of the protocol requires requestors to send events to the owner of a selec- tion. This restriction is imposed to prepare for possible future extensions. 1m70m 1mInter-Client Communication Conventions X11, Release 6.40m SetSelectionOwner(selection=PRIMARY, owner=Window, time=timestamp) owner = GetSelectionOwner(selection=PRIMARY) if (owner != Window) Failure If the 4mSetSelectionOwner24m request succeeds (not merely appears to succeed), the client that issues it is recorded by the server as being the owner of the selection for the time period starting at the specified time. 1m2.2. Responsibilities of the Selection Owner0m When a requestor wants the value of a selection, the owner receives a 4mSelectionRequest24m event, which is defined as fol- lows: __ | 4mSelectionRequest0m 4mowner24m: WINDOW 4mselection24m: ATOM 4mtarget24m: ATOM 4mproperty24m: ATOM or 4mNone0m 4mrequestor24m: WINDOW 4mtime24m: TIMESTAMP or 4mCurrentTime0m |__ The specified owner and selection will be the values that were specified in the 4mSetSelectionOwner24m request. The owner should compare the timestamp with the period it has owned the selection and, if the time is outside, refuse the 4mSelec-0m 4mtionRequest24m by sending the requestor window a 4mSelectionNo-0m 4mtify24m event with the property set to 4mNone24m (by means of a 4mSendEvent24m request with an empty event mask). More advanced selection owners are free to maintain a his- tory of the value of the selection and to respond to requests for the value of the selection during periods they owned it even though they do not own it now. If the specified property is 4mNone24m, the requestor is an obso- lete client. Owners are encouraged to support these clients by using the specified target atom as the property name to be used for the reply. Otherwise, the owner should use the target to decide the form into which the selection should be converted. Some targets may be defined such that requestors can pass parame- ters along with the request. The owner will find these parameters in the property named in the selection request. The type, format, and contents of this property are depen- dent upon the definition of the target. If the target is 1m80m 1mInter-Client Communication Conventions X11, Release 6.40m not defined to have parameters, the owner should ignore the property if it is present. If the selection cannot be con- verted into a form based on the target (and parameters, if any), the owner should refuse the 4mSelectionRequest24m as previ- ously described. If the specified property is not 4mNone24m, the owner should place the data resulting from converting the selection into the specified property on the requestor window and should set the property's type to some appropriate value, which need not be the same as the specified target. Convention All properties used to reply to 4mSelectionRequest0m events must be placed on the requestor window. In either case, if the data comprising the selection cannot be stored on the requestor window (for example, because the server cannot provide sufficient memory), the owner must refuse the 4mSelectionRequest24m, as previously described. See also section 2.5. If the property is successfully stored, the owner should acknowledge the successful conversion by sending the requestor window a 4mSelectionNotify24m event (by means of a 4mSendEvent24m request with an empty mask). 4mSelectionNotify24m is defined as follows: __ | 4mSelectionNotify0m 4mrequestor24m: WINDOW 4mselection24m, 4mtarget24m: ATOM 4mproperty24m: ATOM or 4mNone0m 4mtime24m: TIMESTAMP or 4mCurrentTime0m |__ The owner should set the specified selection, target, time, and property arguments to the values received in the 4mSelec-0m 4mtionRequest24m event. (Note that setting the property argument to 4mNone24m indicates that the conversion requested could not be made.) Convention The selection, target, time, and property argu- ments in the 4mSelectionNotify24m event should be set to the values received in the 4mSelectionRequest0m event. 1m90m 1mInter-Client Communication Conventions X11, Release 6.40m If the owner receives more than one 4mSelectionRequest24m event with the same requestor, selection, target, and timestamp it must respond to them in the same order in which they were received. Rationale It is possible for a requestor to have multiple outstanding requests that use the same requestor window, selection, target, and timestamp, and that differ only in the property. If this occurs, and one of the conversion requests fails, the result- ing 4mSelectionNotify24m event will have its property argument set to 4mNone24m. This may make it impossible for the requestor to determine which conversion request had failed, unless the requests are responded to in order. The data stored in the property must eventually be deleted. A convention is needed to assign the responsibility for doing so. Convention Selection requestors are responsible for deleting properties whose names they receive in 4mSelection-0m 4mNotify24m events (see section 2.4) or in properties with type MULTIPLE. A selection owner will often need confirmation that the data comprising the selection has actually been transferred. (For example, if the operation has side effects on the owner's internal data structures, these should not take place until the requestor has indicated that it has success- fully received the data.) Owners should express interest in 4mPropertyNotify24m events for the specified requestor window and wait until the property in the 4mSelectionNotify24m event has been deleted before assuming that the selection data has been transferred. For the MULTIPLE request, if the differ- ent conversions require separate confirmation, the selection owner can also watch for the deletion of the individual properties named in the property in the 4mSelectionNotify0m event. When some other client acquires a selection, the previous owner receives a 4mSelectionClear24m event, which is defined as follows: 1m100m 1mInter-Client Communication Conventions X11, Release 6.40m __ | 4mSelectionClear0m 4mowner24m: WINDOW 4mselection24m: ATOM 4mtime24m: TIMESTAMP |__ The timestamp argument is the time at which the ownership changed hands, and the owner argument is the window the pre- vious owner specified in its 4mSetSelectionOwner24m request. If an owner loses ownership while it has a transfer in progress (that is, before it receives notification that the requestor has received all the data), it must continue to service the ongoing transfer until it is complete. If the selection value completely changes, but the owner happens to be the same client (for example, selecting a totally different piece of text in the same 1mxterm 22mas before), then the client should reacquire the selection own- ership as if it were not the owner, providing a new time- stamp. If the selection value is modified, but can still reasonably be viewed as the same selected object,3 the owner should take no action. 1m2.3. Giving Up Selection Ownership0m Clients may either give up selection ownership voluntarily or lose it forcibly as the result of some other client's actions. 1m2.3.1. Voluntarily Giving Up Selection Ownership0m To relinquish ownership of a selection voluntarily, a client should execute a 4mSetSelectionOwner24m request for that selec- tion atom, with owner specified as 4mNone24m and the time speci- fied as the timestamp that was used to acquire the selec- tion. Alternatively, the client may destroy the window used as the owner value of the 4mSetSelectionOwner24m request, or the client may terminate. In both cases, the ownership of the selec- tion involved will revert to 4mNone24m. 1m2.3.2. Forcibly Giving Up Selection Ownership0m If a client gives up ownership of a selection or if some other client executes a 4mSetSelectionOwner24m for it and thus reassigns it forcibly, the previous owner will receive a ----------- 3 The division between these two cases is a mat- ter of judgment on the part of the software devel- oper. 1m110m 1mInter-Client Communication Conventions X11, Release 6.40m 4mSelectionClear24m event. For the definition of a 4mSelectionClear0m event, see section 2.2. The timestamp is the time the selection changed hands. The specified owner is the window that was specified by the cur- rent owner in its 4mSetSelectionOwner24m request. 1m2.4. Requesting a Selection0m A client that wishes to obtain the value of a selection in a particular form (the requestor) issues a 4mConvertSelection0m request, which is defined as follows: __ | 4mConvertSelection0m 4mselection24m, 4mtarget24m: ATOM 4mproperty24m: ATOM or 4mNone0m 4mrequestor24m: WINDOW 4mtime24m: TIMESTAMP or 4mCurrentTime0m |__ The selection argument specifies the particular selection involved, and the target argument specifies the required form of the information. For information about the choice of suitable atoms to use, see section 2.6. The requestor should set the requestor argument to a window that it cre- ated; the owner will place the reply property there. The requestor should set the time argument to the timestamp on the event that triggered the request for the selection value. Note that clients should not specify 4mCurrentTime24m. Convention Clients should not use 4mCurrentTime24m for the time argument of a 4mConvertSelection24m request. Instead, they should use the timestamp of the event that caused the request to be made. The requestor should set the property argument to the name of a property that the owner can use to report the value of the selection. Requestors should ensure that the named property does not exist on the window before issuing the 4mConvertSelection24m request.4 The exception to this rule is when the requestor intends to pass parameters with the request (see below). 1m120m 1mInter-Client Communication Conventions X11, Release 6.40m Rationale It is necessary for requestors to delete the prop- erty before issuing the request so that the target can later be extended to take parameters without introducing an incompatibility. Also note that the requestor of a selection need not know the client that owns the selection nor the window on which the selection was acquired. Some targets may be defined such that requestors can pass parameters along with the request. If the requestor wishes to provide parameters to a request, they should be placed in the specified property on the requestor window before the requestor issues the 4mConvertSelection24m request, and this property should be named in the request. Some targets may be defined so that parameters are optional. If no parameters are to be supplied with the request of such a target, the requestor must ensure that the property does not exist before issuing the 4mConvertSelection24m request. The protocol allows the property field to be set to 4mNone24m, in which case the owner is supposed to choose a property name. However, it is difficult for the owner to make this choice safely. Conventions 1. Requestors should not use 4mNone24m for the prop- erty argument of a 4mConvertSelection24m request. 2. Owners receiving 4mConvertSelection24m requests with a property argument of 4mNone24m are talking to an obsolete client. They should choose the target atom as the property name to be used for the reply. The result of the 4mConvertSelection24m request is that a 4mSelec-0m 4mtionNotify24m event will be received. For the definition of a ----------- 4 This requirement is new in version 2.0, and, in general, existing clients do not conform to this requirement. To prevent these clients from breaking, no existing targets should be extended to take parameters until sufficient time has passed for clients to be updated. Note that the MULTIPLE target was defined to take parameters in version 1.0 and its definition is not changing. There is thus no conformance problem with MULTI- PLE. 1m130m 1mInter-Client Communication Conventions X11, Release 6.40m 4mSelectionNotify24m event, see section 2.2. The requestor, selection, time, and target arguments will be the same as those on the 4mConvertSelection24m request. If the property argument is 4mNone24m, the conversion has been refused. This can mean either that there is no owner for the selection, that the owner does not support the conver- sion implied by the target, or that the server did not have sufficient space to accommodate the data. If the property argument is not 4mNone24m, then that property will exist on the requestor window. The value of the selec- tion can be retrieved from this property by using the 4mGet-0m 4mProperty24m request, which is defined as follows: __ | 4mGetProperty0m 4mwindow24m: WINDOW 4mproperty24m: ATOM 4mtype24m: ATOM or 4mAnyPropertyType0m 4mlong-offset24m, 4mlong-length24m: CARD32 4mdelete24m: BOOL -> type: ATOM or 4mNone0m format: {0, 8, 16, 32} bytes-after: CARD32 value: LISTofINT8 or LISTofINT16 or LISTofINT32 |__ When using 4mGetProperty24m to retrieve the value of a selection, the property argument should be set to the corresponding value in the 4mSelectionNotify24m event. Because the requestor has no way of knowing beforehand what type the selection owner will use, the type argument should be set to 4mAnyProp-0m 4mertyType24m. Several 4mGetProperty24m requests may be needed to retrieve all the data in the selection; each should set the long-offset argument to the amount of data received so far, and the size argument to some reasonable buffer size (see section 2.5). If the returned value of bytes-after is zero, the whole property has been transferred. Once all the data in the selection has been retrieved (which may require getting the values of several properties -- see section 2.7), the requestor should delete the property in the 4mSelectionNotify24m request by using a 4mGetProperty24m request with the delete argument set to 4mTrue24m. As previously dis- cussed, the owner has no way of knowing when the data has been transferred to the requestor unless the property is removed. 1m140m 1mInter-Client Communication Conventions X11, Release 6.40m Convention The requestor must delete the property named in the 4mSelectionNotify24m once all the data has been retrieved. The requestor should invoke either 4mDeleteProperty24m or 4mGetProperty24m(delete==True) after it has successfully retrieved all the data in the selection. For further information, see section 2.5. 1m2.5. Large Data Transfers0m Selections can get large, which poses two problems: · Transferring large amounts of data to the server is expensive. · All servers will have limits on the amount of data that can be stored in properties. Exceeding this limit will result in an 4mAlloc24m error on the 4mChangeProperty24m request that the selection owner uses to store the data. The problem of limited server resources is addressed by the following conventions: Conventions 1. Selection owners should transfer the data describing a large selection (relative to the maximum-request-size they received in the connection handshake) using the INCR property mechanism (see section 2.7.2). 2. Any client using 4mSetSelectionOwner24m to acquire selection ownership should arrange to process 4mAlloc24m errors in property change requests. For clients using Xlib, this involves using the 4mXSetErrorHandler24m function to override the default handler. 3. A selection owner must confirm that no 4mAlloc0m error occurred while storing the properties for a selection before replying with a con- firming 4mSelectionNotify24m event. 4. When storing large amounts of data (relative to maximum-request-size), clients should use a sequence of 4mChangeProperty24m(mode==Append) requests for reasonable quantities of data. This avoids locking servers up and limits the waste of data an 4mAlloc24m error would cause. 1m150m 1mInter-Client Communication Conventions X11, Release 6.40m 5. If an 4mAlloc24m error occurs during the storing of the selection data, all properties stored for this selection should be deleted and the 4mConvertSelection24m request should be refused (see section 2.2). 6. To avoid locking servers up for inordinate lengths of time, requestors retrieving large quantities of data from a property should perform a series of 4mGetProperty24m requests, each asking for a reasonable amount of data. Advice to Implementors Single-threaded servers should take care to avoid locking up during large data transfers. 1m2.6. Use of Selection Atoms0m Defining a new atom consumes resources in the server that are not released until the server reinitializes. Thus, reducing the need for newly minted atoms is an important goal for the use of the selection atoms. 1m2.6.1. Selection Atoms0m There can be an arbitrary number of selections, each named by an atom. To conform with the inter-client conventions, however, clients need deal with only these three selections: · PRIMARY · SECONDARY · CLIPBOARD Other selections may be used freely for private communica- tion among related groups of clients. 1m2.6.1.1. The PRIMARY Selection0m The selection named by the atom PRIMARY is used for all com- mands that take only a single argument and is the principal means of communication between clients that use the selec- tion mechanism. 1m2.6.1.2. The SECONDARY Selection0m The selection named by the atom SECONDARY is used: · As the second argument to commands taking two arguments (for example, "exchange primary and secondary 1m160m 1mInter-Client Communication Conventions X11, Release 6.40m selections") · As a means of obtaining data when there is a primary selection and the user does not want to disturb it 1m2.6.1.3. The CLIPBOARD Selection0m The selection named by the atom CLIPBOARD is used to hold data that is being transferred between clients, that is, data that usually is being cut and then pasted or copied and then pasted. Whenever a client wants to transfer data to the clipboard: · It should assert ownership of the CLIPBOARD. · If it succeeds in acquiring ownership, it should be pre- pared to respond to a request for the contents of the CLIPBOARD in the usual way (retaining the data to be able to return it). The request may be generated by the clipboard client described below. · If it fails to acquire ownership, a cutting client should not actually perform the cut or provide feedback that would suggest that it has actually transferred data to the clipboard. The owner should repeat this process whenever the data to be transferred would change. Clients wanting to paste data from the clipboard should request the contents of the CLIPBOARD selection in the usual way. Except while a client is actually deleting or copying data, the owner of the CLIPBOARD selection may be a single, spe- cial client implemented for the purpose. This client main- tains the content of the clipboard up-to-date and responds to requests for data from the clipboard as follows: · It should assert ownership of the CLIPBOARD selection and reassert it any time the clipboard data changes. · If it loses the selection (because another client has some new data for the clipboard), it should: - Obtain the contents of the selection from the new owner by using the timestamp in the 4mSelectionClear0m event. - Attempt to reassert ownership of the CLIPBOARD selection by using the same timestamp. - Restart the process using a newly acquired time- stamp if this attempt fails. This timestamp should 1m170m 1mInter-Client Communication Conventions X11, Release 6.40m be obtained by asking the current owner of the CLIPBOARD selection to convert it to a TIMESTAMP. If this conversion is refused or if the same time- stamp is received twice, the clipboard client should acquire a fresh timestamp in the usual way (for example by a zero-length append to a prop- erty). · It should respond to requests for the CLIPBOARD contents in the usual way. A special CLIPBOARD client is not necessary. The protocol used by the cutting client and the pasting client is the same whether the CLIPBOARD client is running or not. The reasons for running the special client include: · Stability - If the cutting client were to crash or ter- minate, the clipboard value would still be available. · Feedback - The clipboard client can display the contents of the clipboard. · Simplicity - A client deleting data does not have to retain it for so long, thus reducing the chance of race conditions causing problems. The reasons not to run the clipboard client include: · Performance - Data is transferred only if it is actually required (that is, when some client actually wants the data). · Flexibility - The clipboard data may be available as more than one target. 1m2.6.2. Target Atoms0m The atom that a requestor supplies as the target of a 4mCon-0m 4mvertSelection24m request determines the form of the data sup- plied. The set of such atoms is extensible, but a generally accepted base set of target atoms is needed. As a starting point for this, the following table contains those that have been suggested so far. --------------------------------------------------------------------- 1mAtom Type Data Received0m --------------------------------------------------------------------- ADOBE_PORTABLE_DOCUMENT_FORMAT STRING [1] APPLE_PICT APPLE_PICT [2] BACKGROUND PIXEL A list of pixel values BITMAP BITMAP A list of bitmap IDs 1m180m 1mInter-Client Communication Conventions X11, Release 6.40m --------------------------------------------------------------------- 1mAtom Type Data Received0m --------------------------------------------------------------------- CHARACTER_POSITION SPAN The start and end of the selec- tion in bytes CLASS TEXT (see section 4.1.2.5) CLIENT_WINDOW WINDOW Any top-level window owned by the selection owner COLORMAP COLORMAP A list of colormap IDs COLUMN_NUMBER SPAN The start and end column num- bers COMPOUND_TEXT COMPOUND_TEXT Compound Text DELETE NULL (see section 2.6.3.1) DRAWABLE DRAWABLE A list of drawable IDs ENCAPSULATED_POSTSCRIPT STRING [3], Appendix H5 ENCAPSULATED_POSTSCRIPT_INTERCHANGE STRING [3], Appendix H FILE_NAME TEXT The full path name of a file FOREGROUND PIXEL A list of pixel values HOST_NAME TEXT (see section 4.1.2.9) INSERT_PROPERTY NULL (see section 2.6.3.3) INSERT_SELECTION NULL (see section 2.6.3.2) LENGTH INTEGER The number of bytes in the selection6 LINE_NUMBER SPAN The start and end line numbers LIST_LENGTH INTEGER The number of disjoint parts of the selection MODULE TEXT The name of the selected proce- dure MULTIPLE ATOM_PAIR (see the discussion that fol- lows) NAME TEXT (see section 4.1.2.1) ODIF TEXT ISO Office Document Interchange Format OWNER_OS TEXT The operating system of the owner client PIXMAP PIXMAP7 A list of pixmap IDs POSTSCRIPT STRING [3] PROCEDURE TEXT The name of the selected proce- dure PROCESS INTEGER, TEXT The process ID of the owner STRING STRING ISO Latin-1 (+TAB+NEWLINE) text TARGETS ATOM A list of valid target atoms TASK INTEGER, TEXT The task ID of the owner TEXT TEXT The text in the owner's choice of encoding TIMESTAMP INTEGER The timestamp used to acquire the selection USER TEXT The name of the user running the owner UTF8_STRING TEXT UTF-8 text --------------------------------------------------------------------- 1m190m 1mInter-Client Communication Conventions X11, Release 6.40m References: [1] Adobe Systems, Incorporated. 4mPortable24m 4mDocument24m 4mFormat0m 4mReference24m 4mManual.24m Reading, MA, Addison-Wesley, ISBN 0-201-62628-4. [2] Apple Computer, Incorporated. 4mInside24m 4mMacintosh,24m 4mVolume0m 4mV.24m Chapter 4, "Color QuickDraw," Color Picture Format. ISBN 0-201-17719-6. [3] Adobe Systems, Incorporated. 4mPostScript24m 4mLanguage24m 4mRef-0m 4merence24m 4mManual.24m Reading, MA, Addison-Wesley, ISBN 0-201-18127-4. It is expected that this table will grow over time. Selection owners are required to support the following tar- gets. All other targets are optional. · TARGETS - The owner should return a list of atoms that represent the targets for which an attempt to convert the current selection will succeed (barring unforseeable problems such as 4mAlloc24m errors). This list should include all the required atoms. · MULTIPLE - The MULTIPLE target atom is valid only when a property is specified on the 4mConvertSelection24m request. If the property argument in the 4mSelectionRequest24m event is 4mNone24m and the target is MULTIPLE, it should be refused. ----------- 5 Earlier versions of this document erroneously specified that conversion of the PIXMAP target returns a property of type DRAWABLE instead of PIXMAP. Implementors should be aware of this and may want to support the DRAWABLE type as well to allow for compatibility with older clients. 6 The targets ENCAPSULATED_POSTSCRIPT and ENCAP- SULATED_POSTSCRIPT_INTERCHANGE are equivalent to the targets _ADOBE_EPS and _ADOBE_EPSI (respec- tively) that appear in the selection targets reg- istry. The _ADOBE_ targets are deprecated, but clients are encouraged to continue to support them for backward compatibility. 7 This definition is ambiguous, as the selection may be converted into any of several targets that may return differing amounts of data. The requestor has no way of knowing which, if any, of these targets corresponds to the result of LENGTH. Clients are advised that no guarantees can be made about the result of a conversion to LENGTH; its use is thus deprecated. 1m200m 1mInter-Client Communication Conventions X11, Release 6.40m When a selection owner receives a 4mSelectionRequest24m(tar- get==MULTIPLE) request, the contents of the property named in the request will be a list of atom pairs: the first atom naming a target and the second naming a prop- erty (4mNone24m is not valid here). The effect should be as if the owner had received a sequence of 4mSelectionRequest0m events (one for each atom pair) except that: - The owner should reply with a 4mSelectionNotify24m only when all the requested conversions have been per- formed. - If the owner fails to convert the target named by an atom in the MULTIPLE property, it should replace that atom in the property with 4mNone24m. Convention The entries in a MULTIPLE property must be processed in the order they appear in the property. For further information, see sec- tion 2.6.3. The requestor should delete each individual property when it has copied the data from that conversion, and the property specified in the MULTIPLE request when it has copied all the data. The requests are otherwise to be processed indepen- dently, and they should succeed or fail independently. The MULTIPLE target is an optimization that reduces the amount of protocol traffic between the owner and the requestor; it is not a transaction mechanism. For exam- ple, a client may issue a MULTIPLE request with two tar- gets: a data target and the DELETE target. The DELETE target will still be processed even if the conversion of the data target fails. · TIMESTAMP - To avoid some race conditions, it is impor- tant that requestors be able to discover the timestamp the owner used to acquire ownership. Until and unless the protocol is changed so that a 4mGetSelectionOwner0m request returns the timestamp used to acquire ownership, selection owners must support conversion to TIMESTAMP, returning the timestamp they used to obtain the selec- tion. 1m2.6.3. Selection Targets with Side Effects0m Some targets (for example, DELETE) have side effects. To render these targets unambiguous, the entries in a MULTIPLE property must be processed in the order that they appear in the property. 1m210m 1mInter-Client Communication Conventions X11, Release 6.40m In general, targets with side effects will return no infor- mation, that is, they will return a zero length property of type NULL. (Type NULL means the result of 4mInternAtom24m on the string "NULL", not the value zero.) In all cases, the requested side effect must be performed before the conver- sion is accepted. If the requested side effect cannot be performed, the corresponding conversion request must be refused. Conventions 1. Targets with side effects should return no information (that is, they should have a zero-length property of type NULL). 2. The side effect of a target must be performed before the conversion is accepted. 3. If the side effect of a target cannot be per- formed, the corresponding conversion request must be refused. Problem The need to delay responding to the 4mConvertSelec-0m 4mtion24m request until a further conversion has suc- ceeded poses problems for the Intrinsics interface that need to be addressed. These side-effect targets are used to implement operations such as "exchange PRIMARY and SECONDARY selections." 1m2.6.3.1. DELETE0m When the owner of a selection receives a request to convert it to DELETE, it should delete the corresponding selection (whatever doing so means for its internal data structures) and return a zero-length property of type NULL if the dele- tion was successful. 1m2.6.3.2. INSERT_SELECTION0m When the owner of a selection receives a request to convert it to INSERT_SELECTION, the property named will be of type ATOM_PAIR. The first atom will name a selection, and the second will name a target. The owner should use the selec- tion mechanism to convert the named selection into the named target and should insert it at the location of the selection for which it got the INSERT_SELECTION request (whatever doing so means for its internal data structures). 1m220m 1mInter-Client Communication Conventions X11, Release 6.40m 1m2.6.3.3. INSERT_PROPERTY0m When the owner of a selection receives a request to convert it to INSERT_PROPERTY, it should insert the property named in the request at the location of the selection for which it got the INSERT_SELECTION request (whatever doing so means for its internal data structures). 1m2.7. Use of Selection Properties0m The names of the properties used in selection data transfer are chosen by the requestor. The use of 4mNone24m property fields in 4mConvertSelection24m requests (which request the selection owner to choose a name) is not permitted by these conventions. The selection owner always chooses the type of the property in the selection data transfer. Some types have special semantics assigned by convention, and these are reviewed in the following sections. In all cases, a request for conversion to a target should return either a property of one of the types listed in the previous table for that target or a property of type INCR and then a property of one of the listed types. Certain selection properties may contain resource IDs. The selection owner should ensure that the resource is not destroyed and that its contents are not changed until after the selection transfer is complete. Requestors that rely on the existence or on the proper contents of a resource must operate on the resource (for example, by copying the con- tents of a pixmap) before deleting the selection property. The selection owner will return a list of zero or more items of the type indicated by the property type. In general, the number of items in the list will correspond to the number of disjoint parts of the selection. Some targets (for example, side-effect targets) will be of length zero irrespective of the number of disjoint selection parts. In the case of fixed-size items, the requestor may determine the number of items by the property size. Selection property types are listed in the table below. For variable-length items such as text, the separators are also listed. ------------------------------------- 1mType Atom Format Separator0m ------------------------------------- APPLE_PICT 8 Self-sizing ATOM 32 Fixed-size ATOM_PAIR 32 Fixed-size BITMAP 32 Fixed-size C_STRING 8 Zero 1m230m 1mInter-Client Communication Conventions X11, Release 6.40m ------------------------------------- 1mType Atom Format Separator0m ------------------------------------- COLORMAP 32 Fixed-size COMPOUND_TEXT 8 Zero DRAWABLE 32 Fixed-size INCR 32 Fixed-size INTEGER 32 Fixed-size PIXEL 32 Fixed-size PIXMAP 32 Fixed-size SPAN 32 Fixed-size STRING 8 Zero UTF8_STRING 8 Zero WINDOW 32 Fixed-size ------------------------------------- It is expected that this table will grow over time. 1m2.7.1. TEXT Properties0m In general, the encoding for the characters in a text string property is specified by its type. It is highly desirable for there to be a simple, invertible mapping between string property types and any character set names embedded within font names in any font naming standard adopted by the Con- sortium. The atom TEXT is a polymorphic target. Requesting conver- sion into TEXT will convert into whatever encoding is conve- nient for the owner. The encoding chosen will be indicated by the type of the property returned. TEXT is not defined as a type; it will never be the returned type from a selec- tion conversion request. If the requestor wants the owner to return the contents of the selection in a specific encoding, it should request con- version into the name of that encoding. In the table in section 2.6.2, the word TEXT (in the Type column) is used to indicate one of the registered encoding names. The type would not actually be TEXT; it would be STRING or some other ATOM naming the encoding chosen by the owner. STRING as a type or a target specifies the ISO Latin-1 char- acter set plus the control characters TAB (hex 09) and NEW- LINE (hex 0A). The spacing interpretation of TAB is context dependent. Other ASCII control characters are explicitly not included in STRING at the present time. COMPOUND_TEXT as a type or a target specifies the Compound Text interchange format; see the 4mCompound24m 4mText24m 4mEncoding24m. 1m240m 1mInter-Client Communication Conventions X11, Release 6.40m UTF8_STRING as a type or a target specifies an UTF-8 encoded string, with NEWLINE (U+000A, hex 0A) as end-of-line marker. There are some text objects where the source or intended user, as the case may be, does not have a specific character set for the text, but instead merely requires a zero-termi- nated sequence of bytes with no other restriction; no ele- ment of the selection mechanism may assume that any byte value is forbidden or that any two differing sequences are equivalent.8 For these objects, the type C_STRING should be used. Rationale An example of the need for C_STRING is to transmit the names of files; many operating systems do not interpret filenames as having a character set. For example, the same character string uses a differ- ent sequence of bytes in ASCII and EBCDIC, and so most operating systems see these as different filenames and offer no way to treat them as the same. Thus no character-set based property type is suitable. Type STRING, COMPOUND_TEXT, UTF8_STRING, and C_STRING prop- erties will consist of a list of elements separated by null characters; other encodings will need to specify an appro- priate list format. 1m2.7.2. INCR Properties0m Requestors may receive a property of type INCR9 in response to any target that results in selection data. This indi- cates that the owner will send the actual data incremen- tally. The contents of the INCR property will be an inte- ger, which represents a lower bound on the number of bytes of data in the selection. The requestor and the selection owner transfer the data in the selection in the following manner. The selection requestor starts the transfer process by deleting the (type==INCR) property forming the reply to the selection. ----------- 8 Note that this is different from STRING, where many byte values are forbidden, and from COM- POUND_TEXT, where, for example, inserting the sequence 27, 40, 66 (designate ASCII into GL) at the start does not alter the meaning. 9 These properties were called INCREMENTAL in an earlier draft. The protocol for using them has changed, and so the name has changed to avoid con- fusion. 1m250m 1mInter-Client Communication Conventions X11, Release 6.40m The selection owner then: · Appends the data in suitable-size chunks to the same property on the same window as the selection reply with a type corresponding to the actual type of the converted selection. The size should be less than the maximum- request-size in the connection handshake. · Waits between each append for a 4mPropertyNo-0m 4mtify24m(state==Deleted) event that shows that the requestor has read the data. The reason for doing this is to limit the consumption of space in the server. · Waits (after the entire data has been transferred to the server) until a 4mPropertyNotify24m(state==Deleted) event that shows that the data has been read by the requestor and then writes zero-length data to the property. The selection requestor: · Waits for the 4mSelectionNotify24m event. · Loops: - Retrieving data using 4mGetProperty24m with the delete argument 4mTrue24m. - Waiting for a 4mPropertyNotify24m with the state argu- ment 4mNewValue24m. · Waits until the property named by the 4mPropertyNotify0m event is zero-length. · Deletes the zero-length property. The type of the converted selection is the type of the first partial property. The remaining partial properties must have the same type. 1m2.7.3. DRAWABLE Properties0m Requestors may receive properties of type PIXMAP, BITMAP, DRAWABLE, or WINDOW, which contain an appropriate ID. While information about these drawables is available from the server by means of the 4mGetGeometry24m request, the following items are not: · Foreground pixel · Background pixel · Colormap ID 1m260m 1mInter-Client Communication Conventions X11, Release 6.40m In general, requestors converting into targets whose returned type in the table in section 2.6.2 is one of the DRAWABLE types should expect to convert also into the fol- lowing targets (using the MULTIPLE mechanism): · FOREGROUND returns a PIXEL value. · BACKGROUND returns a PIXEL value. · COLORMAP returns a colormap ID. 1m2.7.4. SPAN Properties0m Properties with type SPAN contain a list of cardinal-pairs with the length of the cardinals determined by the format. The first specifies the starting position, and the second specifies the ending position plus one. The base is zero. If they are the same, the span is zero-length and is before the specified position. The units are implied by the target atom, such as LINE_NUMBER or CHARACTER_POSITION. 1m2.8. Manager Selections0m Certain clients, often called managers, take on responsibil- ity for managing shared resources. A client that manages a shared resource should take ownership of an appropriate selection, named using the conventions described in sections 1.2.3 and 1.2.6. A client that manages multiple shared resources (or groups of resources) should take ownership of a selection for each one. The manager may support conversion of various targets for that selection. Managers are encouraged to use this tech- nique as the primary means by which clients interact with the managed resource. Note that the conventions for inter- acting with the window manager predate this section; as a result many interactions with the window manager use other techniques. Before a manager takes ownership of a manager selection, it should use the 4mGetSelectionOwner24m request to check whether the selection is already owned by another client, and, where appropriate, it should ask the user if the new manager should replace the old one. If so, it may then take owner- ship of the selection. Managers should acquire the selec- tion using a window created expressly for this purpose. Managers must conform to the rules for selection owners described in sections 2.1 and 2.2, and they must also sup- port the required targets listed in section 2.6.2. If a manager loses ownership of a manager selection, this means that a new manager is taking over its responsibili- ties. The old manager must release all resources it has managed and must then destroy the window that owned the 1m270m 1mInter-Client Communication Conventions X11, Release 6.40m selection. For example, a window manager losing ownership of WM_S2 must deselect from 4mSubstructureRedirect24m on the root window of screen 2 before destroying the window that owned WM_S2. When the new manager notices that the window owning the selection has been destroyed, it knows that it can success- fully proceed to control the resource it is planning to man- age. If the old manager does not destroy the window within a reasonable time, the new manager should check with the user before destroying the window itself or killing the old manager. If a manager wants to give up, on its own, management of a shared resource controlled by a selection, it must do so by releasing the resources it is managing and then by destroy- ing the window that owns the selection. It should not first disown the selection, since this introduces a race condi- tion. Clients who are interested in knowing when the owner of a manager selection is no longer managing the corresponding shared resource should select for 4mStructureNotify24m on the window owning the selection so they can be notified when the window is destroyed. Clients are warned that after doing a 4mGetSelectionOwner24m and selecting for 4mStructureNotify24m, they should do a 4mGetSelectionOwner24m again to ensure that the owner did not change after initially getting the selection owner and before selecting for 4mStructureNotify24m. Immediately after a manager successfully acquires ownership of a manager selection, it should announce its arrival by sending a 4mClientMessage24m event. This event should be sent using the 4mSendEvent24m protocol request with the following arguments: --------------------------------------------------------------- 1mArgument Value0m --------------------------------------------------------------- destination: the root window of screen 0, or the root win- dow of the appropriate screen if the manager is managing a screen-specific resource propagate: False event-mask: 4mStructureNotify0m event: 4mClientMessage0m type: MANAGER format: 32 data[0]:10 timestamp data[1]: manager selection atom data[2]: the window owning the selection data[3]: manager-selection-specific data data[4]: manager-selection-specific data --------------------------------------------------------------- 1m280m 1mInter-Client Communication Conventions X11, Release 6.40m Clients that wish to know when a specific manager has started should select for 4mStructureNotify24m on the appropriate root window and should watch for the appropriate MANAGER 4mClientMessage24m. 1m3. Peer-to-Peer Communication by Means of Cut Buffers0m The cut buffer mechanism is much simpler but much less pow- erful than the selection mechanism. The selection mechanism is active in that it provides a link between the owner and requestor clients. The cut buffer mechanism is passive; an owner places data in a cut buffer from which a requestor retrieves the data at some later time. The cut buffers consist of eight properties on the root of screen zero, named by the predefined atoms CUT_BUFFER0 to CUT_BUFFER7. These properties must, at present, have type STRING and format 8. A client that uses the cut buffer mechanism must initially ensure that all eight properties exist by using 4mChangeProperty24m requests to append zero-length data to each. A client that stores data in the cut buffers (an owner) first must rotate the ring of buffers by plus 1 by using 4mRotateProperties24m requests to rename each buffer; that is, CUT_BUFFER0 to CUT_BUFFER1, CUT_BUFFER1 to CUT_BUFFER2, ..., and CUT_BUFFER7 to CUT_BUFFER0. It then must store the data into CUT_BUFFER0 by using a 4mChangeProperty24m request in mode 4mReplace24m. A client that obtains data from the cut buffers should use a 4mGetProperty24m request to retrieve the contents of CUT_BUFFER0. In response to a specific user request, a client may rotate the cut buffers by minus 1 by using 4mRotateProperties0m requests to rename each buffer; that is, CUT_BUFFER7 to CUT_BUFFER6, CUT_BUFFER6 to CUT_BUFFER5, ..., and CUT_BUFFER0 to CUT_BUFFER7. Data should be stored to the cut buffers and the ring rotated only when requested by explicit user action. Users depend on their mental model of cut buffer operation and need to be able to identify operations that transfer data to and fro. ----------- 10 We use the notation data[n] to indicate the nth element of the LISTofINT8, LISTofINT16, or LISTofINT32 in the data field of the 4mClientMes-0m 4msage24m, according to the format field. The list is indexed from zero. 1m290m 1mInter-Client Communication Conventions X11, Release 6.40m 1m4. Client-to-Window-Manager Communication0m To permit window managers to perform their role of mediating the competing demands for resources such as screen space, the clients being managed must adhere to certain conventions and must expect the window managers to do likewise. These conventions are covered here from the client's point of view. In general, these conventions are somewhat complex and will undoubtedly change as new window management paradigms are developed. Thus, there is a strong bias toward defining only those conventions that are essential and that apply generally to all window management paradigms. Clients designed to run with a particular window manager can easily define private protocols to add to these conventions, but they must be aware that their users may decide to run some other window manager no matter how much the designers of the private protocol are convinced that they have seen the "one true light" of user interfaces. It is a principle of these conventions that a general client should neither know nor care which window manager is running or, indeed, if one is running at all. The conventions do not support all client functions without a window manager running; for example, the concept of Iconic is not directly supported by clients. If no window manager is running, the concept of Iconic does not apply. A goal of the conventions is to make it possible to kill and restart window managers without loss of functionality. Each window manager will implement a particular window man- agement policy; the choice of an appropriate window manage- ment policy for the user's circumstances is not one for an individual client to make but will be made by the user or the user's system administrator. This does not exclude the possibility of writing clients that use a private protocol to restrict themselves to operating only under a specific window manager. Rather, it merely ensures that no claim of general utility is made for such programs. For example, the claim is often made: "The client I'm writ- ing is important, and it needs to be on top." Perhaps it is important when it is being run in earnest, and it should then be run under the control of a window manager that rec- ognizes "important" windows through some private protocol and ensures that they are on top. However, imagine, for example, that the "important" client is being debugged. Then, ensuring that it is always on top is no longer the appropriate window management policy, and it should be run under a window manager that allows other windows (for exam- ple, the debugger) to appear on top. 1m300m 1mInter-Client Communication Conventions X11, Release 6.40m 1m4.1. Client's Actions0m In general, the object of the X Version 11 design is that clients should, as far as possible, do exactly what they would do in the absence of a window manager, except for the following: · Hinting to the window manager about the resources they would like to obtain · Cooperating with the window manager by accepting the resources they are allocated even if they are not those requested · Being prepared for resource allocations to change at any time 1m4.1.1. Creating a Top-Level Window0m A client's 4mtop-level24m 4mwindow24m is a window whose override-redi- rect attribute is 4mFalse24m. It must either be a child of a root window, or it must have been a child of a root window immediately prior to having been reparented by the window manager. If the client reparents the window away from the root, the window is no longer a top-level window; but it can become a top-level window again if the client reparents it back to the root. A client usually would expect to create its top-level win- dows as children of one or more of the root windows by using some boilerplate like the following: win = XCreateSimpleWindow(dpy, DefaultRootWindow(dpy), xsh.x, xsh.y, xsh.width, xsh.height, bw, bd, bg); If a particular one of the root windows was required, how- ever, it could use something like the following: win = XCreateSimpleWindow(dpy, RootWindow(dpy, screen), xsh.x, xsh.y, xsh.width, xsh.height, bw, bd, bg); Ideally, it should be possible to override the choice of a root window and allow clients (including window managers) to treat a nonroot window as a pseudo-root. This would allow, for example, the testing of window managers and the use of application-specific window managers to control the subwin- dows owned by the members of a related suite of clients. Doing so properly requires an extension, the design of which is under study. 1m310m 1mInter-Client Communication Conventions X11, Release 6.40m From the client's point of view, the window manager will regard its top-level window as being in one of three states: · Normal · Iconic · Withdrawn Newly created windows start in the Withdrawn state. Transi- tions between states happen when the top-level window is mapped and unmapped and when the window manager receives certain messages. For further details, see sections 4.1.2.4 and 4.1.4. 1m4.1.2. Client Properties0m Once the client has one or more top-level windows, it should place properties on those windows to inform the window man- ager of the behavior that the client desires. Window man- agers will assume values they find convenient for any of these properties that are not supplied; clients that depend on particular values must explicitly supply them. The win- dow manager will not change properties written by the client. The window manager will examine the contents of these prop- erties when the window makes the transition from the With- drawn state and will monitor some properties for changes while the window is in the Iconic or Normal state. When the client changes one of these properties, it must use 4mReplace0m mode to overwrite the entire property with new data; the window manager will retain no memory of the old value of the property. All fields of the property must be set to suit- able values in a single 4mReplace24m mode 4mChangeProperty24m request. This ensures that the full contents of the property will be available to a new window manager if the existing one crashes, if it is shut down and restarted, or if the session needs to be shut down and restarted by the session manager. Convention Clients writing or rewriting window manager prop- erties must ensure that the entire content of each property remains valid at all times. Some of these properties may contain the IDs of resources, such as windows or pixmaps. Clients should ensure that these resources exist for at least as long as the window on which the property resides. If these properties are longer than expected, clients should ignore the remainder of the property. Extending these 1m320m 1mInter-Client Communication Conventions X11, Release 6.40m properties is reserved to the X Consortium; private exten- sions to them are forbidden. Private additional communica- tion between clients and window managers should take place using separate properties. The only exception to this rule is the WM_PROTOCOLS property, which may be of arbitrary length and which may contain atoms representing private pro- tocols (see section 4.1.2.7). The next sections describe each of the properties the clients need to set, in turn. They are summarized in the table in section 4.4. 1m4.1.2.1. WM_NAME Property0m The WM_NAME property is an uninterpreted string that the client wants the window manager to display in association with the window (for example, in a window headline bar). The encoding used for this string (and all other uninter- preted string properties) is implied by the type of the property. The type atoms to be used for this purpose are described in section 2.7.1. Window managers are expected to make an effort to display this information. Simply ignoring WM_NAME is not acceptable behavior. Clients can assume that at least the first part of this string is visible to the user and that if the infor- mation is not visible to the user, it is because the user has taken an explicit action to make it invisible. On the other hand, there is no guarantee that the user can see the WM_NAME string even if the window manager supports window headlines. The user may have placed the headline off-screen or have covered it by other windows. WM_NAME should not be used for application-critical information or to announce asynchronous changes of an application's state that require timely user response. The expected uses are to permit the user to identify one of a number of instances of the same client and to provide the user with noncritical state information. Even window managers that support headline bars will place some limit on the length of the WM_NAME string that can be visible; brevity here will pay dividends. 1m4.1.2.2. WM_ICON_NAME Property0m The WM_ICON_NAME property is an uninterpreted string that the client wants to be displayed in association with the window when it is iconified (for example, in an icon label). In other respects, including the type, it is similar to WM_NAME. For obvious geometric reasons, fewer characters will normally be visible in WM_ICON_NAME than WM_NAME. 1m330m 1mInter-Client Communication Conventions X11, Release 6.40m Clients should not attempt to display this string in their icon pixmaps or windows; rather, they should rely on the window manager to do so. 1m4.1.2.3. WM_NORMAL_HINTS Property0m The type of the WM_NORMAL_HINTS property is WM_SIZE_HINTS. Its contents are as follows: ------------------------------------------------------------- 1mField Type Comments0m ------------------------------------------------------------- flags CARD32 (see the next table) pad 4*CARD32 For backwards compatibility min_width INT32 If missing, assume base_width min_height INT32 If missing, assume base_height max_width INT32 max_height INT32 width_inc INT32 height_inc INT32 min_aspect (INT32,INT32) max_aspect (INT32,INT32) base_width INT32 If missing, assume min_width base_height INT32 If missing, assume min_height win_gravity INT32 If missing, assume 4mNorthWest0m ------------------------------------------------------------- The WM_SIZE_HINTS.flags bit definitions are as follows: ----------------------------------------------------------------- 1mName Value Field0m ----------------------------------------------------------------- 4mUSPosition24m 1 User-specified x, y 4mUSSize24m 2 User-specified width, height 4mPPosition24m 4 Program-specified position 4mPSize24m 8 Program-specified size 4mPMinSize24m 16 Program-specified minimum size 4mPMaxSize24m 32 Program-specified maximum size 4mPResizeInc24m 64 Program-specified resize increments 4mPAspect24m 128 Program-specified min and max aspect ratios 4mPBaseSize24m 256 Program-specified base size 4mPWinGrav-24m 512 Program-specified window gravity 4mity0m ----------------------------------------------------------------- To indicate that the size and position of the window (when a transition from the Withdrawn state occurs) was specified by the user, the client should set the 4mUSPosition24m and 4mUSSize0m flags, which allow a window manager to know that the user specifically asked where the window should be placed or how the window should be sized and that further interaction is superfluous. To indicate that it was specified by the 1m340m 1mInter-Client Communication Conventions X11, Release 6.40m client without any user involvement, the client should set 4mPPosition24m and 4mPSize24m. The size specifiers refer to the width and height of the client's window excluding borders. The win_gravity may be any of the values specified for WINGRAVITY in the core protocol except for 4mUnmap24m: 4mNorthWest0m (1), 4mNorth24m (2), 4mNorthEast24m (3), 4mWest24m (4), 4mCenter24m (5), 4mEast0m (6), 4mSouthWest24m (7), 4mSouth24m (8), and 4mSouthEast24m (9). It speci- fies how and whether the client window wants to be shifted to make room for the window manager frame. If the win_gravity is 4mStatic24m, the window manager frame is positioned so that the inside border of the client window inside the frame is in the same position on the screen as it was when the client requested the transition from Withdrawn state. Other values of win_gravity specify a window refer- ence point. For 4mNorthWest24m, 4mNorthEast24m, 4mSouthWest24m, and 4mSouth-0m 4mEast24m the reference point is the specified outer corner of the window (on the outside border edge). For 4mNorth24m, 4mSouth24m, 4mEast24m, and 4mWest24m the reference point is the center of the specified outer edge of the window border. For 4mCenter24m the reference point is the center of the window. The reference point of the window manager frame is placed at the location on the screen where the reference point of the client window was when the client requested the transition from Withdrawn state. The min_width and min_height elements specify the minimum size that the window can be for the client to be useful. The max_width and max_height elements specify the maximum size. The base_width and base_height elements in conjunc- tion with width_inc and height_inc define an arithmetic pro- gression of preferred window widths and heights for non-neg- ative integers 4mi24m and 4mj24m: 4mwidth24m=4mbase24m_4mwidth24m+(4mi24m×4mwidth24m_4minc24m) 4mheight24m=4mbase24m_4mheight24m+(4mj24m×4mheight24m_4minc24m) Window managers are encouraged to use 4mi24m and 4mj24m instead of width and height in reporting window sizes to users. If a base size is not provided, the minimum size is to be used in its place and vice versa. The min_aspect and max_aspect fields are fractions with the numerator first and the denominator second, and they allow a client to specify the range of aspect ratios it prefers. 1m350m 1mInter-Client Communication Conventions X11, Release 6.40m Window managers that honor aspect ratios should take into account the base size in determining the preferred window size. If a base size is provided along with the aspect ratio fields, the base size should be subtracted from the window size prior to checking that the aspect ratio falls in range. If a base size is not provided, nothing should be subtracted from the window size. (The minimum size is not to be used in place of the base size for this purpose.) 1m4.1.2.4. WM_HINTS Property0m The WM_HINTS property (whose type is WM_HINTS) is used to communicate to the window manager. It conveys the informa- tion the window manager needs other than the window geome- try, which is available from the window itself; the con- straints on that geometry, which is available from the WM_NORMAL_HINTS structure; and various strings, which need separate properties, such as WM_NAME. The contents of the properties are as follows: ----------------------------------------------------------- 1mField Type Comments0m ----------------------------------------------------------- flags CARD32 (see the next table) input CARD32 The client's input model initial_state CARD32 The state when first mapped icon_pixmap PIXMAP The pixmap for the icon image icon_window WINDOW The window for the icon image icon_x INT32 The icon location icon_y INT32 icon_mask PIXMAP The mask for the icon shape window_group WINDOW The ID of the group leader window ----------------------------------------------------------- The WM_HINTS.flags bit definitions are as follows: ------------------------------------------------- 1mName Value Field0m ------------------------------------------------- 4mInputHint24m 1 input 4mStateHint24m 2 initial_state 4mIconPixmapHint24m 4 icon_pixmap 4mIconWindowHint24m 8 icon_window 4mIconPosition-24m 16 icon_x & icon_y 4mHint0m 4mIconMaskHint24m 32 icon_mask 4mWindowGroupHint24m 64 window_group 4mMessageHint24m 128 (this bit is obsolete) 4mUrgencyHint24m 256 urgency ------------------------------------------------- 1m360m 1mInter-Client Communication Conventions X11, Release 6.40m Window managers are free to assume convenient values for all fields of the WM_HINTS property if a window is mapped with- out one. The input field is used to communicate to the window manager the input focus model used by the client (see section 4.1.7). Clients with the Globally Active and No Input models should set the input flag to 4mFalse24m. Clients with the Passive and Locally Active models should set the input flag to 4mTrue24m. From the client's point of view, the window manager will regard the client's top-level window as being in one of three states: · Normal · Iconic · Withdrawn The semantics of these states are described in section 4.1.4. Newly created windows start in the Withdrawn state. Transitions between states happen when a top-level window is mapped and unmapped and when the window manager receives certain messages. The value of the initial_state field determines the state the client wishes to be in at the time the top-level window is mapped from the Withdrawn state, as shown in the follow- ing table: --------------------------------------------- 1mState Value Comments0m --------------------------------------------- 4mNormalState24m 1 The window is visible. 4mIconicState24m 3 The icon is visible. --------------------------------------------- The icon_pixmap field may specify a pixmap to be used as an icon. This pixmap should be: · One of the sizes specified in the WM_ICON_SIZE property on the root if it exists (see section 4.1.3.2). · 1-bit deep. The window manager will select, through the defaults database, suitable background (for the 0 bits) and foreground (for the 1 bits) colors. These defaults can, of course, specify different colors for the icons of different clients. 1m370m 1mInter-Client Communication Conventions X11, Release 6.40m The icon_mask specifies which pixels of the icon_pixmap should be used as the icon, allowing for icons to appear nonrectangular. The icon_window field is the ID of a window the client wants used as its icon. Most, but not all, window managers will support icon windows. Those that do not are likely to have a user interface in which small windows that behave like icons are completely inappropriate. Clients should not attempt to remedy the omission by working around it. Clients that need more capabilities from the icons than a simple 2-color bitmap should use icon windows. Rules for clients that do are set out in section 4.1.9. The (icon_x,icon_y) coordinate is a hint to the window man- ager as to where it should position the icon. The policies of the window manager control the positioning of icons, so clients should not depend on attention being paid to this hint. The window_group field lets the client specify that this window belongs to a group of windows. An example is a sin- gle client manipulating multiple children of the root win- dow. Conventions 1. The window_group field should be set to the ID of the group leader. The window group leader may be a window that exists only for that purpose; a placeholder group leader of this kind would never be mapped either by the client or by the window manager. 2. The properties of the window group leader are those for the group as a whole (for example, the icon to be shown when the entire group is iconified). Window managers may provide facilities for manipulating the group as a whole. Clients, at present, have no way to oper- ate on the group as a whole. The messages bit, if set in the flags field, indicates that the client is using an obsolete window manager communication protocol,11 rather than the WM_PROTOCOLS mechanism of sec- tion 4.1.2.7. ----------- 11 This obsolete protocol was described in the July 27, 1988, draft of the ICCCM. Windows using it can also be detected because their WM_HINTS 1m380m 1mInter-Client Communication Conventions X11, Release 6.40m The 4mUrgencyHint24m flag, if set in the flags field, indicates that the client deems the window contents to be urgent, requiring the timely response of the user. The window man- ager must make some effort to draw the user's attention to this window while this flag is set. The window manager must also monitor the state of this flag for the entire time the window is in the Normal or Iconic state and must take appro- priate action when the state of the flag changes. The flag is otherwise independent of the window's state; in particu- lar, the window manager is not required to deiconify the window if the client sets the flag on an Iconic window. Clients must provide some means by which the user can cause the 4mUrgencyHint24m flag to be set to zero or the window to be withdrawn. The user's action can either mitigate the actual condition that made the window urgent, or it can merely shut off the alarm. Rationale This mechanism is useful for alarm dialog boxes or reminder windows, in cases where mapping the win- dow is not enough (e.g., in the presence of multi- workspace or virtual desktop window managers), and where using an override-redirect window is too intrusive. For example, the window manager may attract attention to an urgent window by adding an indicator to its title bar or its icon. Window managers may also take additional action for a window that is newly urgent, such as by flashing its icon (if the window is iconic) or by raising it to the top of the stack. 1m4.1.2.5. WM_CLASS Property0m The WM_CLASS property (of type STRING without control char- acters) contains two consecutive null-terminated strings. These specify the Instance and Class names to be used by both the client and the window manager for looking up resources for the application or as identifying information. This property must be present when the window leaves the Withdrawn state and may be changed only while the window is in the Withdrawn state. Window managers may examine the property only when they start up and when the window leaves the Withdrawn state, but there should be no need for a client to change its state dynamically. The two strings, respectively, are: ----------- properties are 4 bytes longer than expected. Win- dow managers are free to support clients using the obsolete protocol in a backwards compatibility mode. 1m390m 1mInter-Client Communication Conventions X11, Release 6.40m · A string that names the particular instance of the application to which the client that owns this window belongs. Resources that are specified by instance name override any resources that are specified by class name. Instance names can be specified by the user in an oper- ating-system specific manner. On POSIX-conformant sys- tems, the following conventions are used: - If "-name NAME" is given on the command line, NAME is used as the instance name. - Otherwise, if the environment variable RESOURCE_NAME is set, its value will be used as the instance name. - Otherwise, the trailing part of the name used to invoke the program (argv[0] stripped of any direc- tory names) is used as the instance name. · A string that names the general class of applications to which the client that owns this window belongs. Resources that are specified by class apply to all applications that have the same class name. Class names are specified by the application writer. Examples of commonly used class names include: "Emacs", "XTerm", "XClock", "XLoad", and so on. Note that WM_CLASS strings are null-terminated and, thus, differ from the general conventions that STRING properties are null-separated. This inconsistency is necessary for backwards compatibility. 1m4.1.2.6. WM_TRANSIENT_FOR Property0m The WM_TRANSIENT_FOR property (of type WINDOW) contains the ID of another top-level window. The implication is that this window is a pop-up on behalf of the named window, and window managers may decide not to decorate transient windows or may treat them differently in other ways. In particular, window managers should present newly mapped WM_TRANSIENT_FOR windows without requiring any user interaction, even if map- ping top-level windows normally does require interaction. Dialogue boxes, for example, are an example of windows that should have WM_TRANSIENT_FOR set. It is important not to confuse WM_TRANSIENT_FOR with over- ride-redirect. WM_TRANSIENT_FOR should be used in those cases where the pointer is not grabbed while the window is mapped (in other words, if other windows are allowed to be active while the transient is up). If other windows must be prevented from processing input (for example, when imple- menting pop-up menus), use override-redirect and grab the pointer while the window is mapped. 1m400m 1mInter-Client Communication Conventions X11, Release 6.40m 1m4.1.2.7. WM_PROTOCOLS Property0m The WM_PROTOCOLS property (of type ATOM) is a list of atoms. Each atom identifies a communication protocol between the client and the window manager in which the client is willing to participate. Atoms can identify both standard protocols and private protocols specific to individual window man- agers. All the protocols in which a client can volunteer to take part involve the window manager sending the client a 4mClientMessage24m event and the client taking appropriate action. For details of the contents of the event, see sec- tion 4.2.8. In each case, the protocol transactions are initiated by the window manager. The WM_PROTOCOLS property is not required. If it is not present, the client does not want to participate in any win- dow manager protocols. The X Consortium will maintain a registry of protocols to avoid collisions in the name space. The following table lists the protocols that have been defined to date. ----------------------------------------------------------------------- 1mProtocol Section Purpose0m ----------------------------------------------------------------------- WM_TAKE_FOCUS 4.1.7 Assignment of input focus WM_SAVE_YOURSELF Appendix C Save client state request (deprecated) WM_DELETE_WINDOW 4.2.8.1 Request to delete top-level window ----------------------------------------------------------------------- It is expected that this table will grow over time. 1m4.1.2.8. WM_COLORMAP_WINDOWS Property0m The WM_COLORMAP_WINDOWS property (of type WINDOW) on a top- level window is a list of the IDs of windows that may need colormaps installed that differ from the colormap of the top-level window. The window manager will watch this list of windows for changes in their colormap attributes. The top-level window is always (implicitly or explicitly) on the watch list. For the details of this mechanism, see section 4.1.8. 1m4.1.2.9. WM_CLIENT_MACHINE Property0m The client should set the WM_CLIENT_MACHINE property (of one of the TEXT types) to a string that forms the name of the machine running the client as seen from the machine running the server. 1m410m 1mInter-Client Communication Conventions X11, Release 6.40m 1m4.1.3. Window Manager Properties0m The properties that were described in the previous section are those that the client is responsible for maintaining on its top-level windows. This section describes the proper- ties that the window manager places on client's top-level windows and on the root. 1m4.1.3.1. WM_STATE Property0m The window manager will place a WM_STATE property (of type WM_STATE) on each top-level client window that is not in the Withdrawn state. Top-level windows in the Withdrawn state may or may not have the WM_STATE property. Once the top- level window has been withdrawn, the client may re-use it for another purpose. Clients that do so should remove the WM_STATE property if it is still present. Some clients (such as 1mxprop22m) will ask the user to click over a window on which the program is to operate. Typically, the intent is for this to be a top-level window. To find a top- level window, clients should search the window hierarchy beneath the selected location for a window with the WM_STATE property. This search must be recursive in order to cover all window manager reparenting possibilities. If no window with a WM_STATE property is found, it is recommended that programs use a mapped child-of-root window if one is present beneath the selected location. The contents of the WM_STATE property are defined as fol- lows: -------------------------------------- 1mField Type Comments0m -------------------------------------- state CARD32 (see the next table) icon WINDOW ID of icon window -------------------------------------- The following table lists the WM_STATE.state values: ----------------------- 1mState Value0m ----------------------- 4mWithdrawnState24m 0 4mNormalState24m 1 4mIconicState24m 3 ----------------------- Adding other fields to this property is reserved to the X Consortium. Values for the state field other than those defined in the above table are reserved for use by the X 1m420m 1mInter-Client Communication Conventions X11, Release 6.40m Consortium. The state field describes the window manager's idea of the state the window is in, which may not match the client's idea as expressed in the initial_state field of the WM_HINTS property (for example, if the user has asked the window man- ager to iconify the window). If it is 4mNormalState24m, the win- dow manager believes the client should be animating its win- dow. If it is 4mIconicState24m, the client should animate its icon window. In either state, clients should be prepared to handle exposure events from either window. When the window is withdrawn, the window manager will either change the state field's value to 4mWithdrawnState24m or it will remove the WM_STATE property entirely. The icon field should contain the window ID of the window that the window manager uses as the icon for the window on which this property is set. If no such window exists, the icon field should be 4mNone24m. Note that this window could be but is not necessarily the same window as the icon window that the client may have specified in its WM_HINTS property. The WM_STATE icon may be a window that the window manager has supplied and that contains the client's icon pixmap, or it may be an ancestor of the client's icon window. 1m4.1.3.2. WM_ICON_SIZE Property0m A window manager that wishes to place constraints on the sizes of icon pixmaps and/or windows should place a property called WM_ICON_SIZE on the root. The contents of this prop- erty are listed in the following table. -------------------------------------------------------- 1mField Type Comments0m -------------------------------------------------------- min_width CARD32 The data for the icon size series min_height CARD32 max_width CARD32 max_height CARD32 width_inc CARD32 height_inc CARD32 -------------------------------------------------------- For more details see section 14.1.12 in 4mXlib24m 4m-24m 4mC24m 4mLanguage24m 4mX0m 4mInterface24m. 1m4.1.4. Changing Window State0m From the client's point of view, the window manager will regard each of the client's top-level windows as being in one of three states, whose semantics are as follows: 1m430m 1mInter-Client Communication Conventions X11, Release 6.40m · 4mNormalState24m - The client's top-level window is viewable. · 4mIconicState24m - The client's top-level window is iconic (whatever that means for this window manager). The client can assume that its top-level window is not view- able, its icon_window (if any) will be viewable and, failing that, its icon_pixmap (if any) or its WM_ICON_NAME will be displayed. · 4mWithdrawnState24m - Neither the client's top-level window nor its icon is visible. In fact, the window manager may implement states with seman- tics other than those described above. For example, a win- dow manager might implement a concept of an "inactive" state in which an infrequently used client's window would be rep- resented as a string in a menu. But this state is invisible to the client, which would see itself merely as being in the Iconic state. Newly created top-level windows are in the Withdrawn state. Once the window has been provided with suitable properties, the client is free to change its state as follows: · Withdrawn -> Normal - The client should map the window with WM_HINTS.initial_state being 4mNormalState24m. · Withdrawn -> Iconic - The client should map the window with WM_HINTS.initial_state being 4mIconicState24m. · Normal -> Iconic - The client should send a 4mClientMes-0m 4msage24m event as described later in this section. · Normal -> Withdrawn - The client should unmap the window and follow it with a synthetic 4mUnmapNotify24m event as described later in this section. · Iconic -> Normal - The client should map the window. The contents of WM_HINTS.initial_state are irrelevant in this case. · Iconic -> Withdrawn - The client should unmap the window and follow it with a synthetic 4mUnmapNotify24m event as described later in this section. Only the client can effect a transition into or out of the Withdrawn state. Once a client's window has left the With- drawn state, the window will be mapped if it is in the Nor- mal state and the window will be unmapped if it is in the Iconic state. Reparenting window managers must unmap the client's window when it is in the Iconic state, even if an ancestor window being unmapped renders the client's window unviewable. Conversely, if a reparenting window manager renders the client's window unviewable by unmapping an 1m440m 1mInter-Client Communication Conventions X11, Release 6.40m ancestor, the client's window is by definition in the Iconic state and must also be unmapped. Advice to Implementors Clients can select for 4mStructureNotify24m on their top-level windows to track transitions between Normal and Iconic states. Receipt of a 4mMapNotify0m event will indicate a transition to the Normal state, and receipt of an 4mUnmapNotify24m event will indicate a transition to the Iconic state. When changing the state of the window to Withdrawn, the client must (in addition to unmapping the window) send a synthetic 4mUnmapNotify24m event by using a 4mSendEvent24m request with the following arguments: ---------------------------------------------------------- 1mArgument Value0m ---------------------------------------------------------- destination: The root propagate: 4mFalse0m event-mask: (4mSubstructureRedirect|Substruc-0m 4mtureNotify24m) event: an 4mUnmapNo-0m 4mtify24m with: event: The root window: The window itself from-configure: 4mFalse0m ---------------------------------------------------------- Rationale The reason for requiring the client to send a syn- thetic 4mUnmapNotify24m event is to ensure that the window manager gets some notification of the client's desire to change state, even though the window may already be unmapped when the desire is expressed. Advice to Implementors For compatibility with obsolete clients, window managers should trigger the transition to the Withdrawn state on the real 4mUnmapNotify24m rather than waiting for the synthetic one. They should also trigger the transition if they receive a syn- thetic 4mUnmapNotify24m on a window for which they have not yet received a real 4mUnmapNotify24m. 1m450m 1mInter-Client Communication Conventions X11, Release 6.40m When a client withdraws a window, the window manager will then update or remove the WM_STATE property as described in section 4.1.3.1. Clients that want to re-use a client win- dow (e.g., by mapping it again or reparenting it elsewhere) after withdrawing it must wait for the withdrawal to be com- plete before proceeding. The preferred method for doing this is for clients to wait for the window manager to update or remove the WM_STATE property.12 If the transition is from the Normal to the Iconic state, the client should send a 4mClientMessage24m event to the root with: · Window == the window to be iconified · Type13 == the atom WM_CHANGE_STATE · Format == 32 · Data[0] == IconicState Rationale The format of this 4mClientMessage24m event does not match the format of 4mClientMessages24m in sec- tion 4.2.8. This is because they are sent by the window manager to clients, and this mes- sage is sent by clients to the window manager. Other values of data[0] are reserved for future extensions to these conventions. The parameters of the 4mSendEvent0m request should be those described for the synthetic 4mUnmapNo-0m 4mtify24m event. ----------- 12 Earlier versions of these conventions prohib- ited clients from reading the WM_STATE property. Clients operating under the earlier conventions used the technique of tracking 4mReparentNotify0m events to wait for the top-level window to be reparented back to the root window. This is still a valid technique; however, it works only for reparenting window managers, and the WM_STATE technique is to be preferred. 13 The type field of the 4mClientMessage24m event (called the message_type field by Xlib) should not be confused with the code field of the event itself, which will have the value 33 (4mClientMes-0m 4msage24m). 1m460m 1mInter-Client Communication Conventions X11, Release 6.40m Advice to Implementors Clients can also select for 4mVisibilityChange0m events on their top-level or icon windows. They will then receive a 4mVisibilityNotify24m(state==Fully- Obscured) event when the window concerned becomes completely obscured even though mapped (and thus, perhaps a waste of time to update) and a 4mVisibili-0m 4mtyNotify24m(state!=FullyObscured) event when it becomes even partly viewable. Advice to Implementors When a window makes a transition from the Normal state to either the Iconic or the Withdrawn state, clients should be aware that the window manager may make transients for this window inaccessible. Clients should not rely on transient windows being available to the user when the transient owner window is not in the Normal state. When withdraw- ing a window, clients are advised to withdraw transients for the window. 1m4.1.5. Configuring the Window0m Clients can resize and reposition their top-level windows by using the 4mConfigureWindow24m request. The attributes of the window that can be altered with this request are as follows: · The [x,y] location of the window's upper left-outer cor- ner · The [width,height] of the inner region of the window (excluding borders) · The border width of the window · The window's position in the stack The coordinate system in which the location is expressed is that of the root (irrespective of any reparenting that may have occurred). The border width to be used and win_gravity position hint to be used are those most recently requested by the client. Client configure requests are interpreted by the window manager in the same manner as the initial window geometry mapped from the Withdrawn state, as described in section 4.1.2.3. Clients must be aware that there is no guarantee that the window manager will allocate them the requested size or location and must be prepared to deal with any size and location. If the window manager decides to respond to a 4mConfigureRequest24m request by: 1m470m 1mInter-Client Communication Conventions X11, Release 6.40m · Not changing the size, location, border width, or stack- ing order of the window at all. A client will receive a synthetic 4mConfigureNotify24m event that describes the (unchanged) geometry of the window. The (x,y) coordinates will be in the root coordinate system, adjusted for the border width the client requested, irrespective of any reparenting that has taken place. The border_width will be the border width the client requested. The client will not receive a real 4mConfigureNotify24m event because no change has actu- ally taken place. · Moving or restacking the window without resizing it or changing its border width. A client will receive a synthetic 4mConfigureNotify24m event following the change that describes the new geometry of the window. The event's (x,y) coordinates will be in the root coordinate system adjusted for the border width the client requested. The border_width will be the bor- der width the client requested. The client may not receive a real 4mConfigureNotify24m event that describes this change because the window manager may have reparented the top-level window. If the client does receive a real event, the synthetic event will follow the real one. · Resizing the window or changing its border width (regardless of whether the window was also moved or restacked). A client that has selected for 4mStructureNotify24m events will receive a real 4mConfigureNotify24m event. Note that the coordinates in this event are relative to the par- ent, which may not be the root if the window has been reparented. The coordinates will reflect the actual border width of the window (which the window manager may have changed). The 4mTranslateCoordinates24m request can be used to convert the coordinates if required. The general rule is that coordinates in real 4mConfigureNotify0m events are in the parent's space; in synthetic events, they are in the root space. Advice to Implementors Clients cannot distinguish between the case where a top-level window is resized and moved from the case where the window is resized but not moved, since a real 4mConfigureNotify24m event will be received in both cases. Clients that are con- cerned with keeping track of the absolute position of a top-level window should keep a piece of state indicating whether they are certain of its 1m480m 1mInter-Client Communication Conventions X11, Release 6.40m position. Upon receipt of a real 4mConfigureNotify0m event on the top-level window, the client should note that the position is unknown. Upon receipt of a synthetic 4mConfigureNotify24m event, the client should note the position as known, using the posi- tion in this event. If the client receives a 4mKey-0m 4mPress24m, 4mKeyRelease24m, 4mButtonPress24m, 4mButtonRelease24m, 4mMotionNotify24m, 4mEnterNotify24m, or 4mLeaveNotify24m event on the window (or on any descendant), the client can deduce the top-level window's position from the difference between the (event-x, event-y) and (root-x, root-y) coordinates in these events. Only when the position is unknown does the client need to use the 4mTranslateCoordinates24m request to find the position of a top-level window. Clients should be aware that their borders may not be visi- ble. Window managers are free to use reparenting techniques to decorate client's top-level windows with borders contain- ing titles, controls, and other details to maintain a con- sistent look-and-feel. If they do, they are likely to over- ride the client's attempts to set the border width and set it to zero. Clients, therefore, should not depend on the top-level window's border being visible or use it to display any critical information. Other window managers will allow the top-level windows border to be visible. Convention Clients should set the desired value of the bor- der-width attribute on all 4mConfigureWindow0m requests to avoid a race condition. Clients that change their position in the stack must be aware that they may have been reparented, which means that windows that used to be siblings no longer are. Using a nonsibling as the sibling parameter on a 4mConfigureWindow0m request will cause an error. Convention Clients that use a 4mConfigureWindow24m request to request a change in their position in the stack should do so using 4mNone24m in the sibling field. Clients that must position themselves in the stack relative to some window that was originally a sibling must do the 4mConfigureWindow24m request (in case they are running under a nonreparenting window manager), be prepared to deal with a resulting error, and then follow with a synthetic 4mConfigur-0m 4meRequest24m event by invoking a 4mSendEvent24m request with the 1m490m 1mInter-Client Communication Conventions X11, Release 6.40m following arguments: --------------------------------------------------------- 1mArgument Value0m --------------------------------------------------------- destination: The root propagate: 4mFalse0m event-mask: (4mSubstructureRedirect|Substruc-0m 4mtureNotify24m) event: a 4mConfigur-0m 4meRequest24m with: event: The root window: The window itself ... Other parameters from the 4mConfig-0m 4mureWindow24m request --------------------------------------------------------- Window managers are in any case free to position windows in the stack as they see fit, and so clients should not rely on receiving the stacking order they have requested. Clients should ignore the above-sibling field of both real and syn- thetic 4mConfigureNotify24m events received on their top-level windows because this field may not contain useful informa- tion. 1m4.1.6. Changing Window Attributes0m The attributes that may be supplied when a window is created may be changed by using the 4mChangeWindowAttributes24m request. The window attributes are listed in the following table: ------------------------------------------- 1mAttribute Private to Client0m ------------------------------------------- Background pixmap Yes Background pixel Yes Border pixmap Yes Border pixel Yes Bit gravity Yes Window gravity No Backing-store hint Yes Save-under hint No Event mask No Do-not-propagate mask Yes Override-redirect flag No Colormap Yes Cursor Yes ------------------------------------------- Most attributes are private to the client and will never be interfered with by the window manager. For the attributes that are not private to the client: 1m500m 1mInter-Client Communication Conventions X11, Release 6.40m · The window manager is free to override the window grav- ity; a reparenting window manager may want to set the top-level window's window gravity for its own purposes. · Clients are free to set the save-under hint on their top-level windows, but they must be aware that the hint may be overridden by the window manager. · Windows, in effect, have per-client event masks, and so, clients may select for whatever events are convenient irrespective of any events the window manager is select- ing for. There are some events for which only one client at a time may select, but the window manager should not select for them on any of the client's win- dows. · Clients can set override-redirect on top-level windows but are encouraged not to do so except as described in sections 4.1.10 and 4.2.9. 1m4.1.7. Input Focus0m There are four models of input handling: · No Input - The client never expects keyboard input. An example would be 4mxload24m or another output-only client. · Passive Input - The client expects keyboard input but never explicitly sets the input focus. An example would be a simple client with no subwindows, which will accept input in 4mPointerRoot24m mode or when the window manager sets the input focus to its top-level window (in click- to-type mode). · Locally Active Input - The client expects keyboard input and explicitly sets the input focus, but it only does so when one of its windows already has the focus. An exam- ple would be a client with subwindows defining various data entry fields that uses Next and Prev keys to move the input focus between the fields. It does so when its top-level window has acquired the focus in 4mPointerRoot0m mode or when the window manager sets the input focus to its top-level window (in click-to-type mode). · Globally Active Input - The client expects keyboard input and explicitly sets the input focus, even when it is in windows the client does not own. An example would be a client with a scroll bar that wants to allow users to scroll the window without disturbing the input focus even if it is in some other window. It wants to acquire the input focus when the user clicks in the scrolled region but not when the user clicks in the scroll bar itself. Thus, it wants to prevent the window manager from setting the input focus to any of its windows. 1m510m 1mInter-Client Communication Conventions X11, Release 6.40m The four input models and the corresponding values of the input field and the presence or absence of the WM_TAKE_FOCUS atom in the WM_PROTOCOLS property are listed in the follow- ing table: ---------------------------------------------- 1mInput Model Input Field WM_TAKE_FOCUS0m ---------------------------------------------- No Input 4mFalse24m Absent Passive 4mTrue24m Absent Locally Active 4mTrue24m Present Globally Active 4mFalse24m Present ---------------------------------------------- Passive and Locally Active clients set the input field of WM_HINTS to 4mTrue24m, which indicates that they require window manager assistance in acquiring the input focus. No Input and Globally Active clients set the input field to 4mFalse24m, which requests that the window manager not set the input focus to their top-level window. Clients that use a 4mSetInputFocus24m request must set the time field to the timestamp of the event that caused them to make the attempt. This cannot be a 4mFocusIn24m event because they do not have timestamps. Clients may also acquire the focus without a corresponding 4mEnterNotify24m. Note that clients must not use 4mCurrentTime24m in the time field. Clients using the Globally Active model can only use a 4mSet-0m 4mInputFocus24m request to acquire the input focus when they do not already have it on receipt of one of the following events: · 4mButtonPress0m · 4mButtonRelease0m · Passive-grabbed 4mKeyPress0m · Passive-grabbed 4mKeyRelease0m In general, clients should avoid using passive-grabbed key events for this purpose, except when they are unavoidable (as, for example, a selection tool that establishes a pas- sive grab on the keys that cut, copy, or paste). The method by which the user commands the window manager to set the focus to a window is up to the window manager. For example, clients cannot determine whether they will see the click that transfers the focus. Windows with the atom WM_TAKE_FOCUS in their WM_PROTOCOLS property may receive a 4mClientMessage24m event from the window 1m520m 1mInter-Client Communication Conventions X11, Release 6.40m manager (as described in section 4.2.8) with WM_TAKE_FOCUS in its data[0] field and a valid timestamp (i.e., not 4mCur-0m 4mrentTime24m) in its data[1] field. If they want the focus, they should respond with a 4mSetInputFocus24m request with its window field set to the window of theirs that last had the input focus or to their default input window, and the time field set to the timestamp in the message. For further information, see section 4.2.7. A client could receive WM_TAKE_FOCUS when opening from an icon or when the user has clicked outside the top-level win- dow in an area that indicates to the window manager that it should assign the focus (for example, clicking in the head- line bar can be used to assign the focus). The goal is to support window managers that want to assign the input focus to a top-level window in such a way that the top-level window either can assign it to one of its subwin- dows or can decline the offer of the focus. For example, a clock or a text editor with no currently open frames might not want to take focus even though the window manager gener- ally believes that clients should take the input focus after being deiconified or raised. Clients that set the input focus need to decide a value for the revert-to field of the 4mSetInputFocus24m request. This determines the behavior of the input focus if the window the focus has been set to becomes not viewable. The value can be any of the following: · 4mParent24m - In general, clients should use this value when assigning focus to one of their subwindows. Unmapping the subwindow will cause focus to revert to the parent, which is probably what you want. · 4mPointerRoot24m - Using this value with a click-to-type focus management policy leads to race conditions because the window becoming unviewable may coincide with the window manager deciding to move the focus elsewhere. · 4mNone24m - Using this value causes problems if the window manager reparents the window, as most window managers will, and then crashes. The input focus will be 4mNone24m, and there will probably be no way to change it. Note that neither 4mPointerRoot24m nor 4mNone24m is really safe to use. Convention Clients that invoke a 4mSetInputFocus24m request should set the revert-to argument to 4mParent24m. 1m530m 1mInter-Client Communication Conventions X11, Release 6.40m A convention is also required for clients that want to give up the input focus. There is no safe value set for them to set the input focus to; therefore, they should ignore input material. Convention Clients should not give up the input focus of their own volition. They should ignore input that they receive instead. 1m4.1.8. Colormaps0m The window manager is responsible for installing and unin- stalling colormaps on behalf of clients with top-level win- dows that the window manager manages. Clients provide the window manager with hints as to which colormaps to install and uninstall. Clients must not install or uninstall colormaps themselves (except under the circumstances noted below). When a client's top-level win- dow gets the colormap focus (as a result of whatever col- ormap focus policy is implemented by the window manager), the window manager will ensure that one or more of the client's colormaps are installed. Clients whose top-level windows and subwindows all use the same colormap should set its ID in the colormap field of the top-level window's attributes. They should not set a WM_COLORMAP_WINDOWS property on the top-level window. If they want to change the colormap, they should change the top-level window's colormap attribute. The window manager will track changes to the window's colormap attribute and install colormaps as appropriate. Clients that create windows can use the value 4mCopyFromParent0m to inherit their parent's colormap. Window managers will ensure that the root window's colormap field contains a col- ormap that is suitable for clients to inherit. In particu- lar, the colormap will provide distinguishable colors for 4mBlackPixel24m and 4mWhitePixel24m. Top-level windows that have subwindows or override-redirect pop-up windows whose colormap requirements differ from the top-level window should have a WM_COLORMAP_WINDOWS property. This property contains a list of IDs for windows whose col- ormaps the window manager should attempt to have installed when, in the course of its individual colormap focus policy, it assigns the colormap focus to the top-level window (see section 4.1.2.8). The list is ordered by the importance to the client of having the colormaps installed. The window manager will track changes to this property and will track changes to the colormap attribute of the windows in the 1m540m 1mInter-Client Communication Conventions X11, Release 6.40m property. If the relative importance of colormaps changes, the client should update the WM_COLORMAP_WINDOWS property to reflect the new ordering. If the top-level window does not appear in the list, the window manager will assume it to be of higher priority than any window in the list. WM_TRANSIENT_FOR windows can either have their own WM_COL- ORMAP_WINDOWS property or appear in the property of the win- dow they are transient for, as appropriate. Rationale An alternative design was considered for how clients should hint to the window manager about their colormap requirements. This alternative design specified a list of colormaps instead of a list of windows. The current design, a list of windows, was chosen for two reasons. First, it allows window managers to find the visuals of the colormaps, thus permitting visual-dependent col- ormap installation policies. Second, it allows window managers to select for 4mVisibilityChange0m events on the windows concerned and to ensure that colormaps are only installed if the windows that need them are visible. The alternative design allows for neither of these policies. Advice to Implementors Clients should be aware of the min-installed-maps and max-installed-maps fields of the connection setup information, and the effect that the minimum value has on the "required list" defined by the Protocol in the description of the 4mInstallColormap0m request. Briefly, the min-installed-maps most recently installed maps are guaranteed to be installed. This value is often one; clients need- ing multiple colormaps should beware. Whenever possible, clients should use the mechanisms described above and let the window manager handle colormap installation. However, clients are permitted to perform colormap installation on their own while they have the pointer grabbed. A client performing colormap installation must notify the window manager prior to the first installa- tion. When the client has finished its colormap installa- tion, it must also notify the window manager. The client notifies the window manager by issuing a 4mSendEvent24m request with the following arguments: 1m550m 1mInter-Client Communication Conventions X11, Release 6.40m ---------------------------------------------------------- 1mArgument Value0m ---------------------------------------------------------- destination: the root window of the screen on which the colormap is being installed propagate: 4mFalse0m event-mask: 4mColormapChange0m event: a 4mClientMes-0m 4msage24m with: window: the root window, as above type: WM_COLORMAP_NOTIFY format: 32 data[0]: the timestamp of the event that caused the client to start or stop installing colormaps data[1]: 1 if the client is starting col- ormap installation, 0 if the client is finished with colormap installa- tion data[2]: reserved, must be zero data[3]: reserved, must be zero data[4]: reserved, must be zero ---------------------------------------------------------- This feature was introduced in version 2.0 of this document, and there will be a significant period of time before all window managers can be expected to implement this feature. Before using this feature, clients must check the compliance level of the window manager (using the mechanism described in section 4.3) to verify that it supports this feature. This is necessary to prevent colormap installation conflicts between clients and older window managers. Window managers should refrain from installing colormaps while a client has requested control of colormap installa- tion. The window manager should continue to track the set of installed colormaps so that it can reinstate its colormap focus policy when the client has finished colormap installa- tion. This technique has race conditions that may result in the colormaps continuing to be installed even after a client has issued its notification message. For example, the window manager may have issued some 4mInstallColormap24m requests that are not executed until after the client's 4mSendEvent24m and 4mInstallColormap24m requests, thus uninstalling the client's colormaps. If this occurs while the client still has the pointer grabbed and before the client has issued the "fin- ished" message, the client may reinstall the desired col- ormaps. 1m560m 1mInter-Client Communication Conventions X11, Release 6.40m Advice to Implementors Clients are expected to use this mechanism for things such as pop-up windows and for animations that use override-redirect windows. If a client fails to issue the "finished" message, the window manager may be left in a state where its colormap installation policy is suspended. Window manager implementors may want to implement a feature that resets colormap installation policy in response to a command from the user. 1m4.1.9. Icons0m A client can hint to the window manager about the desired appearance of its icon by setting: · A string in WM_ICON_NAME. All clients should do this because it provides a fall- back for window managers whose ideas about icons differ widely from those of the client. · A 4mPixmap24m into the icon_pixmap field of the WM_HINTS property and possibly another into the icon_mask field. The window manager is expected to display the pixmap masked by the mask. The pixmap should be one of the sizes found in the WM_ICON_SIZE property on the root. If this property is not found, the window manager is unlikely to display icon pixmaps. Window managers usu- ally will clip or tile pixmaps that do not match WM_ICON_SIZE. · A window into the icon_window field of the WM_HINTS property. The window manager is expected to map that window when- ever the client is in the Iconic state. In general, the size of the icon window should be one of those specified in WM_ICON_SIZE on the root, if it exists. Window man- agers are free to resize icon windows. In the Iconic state, the window manager usually will ensure that: · If the window's WM_HINTS.icon_window is set, the window it names is visible. · If the window's WM_HINTS.icon_window is not set but the window's WM_HINTS.icon_pixmap is set, the pixmap it names is visible. 1m570m 1mInter-Client Communication Conventions X11, Release 6.40m · Otherwise, the window's WM_ICON_NAME string is visible. Clients should observe the following conventions about their icon windows: Conventions 1. The icon window should be an 4mInputOutput0m child of the root. 2. The icon window should be one of the sizes specified in the WM_ICON_SIZE property on t