diff options
| author | Kaleb Keithley <kaleb@freedesktop.org> | 2003-11-14 15:54:49 +0000 |
|---|---|---|
| committer | Kaleb Keithley <kaleb@freedesktop.org> | 2003-11-14 15:54:49 +0000 |
| commit | 3e77e75b5a28b1b5a258396f4f15a61c9f3dc87c (patch) | |
| tree | 42d6da65aa200c129a1d52dd9e9e33168f626df6 /specs/XProtocol/X11.protocol | |
R6.6 is the Xorg base-lineXORG-MAIN
Diffstat (limited to 'specs/XProtocol/X11.protocol')
| -rw-r--r-- | specs/XProtocol/X11.protocol | 10303 |
1 files changed, 10303 insertions, 0 deletions
diff --git a/specs/XProtocol/X11.protocol b/specs/XProtocol/X11.protocol new file mode 100644 index 0000000..660700b --- /dev/null +++ b/specs/XProtocol/X11.protocol @@ -0,0 +1,10303 @@ +.\" $Xorg: X11.protocol,v 1.3 2000/08/17 19:42:23 cpqbld Exp $ +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.ps 11 +.nr PS 11 +\& +.sp 8 +.ce 4 +\s+2\fBX Window System Protocol\fP\s-2 + +\s+1\fBX Consortium Standard\fP\s-1 + +\s+1\fBX Version 11, Release 6.4\fP\s-1 +.sp 6 +.ce 5 +\s-1Robert W. Scheifler +.sp 6p +X Consortium, Inc. +.bp +\& +.ps 9 +.nr PS 9 +.sp 8 +.LP +X Window System is a trademark of X Consortium, Inc. +.LP +Copyright \(co 1986, 1987, 1988, 1994 +X Consortium +.LP +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the ``Software''), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: +.LP +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. +.LP +THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN +AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.LP +Except as contained in this notice, the name of the X Consortium shall not be +used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from the X Consortium. +.ps 11 +.nr PS 11 +.bp +.XS iii +Acknowledgments +.XE +\& +.sp 1 +.ce 3 +\s+1\fBAcknowledgments\fP\s-1 +.sp 2 +.na +.LP +The primary contributers to the X11 protocol are: +.LP +.Ds +Dave Carver (Digital HPW) +Branko Gerovac (Digital HPW) +Jim Gettys (MIT/Project Athena, Digital) +Phil Karlton (Digital WSL) +Scott McGregor (Digital SSG) +Ram Rao (Digital UEG) +David Rosenthal (Sun) +Dave Winchell (Digital UEG) +.De +.LP +The implementors of initial server who provided useful +input are: +.LP +.Ds +Susan Angebranndt (Digital) +Raymond Drewry (Digital) +Todd Newman (Digital) +.De +.LP +The invited reviewers who provided useful input are: +.LP +.Ds +Andrew Cherenson (Berkeley) +Burns Fisher (Digital) +Dan Garfinkel (HP) +Leo Hourvitz (Next) +Brock Krizan (HP) +David Laidlaw (Stellar) +Dave Mellinger (Interleaf) +Ron Newman (MIT) +John Ousterhout (Berkeley) +Andrew Palay (ITC CMU) +Ralph Swick (MIT) +Craig Taylor (Sun) +Jeffery Vroom (Stellar) +.De +.LP +Thanks go to Al Mento of Digital's UEG Documentation Group for +formatting this document. +.LP +This document does not attempt to provide the rationale or pragmatics required +to fully understand the protocol or to place it in perspective within a +complete system. +.LP +The protocol contains many management mechanisms that are not intended for +normal applications. +Not all mechanisms are needed to build a particular user interface. +It is important to keep in mind that the protocol is intended to +provide mechanism, not policy. +.LP +.Ds 0 +Robert W. Scheifler +X Consortium, Inc. +.De +.bp 1 +.EH '\fBX Protocol\fP''\fBX11, Release 6.4\fP' +.OH '\fBX Protocol\fP''\fBX11, Release 6.4\fP' +.EF ''\fB % \fP'' +.OF ''\fB % \fP'' +.NH 1 +Protocol Formats +.XS +\*(SN Protocol Formats +.XE +.SH +Request Format +.LP +Every request contains an 8-bit major opcode and a 16-bit length field +expressed in units of four bytes. +Every request consists of four bytes of a header +(containing the major opcode, the length field, and a data byte) +followed by zero or more additional bytes of data. +The length field defines the total length of the request, including the header. +The length field in a request must equal the minimum length required to contain +the request. +If the specified length is smaller or larger than the required length, +an error is generated. +Unused bytes in a request are not required to be zero. +Major opcodes 128 through 255 are reserved for extensions. +Extensions are intended to contain multiple requests, +so extension requests typically have an additional minor opcode encoded +in the second data byte in the request header. +However, the placement and interpretation of this minor opcode and of all +other fields in extension requests are not defined by the core protocol. +Every request on a given connection is implicitly assigned a sequence number, +starting with one, that is used in replies, errors, and events. +.SH +Reply Format +.LP +Every reply contains a 32-bit length field expressed in units of four bytes. +Every reply consists of 32 bytes followed by zero or more additional bytes of +data, as specified in the length field. +Unused bytes within a reply are not guaranteed to be zero. +Every reply also contains the least significant 16 bits of the sequence number +of the corresponding request. +.SH +Error Format +.LP +Error reports are 32 bytes long. +Every error includes an 8-bit error code. +Error codes 128 through 255 are reserved for extensions. +Every error also includes the major and minor opcodes of the failed request +and the least significant 16 bits of the sequence number of the request. +For the following errors (see section 4), +the failing resource ID is also returned: +.PN Colormap , +.PN Cursor , +.PN Drawable , +.PN Font , +.PN GContext , +.PN IDChoice , +.PN Pixmap , +and +.PN Window . +For +.PN Atom +errors, the failing atom is returned. +For +.PN Value +errors, the failing value is returned. +Other core errors return no additional data. +Unused bytes within an error are not guaranteed to be zero. +.SH +Event Format +.LP +Events are 32 bytes long. +Unused bytes within an event are not guaranteed to be zero. +Every event contains an 8-bit type code. +The most significant bit in this code is set if the event was generated from a +.PN SendEvent +request. +Event codes 64 through 127 are reserved for extensions, although the core +protocol does not define a mechanism for selecting interest in such events. +Every core event (with the exception of +.PN KeymapNotify ) +also contains the least significant 16 bits of the sequence number of the last +request issued by the client that was (or is currently being) processed by +the server. +.NH 1 +Syntactic Conventions +.XS +\*(SN Syntactic Conventions +.XE +.LP +The rest of this document uses the following syntactic conventions. +.IP \(bu 5 +The syntax {...} encloses a set of alternatives. +.IP \(bu 5 +The syntax [...] encloses a set of structure components. +.IP \(bu 5 +In general, TYPEs are in uppercase and +.PN AlternativeValues +are capitalized. +.IP \(bu 5 +Requests in section 9 are described in the following format: +.IP +.Ds 0 +.TA .75i +.ta .75i +.PN RequestName + \fIarg1\fP\^: type1 + ... + \fIargN\fP\^: typeN + \(-> + result1: type1 + ... + resultM: typeM + + Errors: kind1, ..., kindK + + Description. +.De +.IP +If no \(-> is present in the description, +then the request has no reply (it is asynchronous), +although errors may still be reported. +If \(->+ is used, +then one or more replies can be generated for a single request. +.IP \(bu 5 +Events in section 11 are described in the following format: +.IP +.Ds 0 +.TA .75i +.ta .75i +.PN EventName + \fIvalue1\fP\^: type1 + ... + \fIvalueN\fP\^: typeN + + Description. +.De +.NH 1 +Common Types +.XS +\*(SN Common Types +.XE +.LP +.TS H +lw(1.25i) lw(4.5i). +_ +.sp 6p +.B +Name Value +.sp 6p +_ +.sp 6p +.TH +.R +.IN "Types" "LISTofFOO" "@DEF@" +LISTofFOO T{ +A type name of the form LISTofFOO means a counted list of elements of type +FOO. +The size of the length field may vary (it is not necessarily the same +size as a FOO), and in some cases, it may be implicit. +It is fully specified in Appendix B. +Except where explicitly noted, +zero-length lists are legal. +T} +.sp 3p +.IN "Types" "BITMASK" "@DEF@" +T{ +BITMASK +.br +.ns +.IN "Types" "LISTofVALUE" "@DEF@" +LISTofVALUE +T} T{ +The types BITMASK and LISTofVALUE are somewhat special. +Various requests contain arguments of the form: +.br +\fIvalue-mask\fP\^: BITMASK +.br +\fIvalue-list\fP\^: LISTofVALUE +.br +These are used to allow the client to specify a subset of a heterogeneous +collection of optional arguments. +The value-mask specifies which arguments are to be provided; +each such argument is assigned a unique bit position. +The representation of the BITMASK will typically contain more bits than +there are defined arguments. +The unused bits in the value-mask must be zero (or the server generates a +.PN Value +error). +The value-list contains one value for each bit set to 1 in the mask, +from least significant to most significant bit in the mask. +Each value is represented with four bytes, +but the actual value occupies only the least significant bytes as required. +The values of the unused bytes do not matter. +T} +.sp 3p +.IN "Types" "OR" "@DEF@" +OR T{ +A type of the form ``T1 or ... or Tn'' means the union of the indicated types. +A single-element type is given as the element without enclosing braces. +T} +.IN "Types" "WINDOW" "@DEF@" +WINDOW 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "PIXMAP" "@DEF@" +PIXMAP 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "CURSOR" "@DEF@" +CURSOR 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "FONT" "@DEF@" +FONT 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "GCONTEXT" "@DEF@" +GCONTEXT 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "COLORMAP" "@DEF@" +COLORMAP 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "DRAWABLE" "@DEF@" +DRAWABLE WINDOW or PIXMAP +.IN "Types" "FONTABLE" "@DEF@" +FONTABLE FONT or GCONTEXT +.IN "Types" "ATOM" "@DEF@" +ATOM 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "VISUALID" "@DEF@" +VISUALID 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "VALUE" "@DEF@" +VALUE 32-bit quantity (used only in LISTofVALUE) +.IN "Types" "BYTE" "@DEF@" +BYTE 8-bit value +.IN "Types" "INT8" "@DEF@" +INT8 8-bit signed integer +.IN "Types" "INT16" "@DEF@" +INT16 16-bit signed integer +.IN "Types" "INT32" "@DEF@" +INT32 32-bit signed integer +.IN "Types" "CARD8" "@DEF@" +CARD8 8-bit unsigned integer +.IN "Types" "CARD16" "@DEF@" +CARD16 16-bit unsigned integer +.IN "Types" "CARD32" "@DEF@" +CARD32 32-bit unsigned integer +.IN "Types" "TIMESTAMP" "@DEF@" +TIMESTAMP CARD32 +.IN "Types" "BITGRAVITY" "@DEF@" +BITGRAVITY T{ +.Pn { Forget , +.PN Static , +.PN NorthWest , +.PN North , +.PN NorthEast , +.PN West , +.PN Center , +.br +\ +.PN East , +.PN SouthWest , +.PN South , +.PN SouthEast } +T} +.IN "Types" "WINGRAVITY" "@DEF@" +WINGRAVITY T{ +.Pn { Unmap , +.PN Static , +.PN NorthWest , +.PN North , +.PN NorthEast , +.PN West , +.PN Center , +.br +\ +.PN East , +.PN SouthWest , +.PN South , +.PN SouthEast } +T} +.IN "Types" "BOOL" "@DEF@" +BOOL T{ +.Pn { True , +.PN False } +T} +.IN "Types" "EVENT" "@DEF@" +EVENT T{ +.Pn { KeyPress , +.PN KeyRelease , +.PN OwnerGrabButton , +.PN ButtonPress , +.br +\ +.PN ButtonRelease , +.PN EnterWindow , +.PN LeaveWindow , +.PN PointerMotion , +.br +\ +.PN PointerMotionHint , +.PN Button1Motion , +.PN Button2Motion , +.br +\ +.PN Button3Motion , +.PN Button4Motion , +.PN Button5Motion , +.PN ButtonMotion , +.br +\ +.PN Exposure , +.PN VisibilityChange , +.PN StructureNotify , +.PN ResizeRedirect , +.br +\ +.PN SubstructureNotify , +.PN SubstructureRedirect , +.PN FocusChange , +.br +\ +.PN PropertyChange , +.PN ColormapChange , +.PN KeymapState } +T} +.IN "Types" "POINTEREVENT" "@DEF@" +POINTEREVENT T{ +.Pn { ButtonPress , +.PN ButtonRelease , +.PN EnterWindow , +.PN LeaveWindow , +.br +\ +.PN PointerMotion , +.PN PointerMotionHint , +.PN Button1Motion , +.br +\ +.PN Button2Motion , +.PN Button3Motion , +.PN Button4Motion , +.PN Button5Motion , +.br +\ +.PN ButtonMotion , +.PN KeymapState } +T} +.IN "Types" "DEVICEEVENT" "@DEF@" +DEVICEEVENT T{ +.Pn { KeyPress , +.PN KeyRelease , +.PN ButtonPress , +.PN ButtonRelease , +.br +\ +.PN PointerMotion , +.PN Button1Motion , +.PN Button2Motion , +.PN Button3Motion , +.br +\ +.PN Button4Motion , +.PN Button5Motion , +.PN ButtonMotion } +T} +.IN "Types" "KEYSYM" "@DEF@" +KEYSYM 32-bit value (top three bits guaranteed to be zero) +.IN "Types" "KEYCODE" "@DEF@" +KEYCODE CARD8 +.IN "Types" "BUTTON" "@DEF@" +BUTTON CARD8 +.IN "Types" "KEYMASK" "@DEF@" +KEYMASK T{ +.Pn { Shift , +.PN Lock , +.PN Control , +.PN Mod1 , +.PN Mod2 , +.PN Mod3 , +.PN Mod4 , +.PN Mod5 } +T} +.IN "Types" "BUTMASK" "@DEF@" +BUTMASK T{ +.Pn { Button1 , +.PN Button2 , +.PN Button3 , +.PN Button4 , +.PN Button5 } +T} +.IN "Types" "KEYBUTMASK" "@DEF@" +KEYBUTMASK KEYMASK or BUTMASK +.IN "Types" "STRING8" "@DEF@" +STRING8 LISTofCARD8 +.IN "Types" "STRING16" "@DEF@" +STRING16 LISTofCHAR2B +.IN "Types" "CHAR2B" "@DEF@" +CHAR2B [byte1, byte2: CARD8] +.IN "Types" "POINT" "@DEF@" +POINT [x, y: INT16] +.IN "Types" "RECTANGLE" "@DEF@" +RECTANGLE T{ +[x, y: INT16, +.br +\ width, height: CARD16] +T} +.IN "Types" "ARC" "@DEF@" +ARC T{ +[x, y: INT16, +.br +\ width, height: CARD16, +.br +\ angle1, angle2: INT16] +T} +.IN "Types" "HOST" "@DEF@" +HOST T{ +[family: +.Pn { Internet , +.PN DECnet , +.PN Chaos } +T} + T{ +\ address: LISTofBYTE] +T} +.TE +.LP +The [x,y] coordinates of a RECTANGLE specify the upper-left corner. +.LP +The primary interpretation of large characters in a STRING16 is that they +are composed of two bytes used to index a two-dimensional matrix, +hence, the use of CHAR2B rather than CARD16. +This corresponds to the JIS/ISO method of indexing 2-byte characters. +It is expected that most large fonts will be defined with 2-byte +matrix indexing. +For large fonts constructed with linear indexing, +a CHAR2B can be interpreted as a 16-bit number by treating byte1 as +the most significant byte. +This means that clients should always transmit such +16-bit character values most significant byte first, as the server will never +byte-swap CHAR2B quantities. +.LP +The length, format, and interpretation of a HOST address are specific to the +family (see +.PN ChangeHosts +request). +.NH 1 +Errors +.XS +\*(SN Errors +.XE +.LP +In general, when a request terminates with an error, +the request has no side effects (that is, there is no partial execution). +The only requests for which this is not true are +.PN ChangeWindowAttributes , +.PN ChangeGC , +.PN PolyText8 , +.PN PolyText16 , +.PN FreeColors , +.PN StoreColors , +and +.PN ChangeKeyboardControl . +.LP +The following error codes result from various requests as follows: +.TS H +lw(1.5i) lw(4.25i). +_ +.sp 6p +.B +Error Description +.sp 6p +_ +.sp 6p +.TH +.R +.IN "Error Codes" "Access" "@DEF@" +T{ +.PN Access +T} T{ +An attempt is made to grab a key/button combination already grabbed by another +client. +.sp 6p +An attempt is made to free a colormap entry not allocated by the client +or to free an entry in a colormap that was created with all entries writable. +.sp 6p +An attempt is made to store into a read-only or an unallocated colormap entry. +.sp 6p +An attempt is made to modify the access control list from other than the local +host (or otherwise authorized client). +.sp 6p +An attempt is made to select an event type that only one client can +select at a time when another client has already selected it. +T} +.sp 6p +.IN "Error Codes" "Alloc" "@DEF@" +T{ +.PN Alloc +T} T{ +The server failed to allocate the requested resource. +Note that the explicit listing of +.PN Alloc +errors in request only covers allocation errors at a very coarse level +and is not intended to cover all cases +of a server running out of allocation space in the middle of service. +The semantics when a server runs out of allocation space are left unspecified, +but a server may generate an +.PN Alloc +error on any request for this reason, +and clients should be prepared to receive such errors and handle +or discard them. +T} +.sp 6p +.IN "Error Codes" "Atom" "@DEF@" +T{ +.PN Atom +T} T{ +A value for an ATOM argument does not name a defined ATOM. +T} +.sp 6p +.IN "Error Codes" "Colormap" "@DEF@" +T{ +.PN Colormap +T} T{ +A value for a COLORMAP argument does not name a defined COLORMAP. +T} +.sp 6p +.IN "Error Codes" "Cursor" "@DEF@" +T{ +.PN Cursor +T} T{ +A value for a CURSOR argument does not name a defined CURSOR. +T} +.sp 6p +.IN "Error Codes" "Drawable" "@DEF@" +T{ +.PN Drawable +T} T{ +A value for a DRAWABLE argument does not name a defined WINDOW or +PIXMAP. +T} +.sp 6p +.IN "Error Codes" "Font" "@DEF@" +T{ +.PN Font +T} T{ +A value for a FONT argument does not name a defined FONT. +.sp 6p +A value for a FONTABLE argument does not name a defined FONT or a +defined GCONTEXT. +T} +.sp 6p +.IN "Error Codes" "GContext" "@DEF@" +T{ +.PN GContext +T} T{ +A value for a GCONTEXT argument does not name a defined GCONTEXT. +T} +.sp 6p +.IN "Error Codes" "IDChoice" "@DEF@" +T{ +.PN IDChoice +T} T{ +The value chosen for a resource identifier either is not included +in the range assigned to the client or is already in use. +T} +.sp 6p +.IN "Error Codes" "Implementation" "@DEF@" +T{ +.PN Implementation +T} T{ +The server does not implement some aspect of the request. +A server that generates this error for a core request is deficient. +As such, this error is not listed for any of the requests, +but clients should be prepared to receive such errors +and handle or discard them. +T} +.sp 6p +.IN "Error Codes" "Length" "@DEF@" +T{ +.PN Length +T} T{ +The length of a request is shorter or longer than that required +to minimally contain the arguments. +.sp 6p +The length of a request exceeds the maximum length accepted by the +server. +T} +.sp 6p +.IN "Error Codes" "Match" "@DEF@" +T{ +.PN Match +T} T{ +An +.PN InputOnly +window is used as a DRAWABLE. +.sp 6p +In a graphics request, the GCONTEXT argument does not have the same +root and depth as the destination DRAWABLE argument. +.sp 6p +Some argument (or pair of arguments) has the correct type and range, +but it fails to match in some other way required by the request. +T} +.sp 6p +.IN "Error Codes" "Name" "@DEF@" +T{ +.PN Name +T} T{ +A font or color of the specified name does not exist. +T} +.sp 6p +.IN "Error Codes" "Pixmap" "@DEF@" +T{ +.PN Pixmap +T} T{ +A value for a PIXMAP argument does not name a defined PIXMAP. +T} +.sp 6p +.IN "Error Codes" "Request" "@DEF@" +T{ +.PN Request +T} T{ +The major or minor opcode does not specify a valid request. +T} +.sp 6p +.IN "Error Codes" "Value" "@DEF@" +T{ +.PN Value +T} T{ +Some numeric value falls outside the range of values accepted by the request. +Unless a specific range is specified for an argument, +the full range defined by the argument's type is accepted. +Any argument defined as a set of alternatives typically can generate +this error (due to the encoding). +T} +.sp 6p +.IN "Error Codes" "Window" "@DEF@" +T{ +.PN Window +T} T{ +A value for a WINDOW argument does not name a defined WINDOW. +T} +.sp 6p +_ +.TE +.NT Note +The +.PN Atom , +.PN Colormap , +.PN Cursor , +.PN Drawable , +.PN Font , +.PN GContext , +.PN Pixmap , +and +.PN Window +errors are also used when the argument type is extended by union with a +set of fixed alternatives, for example, <WINDOW or +.PN PointerRoot +or +.PN None >. +.NE +.NH 1 +Keyboards +.XS +\*(SN Keyboards +.XE +.LP +A KEYCODE represents a physical (or logical) key. +Keycodes lie in the inclusive range [8,255]. +A keycode value carries no intrinsic information, +although server implementors may attempt to encode geometry information +(for example, matrix) to be interpreted in a server-dependent fashion. +The mapping between keys and keycodes cannot be changed using the +protocol. +.LP +A KEYSYM is an encoding of a symbol on the cap of a key. +The set of defined KEYSYMs include the character sets Latin-1, Latin-2, +Latin-3, Latin-4, Kana, Arabic, Cyrillic, Greek, Tech, Special, Publish, APL, +Hebrew, Thai, and Korean as well as a set of symbols common on keyboards +(Return, Help, Tab, +and so on). +KEYSYMs with the most significant bit (of the 29 bits) set are reserved +as vendor-specific. +.LP +A list of KEYSYMs is associated with each KEYCODE. +The list is intended to convey the set of symbols on the corresponding key. +If the list (ignoring trailing +.PN NoSymbol +entries) is a single KEYSYM ``\fIK\fP'', +then the list is treated as if it were +the list ``\fIK\fP NoSymbol \fIK\fP NoSymbol''. +If the list (ignoring trailing NoSymbol entries) is a pair of KEYSYMs +``\fIK1 K2\fP'', then the list is treated as if it were the list +``\fIK1 K2 K1 K2\fP''. +If the list (ignoring trailing +.PN NoSymbol +entries) is +a triple of KEYSYMs ``\fIK1 K2 K3\fP'', +then the list is treated as if it were the list ``\fIK1 K2 K3\fP NoSymbol''. +When an explicit ``void'' element is desired in the list, +the value +.PN VoidSymbol +can be used. +.LP +The first four elements of the list are split into two groups of KEYSYMs. +Group 1 contains the first and second KEYSYMs, Group 2 contains the third and +fourth KEYSYMs. +Within each group, +if the second element of the group is +.PN NoSymbol , +then the group should be treated as if the second element were the +same as the first element, except when the first element is an alphabetic +KEYSYM ``\fIK\fP'' for which both lowercase and uppercase forms are defined. +In that case, the group should be treated as if the first element were the +lowercase form of ``\fIK\fP'' and the second element were the uppercase form +of ``\fIK\fP''. +.LP +The standard rules for obtaining a KEYSYM from a +.PN KeyPress +event make use of only the Group 1 and Group 2 KEYSYMs; no interpretation of +other KEYSYMs in the list is defined. The modifier state determines which +group to use. Switching between groups is controlled by the KEYSYM named +MODE SWITCH, by attaching that KEYSYM to some KEYCODE and attaching that +KEYCODE to any one of the modifiers +.PN Mod1 +through +.PN Mod5 . +This modifier is +called the ``group modifier''. For any KEYCODE, Group 1 is used when the +group modifier is off, and Group 2 is used when the group modifier is on. +.LP +The +.PN Lock +modifier is interpreted as CapsLock when the KEYSYM named CAPS +LOCK is attached to some KEYCODE and that KEYCODE is attached to the +.PN Lock +modifier. The +.PN Lock +modifier is interpreted as ShiftLock when the KEYSYM +named SHIFT LOCK is attached to some KEYCODE and that KEYCODE is attached +to the +.PN Lock +modifier. If the +.PN Lock +modifier could be interpreted as both +CapsLock and ShiftLock, the CapsLock interpretation is used. +.LP +The operation of ``keypad'' keys is controlled by the KEYSYM named NUM LOCK, +by attaching that KEYSYM to some KEYCODE and attaching that KEYCODE to any +one of the modifiers +.PN Mod1 +through +.PN Mod5 . +This modifier is called the +``numlock modifier''. The standard KEYSYMs with the prefix KEYPAD in their +name are called ``keypad'' KEYSYMs; these are KEYSYMS with numeric value in +the hexadecimal range #xFF80 to #xFFBD inclusive. In addition, +vendor-specific KEYSYMS in the hexadecimal range #x11000000 to #x1100FFFF +are also keypad KEYSYMs. +.LP +Within a group, the choice of KEYSYM is determined by applying the first +rule that is satisfied from the following list: +.IP \(bu 5 +The numlock modifier is on and the second KEYSYM is a keypad KEYSYM. In +this case, if the +.PN Shift +modifier is on, or if the +.PN Lock +modifier is on and +is interpreted as ShiftLock, then the first KEYSYM is used; otherwise, the +second KEYSYM is used. +.IP \(bu 5 +The +.PN Shift +and +.PN Lock +modifiers are both off. In this case, the first +KEYSYM is used. +.IP \(bu 5 +The +.PN Shift +modifier is off, and the +.PN Lock +modifier is on and is +interpreted as CapsLock. In this case, the first KEYSYM is used, but if +that KEYSYM is lowercase alphabetic, then the corresponding uppercase +KEYSYM is used instead. +.IP \(bu 5 +The +.PN Shift +modifier is on, and the +.PN Lock +modifier is on and is interpreted +as CapsLock. In this case, the second KEYSYM is used, but if that KEYSYM +is lowercase alphabetic, then the corresponding uppercase KEYSYM is used +instead. +.IP \(bu 5 +The +.PN Shift +modifier is on, or the +.PN Lock +modifier is on and is interpreted +as ShiftLock, or both. In this case, the second KEYSYM is used. +.LP +The mapping between KEYCODEs and KEYSYMs is not used directly by the server; +it is merely stored for reading and writing by clients. +.NH 1 +Pointers +.XS +\*(SN Pointers +.XE +.LP +Buttons are always numbered starting with one. +.NH 1 +Predefined Atoms +.XS +\*(SN Predefined Atoms +.XE +.LP +Predefined atoms are not strictly necessary and may not be useful in all +environments, but they will eliminate many +.PN InternAtom +requests in most applications. +Note that they are predefined only in the sense of having numeric values, +not in the sense of having required semantics. +The core protocol imposes no semantics on these names, +but semantics are specified in other X Consortium standards, +such as the \fIInter-Client Communication Conventions Manual\fP +and the \fIX Logical Font Description Conventions\fP. +.LP +The following names have predefined atom values. +Note that uppercase and lowercase matter. +.TS +lw(1.75i) l w(1.75i) lw(1.75i). +ARC ITALIC_ANGLE STRING +ATOM MAX_SPACE SUBSCRIPT_X +BITMAP MIN_SPACE SUBSCRIPT_Y +CAP_HEIGHT NORM_SPACE SUPERSCRIPT_X +CARDINAL NOTICE SUPERSCRIPT_Y +COLORMAP PIXMAP UNDERLINE_POSITION +COPYRIGHT POINT UNDERLINE_THICKNESS +CURSOR POINT_SIZE VISUALID +CUT_BUFFER0 PRIMARY WEIGHT +CUT_BUFFER1 QUAD_WIDTH WINDOW +CUT_BUFFER2 RECTANGLE WM_CLASS +CUT_BUFFER3 RESOLUTION WM_CLIENT_MACHINE +CUT_BUFFER4 RESOURCE_MANAGER WM_COMMAND +CUT_BUFFER5 RGB_BEST_MAP WM_HINTS +CUT_BUFFER6 RGB_BLUE_MAP WM_ICON_NAME +CUT_BUFFER7 RGB_COLOR_MAP WM_ICON_SIZE +DRAWABLE RGB_DEFAULT_MAP WM_NAME +END_SPACE RGB_GRAY_MAP WM_NORMAL_HINTS +FAMILY_NAME RGB_GREEN_MAP WM_SIZE_HINTS +FONT RGB_RED_MAP WM_TRANSIENT_FOR +FONT_NAME SECONDARY WM_ZOOM_HINTS +FULL_NAME STRIKEOUT_ASCENT X_HEIGHT +INTEGER STRIKEOUT_DESCENT +.TE +.LP +To avoid conflicts with possible future names for which semantics might be +imposed (either at the protocol level or in terms of higher level user +interface models), +names beginning with an underscore should be used for atoms +that are private to a particular vendor or organization. +To guarantee no conflicts between vendors and organizations, +additional prefixes need to be used. +However, the protocol does not define the mechanism for choosing such prefixes. +For names private to a single application or end user but stored in globally +accessible locations, +it is suggested that two leading underscores be used to avoid conflicts with +other names. +.NH 1 +Connection Setup +.XS +\*(SN Connection Setup +.XE +.LP +For remote clients, +the X protocol can be built on top of any reliable byte stream. +.SH +Connection Initiation +.LP +The client must send an initial byte of data to identify the byte order to be +employed. +The value of the byte must be octal 102 or 154. +The value 102 (ASCII uppercase B) means values are transmitted most significant +byte first, and value 154 (ASCII lowercase l) means values are transmitted +least significant byte first. +Except where explicitly noted in the protocol, +all 16-bit and 32-bit quantities sent by the client must be transmitted with +this byte order, +and all 16-bit and 32-bit quantities returned by the server will be transmitted +with this byte order. +.LP +Following the byte-order byte, +the client sends the following information at connection setup: +.IP +protocol-major-version: CARD16 +.br +protocol-minor-version: CARD16 +.br +authorization-protocol-name: STRING8 +.br +authorization-protocol-data: STRING8 +.LP +The version numbers indicate what version of the protocol the client +expects the server to implement. +.LP +The authorization name indicates what authorization (and authentication) +protocol the client +expects the server to use, and the data is specific to that protocol. +Specification of valid authorization mechanisms is not part of the core +X protocol. +A server that does not implement the protocol the client expects +or that only implements the host-based mechanism may simply ignore this +information. +If both name and data strings are empty, +this is to be interpreted as ``no explicit authorization.'' +.SH +Server Response +.LP +The client receives the following information at connection setup: +.IP +success: +.Pn { Failed , +.PN Success , +.PN Authenticate } +.LP +The client receives the following additional data if the returned success +value is +.PN Failed , +and the connection is not successfully established: +.IP +protocol-major-version: CARD16 +.br +protocol-minor-version: CARD16 +.br +reason: STRING8 +.LP +The client receives the following additional data if the returned success +value is +.PN Authenticate , +and further authentication negotiation is required: +.IP +reason: STRING8 +.LP +The contents of the reason string are specific to the authorization +protocol in use. The semantics of this authentication negotiation are +not constrained, except that the negotiation must eventually terminate +with a reply from the server containing a success value of +.PN Failed +or +.PN Success . +.LP +The client receives the following additional data if the returned success +value is +.PN Success , +and the connection is successfully established: +.IP +protocol-major-version: CARD16 +.br +protocol-minor-version: CARD16 +.br +vendor: STRING8 +.br +release-number: CARD32 +.br +resource-id-base, resource-id-mask: CARD32 +.br +image-byte-order: +.Pn { LSBFirst , +.PN MSBFirst } +.br +bitmap-scanline-unit: {8, 16, 32} +.br +bitmap-scanline-pad: {8, 16, 32} +.br +bitmap-bit-order: +.Pn { LeastSignificant , +.PN MostSignificant } +.br +pixmap-formats: LISTofFORMAT +.br +roots: LISTofSCREEN +.br +motion-buffer-size: CARD32 +.br +maximum-request-length: CARD16 +.br +min-keycode, max-keycode: KEYCODE +.IP +where: +.TS +rw(1.25i) lw(4i). +T{ +FORMAT: +T} T{ +[depth: CARD8, +.br +\ bits-per-pixel: {1, 4, 8, 16, 24, 32} +.br +\ scanline-pad: {8, 16, 32}] +T} +.sp +T{ +SCREEN: +T} T{ +[root: WINDOW +.br +\ width-in-pixels, height-in-pixels: CARD16 +.br +\ width-in-millimeters, height-in-millimeters: CARD16 +.br +\ allowed-depths: LISTofDEPTH +.br +\ root-depth: CARD8 +.br +\ root-visual: VISUALID +.br +\ default-colormap: COLORMAP +.br +\ white-pixel, black-pixel: CARD32 +.br +\ min-installed-maps, max-installed-maps: CARD16 +.br +\ backing-stores: +.Pn { Never , +.PN WhenMapped , +.PN Always } +.br +\ save-unders: BOOL +.br +\ current-input-masks: SETofEVENT] +T} +.sp +T{ +DEPTH: +T} T{ +[depth: CARD8 +.br +\ visuals: LISTofVISUALTYPE] +T} +.sp +T{ +VISUALTYPE: +T} T{ +[visual-id: VISUALID +.br +\ class: +.Pn { StaticGray , +.PN StaticColor , +.PN TrueColor , +.PN GrayScale , +.br +\ \ \ \ \ \ \ \ \ \ +.PN PseudoColor , +.PN DirectColor } +.br +\ red-mask, green-mask, blue-mask: CARD32 +.br +\ bits-per-rgb-value: CARD8 +.br +\ colormap-entries: CARD16] +T} +.TE +.SH +Server Information +.LP +The information that is global to the server is: +.LP +The protocol version numbers are an escape hatch in case future revisions of +the protocol are necessary. +In general, +the major version would increment for incompatible changes, +and the minor version would increment for small upward compatible changes. +Barring changes, +the major version will be 11, and the minor version will be 0. +The protocol version numbers returned indicate the protocol the server +actually supports. +This might not equal the version sent by the client. +The server can (but need not) refuse connections from clients that offer a +different version than the server supports. +A server can (but need not) support more than one version simultaneously. +.LP +The vendor string gives some identification of the owner of the server +implementation. +The vendor controls the semantics of the release number. +.LP +The resource-id-mask contains a single contiguous set of bits (at least 18). +The client allocates resource IDs for types WINDOW, PIXMAP, +CURSOR, FONT, GCONTEXT, and COLORMAP by choosing a value with only +some subset of these bits set and ORing it with resource-id-base. +Only values constructed in this way can be used to name newly created +resources over this connection. +Resource IDs never have the top three bits set. +The client is not restricted to linear or contiguous allocation +of resource IDs. +Once an ID has been freed, +it can be reused. +An ID must be unique with respect to the IDs of all other resources, +not just other resources of the same type. +However, note that the value spaces of resource identifiers, +atoms, visualids, and keysyms are distinguished by context, and +as such, are not required to be disjoint; for example, a given numeric value +might be both a valid window ID, a valid atom, and a valid keysym. +.LP +Although the server is in general responsible for byte-swapping data to +match the client, +images are always transmitted and received in formats (including byte order) +specified by the server. +The byte order for images is given by image-byte-order and applies to each +scanline unit in XY format (bitmap format) and to each pixel value in Z format. +.LP +A bitmap is represented in scanline order. +Each scanline is padded to a multiple of bits as given by bitmap-scanline-pad. +The pad bits are of arbitrary value. +The scanline is quantized in multiples of bits as given by bitmap-scanline-unit. +The bitmap-scanline-unit is always less than or equal to the +bitmap-scanline-pad. +Within each unit, +the leftmost bit in the bitmap is either the least significant +or most significant bit in the unit, as given by bitmap-bit-order. +If a pixmap is represented in XY format, +each plane is represented as a bitmap, and the planes appear from +most significant to least significant in bit order with no padding +between planes. +.LP +Pixmap-formats contains one entry for each depth value. +The entry describes the Z format used to represent images of that depth. +An entry for a depth is included if any screen supports that depth, +and all screens supporting that depth must support only that Z format for that +depth. +In Z format, +the pixels are in scanline order, left to right within a scanline. +The number of bits used to hold each pixel is given by bits-per-pixel. +Bits-per-pixel may be larger than strictly required by the depth, +in which case the least significant bits are used to hold +the pixmap data, and the values of the unused high-order bits are +undefined. +When the bits-per-pixel is 4, +the order of nibbles in the byte is the same as the image byte-order. +When the bits-per-pixel is 1, +the format is identical for bitmap format. +Each scanline is padded to a multiple of bits as given by scanline-pad. +When bits-per-pixel is 1, +this will be identical to bitmap-scanline-pad. +.LP +How a pointing device roams the screens is up to the server +implementation and is transparent to the protocol. +No geometry is defined among screens. +.LP +The server may retain the recent history of pointer motion and do so to a +finer granularity than is reported by +.PN MotionNotify +events. +The +.PN GetMotionEvents +request makes such history available. +The motion-buffer-size gives the approximate maximum number +of elements in the history buffer. +.LP +Maximum-request-length specifies the maximum length of a request +accepted by the server, in 4-byte units. +That is, length is the maximum value that can appear in the length field of a +request. +Requests larger than this maximum generate a +.PN Length +error, +and the server will read and simply discard the entire request. +Maximum-request-length will always be at least 4096 +(that is, requests of length up to and including 16384 bytes +will be accepted by all servers). +.LP +Min-keycode and max-keycode specify the smallest and largest keycode +values transmitted by the server. +Min-keycode is never less than 8, +and max-keycode is never greater than 255. +Not all keycodes in this range are required to have corresponding keys. +.SH +Screen Information +.LP +The information that applies per screen is: +.LP +The allowed-depths specifies what pixmap and window depths are supported. +Pixmaps are supported for each depth listed, +and windows of that depth are supported if at least one visual type is listed +for the depth. +A pixmap depth of one is always supported and listed, +but windows of depth one might not be supported. +A depth of zero is never listed, +but zero-depth +.PN InputOnly +windows are always supported. +.LP +Root-depth and root-visual specify the depth and visual type of the +root window. +Width-in-pixels and height-in-pixels specify the size of +the root window (which cannot be changed). +The class of the root window is always +.PN InputOutput . +Width-in-millimeters and height-in-millimeters can be used to determine the +physical size and the aspect ratio. +.LP +The default-colormap is the one initially associated with the root window. +Clients with minimal color requirements creating windows of +the same depth as the root may want to allocate from this map by +default. +.LP +Black-pixel and white-pixel can be used in implementing a monochrome +application. +These pixel values are for permanently allocated entries in the +default-colormap. +The actual RGB values may be settable on some screens +and, in any case, may not actually be black and white. +The names are intended to convey the expected relative intensity of the colors. +.LP +The border of the root window is initially a pixmap filled with the black-pixel. +The initial background of the root window is a pixmap filled with some +unspecified two-color pattern using black-pixel and white-pixel. +.LP +Min-installed-maps specifies the number of maps that can be guaranteed +to be installed simultaneously (with +.PN InstallColormap ), +regardless of the number of entries allocated in each map. +Max-installed-maps specifies the maximum number of maps that might possibly be +installed simultaneously, depending on their allocations. +Multiple static-visual colormaps with identical contents but differing in +resource ID should be considered as a single map for the purposes of this +number. +For the typical case of a single hardware colormap, both values will be 1. +.LP +Backing-stores indicates when the server supports backing stores for +this screen, although it may be storage limited in the number of +windows it can support at once. +If save-unders is +.PN True , +the server can support the save-under mode in +.PN CreateWindow +and +.PN ChangeWindowAttributes , +although again it may be storage limited. +.LP +The current-input-events is what +.PN GetWindowAttributes +would return for the all-event-masks for the root window. +.SH +Visual Information +.LP +The information that applies per visual-type is: +.LP +A given visual type might be listed for more than one depth or for +more than one screen. +.LP +For +.PN PseudoColor , +a pixel value indexes a colormap to produce independent RGB values; +the RGB values can be changed dynamically. +.PN GrayScale +is treated in the same way as +.PN PseudoColor +except which primary drives the screen is undefined; +thus, the client should always store the +same value for red, green, and blue in colormaps. +For +.PN DirectColor , +a pixel value is decomposed into separate RGB subfields, +and each subfield separately indexes the colormap for the corresponding value. +The RGB values can be changed dynamically. +.PN TrueColor +is treated in the same way as +.PN DirectColor +except the colormap has predefined read-only RGB values. +These values are server-dependent but provide linear or near-linear +increasing ramps in each primary. +.PN StaticColor +is treated in the same way as +.PN PseudoColor +except the colormap has predefined read-only RGB values, +which are server-dependent. +.PN StaticGray +is treated in the same way as +.PN StaticColor +except the red, green, and blue values are equal for any +single pixel value, resulting in shades of gray. +.PN StaticGray +with a two-entry colormap can be thought of as monochrome. +.LP +The red-mask, green-mask, and blue-mask are only defined for +.PN DirectColor +and +.PN TrueColor . +Each has one contiguous set of bits set to 1 with no intersections. +Usually each mask has the same number of bits set to 1. +.LP +The bits-per-rgb-value specifies the log base 2 of the number of +distinct color intensity values (individually) of red, green, and blue. +This number need not bear any relation to the number of colormap entries. +Actual RGB values are always passed in the protocol within a +16-bit spectrum, with 0 being minimum intensity and 65535 being the +maximum intensity. +On hardware that provides a linear zero-based intensity ramp, +the following relationship exists: +.LP +.RS +.DS +hw-intensity = protocol-intensity / (65536 / total-hw-intensities) +.DE +.RE +.LP +Colormap entries are indexed from 0. +The colormap-entries defines the number of available colormap entries in a +newly created colormap. +For +.PN DirectColor +and +.PN TrueColor , +this will usually be 2 to the power of the maximum number of bits set to 1 in +red-mask, green-mask, and blue-mask. +.NH 1 +Requests +.XS +\*(SN Requests +.XE +.EQ +delim %% +.EN +.LP +.sM +.IN "CreateWindow" "" "@DEF@" +.PN CreateWindow +.in +.2i +.LP +\fIwid\fP, \fIparent\fP\^: WINDOW +.br +\fIclass\fP\^: +.Pn { InputOutput , +.PN InputOnly , +.PN CopyFromParent } +.br +\fIdepth\fP\^: CARD8 +.br +\fIvisual\fP\^: VISUALID or +.PN CopyFromParent +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIwidth\fP, \fIheight\fP, \fIborder-width\fP\^: CARD16 +.br +\fIvalue-mask\fP\^: BITMASK +.br +\fIvalue-list\fP\^: LISTofVALUE +.LP +Errors: +.PN Alloc , +.PN Colormap , +.PN Cursor , +.PN IDChoice , +.PN Match , +.PN Pixmap , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request creates an unmapped window and assigns the identifier wid to it. +.LP +A class of +.PN CopyFromParent +means the class is taken from the parent. +A depth of zero for class +.PN InputOutput +or +.PN CopyFromParent +means the depth is taken from the parent. +A visual of +.PN CopyFromParent +means the visual type is taken from the parent. +For class +.PN InputOutput , +the visual type and depth must be a combination supported for the screen +(or a +.PN Match +error results). +The depth need not be the same as the parent, +but the parent must not be of class +.PN InputOnly +(or a +.PN Match +error results). +For class +.PN InputOnly , +the depth must be zero (or a +.PN Match +error results), and the visual must be one supported for the screen (or a +.PN Match +error results). +However, the parent can have any depth and class. +.LP +The server essentially acts as if +.PN InputOnly +windows do not exist for the purposes of graphics requests, +exposure processing, and +.PN VisibilityNotify +events. +An +.PN InputOnly +window cannot be used as a drawable (as a source or destination for graphics +requests). +.PN InputOnly +and +.PN InputOutput +windows act identically in other respects\-properties, +grabs, input control, and so on. +.LP +The coordinate system has the X axis horizontal and the Y axis vertical +with the origin [0, 0] at the upper-left corner. +Coordinates are integral, +in terms of pixels, +and coincide with pixel centers. +Each window and pixmap has its own coordinate system. +For a window, +the origin is inside the border at the inside, upper-left corner. +.LP +The x and y coordinates +for the window are relative to the parent's origin +and specify the position of the upper-left outer corner of the window +(not the origin). +The width and height specify the inside size (not including the border) +and must be nonzero (or a +.PN Value +error results). +The border-width for an +.PN InputOnly +window must be zero (or a +.PN Match +error results). +.LP +The window is placed on top in the stacking order with respect to siblings. +.LP +The value-mask and value-list specify attributes of the window that are +to be explicitly initialized. +The possible values are: +.TS H +l lw(2.6i). +_ +.sp 6p +.B +Attribute Type +.sp 6p +_ +.TH +.R +.sp 6p +T{ +background-pixmap +T} T{ +PIXMAP or +.PN None +or +.PN ParentRelative +T} +T{ +background-pixel +T} T{ +CARD32 +T} +T{ +border-pixmap +T} T{ +PIXMAP or +.PN CopyFromParent +T} +T{ +border-pixel +T} T{ +CARD32 +T} +T{ +bit-gravity +T} T{ +BITGRAVITY +T} +T{ +win-gravity +T} T{ +WINGRAVITY +T} +T{ +backing-store +T} T{ +.Pn { NotUseful , +.PN WhenMapped , +.PN Always } +T} +T{ +backing-planes +T} T{ +CARD32 +T} +T{ +backing-pixel +T} T{ +CARD32 +T} +T{ +save-under +T} T{ +BOOL +T} +T{ +event-mask +T} T{ +SETofEVENT +T} +T{ +do-not-propagate-mask +T} T{ +SETofDEVICEEVENT +T} +T{ +override-redirect +T} T{ +BOOL +T} +T{ +colormap +T} T{ +COLORMAP or +.PN CopyFromParent +T} +T{ +cursor +T} T{ +CURSOR or +.PN None +T} +.sp 6p +_ +.TE +.LP +The default values when attributes are not explicitly initialized +are: +.TS H +l l. +_ +.sp 6p +.B +Attribute Default +.sp 6p +_ +.TH +.R +.sp 6p +T{ +background-pixmap +T} T{ +.PN None +T} +T{ +border-pixmap +T} T{ +.PN CopyFromParent +T} +T{ +bit-gravity +T} T{ +.PN Forget +T} +T{ +win-gravity +T} T{ +.PN NorthWest +T} +T{ +backing-store +T} T{ +.PN NotUseful +T} +T{ +backing-planes +T} T{ +all ones +T} +T{ +backing-pixel +T} T{ +zero +T} +T{ +save-under +T} T{ +.PN False +T} +T{ +event-mask +T} T{ +{} (empty set) +T} +T{ +do-not-propagate-mask +T} T{ +{} (empty set) +T} +T{ +override-redirect +T} T{ +.PN False +T} +T{ +colormap +T} T{ +.PN CopyFromParent +T} +T{ +cursor +T} T{ +.PN None +T} +.sp 6p +_ +.TE +.LP +Only the following attributes are defined for +.PN InputOnly +windows: +.IP \(bu 5 +win-gravity +.IP \(bu 5 +event-mask +.IP \(bu 5 +do-not-propagate-mask +.IP \(bu 5 +override-redirect +.IP \(bu 5 +cursor +.LP +It is a +.PN Match +error to specify any other attributes for +.PN InputOnly +windows. +.LP +If background-pixmap is given, +it overrides the default background-pixmap. +The background pixmap and the window must have the +same root and the same depth (or a +.PN Match +error results). +Any size pixmap can be used, although some sizes may be faster than others. +If background +.PN None +is specified, the window has no defined background. +If background +.PN ParentRelative +is specified, the parent's background is used, +but the window must have the same depth as the parent (or a +.PN Match +error results). +If the parent has background +.PN None , +then the window will also have background +.PN None . +A copy of the parent's background is not made. +The parent's background is reexamined each time the window background is +required. +If background-pixel is given, it overrides the default +background-pixmap and any background-pixmap given explicitly, +and a pixmap of undefined size filled with background-pixel is used for the +background. +Range checking is not performed on the background-pixel value; +it is simply truncated to the appropriate number of bits. +For a +.PN ParentRelative +background, +the background tile origin always aligns with the parent's background tile +origin. +Otherwise, the background tile origin is always the window origin. +.LP +When no valid contents are available for regions of a window +and the regions are either visible or the server is maintaining backing store, +the server automatically tiles the regions with the window's background +unless the window has a background of +.PN None . +If the background is +.PN None , +the previous screen contents from other windows of the same depth as the window +are simply left in place if the contents come from the parent of the window +or an inferior of the parent; +otherwise, the initial contents of the exposed regions are undefined. +Exposure events are then generated for the regions, even if the background is +.PN None . +.LP +The border tile origin is always the same as the background tile origin. +If border-pixmap is given, +it overrides the default border-pixmap. +The border pixmap and the window must have the same root +and the same depth (or a +.PN Match +error results). +Any size pixmap can be used, +although some sizes may be faster than others. +If +.PN CopyFromParent +is given, the parent's border pixmap is copied (subsequent changes to +the parent's border attribute do not affect the child), +but the window must have the same depth as the parent (or a +.PN Match +error results). +The pixmap might be copied by sharing the same pixmap object between the +child and parent or by making a complete copy of the pixmap contents. +If border-pixel is given, +it overrides the default border-pixmap and any border-pixmap given explicitly, +and a pixmap of undefined size filled with border-pixel is used for the border. +Range checking is not performed on the border-pixel value; +it is simply truncated to the appropriate number of bits. +.LP +Output to a window is always clipped to the inside of the window, +so that the border is never affected. +.LP +The bit-gravity defines which region of the window should be retained +if the window is resized, and win-gravity defines how the window should +be repositioned if the parent is resized (see +.PN ConfigureWindow +request). +.LP +A backing-store of +.PN WhenMapped +advises the server that maintaining contents of obscured regions +when the window is mapped would be beneficial. +A backing-store of +.PN Always +advises the server that maintaining contents even when the window is +unmapped would be beneficial. +In this case, +the server may generate an exposure event when the window is created. +A value of +.PN NotUseful +advises the server that maintaining contents is unnecessary, +although a server may still choose to maintain contents while the window +is mapped. +Note that if the server maintains contents, +then the server should maintain complete contents +not just the region within the parent boundaries, +even if the window is larger than its parent. +While the server maintains contents, +exposure events will not normally be generated, +but the server may stop maintaining contents at any time. +.LP +If save-under is +.PN True , +the server is advised that when this window is +mapped, saving the contents of windows it obscures would be beneficial. +.LP +When the contents of obscured regions of a window are being maintained, +regions obscured by noninferior windows are included in the +destination (and source, when the window is the source) of graphics +requests, but regions obscured by inferior windows are not included. +.LP +The backing-planes indicates (with bits set to 1) which bit planes +of the window hold dynamic data that must be preserved in backing-stores +and during save-unders. +The backing-pixel specifies what value to use in planes not +covered by backing-planes. +The server is free to save only the specified bit planes in the backing-store +or save-under and regenerate the remaining planes with the specified pixel +value. +Any bits beyond the specified depth of the window in these +values are simply ignored. +.LP +The event-mask defines which events the client is interested in for +this window (or for some event types, inferiors of the window). +The do-not-propagate-mask defines which events should not be propagated to +ancestor windows when no client has the event type selected in this +window. +.LP +The override-redirect specifies whether map and configure requests on this +window should override a +.PN SubstructureRedirect +on the parent, typically to inform a window manager not to tamper with +the window. +.LP +The colormap specifies the colormap that best reflects the true +colors of the window. +Servers capable of supporting multiple hardware colormaps may use this +information, and window managers may use it for +.PN InstallColormap +requests. +The colormap must have the same visual type and root as the window (or a +.PN Match +error results). +If +.PN CopyFromParent +is specified, +the parent's colormap is copied (subsequent changes to the parent's +colormap attribute do not affect the child). +However, the window must have the same visual type as the parent (or a +.PN Match +error results), and the parent must not have a colormap of +.PN None +(or a +.PN Match +error results). +For an explanation of +.PN None , +see +.PN FreeColormap +request. +The colormap is copied by sharing the colormap object between the child +and the parent, +not by making a complete copy of the colormap contents. +.LP +If a cursor is specified, +it will be used whenever the pointer is in the window. +If +.PN None +is specified, +the parent's cursor will be used when the pointer is in the window, +and any change in the parent's cursor will cause an immediate change +in the displayed cursor. +.LP +This request generates a +.PN CreateNotify +event. +.LP +The background and border pixmaps and the cursor may be freed +immediately if no further explicit references to them are to be made. +.LP +Subsequent drawing into the background or border pixmap has an +undefined effect on the window state. +The server might or might not make a copy of the pixmap. +.sp +.LP +.sM +.IN "ChangeWindowAttributes" "" "@DEF@" +.PN ChangeWindowAttributes +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIvalue-mask\fP\^: BITMASK +.br +\fIvalue-list\fP\^: LISTofVALUE +.LP +Errors: +.PN Access , +.PN Colormap , +.PN Cursor , +.PN Match , +.PN Pixmap , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +The value-mask and value-list specify which attributes are to be changed. +The values and restrictions are the same as for +.PN CreateWindow . +.LP +Setting a new background, whether by background-pixmap or +background-pixel, overrides any previous background. +Setting a new border, whether by border-pixel or border-pixmap, +overrides any previous border. +.LP +Changing the background does not cause the window contents to be changed. +Setting the border or changing the background such that the +border tile origin changes causes the border to be repainted. +Changing the background of a root window to +.PN None +or +.PN ParentRelative +restores the default background pixmap. +Changing the border of a root window to +.PN CopyFromParent +restores the default border pixmap. +.LP +Changing the win-gravity does not affect the current position of the +window. +.LP +Changing the backing-store of an obscured window to +.PN WhenMapped +or +.PN Always +or changing the backing-planes, backing-pixel, or save-under of +a mapped window may have no immediate effect. +.LP +Multiple clients can select input on the same window; +their event-masks are disjoint. +When an event is generated, +it will be reported to all interested clients. +However, only one client at a time can select for +.PN SubstructureRedirect , +only one client at a time can select for +.PN ResizeRedirect , +and only one client at a time can select for +.PN ButtonPress . +An attempt to violate these restrictions results in an +.PN Access +error. +.LP +There is only one do-not-propagate-mask for a window, not one per +client. +.LP +Changing the colormap of a window (by defining a new map, not by +changing the contents of the existing map) generates a +.PN ColormapNotify +event. +Changing the colormap of a visible window might have no immediate effect +on the screen (see +.PN InstallColormap +request). +.LP +Changing the cursor of a root window to +.PN None +restores the default cursor. +.LP +The order in which attributes are verified and altered is server-dependent. +If an error is generated, +a subset of the attributes may have been altered. +.sp +.LP +.sM +.IN "GetWindowAttributes" "" "@DEF@" +.PN GetWindowAttributes +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.in -.2i +.LP + \(-> +.in +.2i +.LP +visual: VISUALID +.br +class: +.Pn { InputOutput , +.PN InputOnly } +.br +bit-gravity: BITGRAVITY +.br +win-gravity: WINGRAVITY +.br +backing-store: +.Pn { NotUseful , +.PN WhenMapped , +.PN Always } +.br +backing-planes: CARD32 +.br +backing-pixel: CARD32 +.br +save-under: BOOL +.br +colormap: COLORMAP or +.PN None +.br +map-is-installed: BOOL +.br +map-state: +.Pn { Unmapped , +.PN Unviewable , +.PN Viewable } +.br +all-event-masks, your-event-mask: SETofEVENT +.br +do-not-propagate-mask: SETofDEVICEEVENT +.br +override-redirect: BOOL +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +This request returns the current attributes of the window. +A window is +.PN Unviewable +if it is mapped but some ancestor is unmapped. +All-event-masks is the inclusive-OR of all event masks selected on the window +by clients. +Your-event-mask is the event mask selected by the querying client. +.sp +.LP +.sM +.IN "DestroyWindow" "" "@DEF@" +.PN DestroyWindow +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +If the argument window is mapped, +an +.PN UnmapWindow +request is performed automatically. +The window and all inferiors are then destroyed, and a +.PN DestroyNotify +event is generated for each window. +The ordering of the +.PN DestroyNotify +events is such that for any given window, +.PN DestroyNotify +is generated on all inferiors of the window before being generated on +the window itself. +The ordering among siblings and across subhierarchies is not otherwise +constrained. +.LP +Normal exposure processing on formerly obscured windows is performed. +.LP +If the window is a root window, +this request has no effect. +.sp +.LP +.sM +.IN "DestroySubwindows" "" "@DEF@" +.PN DestroySubwindows +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +This request performs a +.PN DestroyWindow +request on all children of the window, in bottom-to-top stacking order. +.sp +.LP +.sM +.IN "ChangeSaveSet" "" "@DEF@" +.PN ChangeSaveSet +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fImode\fP\^: +.Pn { Insert , +.PN Delete } +.LP +Errors: +.PN Match , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request adds or removes the specified window from the client's +save-set. +The window must have been created by some other client (or a +.PN Match +error results). +For further information about the use of the save-set, +see section 10. +.LP +When windows are destroyed, +the server automatically removes them from the save-set. +.sp +.LP +.sM +.IN "ReparentWindow" "" "@DEF@" +.PN ReparentWindow +.in +.2i +.LP +\fIwindow\fP\^, \fIparent\fP\^: WINDOW +.br +\fIx\fP\^, \fIy\fP\^: INT16 +.LP +Errors: +.PN Match , +.PN Window +.in -.2i +.eM +.LP +If the window is mapped, +an +.PN UnmapWindow +request is performed automatically first. +The window is then removed from its current position in the hierarchy +and is inserted as a child of the specified parent. +The x and y coordinates are relative to the parent's origin +and specify the new position of the upper-left outer corner of the +window. +The window is placed on top in the stacking order with respect +to siblings. +A +.PN ReparentNotify +event is then generated. +The override-redirect attribute of the window is passed on in this event; +a value of +.PN True +indicates that a window manager should not tamper with this window. +Finally, if the window was originally mapped, a +.PN MapWindow +request is performed automatically. +.LP +Normal exposure processing on formerly obscured windows is performed. +The server might not generate exposure events for regions from the +initial unmap that are immediately obscured by the final map. +.LP +A +.PN Match +error is generated if: +.IP \(bu 5 +The new parent is not on the same screen as the old parent. +.IP \(bu 5 +The new parent is the window itself or an inferior of the window. +.IP \(bu 5 +The new parent is +.PN InputOnly , +and the window is not. +.IP \(bu 5 +The window has a +.PN ParentRelative +background, and the new parent is not the same depth as the window. +.sp +.LP +.sM +.IN "MapWindow" "" "@DEF@" +.PN MapWindow +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +If the window is already mapped, this request has no effect. +.LP +If the override-redirect attribute of the window is +.PN False +and some other client has selected +.PN SubstructureRedirect +on the parent, then a +.PN MapRequest +event is generated, but the window remains unmapped. +Otherwise, the window is mapped, +and a +.PN MapNotify +event is generated. +.LP +If the window is now viewable and its contents have been discarded, +the window is tiled with its background (if no background is defined, +the existing screen contents are not altered), and zero or more exposure +events are generated. +If a backing-store has been maintained while the window was unmapped, +no exposure events are generated. +If a backing-store will now be maintained, +a full-window exposure is always generated. +Otherwise, only visible regions may be reported. +Similar tiling and exposure take place for any newly viewable inferiors. +.sp +.LP +.sM +.IN "MapSubwindows" "" "@DEF@" +.PN MapSubwindows +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +This request performs a +.PN MapWindow +request on all unmapped children of the window, +in top-to-bottom stacking order. +.sp +.LP +.sM +.IN "UnmapWindow" "" "@DEF@" +.PN UnmapWindow +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +If the window is already unmapped, this request has no effect. +Otherwise, the window is unmapped, and an +.PN UnmapNotify +event is generated. +Normal exposure processing on formerly obscured windows is performed. +.sp +.LP +.sM +.IN "UnmapSubwindows" "" "@DEF@" +.PN UnmapSubwindows +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +This request performs an +.PN UnmapWindow +request on all mapped children of the window, +in bottom-to-top stacking order. +.sp +.LP +.sM +.IN "ConfigureWindow" "" "@DEF@" +.PN ConfigureWindow +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIvalue-mask\fP\^: BITMASK +.br +\fIvalue-list\fP\^: LISTofVALUE +.LP +Errors: +.PN Match , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request changes the configuration of the window. +The value-mask and value-list specify which values are to be given. +The possible values are: +.TS H +l lw(3.1i). +_ +.sp 6p +.B +Attribute Type +.sp 6p +_ +.TH +.R +.sp 6p +T{ +x +T} T{ +INT16 +T} +T{ +y +T} T{ +INT16 +T} +T{ +width +T} T{ +CARD16 +T} +T{ +height +T} T{ +CARD16 +T} +T{ +border-width +T} T{ +CARD16 +T} +T{ +sibling +T} T{ +WINDOW +T} +T{ +stack-mode +T} T{ +.Pn { Above , +.PN Below , +.PN TopIf , +.PN BottomIf , +.PN Opposite } +T} +.sp 6p +_ +.TE +.LP +The x and y coordinates are relative to the parent's origin +and specify the position of the upper-left outer corner of the window. +The width and height specify the inside size, not including the border, and +must be nonzero (or a +.PN Value +error results). +Those values not specified are taken from the existing geometry of the window. +Note that changing just the border-width leaves the outer-left corner +of the window in a fixed position but moves the absolute position of the +window's origin. +It is a +.PN Match +error to attempt to make the border-width of an +.PN InputOnly +window nonzero. +.LP +If the override-redirect attribute of the window is +.PN False +and some other client has selected +.PN SubstructureRedirect +on the parent, a +.PN ConfigureRequest +event is generated, and no further processing is performed. +Otherwise, the following is performed: +.LP +If some other client has selected +.PN ResizeRedirect +on the window and the inside width or height of the window is being changed, +a +.PN ResizeRequest +event is generated, +and the current inside width and height are used instead. +Note that the override-redirect attribute of the window has no effect on +.PN ResizeRedirect +and that +.PN SubstructureRedirect +on the parent has precedence over +.PN ResizeRedirect +on the window. +.LP +The geometry of the window is changed as specified, +the window is restacked among siblings, and a +.PN ConfigureNotify +event is generated if the state of the window actually changes. +If the inside width or height of the window has actually changed, +then children of the window are affected, +according to their win-gravity. +Exposure processing is performed on formerly obscured windows +(including the window itself and its inferiors if regions of them were +obscured but now are not). +Exposure processing is also performed on any new regions of the window +(as a result of increasing the width or height) +and on any regions where window contents are lost. +.LP +If the inside width or height of a window is not changed +but the window is moved or its border is changed, +then the contents of the window are not lost but move with the window. +Changing the inside width or height of the window causes its contents to be +moved or lost, depending on the bit-gravity of the window. +It also causes children to be reconfigured, depending on their win-gravity. +For a change of width and height of W and H, +we define the [x, y] pairs as: +.TS H +l l. +_ +.sp 6p +.B +Direction Deltas +.sp 6p +_ +.TH +.R +.sp 6p +T{ +.PN NorthWest +T} T{ +[\^0, 0\^] +T} +T{ +.PN North +T} T{ +[\^W/2, 0\^] +T} +T{ +.PN NorthEast +T} T{ +[\^W, 0\^] +T} +T{ +.PN West +T} T{ +[\^0, H/2\^] +T} +T{ +.PN Center +T} T{ +[\^W/2, H/2\^] +T} +T{ +.PN East +T} T{ +[\^W, H/2\^] +T} +T{ +.PN SouthWest +T} T{ +[\^0, H\^] +T} +T{ +.PN South +T} T{ +[\^W/2, H\^] +T} +T{ +.PN SouthEast +T} T{ +[\^W, H\^] +T} +.sp 6p +_ +.TE +.LP +When a window with one of these bit-gravities is resized, +the corresponding pair defines the change in position of each pixel in the +window. +When a window with one of these win-gravities has its parent window resized, +the corresponding pair defines the change in position +of the window within the parent. +This repositioning generates a +.PN GravityNotify +event. +.PN GravityNotify +events are generated after the +.PN ConfigureNotify +event is generated. +.LP +A gravity of +.PN Static +indicates that the contents or origin should not move relative to the origin +of the root window. +If the change in size of the window is coupled with a change +in position of [X, Y], +then for bit-gravity the change in position of each pixel is [\-X, \-Y] and for +win-gravity the change in position of a child when its parent is so +resized is [\-X, \-Y]. +Note that +.PN Static +gravity still only takes effect when the width or height of the +window is changed, not when the window is simply moved. +.LP +A bit-gravity of +.PN Forget +indicates that the window contents are always discarded after a size change, +even if backing-store or save-under has been requested. +The window is tiled with its background (except, if no background is defined, +the existing screen contents are not altered) +and zero or more exposure events are generated. +.LP +The contents and borders of inferiors are not affected by their parent's +bit-gravity. +A server is permitted to ignore the specified bit-gravity and use +.PN Forget +instead. +.LP +A win-gravity of +.PN Unmap +is like +.PN NorthWest , +but the child is also unmapped when the parent is resized, +and an +.PN UnmapNotify +event is generated. +.PN UnmapNotify +events are generated after the +.PN ConfigureNotify +event is generated. +.LP +If a sibling and a stack-mode are specified, +the window is restacked as follows: +.TS +lw(1i) lw(4.75i). +T{ +.PN Above +T} T{ +The window is placed just above the sibling. +T} +.sp 6p +T{ +.PN Below +T} T{ +The window is placed just below the sibling. +T} +.sp 6p +T{ +.PN TopIf +T} T{ +If the sibling occludes the window, +then the window is placed at the top of the stack. +T} +.sp 6p +T{ +.PN BottomIf +T} T{ +If the window occludes the sibling, +then the window is placed at the bottom of the stack. +T} +.sp 6p +T{ +.PN Opposite +T} T{ +If the sibling occludes the window, +then the window is placed at the top of the stack. +Otherwise, if the window occludes the sibling, +then the window is placed at the bottom of the stack. +T} +.TE +.LP +If a stack-mode is specified but no sibling is specified, +the window is restacked as follows: +.TS +lw(1i) lw(4.75i). +T{ +.PN Above +T} T{ +The window is placed at the top of the stack. +T} +.sp 6p +T{ +.PN Below +T} T{ +The window is placed at the bottom of the stack. +T} +.sp 6p +T{ +.PN TopIf +T} T{ +If any sibling occludes the window, +then the window is placed at the top of the stack. +T} +.sp 6p +T{ +.PN BottomIf +T} T{ +If the window occludes any sibling, +then the window is placed at the bottom of the stack. +T} +.sp 6p +T{ +.PN Opposite +T} T{ +If any sibling occludes the window, +then the window is placed at the top of the stack. +Otherwise, if the window occludes any sibling, +then the window is placed at the bottom of the stack. +T} +.TE +.LP +It is a +.PN Match +error if a sibling is specified without a stack-mode +or if the window is not actually a sibling. +.LP +Note that the computations for +.PN BottomIf , +.PN TopIf , +and +.PN Opposite +are performed with respect to the window's final geometry (as controlled by +the other arguments to the request), not to its initial geometry. +.LP +Attempts to configure a root window have no effect. +.sp +.LP +.sM +.IN "CirculateWindow" "" "@DEF@" +.PN CirculateWindow +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIdirection\fP\^: +.Pn { RaiseLowest , +.PN LowerHighest } +.LP +Errors: +.PN Value , +.PN Window +.in -.2i +.eM +.LP +If some other client has selected +.PN SubstructureRedirect +on the window, then a +.PN CirculateRequest +event is generated, and no further processing is performed. +Otherwise, the following is performed, and then a +.PN CirculateNotify +event is generated if the window is actually restacked. +.LP +For +.PN RaiseLowest , +.PN CirculateWindow +raises the lowest mapped child (if any) that is +occluded by another child to the top of the stack. +For +.PN LowerHighest , +.PN CirculateWindow +lowers the highest mapped child (if any) that occludes another child to +the bottom of the stack. +Exposure processing is performed on formerly obscured windows. +.sp +.LP +.sM +.IN "GetGeometry" "" "@DEF@" +.PN GetGeometry +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.in -.2i +.LP + \(-> +.in +.2i +.LP +root: WINDOW +.br +depth: CARD8 +.br +x, y: INT16 +.br +width, height, border-width: CARD16 +.LP +Errors: +.PN Drawable +.in -.2i +.eM +.LP +This request returns the root and current geometry of the drawable. +The depth is the number of bits per pixel for the object. +The x, y, and border-width will always be zero for pixmaps. +For a window, +the x and y coordinates specify the upper-left outer corner of the window +relative to its parent's origin, +and the width and height specify the inside size, not including the border. +.LP +It is legal to pass an +.PN InputOnly +window as a drawable to this request. +.sp +.LP +.sM +.IN "QueryTree" "" "@DEF@" +.PN QueryTree +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.LP +.in -.2i + \(-> +.in +.2i +.LP +root: WINDOW +.br +parent: WINDOW or +.PN None +.br +children: LISTofWINDOW +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +This request returns the root, the parent, and the children of the window. +The children are listed in bottom-to-top stacking order. +.sp +.LP +.sM +.IN "InternAtom" "" "@DEF@" +.PN InternAtom +.in +.2i +.LP +\fIname\fP\^: STRING8 +.br +\fIonly-if-exists\fP\^: BOOL +.in -.2i +.LP + \(-> +.in +.2i +.LP +atom: ATOM or +.PN None +.LP +Errors: +.PN Alloc , +.PN Value +.in -.2i +.eM +.LP +This request returns the atom for the given name. +If only-if-exists is +.PN False , +then the atom is created if it does not exist. +The string should use the ISO Latin-1 encoding. +Uppercase and lowercase matter. +.LP +The lifetime of an atom is not tied to the interning client. +Atoms remain defined until server reset (see section 10). +.sp +.LP +.sM +.IN "GetAtomName" "" "@DEF@" +.PN GetAtomName +.in +.2i +.LP +\fIatom\fP\^: ATOM +.in -.2i +.LP + \(-> +.in +.2i +.LP +name: STRING8 +.LP +Errors: +.PN Atom +.in -.2i +.eM +.LP +This request returns the name for the given atom. +.sp +.LP +.sM +.IN "ChangeProperty" "" "@DEF@" +.PN ChangeProperty +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIproperty\fP, \fItype\fP\^: ATOM +.br +\fIformat\fP\^: {8, 16, 32} +.br +\fImode\fP\^: +.Pn { Replace , +.PN Prepend , +.PN Append } +.br +\fIdata\fP\^: LISTofINT8 or LISTofINT16 or LISTofINT32 +.LP +Errors: +.PN Alloc , +.PN Atom , +.PN Match , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request alters the property for the specified window. +The type is uninterpreted by the server. +The format specifies whether the data should be viewed as a list of 8-bit, +16-bit, or 32-bit quantities so that the server can correctly byte-swap +as necessary. +.LP +If the mode is +.PN Replace , +the previous property value is discarded. +If the mode is +.PN Prepend +or +.PN Append , +then the type and format must match the existing property value (or a +.PN Match +error results). +If the property is undefined, +it is treated as defined with the correct type +and format with zero-length data. +For +.PN Prepend , +the data is tacked on to the beginning of the existing data, and for +.PN Append , +it is tacked on to the end of the existing data. +.LP +This request generates a +.PN PropertyNotify +event on the window. +.LP +The lifetime of a property is not tied to the storing client. +Properties remain until explicitly deleted, until the window is destroyed, +or until server reset (see section 10). +.LP +The maximum size of a property is server-dependent and may vary dynamically. +.sp +.LP +.sM +.IN "DeleteProperty" "" "@DEF@" +.PN DeleteProperty +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIproperty\fP\^: ATOM +.LP +Errors: +.PN Atom , +.PN Window +.in -.2i +.eM +.LP +This request deletes the property from the specified window +if the property exists and generates a +.PN PropertyNotify +event on the window unless the property does not exist. +.sp +.LP +.sM +.IN "GetProperty" "" "@DEF@" +.PN GetProperty +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIproperty\fP\^: ATOM +.br +\fItype\fP\^: ATOM or +.PN AnyPropertyType +.br +\fIlong-offset\fP, \fIlong-length\fP\^: CARD32 +.br +\fIdelete\fP\^: BOOL +.in -.2i +.LP + \(-> +.in +.2i +.LP +type: ATOM or +.PN None +.br +format: {0, 8, 16, 32} +.br +bytes-after: CARD32 +.br +value: LISTofINT8 or LISTofINT16 or LISTofINT32 +.LP +Errors: +.PN Atom , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +If the specified property does not exist for the specified window, +then the return type is +.PN None , +the format and bytes-after are zero, +and the value is empty. +The delete argument is ignored in this case. +If the specified property exists but its type does not match the specified type, +then the return type is the actual type of the property, +the format is the actual format of the property (never zero), +the bytes-after is the length of the property in bytes +(even if the format is 16 or 32), +and the value is empty. +The delete argument is ignored in this case. +If the specified property exists and either +.PN AnyPropertyType +is specified or the specified type matches the actual type of the property, +then the return type is the actual type of the property, +the format is the actual format of the property (never zero), +and the bytes-after and value are as follows, given: +.DS +N = actual length of the stored property in bytes +\ \ \ \ (even if the format is 16 or 32) +I = 4 * long-offset +T = N \- I +L = MINIMUM(T, 4 * long-length) +A = N \- (I + L) +.DE +.LP +The returned value starts at byte index I in the property (indexing from 0), +and its length in bytes is L. +However, it is a +.PN Value +error if long-offset is given such that L is negative. +The value of bytes-after is A, +giving the number of trailing unread bytes in the stored +property. +If delete is +.PN True +and the bytes-after is zero, +the property is also deleted from the window, +and a +.PN PropertyNotify +event is generated on the window. +.sp +.LP +.sM +.IN "RotateProperties" "" "@DEF@" +.PN RotateProperties +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIdelta\fP\^: INT16 +.br +\fIproperties\fP\^: LISTofATOM +.LP +Errors: +.PN Atom , +.PN Match , +.PN Window +.in -.2i +.eM +.LP +If the property names in the list are viewed as being numbered starting +from zero, and there are N property names in the list, +then the value associated with property name I becomes the value +associated with property name (I + delta) mod N, for all I from zero to N \- 1. +The effect is to rotate the states by delta places around the virtual ring +of property names (right for positive delta, left for negative delta). +.LP +If delta mod N is nonzero, +a +.PN PropertyNotify +event is generated for each property in the order listed. +.LP +If an atom occurs more than once in the list or no property with that +name is defined for the window, +a +.PN Match +error is generated. +If an +.PN Atom +or +.PN Match +error is generated, no properties are changed. +.sp +.LP +.sM +.IN "ListProperties" "" "@DEF@" +.PN ListProperties +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.in -.2i +.LP + \(-> +.in +.2i +.LP +atoms: LISTofATOM +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +This request returns the atoms of properties currently defined on the window. +.sp +.LP +.sM +.IN "SetSelectionOwner" "" "@DEF@" +.PN SetSelectionOwner +.in +.2i +.LP +\fIselection\fP\^: ATOM +.br +\fIowner\fP\^: WINDOW or +.PN None +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.LP +Errors: +.PN Atom , +.PN Window +.in -.2i +.eM +.LP +This request changes the owner, owner window, +and last-change time of the specified selection. +This request has no effect if the specified time is earlier +than the current last-change time of the specified selection or is +later than the current server time. +Otherwise, the last-change time is set to the specified time +with +.PN CurrentTime +replaced by the current server time. +If the owner window is specified as +.PN None , +then the owner of the selection becomes +.PN None +(that is, no owner). +Otherwise, the owner of the selection becomes the client executing the request. +If the new owner (whether a client or +.PN None ) +is not the same as the current owner +and the current owner is not +.PN None , +then the current owner is sent a +.PN SelectionClear +event. +.LP +If the client that is the owner of a selection is later terminated +(that is, its connection is closed) or if the owner window it has +specified in the request is later destroyed, +then the owner of the selection automatically reverts to +.PN None , +but the last-change time is not affected. +.LP +The selection atom is uninterpreted by the server. +The owner window is returned by the +.PN GetSelectionOwner +request and is reported in +.PN SelectionRequest +and +.PN SelectionClear +events. +.LP +Selections are global to the server. +.sp +.LP +.sM +.IN "GetSelectionOwner" "" "@DEF@" +.PN GetSelectionOwner +.in +.2i +.LP +\fIselection\fP\^: ATOM +.in -.2i +.LP + \(-> +.in +.2i +.LP +owner: WINDOW or +.PN None +.LP +Errors: +.PN Atom +.in -.2i +.eM +.LP +This request returns the current owner window of the specified selection, +if any. +If +.PN None +is returned, then there is no owner for the selection. +.sp +.LP +.sM +.IN "ConvertSelection" "" "@DEF@" +.PN ConvertSelection +.in +.2i +.LP +\fIselection\fP, \fItarget\fP\^: ATOM +.br +\fIproperty\fP\^: ATOM or +.PN None +.br +\fIrequestor\fP\^: WINDOW +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.LP +Errors: +.PN Atom , +.PN Window +.in -.2i +.eM +.LP +If the specified selection has an owner, +the server sends a +.PN SelectionRequest +event to that owner. +If no owner for the specified selection exists, +the server generates a +.PN SelectionNotify +event to the requestor with property +.PN None . +The arguments are passed on unchanged in either of the events. +.sp +.LP +.sM +.IN "SendEvent" "" "@DEF@" +.PN SendEvent +.in +.2i +.LP +\fIdestination\fP\^: WINDOW or +.PN PointerWindow +or +.PN InputFocus +.br +\fIpropagate\fP\^: BOOL +.br +\fIevent-mask\fP\^: SETofEVENT +.br +\fIevent\fP\^: <normal-event-format> +.LP +Errors: +.PN Value , +.PN Window +.in -.2i +.eM +.LP +If +.PN PointerWindow +is specified, +destination is replaced with the window that the pointer is in. +If +.PN InputFocus +is specified and the focus window contains the pointer, +destination is replaced with the window that the pointer is in. +Otherwise, destination is replaced with the focus window. +.LP +If the event-mask is the empty set, +then the event is sent to the client that created the destination window. +If that client no longer exists, no event is sent. +.LP +If propagate is +.PN False , +then the event is sent to every client selecting +on destination any of the event types in event-mask. +.LP +If propagate is +.PN True +and no clients have selected on destination any +of the event types in event-mask, +then destination is replaced with the +closest ancestor of destination for which some client has selected a +type in event-mask and no intervening window has that type in its +do-not-propagate-mask. +If no such window exists or if the window is an ancestor of the focus window +and +.PN InputFocus +was originally specified as the destination, +then the event is not sent to any clients. +Otherwise, the event is reported to every client selecting on the final +destination any of the types specified in event-mask. +.LP +The event code must be one of the core events or one of the events +defined by an extension (or a +.PN Value +error results) so that the server can correctly byte-swap the +contents as necessary. +The contents of the event are otherwise unaltered and unchecked +by the server except to force on the most significant bit of the event code +and to set the sequence number in the event correctly. +.LP +Active grabs are ignored for this request. +.sp +.LP +.sM +.IN "GrabPointer" "" "@DEF@" +.PN GrabPointer +.in +.2i +.LP +\fIgrab-window\fP\^: WINDOW +.br +\fIowner-events\fP\^: BOOL +.br +\fIevent-mask\fP\^: SETofPOINTEREVENT +.br +\fIpointer-mode\fP, \fIkeyboard-mode\fP\^: +.Pn { Synchronous , +.PN Asynchronous } +.br +\fIconfine-to\fP\^: WINDOW or +.PN None +.br +\fIcursor\fP\^: CURSOR or +.PN None +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.in -.2i +.LP + \(-> +.in +.2i +.LP +status: +.Pn { Success , +.PN AlreadyGrabbed , +.PN Frozen , +.PN InvalidTime , +.PN NotViewable } +.LP +Errors: +.PN Cursor , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request actively grabs control of the pointer. +Further pointer events are only reported to the grabbing client. +The request overrides any active pointer grab by this client. +.LP +If owner-events is +.PN False , +all generated pointer events are reported with respect to grab-window +and are only reported if selected by event-mask. +If owner-events is +.PN True +and a generated pointer event would normally be reported to this client, +it is reported normally. +Otherwise, the event is reported with respect to the grab-window and is +only reported if selected by event-mask. +For either value of owner-events, +unreported events are simply discarded. +.LP +If pointer-mode is +.PN Asynchronous , +pointer event processing continues normally. +If the pointer is currently frozen by this client, +then processing of pointer events is resumed. +If pointer-mode is +.PN Synchronous , +the state of the pointer (as seen by means of the protocol) appears to freeze, +and no further pointer events are generated by the server until the +grabbing client issues a releasing +.PN AllowEvents +request or until the pointer grab is released. +Actual pointer changes are not lost while the pointer is frozen. +They are simply queued for later processing. +.LP +If keyboard-mode is +.PN Asynchronous , +keyboard event processing is unaffected by activation of the grab. +If keyboard-mode is +.PN Synchronous , +the state of the keyboard (as seen by means of the protocol) appears to freeze, +and no further keyboard events are generated by the server until the grabbing +client issues a releasing +.PN AllowEvents +request or until the pointer grab is released. +Actual keyboard changes are not lost while the keyboard is frozen. +They are simply queued for later processing. +.LP +If a cursor is specified, +then it is displayed regardless of what window the pointer is in. +If no cursor is specified, +then when the pointer is in grab-window or one of its subwindows, +the normal cursor for that window is displayed. +Otherwise, the cursor for grab-window is displayed. +.LP +If a confine-to window is specified, +then the pointer will be restricted to stay contained in that window. +The confine-to window need have no relationship to the grab-window. +If the pointer is not initially in the confine-to window, +then it is warped automatically to the closest edge +(and enter/leave events are generated normally) just before the grab activates. +If the confine-to window is subsequently reconfigured, +the pointer will be warped automatically as necessary to +keep it contained in the window. +.LP +This request generates +.PN EnterNotify +and +.PN LeaveNotify +events. +.LP +The request fails with status +.PN AlreadyGrabbed +if the pointer is actively grabbed by some other client. +The request fails with status +.PN Frozen +if the pointer is frozen by an active grab of another client. +The request fails with status +.PN NotViewable +if grab-window or confine-to window is not viewable +or if the confine-to window lies completely outside the boundaries +of the root window. +The request fails with status +.PN InvalidTime +if the specified time is earlier than the last-pointer-grab time or later than +the current server time. +Otherwise, the last-pointer-grab time is set to the specified time, with +.PN CurrentTime +replaced by the current server time. +.sp +.LP +.sM +.IN "UngrabPointer" "" "@DEF@" +.PN UngrabPointer +.in +.2i +.LP +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.in -.2i +.eM +.LP +This request releases the pointer if this client has it actively grabbed (from +either +.PN GrabPointer +or +.PN GrabButton +or from a normal button press) and releases any queued events. +The request has no effect if the specified time is earlier than +the last-pointer-grab time or is later than the current server time. +.LP +This request generates +.PN EnterNotify +and +.PN LeaveNotify +events. +.LP +An +.PN UngrabPointer +request is performed automatically if the event window or +confine-to window for an active pointer grab becomes not viewable +or if window reconfiguration causes the confine-to window to lie +completely outside the boundaries of the root window. +.sp +.LP +.sM +.IN "GrabButton" "" "@DEF@" +.PN GrabButton +.in +.2i +.LP +\fImodifiers\fP\^: SETofKEYMASK or +.PN AnyModifier +.br +\fIbutton\fP\^: BUTTON or +.PN AnyButton +.br +\fIgrab-window\fP\^: WINDOW +.br +\fIowner-events\fP\^: BOOL +.br +\fIevent-mask\fP\^: SETofPOINTEREVENT +.br +\fIpointer-mode\fP, \fIkeyboard-mode\fP\^: +.Pn { Synchronous , +.PN Asynchronous } +.br +\fIconfine-to\fP\^: WINDOW or +.PN None +.br +\fIcursor\fP\^: CURSOR or +.PN None +.LP +Errors: +.PN Access , +.PN Cursor , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request establishes a passive grab. +In the future, +the pointer is actively grabbed as described in +.PN GrabPointer , +the last-pointer-grab time is set to the time at which the button was +pressed (as transmitted in the +.PN ButtonPress +event), and the +.PN ButtonPress +event is reported if all of the following conditions are true: +.IP \(bu 5 +The pointer is not grabbed and the specified button is logically pressed +when the specified modifier keys are logically down, +and no other buttons or modifier keys are logically down. +.IP \(bu 5 +The grab-window contains the pointer. +.IP \(bu 5 +The confine-to window (if any) is viewable. +.IP \(bu 5 +A passive grab on the same button/key combination does not exist +on any ancestor of grab-window. +.LP +The interpretation of the remaining arguments is the same as for +.PN GrabPointer . +The active grab is terminated automatically when +the logical state of the pointer has all buttons released, +independent of the logical state of modifier keys. +Note that the logical state of a device (as seen by means of the protocol) +may lag the physical state if device event processing is frozen. +.LP +This request overrides all previous passive grabs by the same client on +the same button/key combinations on the same window. +A modifier of +.PN AnyModifier +is equivalent to issuing the request for all possible modifier combinations +(including the combination of no modifiers). +It is not required that all specified modifiers have currently assigned +keycodes. +A button of +.PN AnyButton +is equivalent to issuing the request for all possible buttons. +Otherwise, it is not required that the button specified currently be assigned +to a physical button. +.LP +An +.PN Access +error is generated if some other client has already issued a +.PN GrabButton +request with the same button/key combination on the same window. +When using +.PN AnyModifier +or +.PN AnyButton , +the request fails completely (no grabs are established), and an +.PN Access +error is generated if there is a conflicting grab for any combination. +The request has no effect on an active grab. +.sp +.LP +.sM +.IN "UngrabButton" "" "@DEF@" +.PN UngrabButton +.in +.2i +.LP +\fImodifiers\fP\^: SETofKEYMASK or +.PN AnyModifier +.br +\fIbutton\fP\^: BUTTON or +.PN AnyButton +.br +\fIgrab-window\fP\^: WINDOW +.LP +Errors: +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request releases the passive button/key combination +on the specified window if it was grabbed by this client. +A modifiers argument of +.PN AnyModifier +is equivalent to issuing the request for all possible modifier +combinations (including the combination of no modifiers). +A button of +.PN AnyButton +is equivalent to issuing the request for all possible buttons. +The request has no effect on an active grab. +.sp +.LP +.sM +.IN "ChangeActivePointerGrab" "" "@DEF@" +.PN ChangeActivePointerGrab +.in +.2i +.LP +\fIevent-mask\fP\^: SETofPOINTEREVENT +.br +\fIcursor\fP\^: CURSOR or +.PN None +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.LP +Errors: +.PN Cursor , +.PN Value +.in -.2i +.eM +.LP +This request changes the specified dynamic parameters if the pointer is +actively grabbed by the client and the specified time is no earlier than the +last-pointer-grab time and no later than the current server time. +The interpretation of event-mask and cursor are the same as in +.PN GrabPointer . +This request has no effect on the parameters of any passive grabs established +with +.PN GrabButton . +.sp +.LP +.sM +.IN "GrabKeyboard" "" "@DEF@" +.PN GrabKeyboard +.in +.2i +.LP +\fIgrab-window\fP\^: WINDOW +.br +\fIowner-events\fP\^: BOOL +.br +\fIpointer-mode\fP, \fIkeyboard-mode\fP\^: +.Pn { Synchronous , +.PN Asynchronous } +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.in -.2i +.LP + \(-> +.in +.2i +.LP +status: +.Pn { Success , +.PN AlreadyGrabbed , +.PN Frozen , +.PN InvalidTime , +.PN NotViewable } +.LP +Errors: +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request actively grabs control of the keyboard. +Further key events are reported only to the grabbing client. +This request overrides any active keyboard grab by this client. +.LP +If owner-events is +.PN False , +all generated key events are reported with respect to grab-window. +If owner-events is +.PN True +and if a generated key event would normally be reported to this client, +it is reported normally. +Otherwise, the event is reported with respect to the grab-window. +Both +.PN KeyPress +and +.PN KeyRelease +events are always reported, +independent of any event selection made by the client. +.LP +If keyboard-mode is +.PN Asynchronous , +keyboard event processing continues normally. +If the keyboard is currently frozen by this client, +then processing of keyboard events is resumed. +If keyboard-mode is +.PN Synchronous , +the state of the keyboard (as seen by means of the protocol) appears to freeze. +No further keyboard events are generated by the server until the +grabbing client issues a releasing +.PN AllowEvents +request or until the keyboard grab is released. +Actual keyboard changes are not lost while the keyboard is frozen. +They are simply queued for later processing. +.LP +If pointer-mode is +.PN Asynchronous , +pointer event processing is unaffected by activation of the grab. +If pointer-mode is +.PN Synchronous , +the state of the pointer (as seen by means of the protocol) appears to freeze. +No further pointer events are generated by the server +until the grabbing client issues a releasing +.PN AllowEvents +request or until the keyboard grab is released. +Actual pointer changes are not lost while the pointer is frozen. +They are simply queued for later processing. +.LP +This request generates +.PN FocusIn +and +.PN FocusOut +events. +.LP +The request fails with status +.PN AlreadyGrabbed +if the keyboard is actively grabbed by some other client. +The request fails with status +.PN Frozen +if the keyboard is frozen by an active grab of another client. +The request fails with status +.PN NotViewable +if grab-window is not viewable. +The request fails with status +.PN InvalidTime +if the specified time is earlier than the last-keyboard-grab time +or later than the current server time. +Otherwise, the last-keyboard-grab time is set to the specified time with +.PN CurrentTime +replaced by the current server time. +.sp +.LP +.sM +.IN "UngrabKeyboard" "" "@DEF@" +.PN UngrabKeyboard +.in +.2i +.LP +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.in -.2i +.eM +.LP +This request releases the keyboard if this client has it actively grabbed +(as a result of either +.PN GrabKeyboard +or +.PN GrabKey ) +and releases any queued events. +The request has no effect if the specified time is earlier than the +last-keyboard-grab time or is later than the current server time. +.LP +This request generates +.PN FocusIn +and +.PN FocusOut +events. +.LP +An +.PN UngrabKeyboard +is performed automatically if the event window for an active keyboard grab +becomes not viewable. +.sp +.LP +.sM +.IN "GrabKey" "" "@DEF@" +.PN GrabKey +.in +.2i +.LP +\fIkey\fP\^: KEYCODE or +.PN AnyKey +.br +\fImodifiers\fP\^: SETofKEYMASK or +.PN AnyModifier +.br +\fIgrab-window\fP\^: WINDOW +.br +\fIowner-events\fP\^: BOOL +.br +\fIpointer-mode\fP, \fIkeyboard-mode\fP\^: +.Pn { Synchronous , +.PN Asynchronous } +.LP +Errors: +.PN Access , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request establishes a passive grab on the keyboard. +In the future, +the keyboard is actively grabbed as described in +.PN GrabKeyboard , +the last-keyboard-grab time is set to the time at which the key was pressed +(as transmitted in the +.PN KeyPress +event), and the +.PN KeyPress +event is reported if all of the following conditions are true: +.IP \(bu 5 +The keyboard is not grabbed and the specified key +(which can itself be a modifier key) is logically pressed +when the specified modifier keys are logically down, +and no other modifier keys are logically down. +.IP \(bu 5 +Either the grab-window is an ancestor of (or is) the focus window, +or the grab-window is a descendent of the focus window and contains the pointer. +.IP \(bu 5 +A passive grab on the same key combination does not exist +on any ancestor of grab-window. +.LP +The interpretation of the remaining arguments is the same as for +.PN GrabKeyboard . +The active grab is terminated automatically when the logical state +of the keyboard has the specified key released, +independent of the logical state of modifier keys. +Note that the logical state of a device (as seen by means of the protocol) +may lag the physical state if device event processing is frozen. +.LP +This request overrides all previous passive grabs by the same client +on the same key combinations on the same window. +A modifier of +.PN AnyModifier +is equivalent to issuing the request for all possible modifier combinations +(including the combination of no modifiers). +It is not required that all modifiers specified have +currently assigned keycodes. +A key of +.PN AnyKey +is equivalent to issuing the request for all possible keycodes. +Otherwise, the key must be in the range specified by min-keycode +and max-keycode in the connection setup (or a +.PN Value +error results). +.LP +An +.PN Access +error is generated if some other client has issued a +.PN GrabKey +with the same key combination on the same window. +When using +.PN AnyModifier +or +.PN AnyKey , +the request fails completely (no grabs are established), +and an +.PN Access +error is generated if there is a conflicting grab for any combination. +.sp +.LP +.sM +.IN "UngrabKey" "" "@DEF@" +.PN UngrabKey +.in +.2i +.LP +\fIkey\fP\^: KEYCODE or +.PN AnyKey +.br +\fImodifiers\fP\^: SETofKEYMASK or +.PN AnyModifier +.br +\fIgrab-window\fP\^: WINDOW +.LP +Errors: +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request releases the key combination on the specified window +if it was grabbed by this client. +A modifiers argument of +.PN AnyModifier +is equivalent to issuing the request for all possible modifier combinations +(including the combination of no modifiers). +A key of +.PN AnyKey +is equivalent to issuing the request for all possible keycodes. +This request has no effect on an active grab. +.sp +.LP +.sM +.IN "AllowEvents" "" "@DEF@" +.PN AllowEvents +.in +.2i +.LP +\fImode\fP: +.Pn { AsyncPointer , +.PN SyncPointer , +.PN ReplayPointer , +.PN AsyncKeyboard , +.br +\ \ \ \ \ \ \ \ \ \ +.PN SyncKeyboard , +.PN ReplayKeyboard , +.PN AsyncBoth , +.PN SyncBoth } +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +This request releases some queued events if the client has caused a device to +freeze. +The request has no effect if the specified time is earlier +than the last-grab time of the most recent active grab for the client +or if the specified time is later than the current server time. +.LP +For +.PN AsyncPointer , +if the pointer is frozen by the client, +pointer event processing continues normally. +If the pointer is frozen twice by the client on behalf of two separate grabs, +.PN AsyncPointer +thaws for both. +.PN AsyncPointer +has no effect if the pointer is not frozen by the client, +but the pointer need not be grabbed by the client. +.LP +For +.PN SyncPointer , +if the pointer is frozen and actively grabbed by the client, +pointer event processing continues normally until the next +.PN ButtonPress +or +.PN ButtonRelease +event is reported to the client, +at which time the pointer again appears to freeze. +However, if the reported event causes the pointer grab to be released, +then the pointer does not freeze. +.PN SyncPointer +has no effect if the pointer is not frozen by the +client or if the pointer is not grabbed by the client. +.LP +For +.PN ReplayPointer , +if the pointer is actively grabbed by the client and +is frozen as the result of an event having been sent to the client +(either from the activation of a +.PN GrabButton +or from a previous +.PN AllowEvents +with mode +.PN SyncPointer +but not from a +.PN GrabPointer ), +then the pointer grab is released and that event is completely reprocessed, +this time ignoring any passive grabs at or above (towards the root) +the grab-window of the grab just released. +The request has no effect if the pointer is not grabbed by the client +or if the pointer is not frozen as the result of an event. +.LP +For +.PN AsyncKeyboard , +if the keyboard is frozen by the client, +keyboard event processing continues normally. +If the keyboard is frozen twice by the client on behalf of two separate grabs, +.PN AsyncKeyboard +thaws for both. +.PN AsyncKeyboard +has no effect if the keyboard is not frozen by the client, +but the keyboard need not be grabbed by the client. +.LP +For +.PN SyncKeyboard , +if the keyboard is frozen and actively grabbed by the client, +keyboard event processing continues normally until the next +.PN KeyPress +or +.PN KeyRelease +event is reported to the client, +at which time the keyboard again appears to freeze. +However, if the reported event causes the keyboard grab to be released, +then the keyboard does not freeze. +.PN SyncKeyboard +has no effect if the keyboard is not frozen by the client or +if the keyboard is not grabbed by the client. +.LP +For +.PN ReplayKeyboard , +if the keyboard is actively grabbed by the client +and is frozen as the result of an event having been sent to the client +(either from the activation of a +.PN GrabKey +or from a previous +.PN AllowEvents +with mode +.PN SyncKeyboard +but not from a +.PN GrabKeyboard ), +then the keyboard grab is released and that event is completely reprocessed, +this time ignoring any passive grabs at or above (towards the root) +the grab-window of the grab just released. +The request has no effect if the keyboard is not grabbed by the client +or if the keyboard is not frozen as the result of an event. +.LP +For +.PN SyncBoth , +if both pointer and keyboard are frozen by the client, +event processing (for both devices) continues normally until the next +.PN ButtonPress , +.PN ButtonRelease , +.PN KeyPress , +or +.PN KeyRelease +event is reported to the client for a grabbed device +(button event for the pointer, key event for the keyboard), +at which time the devices again appear to freeze. +However, if the reported event causes the grab to be released, +then the devices do not freeze (but if the other device is still +grabbed, then a subsequent event for it will still cause both devices +to freeze). +.PN SyncBoth +has no effect unless both pointer and keyboard are frozen by the client. +If the pointer or keyboard is frozen twice by the client on behalf +of two separate grabs, +.PN SyncBoth +thaws for both (but a subsequent freeze for +.PN SyncBoth +will only freeze each device once). +.LP +For +.PN AsyncBoth , +if the pointer and the keyboard are frozen by the client, +event processing for both devices continues normally. +If a device is frozen twice by the client on behalf of two separate grabs, +.PN AsyncBoth +thaws for both. +.PN AsyncBoth +has no effect unless both pointer and keyboard are frozen by the client. +.LP +.PN AsyncPointer , +.PN SyncPointer , +and +.PN ReplayPointer +have no effect on processing of keyboard events. +.PN AsyncKeyboard , +.PN SyncKeyboard , +and +.PN ReplayKeyboard +have no effect on processing of pointer events. +.LP +It is possible for both a pointer grab and a keyboard grab to be active +simultaneously (by the same or different clients). +When a device is frozen on behalf of either grab, +no event processing is performed for the device. +It is possible for a single device to be frozen because of both grabs. +In this case, the freeze must be released on behalf of both grabs +before events can again be processed. +If a device is frozen twice by a single client, then a single +.PN AllowEvents +releases both. +.sp +.LP +.sM +.IN "GrabServer" "" "@DEF@" +.PN GrabServer +.eM +.LP +This request disables processing of requests and close-downs on all +connections other than the one this request arrived on. +.sp +.LP +.sM +.IN "UngrabServer" "" "@DEF@" +.PN UngrabServer +.eM +.LP +This request restarts processing of requests and close-downs +on other connections. +.sp +.LP +.sM +.IN "QueryPointer" "" "@DEF@" +.PN QueryPointer +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.in -.2i +.LP + \(-> +.in +.2i +.LP +root: WINDOW +.br +child: WINDOW or +.PN None +.br +same-screen: BOOL +.br +root-x, root-y, win-x, win-y: INT16 +.br +mask: SETofKEYBUTMASK +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +The root window the pointer is logically on and the pointer coordinates +relative to the root's origin are returned. +If same-screen is +.PN False , +then the pointer is not on the same screen as the argument window, +child is +.PN None , +and win-x and win-y are zero. +If same-screen is +.PN True , +then win-x and win-y are the pointer coordinates relative to the +argument window's origin, and child is the child containing the +pointer, if any. +The current logical state of the modifier keys and the buttons +are also returned. +Note that the logical state of a device (as seen by means of the protocol) +may lag the physical state if device event processing is frozen. +.sp +.LP +.sM +.IN "GetMotionEvents" "" "@DEF@" +.PN GetMotionEvents +.in +.2i +.LP +\fIstart\fP, \fIstop\fP\^: TIMESTAMP or +.PN CurrentTime +.br +\fIwindow\fP\^: WINDOW +.in -.2i +.LP + \(-> +.in +.2i +.LP +events: LISTofTIMECOORD +.LP +where: +.TS +l l. +TIMECOORD: [x, y: INT16 +.br + \ time: TIMESTAMP] +.TE +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +This request returns all events in the motion history buffer that fall +between the specified start and stop times (inclusive) +and that have coordinates that lie within (including borders) +the specified window at its present placement. +The x and y coordinates are reported relative to the origin of the window. +.LP +If the start time is later than the stop time or if the start time is +in the future, no events are returned. +If the stop time is in the future, it is equivalent to specifying +.PN CurrentTime . +.sp +.LP +.sM +.IN "TranslateCoordinates" "" "@DEF@" +.PN TranslateCoordinates +.in +.2i +.LP +\fIsrc-window\fP, \fIdst-window\fP: WINDOW +.br +\fIsrc-x\fP, \fIsrc-y\fP\^: INT16 +.in -.2i +.LP + \(-> +.in +.2i +.LP +same-screen: BOOL +.br +child: WINDOW or +.PN None +.br +dst-x, dst-y: INT16 +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +The src-x and src-y coordinates are taken relative to src-window's +origin and are returned as dst-x and dst-y coordinates relative to +dst-window's origin. +If same-screen is +.PN False , +then src-window and dst-window are on different screens, +and dst-x and dst-y are zero. +If the coordinates are contained in a mapped child of dst-window, +then that child is returned. +.sp +.LP +.sM +.IN "WarpPointer" "" "@DEF@" +.PN WarpPointer +.in +.2i +.LP +\fIsrc-window\fP\^: WINDOW or +.PN None +.br +\fIdst-window\fP\^: WINDOW or +.PN None +.br +\fIsrc-x\fP, \fIsrc-y\fP\^: INT16 +.br +\fIsrc-width\fP, \fIsrc-height\fP\^: CARD16 +.br +\fIdst-x\fP, \fIdst-y\fP\^: INT16 +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +If dst-window is +.PN None , +this request moves the pointer by offsets [dst-x, dst-y] +relative to the current position of the pointer. +If dst-window is a window, +this request moves the pointer to [dst-x, dst-y] relative to dst-window's +origin. +However, if src-window is not +.PN None , +the move only takes place if src-window contains the pointer +and the pointer is contained in the specified rectangle of src-window. +.LP +The src-x and src-y coordinates are relative to src-window's origin. +If src-height is zero, +it is replaced with the current height of src-window minus src-y. +If src-width is zero, +it is replaced with the current width of src-window minus src-x. +.LP +This request cannot be used to move the pointer outside the confine-to +window of an active pointer grab. +An attempt will only move the pointer as far as the closest edge +of the confine-to window. +.LP +This request will generate events just as if the user had instantaneously +moved the pointer. +.sp +.LP +.sM +.IN "SetInputFocus" "" "@DEF@" +.PN SetInputFocus +.in +.2i +.LP +\fIfocus\fP\^: WINDOW or +.PN PointerRoot +or +.PN None +.br +\fIrevert-to\fP\^: +.Pn { Parent , +.PN PointerRoot , +.PN None } +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.LP +Errors: +.PN Match , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request changes the input focus and the last-focus-change time. +The request has no effect if the specified time is earlier than the current +last-focus-change time or is later than the current server time. +Otherwise, the last-focus-change time is set to the specified time +with +.PN CurrentTime +replaced by the current server time. +.LP +If +.PN None +is specified as the focus, +all keyboard events are discarded until a new focus window is set. +In this case, the revert-to argument is ignored. +.LP +If a window is specified as the focus, +it becomes the keyboard's focus window. +If a generated keyboard event would normally be reported to +this window or one of its inferiors, the event is reported normally. +Otherwise, the event is reported with respect to the focus window. +.LP +If +.PN PointerRoot +is specified as the focus, +the focus window is dynamically taken to be the root window of whatever screen +the pointer is on at each keyboard event. +In this case, +the revert-to argument is ignored. +.LP +This request generates +.PN FocusIn +and +.PN FocusOut +events. +.LP +The specified focus window must be viewable at the time of the request (or a +.PN Match +error results). +If the focus window later becomes not viewable, +the new focus window depends on the revert-to argument. +If revert-to is +.PN Parent , +the focus reverts to the parent (or the closest viewable ancestor) +and the new revert-to value is taken to be +.PN None . +If revert-to is +.PN PointerRoot +or +.PN None , +the focus reverts to that value. +When the focus reverts, +.PN FocusIn +and +.PN FocusOut +events are generated, +but the last-focus-change time is not affected. +.sp +.LP +.sM +.IN "GetInputFocus" "" "@DEF@" +.PN GetInputFocus +.LP + \(-> +.in +.2i +.LP +focus: WINDOW or +.PN PointerRoot +or +.PN None +.br +revert-to: +.Pn { Parent , +.PN PointerRoot , +.PN None } +.in -.2i +.eM +.LP +This request returns the current focus state. +.sp +.LP +.sM +.IN "QueryKeymap" "" "@DEF@" +.PN QueryKeymap +.LP + \(-> +.in +.2i +.LP +keys: LISTofCARD8 +.in -.2i +.eM +.LP +This request returns a bit vector for the logical state of the keyboard. +Each bit set to 1 indicates that the corresponding key is currently pressed. +The vector is represented as 32 bytes. +Byte N (from 0) contains the bits for keys 8N to 8N + 7 +with the least significant bit in the byte representing key 8N. +Note that the logical state of a device (as seen by means of the protocol) +may lag the physical state if device event processing is frozen. +.sp +.LP +.sM +.IN "OpenFont" "" "@DEF@" +.PN OpenFont +.in +.2i +.LP +\fIfid\fP\^: FONT +.br +\fIname\fP\^: STRING8 +.LP +Errors: +.PN Alloc , +.PN IDChoice , +.PN Name +.in -.2i +.eM +.LP +This request loads the specified font, if necessary, +and associates identifier fid with it. +The font name should use the ISO Latin-1 encoding, +and uppercase and lowercase do not matter. +When the characters ``?'' and ``*'' are used in a font name, a +pattern match is performed and any matching font is used. +In the pattern, +the ``?'' character (octal value 77) will match any single character, +and the ``*'' character (octal value 52) will match any number +of characters. +A structured format for font names is specified in the +X Consortium standard \fIX Logical Font Description Conventions\fP. +.LP +Fonts are not associated with a particular screen +and can be stored as a component of any graphics context. +.sp +.LP +.sM +.IN "CloseFont" "" "@DEF@" +.PN CloseFont +.in +.2i +.LP +\fIfont\fP\^: FONT +.LP +Errors: +.PN Font +.in -.2i +.eM +.LP +This request deletes the association between the resource ID and the font. +The font itself will be freed when no other resource references it. +.sp +.LP +.sM +.IN "QueryFont" "" "@DEF@" +.PN QueryFont +.in +.2i +.LP +\fIfont\fP\^: FONTABLE +.in -.2i +.LP + \(-> +.in +.2i +.LP +font-info: FONTINFO +.br +char-infos: LISTofCHARINFO +.LP +where: +.IP +.TS +l lw(3i). +T{ +FONTINFO: +T} T{ +[draw-direction: +.Pn { LeftToRight , +.PN RightToLeft } +T} + \ min-char-or-byte2, max-char-or-byte2: CARD16 + \ min-byte1, max-byte1: CARD8 + \ all-chars-exist: BOOL + \ default-char: CARD16 + \ min-bounds: CHARINFO + \ max-bounds: CHARINFO + \ font-ascent: INT16 + \ font-descent: INT16 + \ properties: LISTofFONTPROP] +FONTPROP: [name: ATOM + \ value: <32-bit-value>] +CHARINFO: [left-side-bearing: INT16 + \ right-side-bearing: INT16 + \ character-width: INT16 + \ ascent: INT16 + \ descent: INT16 + \ attributes: CARD16] +.TE +.LP +Errors: +.PN Font +.in -.2i +.eM +.LP +This request returns logical information about a font. +If a gcontext is given for font, +the currently contained font is used. +.LP +The draw-direction is just a hint +and indicates whether most char-infos have a positive, +.PN LeftToRight , +or a negative, +.PN RightToLeft , +character-width metric. +The core protocol defines no support for vertical text. +.LP +If min-byte1 and max-byte1 are both zero, +then min-char-or-byte2 specifies the linear character index corresponding +to the first element of char-infos, +and max-char-or-byte2 specifies the linear character index of the last element. +If either min-byte1 or max-byte1 are nonzero, +then both min-char-or-byte2 and max-char-or-byte2 will be less than 256, +and the 2-byte character index values corresponding to char-infos element N +(counting from 0) are: +.DS +byte1 = N/D + min-byte1 +byte2 = N\\\\D + min-char-or-byte2 +.DE +.LP +where: +.DS +D = max-char-or-byte2 \- min-char-or-byte2 + 1 +/ = integer division +\\\\ = integer modulus +.DE +.LP +If char-infos has length zero, +then min-bounds and max-bounds will be identical, +and the effective char-infos is one filled with this char-info, of length: +.DS +L = D * (max-byte1 \- min-byte1 + 1) +.DE +.LP +That is, +all glyphs in the specified linear or matrix range have the same information, +as given by min-bounds (and max-bounds). +If all-chars-exist is +.PN True , +then all characters in char-infos have nonzero bounding boxes. +.LP +The default-char specifies the character that will be used when an +undefined or nonexistent character is used. +Note that default-char is a CARD16, not CHAR2B. +For a font using 2-byte matrix format, +the default-char has byte1 in the most significant byte +and byte2 in the least significant byte. +If the default-char itself specifies an undefined or nonexistent character, +then no printing is performed for an undefined or nonexistent character. +.LP +The min-bounds and max-bounds contain the minimum and maximum values of +each individual CHARINFO component over all char-infos (ignoring +nonexistent characters). +The bounding box of the font (that is, the +smallest rectangle enclosing the shape obtained by superimposing all +characters at the same origin [x,y]) has its upper-left coordinate at: +.DS +[x + min-bounds.left-side-bearing, y \- max-bounds.ascent] +.DE +with a width of: +.DS +max-bounds.right-side-bearing \- min-bounds.left-side-bearing +.DE +.LP +and a height of: +.DS +max-bounds.ascent + max-bounds.descent +.DE +.LP +The font-ascent is the logical extent of the font above the baseline +and is used for determining line spacing. +Specific characters may extend beyond this. +The font-descent is the logical extent of the font at or below the baseline +and is used for determining line spacing. +Specific characters may extend beyond this. +If the baseline is at Y-coordinate y, +then the logical extent of the font is inclusive +between the Y-coordinate values (y \- font-ascent) and (y + font-descent \- 1). +.LP +A font is not guaranteed to have any properties. +The interpretation of the property value (for example, INT32, CARD32) +must be derived from \fIa priori\fP knowledge of the property. +A basic set of font properties is specified in the X Consortium +standard \fIX Logical Font Description Conventions\fP. +.LP +For a character origin at [x,y], +the bounding box of a character (that is, +the smallest rectangle enclosing the character's shape), described in +terms of CHARINFO components, is a rectangle with its upper-left corner at: +.DS +[x + left-side-bearing, y \- ascent] +.DE +.LP +with a width of: +.DS +right-side-bearing \- left-side-bearing +.DE +.LP +and a height of: +.DS +ascent + descent +.DE +.LP +and the origin for the next character is defined to be: +.DS +[x + character-width, y] +.DE +.LP +Note that the baseline is logically viewed as being just below +nondescending characters (when descent is zero, only pixels with +Y-coordinates less than y are drawn) and that the origin is logically +viewed as being coincident with the left edge of a nonkerned character +(when left-side-bearing is zero, no pixels with X-coordinate less than +x are drawn). +.LP +Note that CHARINFO metric values can be negative. +.LP +A nonexistent character is represented with all CHARINFO components +zero. +.LP +The interpretation of the per-character attributes field is +server-dependent. +.sp +.LP +.sM +.IN "QueryTextExtents" "" "@DEF@" +.PN QueryTextExtents +.in +.2i +.LP +\fIfont\fP\^: FONTABLE +.br +\fIstring\fP\^: STRING16 +.in -.2i +.LP + \(-> +.in +.2i +.LP +draw-direction: +.Pn { LeftToRight , +.PN RightToLeft } +.br +font-ascent: INT16 +.br +font-descent: INT16 +.br +overall-ascent: INT16 +.br +overall-descent: INT16 +.br +overall-width: INT32 +.br +overall-left: INT32 +.br +overall-right: INT32 +.LP +Errors: +.PN Font +.in -.2i +.eM +.LP +This request returns the logical extents of the specified string of characters +in the specified font. +If a gcontext is given for font, +the currently contained font is used. +The draw-direction, font-ascent, and font-descent are the same as +described in +.PN QueryFont . +The overall-ascent is the maximum of the ascent metrics of all characters +in the string, and the overall-descent is the maximum of the descent metrics. +The overall-width is the sum of the character-width metrics of all characters +in the string. +For each character in the string, +let W be the sum of the character-width metrics of all characters preceding it +in the string, +let L be the left-side-bearing metric of the character plus W, +and let R be the right-side-bearing metric of the character plus W. +The overall-left is the minimum L of all characters in the string, +and the overall-right is the maximum R. +.LP +For fonts defined with linear indexing rather than 2-byte matrix indexing, +the server will interpret each CHAR2B as a 16-bit number that +has been transmitted most significant byte first (that is, byte1 of the +CHAR2B is taken as the most significant byte). +.LP +Characters with all zero metrics are ignored. +If the font has no defined default-char, +then undefined characters in the string are also ignored. +.sp +.LP +.sM +.IN "ListFonts" "" "@DEF@" +.PN ListFonts +.in +.2i +.LP +\fIpattern\fP\^: STRING8 +.br +\fImax-names\fP\^: CARD16 +.in -.2i +.LP + \(-> +.in +.2i +.LP +names: LISTofSTRING8 +.in -.2i +.eM +.LP +This request returns a list +of available font names (as controlled by the font search path; see +.PN SetFontPath +request) +that match the pattern. +At most, max-names names will be returned. +The pattern should use the ISO Latin-1 encoding, +and uppercase and lowercase do not matter. +In the pattern, +the ``?'' character (octal value 77) will match any single character, +and the ``*'' character (octal value 52) will match any number +of characters. +The returned names are in lowercase. +.sp +.LP +.sM +.IN "ListFontsWithInfo" "" "@DEF@" +.PN ListFontsWithInfo +.in +.2i +.LP +\fIpattern\fP\^: STRING8 +.br +\fImax-names\fP\^: CARD16 +.in -.2i +.LP + \(->+ +.in +.2i +.LP +name: STRING8 +.br +info: FONTINFO +.br +replies-hint: CARD32 +.LP +where: +.LP +FONTINFO: <same type definition as in +.PN QueryFont > +.in -.2i +.eM +.LP +This request is similar to +.PN ListFonts , +but it also returns information about each font. +The information returned for each font is identical to what +.PN QueryFont +would return except that the per-character metrics are not returned. +Note that this request can generate multiple replies. +With each reply, +replies-hint may provide an indication of how many more fonts will be returned. +This number is a hint only and may be larger or smaller than +the number of fonts actually returned. +A zero value does not guarantee that no more fonts will be returned. +After the font replies, +a reply with a zero-length name is sent to indicate the end of the reply +sequence. +.sp +.LP +.sM +.IN "SetFontPath" "" "@DEF@" +.PN SetFontPath +.in +.2i +.LP +\fIpath\fP\^: LISTofSTRING8 +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +This request defines the search path for font lookup. +There is only one search path per server, not one per client. +The interpretation of the strings is operating-system-dependent, +but the strings are intended to specify directories to be searched in the +order listed. +.LP +Setting the path to the empty list restores the default path defined +for the server. +.LP +As a side effect of executing this request, +the server is guaranteed to flush all cached information about fonts +for which there currently are no explicit resource IDs allocated. +.LP +The meaning of an error from this request is system specific. +.sp +.LP +.sM +.IN "GetFontPath" "" "@DEF@" +.PN GetFontPath +.LP + \(-> +.in +.2i +.LP +path: LISTofSTRING8 +.in -.2i +.eM +.LP +This request returns the current search path for fonts. +.sp +.LP +.sM +.IN "CreatePixmap" "" "@DEF@" +.PN CreatePixmap +.in +.2i +.LP +\fIpid\fP\^: PIXMAP +.br +\fIdrawable\fP\^: DRAWABLE +.br +\fIdepth\fP\^: CARD8 +.br +\fIwidth\fP, \fIheight\fP\^: CARD16 +.LP +Errors: +.PN Alloc , +.PN Drawable , +.PN IDChoice , +.PN Value +.in -.2i +.eM +.LP +This request creates a pixmap and assigns the identifier pid to it. +The width and height must be nonzero (or a +.PN Value +error results). +The depth must be one of the depths supported by the root of the specified +drawable (or a +.PN Value +error results). +The initial contents of the pixmap are undefined. +.LP +It is legal to pass an +.PN InputOnly +window as a drawable to this request. +.sp +.LP +.sM +.IN "FreePixmap" "" "@DEF@" +.PN FreePixmap +.in +.2i +.LP +\fIpixmap\fP\^: PIXMAP +.LP +Errors: +.PN Pixmap +.in -.2i +.eM +.LP +This request deletes the association between the resource ID and the pixmap. +The pixmap storage will be freed when no other resource references it. +.sp +.LP +.sM +.IN "CreateGC" "" "@DEF@" +.PN CreateGC +.in +.2i +.LP +\fIcid\fP\^: GCONTEXT +.br +\fIdrawable\fP\^: DRAWABLE +.br +\fIvalue-mask\fP\^: BITMASK +.br +\fIvalue-list\fP\^: LISTofVALUE +.LP +Errors: +.PN Alloc , +.PN Drawable , +.PN Font , +.PN IDChoice , +.PN Match , +.PN Pixmap , +.PN Value +.in -.2i +.eM +.LP +This request creates a graphics context +and assigns the identifier cid to it. +The gcontext can be used with any destination drawable having the same root +and depth as the specified drawable; +use with other drawables results in a +.PN Match +error. +.LP +The value-mask and value-list specify which components are to be +explicitly initialized. +The context components are: +.TS H +lw(1.5i) lw(4.25i). +_ +.sp 6p +.B +Component Type +.sp 6p +_ +.TH +.R +.sp 6p +T{ +function +T} T{ +.Pn { Clear , +.PN And , +.PN AndReverse , +.PN Copy , +.PN AndInverted , +.PN NoOp , +.PN Xor , +.br +\ +.PN Or , +.PN Nor , +.PN Equiv , +.PN Invert , +.PN OrReverse , +.PN CopyInverted , +.br +\ +.PN OrInverted , +.PN Nand , +.PN Set } +T} +T{ +plane-mask +T} T{ +CARD32 +T} +T{ +foreground +T} T{ +CARD32 +T} +T{ +background +T} T{ +CARD32 +T} +T{ +line-width +T} T{ +CARD16 +T} +T{ +line-style +T} T{ +.Pn { Solid , +.PN OnOffDash , +.PN DoubleDash } +T} +T{ +cap-style +T} T{ +.Pn { NotLast , +.PN Butt , +.PN Round , +.PN Projecting } +T} +T{ +join-style +T} T{ +.Pn { Miter , +.PN Round , +.PN Bevel } +T} +T{ +fill-style +T} T{ +.Pn { Solid , +.PN Tiled , +.PN OpaqueStippled , +.PN Stippled } +T} +T{ +fill-rule +T} T{ +.Pn { EvenOdd , +.PN Winding } +T} +T{ +arc-mode +T} T{ +.Pn { Chord , +.PN PieSlice } +T} +T{ +tile +T} T{ +PIXMAP +T} +T{ +stipple +T} T{ +PIXMAP +T} +T{ +tile-stipple-x-origin +T} T{ +INT16 +T} +T{ +tile-stipple-y-origin +T} T{ +INT16 +T} +T{ +font +T} T{ +FONT +T} +T{ +subwindow-mode +T} T{ +.Pn { ClipByChildren , +.PN IncludeInferiors } +T} +T{ +graphics-exposures +T} T{ +BOOL +T} +T{ +clip-x-origin +T} T{ +INT16 +T} +T{ +clip-y-origin +T} T{ +INT16 +T} +T{ +clip-mask +T} T{ +PIXMAP or +.PN None +T} +T{ +dash-offset +T} T{ +CARD16 +T} +T{ +dashes +T} T{ +CARD8 +T} +.sp 6p +_ +.TE +.LP +In graphics operations, +given a source and destination pixel, +the result is computed bitwise on corresponding bits of the pixels; +that is, a Boolean operation is performed in each bit plane. +The plane-mask restricts the operation to a subset of planes, +so the result is: +.LP +.DS +((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) +.DE +.LP +Range checking is not performed on the values for foreground, background, +or plane-mask. +They are simply truncated to the appropriate number of bits. +.LP +The meanings of the functions are: +.TS +lw(1.5i) lw(2i). +_ +.sp 6p +.B +Function Operation +.sp 6p +_ +.R +.sp 6p +T{ +.PN Clear +T} T{ +0 +T} +T{ +.PN And +T} T{ +src AND dst +T} +T{ +.PN AndReverse +T} T{ +src AND (NOT dst) +T} +T{ +.PN Copy +T} T{ +src +T} +T{ +.PN AndInverted +T} T{ +(NOT src) AND dst +T} +T{ +.PN NoOp +T} T{ +dst +T} +T{ +.PN Xor +T} T{ +src XOR dst +T} +T{ +.PN Or +T} T{ +src OR dst +T} +T{ +.PN Nor +T} T{ +(NOT src) AND (NOT dst) +T} +T{ +.PN Equiv +T} T{ +(NOT src) XOR dst +T} +T{ +.PN Invert +T} T{ +NOT dst +T} +T{ +.PN OrReverse +T} T{ +src OR (NOT dst) +T} +T{ +.PN CopyInverted +T} T{ +NOT src +T} +T{ +.PN OrInverted +T} T{ +(NOT src) OR dst +T} +T{ +.PN Nand +T} T{ +(NOT src) OR (NOT dst) +T} +T{ +.PN Set +T} T{ +1 +T} +.sp 6p +_ +.TE +.LP +The line-width is measured in pixels and can be greater than or equal to +one, a wide line, or the special value zero, a thin line. +.LP +Wide lines are drawn centered on the path described by the graphics request. +Unless otherwise specified by the join or cap style, +the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and +width w is a rectangle with vertices at the following real coordinates: +.DS +[x1\-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1\-(w*cs/2)], +[x2\-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2\-(w*cs/2)] +.DE +.LP +The sn is the sine of the angle of the line and cs is the cosine of +the angle of the line. +A pixel is part of the line (and hence drawn) if the center of the pixel +is fully inside the bounding box, which is viewed as having infinitely thin +edges. +If the center of the pixel is exactly on the bounding box, +it is part of the line if and only if the interior is immediately to its right +(x increasing direction). +Pixels with centers on a horizontal edge are a special case and are part of +the line if and only if the interior or the boundary is immediately below +(y increasing direction) and if the interior or the boundary is immediately +to the right (x increasing direction). +Note that this description is a mathematical model describing the pixels +that are drawn for a wide line and does not imply that trigonometry is required +to implement such a model. +Real or fixed point arithmetic is recommended for computing the corners of the +line endpoints for lines greater than one pixel in width. +.LP +Thin lines (zero line-width) are nominally one pixel wide lines drawn using an +unspecified, device-dependent algorithm. +There are only two constraints on this algorithm. +First, if a line is drawn unclipped from [x1,y1] to [x2,y2] +and another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], +then a point [x,y] is touched by drawing the first line if +and only if the point [x+dx,y+dy] is touched by drawing the second line. +Second, the effective set of points comprising a line cannot be affected +by clipping. +Thus, a point is touched in a clipped line if and only if the point lies +inside the clipping region and the point would be touched by the line +when drawn unclipped. +.LP +Note that a wide line drawn from [x1,y1] to [x2,y2] always draws the +same pixels as a wide line drawn from [x2,y2] to [x1,y1], not counting +cap-style and join-style. +Implementors are encouraged to make this property true for thin lines, +but it is not required. +A line-width of zero may differ from a line-width of one in which pixels +are drawn. +In general, +drawing a thin line will be faster than drawing a wide line of width one, +but thin lines may not mix well aesthetically with wide lines +because of the different drawing algorithms. +If it is desirable to obtain precise and uniform results across all displays, +a client should always use a line-width of one, rather than a line-width of +zero. +.LP +The line-style defines which sections of a line are drawn: +.TS +lw(1i) lw(4.75i). +T{ +.PN Solid +T} T{ +The full path of the line is drawn. +T} +.sp 6p +T{ +.PN DoubleDash +T} T{ +The full path of the line is drawn, +but the even dashes are filled differently than the odd dashes +(see fill-style), with +.PN Butt +cap-style used where even and odd dashes meet. +T} +.sp 6p +T{ +.PN OnOffDash +T} T{ +Only the even dashes are drawn, +and cap-style applies to all internal ends of the individual dashes +(except +.PN NotLast +is treated as +.PN Butt ). +T} +.TE +.LP +The cap-style defines how the endpoints of a path are drawn: +.TS +lw(1i) lw(4.75i). +T{ +.PN NotLast +T} T{ +The result is equivalent to +.PN Butt , +except that for a line-width of zero the final endpoint is not drawn. +T} +.sp 6p +T{ +.PN Butt +T} T{ +The result is square at the endpoint (perpendicular to the slope of the +line) with no projection beyond. +T} +.sp 6p +T{ +.PN Round +T} T{ +The result is a circular arc with its diameter equal to the line-width, +centered on the endpoint; it is equivalent to +.PN Butt +for line-width zero. +T} +.sp 6p +T{ +.PN Projecting +T} T{ +The result is square at the end, but the path continues beyond the +endpoint for a distance equal to half the line-width; +it is equivalent to +.PN Butt +for line-width zero. +T} +.TE +.LP +The join-style defines how corners are drawn for wide lines: +.TS +lw(1i) lw(4.75i). +T{ +.PN Miter +T} T{ +The outer edges of the two lines extend to meet at an angle. +However, if the angle is less than 11 degrees, a +.PN Bevel +join-style is used instead. +T} +.sp 6p +T{ +.PN Round +T} T{ +The result is a circular arc with a diameter equal to the line-width, +centered on the joinpoint. +T} +.sp 6p +T{ +.PN Bevel +T} T{ +The result is +.PN Butt +endpoint styles, and then the triangular notch is filled. +T} +.TE +.LP +For a line with coincident endpoints (x1=x2, y1=y2), when the cap-style +is applied to both endpoints, the semantics depends on the line-width +and the cap-style: +.TS +lw(1i) lw(.5i) lw(4.25i). +T{ +.PN NotLast +T} T{ +thin +T} T{ +This is device-dependent, but the desired effect is that nothing is drawn. +T} +.sp 6p +T{ +.PN Butt +T} T{ +thin +T} T{ +This is device-dependent, but the desired effect is that a single pixel is drawn. +T} +.sp 6p +T{ +.PN Round +T} T{ +thin +T} T{ +This is the same as +.PN Butt /thin. +T} +.sp 6p +T{ +.PN Projecting +T} T{ +thin +T} T{ +This is the same as +.PN Butt /thin. +T} +.sp 6p +T{ +.PN Butt +T} T{ +wide +T} T{ +Nothing is drawn. +T} +.sp 6p +T{ +.PN Round +T} T{ +wide +T} T{ +The closed path is a circle, centered at the endpoint and +with a diameter equal to the line-width. +T} +.sp 6p +T{ +.PN Projecting +T} T{ +wide +T} T{ +The closed path is a square, aligned with the coordinate axes, +centered at the endpoint and with sides equal to the line-width. +T} +.TE +.LP +For a line with coincident endpoints (x1=x2, y1=y2), +when the join-style is applied at one or both endpoints, +the effect is as if the line was removed from the overall path. +However, if the total path consists of (or is reduced to) a single point +joined with itself, +the effect is the same as when the cap-style is applied at both endpoints. +.LP +The tile/stipple represents an infinite two-dimensional plane +with the tile/stipple +replicated in all dimensions. When that plane is superimposed on +the drawable for use in a graphics operation, the upper-left corner +of some instance of the tile/stipple is at the coordinates within +the drawable specified by the tile/stipple origin. +The tile/stipple and clip origins are interpreted relative to the +origin of whatever destination drawable is specified in a graphics +request. +.LP +The tile pixmap must have the same root and depth as the gcontext (or a +.PN Match +error results). +The stipple pixmap must have depth one and must have the same root +as the gcontext (or a +.PN Match +error results). +For fill-style +.PN Stippled +(but not fill-style +.PN OpaqueStippled ), +the stipple pattern is tiled in a single plane +and acts as an additional clip mask to be ANDed with the clip-mask. +Any size pixmap can be used for tiling or stippling, +although some sizes may be faster to use than others. +.LP +The fill-style defines the contents of the source for line, text, and +fill requests. +For all text and fill requests (for example, +.PN PolyText8 , +.PN PolyText16 , +.PN PolyFillRectangle , +.PN FillPoly , +and +.PN PolyFillArc ) +as well as for line requests with line-style +.PN Solid , +(for example, +.PN PolyLine , +.PN PolySegment , +.PN PolyRectangle , +.PN PolyArc ) +and for the even dashes for line requests with line-style +.PN OnOffDash +or +.PN DoubleDash : +.TS +lw(1.25i) lw(4.5i). +T{ +.PN Solid +T} T{ +Foreground +T} +.sp 6p +T{ +.PN Tiled +T} T{ +Tile +T} +.sp 6p +T{ +.PN OpaqueStippled +T} T{ +A tile with the same width and height as stipple +but with background everywhere stipple has a zero +and with foreground everywhere stipple has a one +T} +.sp 6p +T{ +.PN Stippled +T} T{ +Foreground masked by stipple +T} +.TE +.LP +For the odd dashes for line requests with line-style +.PN DoubleDash : +.TS +lw(1.25i) lw(4.5i). +T{ +.PN Solid +T} T{ +Background +T} +.sp 6p +T{ +.PN Tiled +T} T{ +Same as for even dashes +T} +.sp 6p +T{ +.PN OpaqueStippled +T} T{ +Same as for even dashes +T} +.sp 6p +T{ +.PN Stippled +T} T{ +Background masked by stipple +T} +.TE +.LP +The dashes value allowed here is actually a simplified form of the more +general patterns that can be set with +.PN SetDashes . +Specifying a value of N here is equivalent to specifying +the two element list [N, N] in +.PN SetDashes . +The value must be nonzero (or a +.PN Value +error results). +The meaning of dash-offset and dashes are explained in the +.PN SetDashes +request. +.LP +The clip-mask restricts writes to the destination drawable. +Only pixels where the clip-mask has bits set to 1 are drawn. +Pixels are not drawn outside the area covered by the clip-mask +or where the clip-mask has bits set to 0. +The clip-mask affects all graphics requests, +but it does not clip sources. +The clip-mask origin is interpreted relative to the origin of whatever +destination drawable is specified in a graphics request. +If a pixmap is specified as the clip-mask, +it must have depth 1 and have the same root as the gcontext (or a +.PN Match +error results). +If clip-mask is +.PN None , +then pixels are always drawn, regardless of the clip origin. +The clip-mask can also be set with the +.PN SetClipRectangles +request. +.LP +For +.PN ClipByChildren , +both source and destination windows are additionally clipped by all viewable +.PN InputOutput +children. +For +.PN IncludeInferiors , +neither source nor destination window is clipped by inferiors. +This will result in including subwindow contents in the +source and drawing through subwindow boundaries of the destination. +The use of +.PN IncludeInferiors +with a source or destination window of one depth with mapped inferiors +of differing depth is not illegal, +but the semantics is undefined by the core protocol. +.LP +The fill-rule defines what pixels are inside (that is, are drawn) for +paths given in +.PN FillPoly +requests. +.PN EvenOdd +means a point is inside if an infinite ray with the point as origin crosses +the path an odd number of times. +For +.PN Winding , +a point is inside if an infinite ray with the point as origin crosses an +unequal number of clockwise and counterclockwise directed path segments. +A clockwise directed path segment is one that crosses the ray from left +to right as observed from the point. +A counter-clockwise segment is one that crosses the ray from right to left +as observed from the point. +The case where a directed line segment is coincident with the ray is +uninteresting because one can simply choose a different ray that is not +coincident with a segment. +.LP +For both fill rules, +a point is infinitely small and the path is an infinitely thin line. +A pixel is inside if the center point of the pixel is inside +and the center point is not on the boundary. +If the center point is on the boundary, +the pixel is inside if and only if the polygon interior is immediately +to its right (x increasing direction). +Pixels with centers along a horizontal edge are a special case +and are inside if and only if the polygon interior is immediately below +(y increasing direction). +.LP +The arc-mode controls filling in the +.PN PolyFillArc +request. +.LP +The graphics-exposures flag controls +.PN GraphicsExposure +event generation for +.PN CopyArea +and +.PN CopyPlane +requests (and any similar requests defined by extensions). +.LP +The default component values are: +.TS H +l lw(4i). +_ +.sp 6p +.B +Component Default +.sp 6p +_ +.TH +.R +.sp 6p +T{ +function +T} T{ +.PN Copy +T} +T{ +plane-mask +T} T{ +all ones +T} +T{ +foreground +T} T{ +0 +T} +T{ +background +T} T{ +1 +T} +T{ +line-width +T} T{ +0 +T} +T{ +line-style +T} T{ +.PN Solid +T} +T{ +cap-style +T} T{ +.PN Butt +T} +T{ +join-style +T} T{ +.PN Miter +T} +T{ +fill-style +T} T{ +.PN Solid +T} +T{ +fill-rule +T} T{ +.PN EvenOdd +T} +T{ +arc-mode +T} T{ +.PN PieSlice +T} +T{ +tile +T} T{ +Pixmap of unspecified size filled with foreground pixel +.br +(that is, client specified pixel if any, else 0) +.br +(subsequent changes to foreground do not affect this pixmap) +T} +T{ +stipple +T} T{ +Pixmap of unspecified size filled with ones +T} +T{ +tile-stipple-x-origin +T} T{ +0 +T} +T{ +tile-stipple-y-origin +T} T{ +0 +T} +T{ +font +T} T{ +<server-dependent-font> +T} +T{ +subwindow-mode +T} T{ +.PN ClipByChildren +T} +T{ +graphics-exposures +T} T{ +.PN True +T} +T{ +clip-x-origin +T} T{ +0 +T} +T{ +clip-y-origin +T} T{ +0 +T} +T{ +clip-mask +T} T{ +.PN None +T} +T{ +dash-offset +T} T{ +0 +T} +T{ +dashes +T} T{ +4 (that is, the list [4, 4]) +T} +.sp 6p +_ +.TE +.LP +Storing a pixmap in a gcontext might or might not result in a copy +being made. +If the pixmap is later used as the destination for a graphics request, +the change might or might not be reflected in the gcontext. +If the pixmap is used simultaneously in a graphics request +as both a destination and as a tile or stipple, +the results are not defined. +.LP +It is quite likely that some amount of gcontext information will be +cached in display hardware and that such hardware can only cache a +small number of gcontexts. +Given the number and complexity of components, +clients should view switching between gcontexts with nearly +identical state as significantly more expensive than making minor +changes to a single gcontext. +.sp +.LP +.sM +.IN "ChangeGC" "" "@DEF@" +.PN ChangeGC +.in +.2i +.LP +\fIgc\fP\^: GCONTEXT +.br +\fIvalue-mask\fP\^: BITMASK +.br +\fIvalue-list\fP\^: LISTofVALUE +.LP +Errors: +.PN Alloc , +.PN Font , +.PN GContext , +.PN Match , +.PN Pixmap , +.PN Value +.in -.2i +.eM +.LP +This request changes components in gc. +The value-mask and value-list specify which components are to be changed. +The values and restrictions are the same +as for +.PN CreateGC . +.LP +Changing the clip-mask also overrides any previous +.PN SetClipRectangles +request on the context. +Changing dash-offset or dashes overrides any previous +.PN SetDashes +request on the context. +.LP +The order in which components are verified and altered is server-dependent. +If an error is generated, +a subset of the components may have been altered. +.sp +.LP +.sM +.IN "CopyGC" "" "@DEF@" +.PN CopyGC +.in +.2i +.LP +\fIsrc-gc\fP, \fIdst-gc\fP\^: GCONTEXT +.br +\fIvalue-mask\fP\^: BITMASK +.LP +Errors: +.PN Alloc , +.PN GContext , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request copies components from src-gc to dst-gc. +The value-mask specifies which components to copy, as for +.PN CreateGC . +The two gcontexts must have the same root and the same depth (or a +.PN Match +error results). +.sp +.LP +.sM +.IN "SetDashes" "" "@DEF@" +.PN SetDashes +.in +.2i +.LP +\fIgc\fP\^: GCONTEXT +.br +\fIdash-offset\fP\^: CARD16 +.br +\fIdashes\fP\^: LISTofCARD8 +.LP +Errors: +.PN Alloc , +.PN GContext , +.PN Value +.in -.2i +.eM +.LP +This request sets dash-offset and dashes in gc for dashed line styles. +Dashes cannot be empty (or a +.PN Value +error results). +Specifying an odd-length list is equivalent to specifying the same list +concatenated with itself to produce an even-length list. +The initial and alternating elements of dashes are the even dashes; +the others are the odd dashes. +Each element specifies a dash length in pixels. +All of the elements must be nonzero (or a +.PN Value +error results). +The dash-offset defines the phase of the pattern, +specifying how many pixels into dashes the pattern should actually begin in +any single graphics request. +Dashing is continuous through path elements combined with a join-style +but is reset to the dash-offset between each sequence of joined lines. +.LP +The unit of measure for dashes is the same as in the ordinary +coordinate system. +Ideally, a dash length is measured along the slope of the line, +but implementations are only required to match this ideal +for horizontal and vertical lines. +Failing the ideal semantics, +it is suggested that the length be measured along the major axis of the line. +The major axis is defined as the x axis for lines drawn at an angle of +between \-45 and +45 degrees or between 135 and 225 degrees from the x axis. +For all other lines, the major axis is the y axis. +.LP +For any graphics primitive, the computation of the endpoint of an individual +dash only depends on the geometry of the primitive, the start position +of the dash, the direction of the dash, and the dash length. +.LP +For any graphics primitive, the total set of pixels used to render the +primitive (both even and odd numbered dash elements) with +.PN DoubleDash +line-style is the same as the set of pixels used to render the +primitive with +.PN Solid +line-style. +.LP +For any graphics primitive, if the primitive is drawn with +.PN OnOffDash +or +.PN DoubleDash +line-style unclipped at position [x,y] and again at position +[x+dx,y+dy], then a point [x1,y1] is included in a dash in the first +instance if and only if the point [x1+dx,y1+dy] is included in the dash in +the second instance. In addition, the effective set of points comprising a +dash cannot be affected by clipping. A point is included in a clipped dash +if and only if the point lies inside the clipping region and the point +would be included in the dash when drawn unclipped. +.sp +.LP +.sM +.IN "SetClipRectangles" "" "@DEF@" +.PN SetClipRectangles +.in +.2i +.LP +\fIgc\fP\^: GCONTEXT +.br +\fIclip-x-origin\fP, \fIclip-y-origin\fP\^: INT16 +.br +\fIrectangles\fP\^: LISTofRECTANGLE +.br +\fIordering\fP\^: +.Pn { UnSorted , +.PN YSorted , +.PN YXSorted , +.PN YXBanded } +.LP +Errors: +.PN Alloc , +.PN GContext , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request changes clip-mask in gc to the specified list of rectangles +and sets the clip origin. +Output will be clipped to remain contained within the rectangles. +The clip origin is interpreted relative to the origin of +whatever destination drawable is specified in a graphics request. +The rectangle coordinates are interpreted relative to the clip origin. +The rectangles should be nonintersecting, or graphics results will be +undefined. +Note that the list of rectangles can be empty, +which effectively disables output. +This is the opposite of passing +.PN None +as the clip-mask in +.PN CreateGC +and +.PN ChangeGC . +.LP +If known by the client, +ordering relations on the rectangles can be specified with the ordering +argument. +This may provide faster operation by the server. +If an incorrect ordering is specified, +the server may generate a +.PN Match +error, but it is not required to do so. +If no error is generated, +the graphics results are undefined. +.PN UnSorted +means that the rectangles are in arbitrary order. +.PN YSorted +means that the rectangles are nondecreasing in their Y origin. +.PN YXSorted +additionally constrains +.PN YSorted +order in that all rectangles with an equal Y origin are +nondecreasing in their X origin. +.PN YXBanded +additionally constrains +.PN YXSorted +by requiring that, for every possible Y scanline, +all rectangles that include that scanline have identical Y origins and Y +extents. +.sp +.LP +.sM +.IN "FreeGC" "" "@DEF@" +.PN FreeGC +.in +.2i +.LP +\fIgc\fP\^: GCONTEXT +.LP +Errors: +.PN GContext +.in -.2i +.eM +.LP +This request deletes the association between the resource ID and the gcontext +and destroys the gcontext. +.sp +.LP +.sM +.IN "ClearArea" "" "@DEF@" +.PN ClearArea +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIwidth\fP, \fIheight\fP: CARD16 +.br +\fIexposures\fP\^: BOOL +.LP +Errors: +.PN Match , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +The x and y coordinates are relative to the window's origin +and specify the upper-left corner of the rectangle. +If width is zero, +it is replaced with the current width of the window minus x. +If height is zero, +it is replaced with the current height of the window minus y. +If the window has a defined background tile, +the rectangle is tiled with a plane-mask of all ones and function of +.PN Copy +and a subwindow-mode of +.PN ClipByChildren . +If the window has background +.PN None , +the contents of the window are not changed. +In either case, +if exposures is +.PN True , +then one or more exposure events are generated for regions of the rectangle +that are either visible or are being retained in a backing store. +.LP +It is a +.PN Match +error to use an +.PN InputOnly +window in this request. +.sp +.LP +.sM +.IN "CopyArea" "" "@DEF@" +.PN CopyArea +.in +.2i +.LP +\fIsrc-drawable\fP, \fIdst-drawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIsrc-x\fP\^, \fIsrc-y\fP\^: INT16 +.br +\fIwidth\fP, \fIheight\fP\^: CARD16 +.br +\fIdst-x\fP, \fIdst-y\fP\^: INT16 +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +This request combines the specified rectangle of src-drawable with the +specified rectangle of dst-drawable. +The src-x and src-y coordinates are relative to src-drawable's origin. +The dst-x and dst-y are relative to dst-drawable's origin, +each pair specifying the upper-left corner of the rectangle. +The src-drawable must have the same root and the same depth +as dst-drawable (or a +.PN Match +error results). +.LP +If regions of the source rectangle are obscured and have not been retained +in backing store +or if regions outside the boundaries of the source drawable are specified, +then those regions are not copied, +but the following occurs on all corresponding destination regions that are +either visible or are retained in backing-store. +If the dst-drawable is a window with a background other than +.PN None , +these corresponding destination regions are tiled +(with plane-mask of all ones and function +.PN Copy ) +with that background. +Regardless of tiling and whether the destination is a window or a pixmap, +if graphics-exposures in gc is +.PN True , +then +.PN GraphicsExposure +events for all corresponding destination regions are generated. +.LP +If graphics-exposures is +.PN True +but no +.PN GraphicsExposure +events are generated, +then a +.PN NoExposure +event is generated. +.LP +GC components: function, plane-mask, subwindow-mode, +graphics-exposures, clip-x-origin, clip-y-origin, clip-mask +.sp +.LP +.sM +.IN "CopyPlane" "" "@DEF@" +.PN CopyPlane +.in +.2i +.LP +\fIsrc-drawable\fP, \fIdst-drawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIsrc-x\fP, \fIsrc-y\fP\^: INT16 +.br +\fIwidth\fP, \fIheight\fP\^: CARD16 +.br +\fIdst-x\fP, \fIdst-y\fP\^: INT16 +.br +\fIbit-plane\fP\^: CARD32 +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +The src-drawable must have the same root as dst-drawable (or a +.PN Match +error results), but it need not have the same depth. +The bit-plane must have exactly one bit set to 1 and the value of bit-plane +must be less than %2 sup n% where \fIn\fP is the depth of src-drawable (or a +.PN Value +error results). +Effectively, a pixmap of the same depth as dst-drawable and with size specified +by the source region is formed using the foreground/background pixels in gc +(foreground everywhere the bit-plane in src-drawable contains a bit set to 1, +background everywhere the bit-plane contains a bit set to 0), +and the equivalent of a +.PN CopyArea +is performed, with all the same exposure semantics. +This can also be thought of as using the specified region of the source +bit-plane as a stipple with a fill-style of +.PN OpaqueStippled +for filling a rectangular area of the destination. +.LP +GC components: function, plane-mask, foreground, background, +subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, +clip-mask +.sp +.LP +.sM +.IN "PolyPoint" "" "@DEF@" +.PN PolyPoint +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIcoordinate-mode\fP\^: +.Pn { Origin , +.PN Previous } +.br +\fIpoints\fP\^: LISTofPOINT +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request combines the foreground pixel in gc with the pixel +at each point in the drawable. +The points are drawn in the order listed. +.LP +The first point is always relative to the drawable's origin. +The rest are relative either to that origin or the previous point, +depending on the coordinate-mode. +.LP +GC components: function, plane-mask, foreground, subwindow-mode, +clip-x-origin, clip-y-origin, clip-mask +.sp +.LP +.sM +.IN "PolyLine" "" "@DEF@" +.PN PolyLine +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIcoordinate-mode\fP\^: +.Pn { Origin , +.PN Previous } +.br +\fIpoints\fP\^: LISTofPOINT +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request draws lines between each pair of points (point[i], point[i+1]). +The lines are drawn in the order listed. +The lines join correctly at all intermediate points, +and if the first and last points coincide, +the first and last lines also join correctly. +.LP +For any given line, +no pixel is drawn more than once. +If thin (zero line-width) lines intersect, +the intersecting pixels are drawn multiple times. +If wide lines intersect, +the intersecting pixels are drawn only once, as though the entire +.PN PolyLine +were a single filled shape. +.LP +The first point is always relative to the drawable's origin. +The rest are relative either to that origin or the previous point, +depending on the coordinate-mode. +.LP +When either of the two lines involved in a +.PN Bevel +join is neither vertical +nor horizontal, then the slope and position of the line segment defining +the bevel join edge is implementation dependent. However, the computation +of the slope and distance (relative to the join point) only depends on +the line width and the slopes of the two lines. +.LP +GC components: function, plane-mask, line-width, line-style, +cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, +clip-y-origin, clip-mask +.LP +GC mode-dependent components: foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, dashes +.sp +.LP +.sM +.IN "PolySegment" "" "@DEF@" +.PN PolySegment +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIsegments\fP\^: LISTofSEGMENT +.LP +where: +.LP +SEGMENT: [x1, y1, x2, y2: INT16] +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +For each segment, +this request draws a line between [x1, y1] and [x2, y2]. +The lines are drawn in the order listed. +No joining is performed at coincident endpoints. +For any given line, +no pixel is drawn more than once. +If lines intersect, +the intersecting pixels are drawn multiple times. +.LP +GC components: function, plane-mask, line-width, line-style, +cap-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, +clip-mask +.LP +GC mode-dependent components: foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, dashes +.sp +.LP +.sM +.IN "PolyRectangle" "" "@DEF@" +.PN PolyRectangle +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIrectangles\fP\^: LISTofRECTANGLE +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +This request draws the outlines of the specified rectangles, as if a five-point +.PN PolyLine +were specified for each rectangle: +.LP +.DS +[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y] +.DE +.LP +The x and y coordinates of each rectangle are relative to the drawable's origin +and define the upper-left corner of the rectangle. +.LP +The rectangles are drawn in the order listed. +For any given rectangle, +no pixel is drawn more than once. +If rectangles intersect, +the intersecting pixels are drawn multiple times. +.LP +GC components: function, plane-mask, line-width, line-style, +cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, +clip-y-origin, clip-mask +.LP +GC mode-dependent components: foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, dashes +.sp +.LP +.sM +.IN "PolyArc" "" "@DEF@" +.PN PolyArc +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIarcs\fP\^: LISTofARC +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +This request draws circular or elliptical arcs. +Each arc is specified by a rectangle and two angles. +The angles are signed integers in degrees scaled by 64, +with positive indicating counterclockwise motion and +negative indicating clockwise motion. +The start of the arc is specified by angle1 relative to the three-o'clock +position from the center of the rectangle, +and the path and extent of the arc is specified by angle2 relative to the +start of the arc. +If the magnitude of angle2 is greater than 360 degrees, +it is truncated to 360 degrees. +The x and y coordinates of the rectangle are relative to the origin of +the drawable. +For an arc specified as [x,y,w,h,a1,a2], +the origin of the major and minor axes is at [x+(w/2),y+(h/2)], +and the infinitely thin path describing the entire circle/ellipse intersects +the horizontal axis at [x,y+(h/2)] and [x+w,y+(h/2)] and intersects the +vertical axis at [x+(w/2),y] and [x+(w/2),y+h]. +These coordinates are not necessarily integral; that is, +they are not truncated to discrete coordinates. +.LP +For a wide line with line-width lw, the ideal bounding outlines for filling +are given by the two infinitely thin paths consisting of all points whose +perpendicular distance from a tangent to the path of the circle/ellipse is +equal to lw/2 (which may be a fractional value). When the width and height +of the arc are not equal and both are nonzero, then the actual bounding +outlines are implementation dependent. However, the computation of the +shape and position of the bounding outlines (relative to the center of the +arc) only depends on the width and height of the arc and the +line-width. +.LP +The cap-style is applied the same as for a line corresponding to the +tangent of the circle/ellipse at the endpoint. When the angle of an arc +face is not an integral multiple of 90 degrees, and the width and height of +the arc are both are nonzero, then the shape and position of the cap at +that face is implementation dependent. However, for a +.PN Butt +cap, the face +is defined by a straight line, and the computation of the position +(relative to the center of the arc) and the slope of the line only +depends on the width and height of the arc and the angle of the arc face. +For other cap styles, the computation of the position (relative to the +center of the arc) and the shape of the cap only depends on the width +and height of the arc, the line-width, the angle of the arc face, and the +direction (clockwise or counter clockwise) of the arc from the endpoint. +.LP +The join-style is applied the same as for two lines corresponding to the +tangents of the circles/ellipses at the join point. When the width and +height of both arcs are nonzero, and the angle of either arc face is not an +integral multiple of 90 degrees, then the shape of the join is +implementation dependent. However, the computation of the shape only +depends on the width and height of each arc, the line-width, the angles of +the two arc faces, the direction (clockwise or counter clockwise) of the +arcs from the join point, and the relative orientation of the two arc +center points. +.LP +For an arc specified as [x,y,w,h,a1,a2], +the angles must be specified in the effectively skewed coordinate system of +the ellipse (for a circle, the angles and coordinate systems are identical). +The relationship between these angles and angles expressed in the normal +coordinate system of the screen (as measured with a protractor) is as +follows: +.DS +skewed-angle = atan(tan(normal-angle) * w/h) + adjust +.DE +.LP +The skewed-angle and normal-angle are expressed in radians (rather +than in degrees scaled by 64) in the range [0,2*PI). +The atan returns a value in the range [\-PI/2,PI/2]. +The adjust is: +.RS +.TS +l l. +0 for normal-angle in the range [0,PI/2) +PI for normal-angle in the range [PI/2,(3*PI)/2) +2*PI for normal-angle in the range [(3*PI)/2,2*PI) +.TE +.RE +.LP +The arcs are drawn in the order listed. +If the last point in one arc coincides with the first point in the following +arc, +the two arcs will join correctly. +If the first point in the first arc coincides with the last point +in the last arc, +the two arcs will join correctly. +For any given arc, +no pixel is drawn more than once. +If two arcs join correctly and the line-width is greater than zero +and the arcs intersect, +no pixel is drawn more than once. +Otherwise, the intersecting pixels of intersecting arcs are drawn multiple +times. +Specifying an arc with one endpoint and a clockwise extent draws the +same pixels as specifying the other endpoint and an equivalent +counterclockwise extent, except as it affects joins. +.LP +By specifying one axis to be zero, +a horizontal or vertical line can be drawn. +.LP +Angles are computed based solely on the coordinate system, +ignoring the aspect ratio. +.LP +GC components: function, plane-mask, line-width, line-style, +cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, +clip-y-origin, clip-mask +.LP +GC mode-dependent components: foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, dashes +.sp +.LP +.sM +.IN "FillPoly" "" "@DEF@" +.PN FillPoly +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIshape\fP\^: +.Pn { Complex , +.PN Nonconvex , +.PN Convex } +.br +\fIcoordinate-mode\fP\^: +.Pn { Origin , +.PN Previous } +.br +\fIpoints\fP\^: LISTofPOINT +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request fills the region closed by the specified path. +The path is closed automatically if the last point in the list does not +coincide with the first point. +No pixel of the region is drawn more than once. +.LP +The first point is always relative to the drawable's origin. +The rest are relative either to that origin or the previous point, +depending on the coordinate-mode. +.LP +The shape parameter may be used by the server to improve performance. +.PN Complex +means the path may self-intersect. +Contiguous coincident points in the path are not treated +as self-intersection. +.LP +.PN Nonconvex +means the path does not self-intersect, +but the shape is not wholly convex. +If known by the client, +specifying +.PN Nonconvex +over +.PN Complex +may improve performance. +If +.PN Nonconvex +is specified for a self-intersecting path, +the graphics results are undefined. +.LP +.PN Convex +means that for every pair of points inside the polygon, +the line segment connecting them does not intersect the path. +If known by the client, +specifying +.PN Convex +can improve performance. +If +.PN Convex +is specified for a path that is not convex, +the graphics results are undefined. +.LP +GC components: function, plane-mask, fill-style, fill-rule, +subwindow-mode, clip-x-origin, clip-y-origin, clip-mask +.LP +GC mode-dependent components: foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin +.sp +.LP +.sM +.IN "PolyFillRectangle" "" "@DEF@" +.PN PolyFillRectangle +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIrectangles\fP\^: LISTofRECTANGLE +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +This request fills the specified rectangles, as if a four-point +.PN FillPoly +were specified for each rectangle: +.DS +[x,y] [x+width,y] [x+width,y+height] [x,y+height] +.DE +.LP +The x and y coordinates of each rectangle are relative to the drawable's origin +and define the upper-left corner of the rectangle. +.LP +The rectangles are drawn in the order listed. +For any given rectangle, +no pixel is drawn more than once. +If rectangles intersect, +the intersecting pixels are drawn multiple times. +.LP +GC components: function, plane-mask, fill-style, subwindow-mode, +clip-x-origin, clip-y-origin, clip-mask +.LP +GC mode-dependent components: foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin +.sp +.LP +.sM +.IN "PolyFillArc" "" "@DEF@" +.PN PolyFillArc +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIarcs\fP\^: LISTofARC +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +For each arc, +this request fills the region closed by the infinitely thin path +described by the specified arc and one or two line segments, +depending on the arc-mode. +For +.PN Chord , +the single line segment joining the endpoints of the arc is used. +For +.PN PieSlice , +the two line segments joining the endpoints of the arc with the center point +are used. +.LP +For an arc specified as [x,y,w,h,a1,a2], the origin of the major and minor +axes is at [x+(w/2),y+(h/2)], and the infinitely thin path describing the +entire circle/ellipse intersects the horizontal axis at [x,y+(h/2)] and +[x+w,y+(h/2)] and intersects the vertical axis at [x+(w/2),y] and +[x+(w/2),y+h]. These coordinates are not necessarily integral; that is, +they are not truncated to discrete coordinates. +.LP +The arc angles are interpreted as specified in the +.PN PolyArc +request. When +the angle of an arc face is not an integral multiple of 90 degrees, then +the precise endpoint on the arc is implementation dependent. However, for +.PN Chord +arc-mode, the computation of the pair of endpoints (relative to the +center of the arc) only depends on the width and height of the arc and +the angles of the two arc faces. For +.PN PieSlice +arc-mode, the computation of +an endpoint only depends on the angle of the arc face for that +endpoint and the ratio of the arc width to arc height. +.LP +The arcs are filled in the order listed. +For any given arc, +no pixel is drawn more than once. +If regions intersect, +the intersecting pixels are drawn multiple times. +.LP +GC components: function, plane-mask, fill-style, arc-mode, +subwindow-mode, clip-x-origin, clip-y-origin, clip-mask +.LP +GC mode-dependent components: foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin +.sp +.LP +.sM +.IN "PutImage" "" "@DEF@" +.PN PutImage +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIdepth\fP\^: CARD8 +.br +\fIwidth\fP, \fIheight\fP\^: CARD16 +.br +\fIdst-x\fP, \fIdst-y\fP\^: INT16 +.br +\fIleft-pad\fP\^: CARD8 +.br +\fIformat\fP\^: +.Pn { Bitmap , +.PN XYPixmap , +.PN ZPixmap } +.br +\fIdata\fP\^: LISTofBYTE +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request combines an image with a rectangle of the drawable. +The dst-x and dst-y coordinates are relative to the drawable's origin. +.LP +If +.PN Bitmap +format is used, +then depth must be one (or a +.PN Match +error results), and the image must be in XY format. +The foreground pixel in gc defines the source for bits set to 1 in the image, +and the background pixel defines the source for the bits set to 0. +.LP +For +.PN XYPixmap +and +.PN ZPixmap , +the depth must match the depth of the drawable (or a +.PN Match +error results). +For +.PN XYPixmap , +the image must be sent in XY format. +For +.PN ZPixmap , +the image must be sent in the Z format defined for the given depth. +.LP +The left-pad must be zero for +.PN ZPixmap +format (or a +.PN Match +error results). +For +.PN Bitmap +and +.PN XYPixmap +format, +left-pad must be less than bitmap-scanline-pad as given in the server +connection setup information (or a +.PN Match +error results). +The first left-pad bits in every scanline are to be ignored by the server. +The actual image begins that many bits into the data. +The width argument defines the width of the actual image +and does not include left-pad. +.LP +GC components: function, plane-mask, subwindow-mode, clip-x-origin, +clip-y-origin, clip-mask +.LP +GC mode-dependent components: foreground, background +.sp +.LP +.sM +.IN "GetImage" "" "@DEF@" +.PN GetImage +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIwidth\fP, \fIheight\fP\^: CARD16 +.br +\fIplane-mask\fP\^: CARD32 +.br +\fIformat\fP\^: +.Pn { XYPixmap , +.PN ZPixmap } +.in -.2i +.LP + \(-> +.in +.2i +.LP +depth: CARD8 +.br +visual: VISUALID or +.PN None +.br +data: LISTofBYTE +.LP +Errors: +.PN Drawable , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request returns the contents of the given rectangle of the drawable in the +given format. +The x and y coordinates are relative to the drawable's origin +and define the upper-left corner of the rectangle. +If +.PN XYPixmap +is specified, +only the bit planes specified in plane-mask are transmitted, +with the planes appearing from most significant to least significant +in bit order. +If +.PN ZPixmap +is specified, then bits in all planes not specified in plane-mask are +transmitted as zero. +Range checking is not performed on plane-mask; +extraneous bits are simply ignored. +The returned depth is as specified when the drawable was created +and is the same as a depth component in a FORMAT structure (in the connection +setup), not a bits-per-pixel component. +If the drawable is a window, +its visual type is returned. +If the drawable is a pixmap, +the visual is +.PN None . +.LP +If the drawable is a pixmap, +then the given rectangle must be wholly contained within the pixmap (or a +.PN Match +error results). +If the drawable is a window, +the window must be viewable, +and it must be the case that, +if there were no inferiors or overlapping windows, +the specified rectangle of the window would be fully visible on the screen +and wholly contained within the outside edges of the window (or a +.PN Match +error results). +Note that the borders of the window can be included and read with this request. +If the window has a backing store, +then the backing-store contents are returned for regions of the window +that are obscured by noninferior windows; +otherwise, the returned contents of such obscured regions are undefined. +Also undefined are the returned contents of visible +regions of inferiors of different depth than the specified window. +The pointer cursor image is not included in the contents returned. +.LP +This request is not general-purpose in the same sense as other +graphics-related requests. +It is intended specifically for rudimentary hardcopy support. +.sp +.LP +.sM +.IN "PolyText8" "" "@DEF@" +.PN PolyText8 +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIitems\fP\^: LISTofTEXTITEM8 +.LP +where: +.TS +r l. +TEXTITEM8: TEXTELT8 or FONT +.br +TEXTELT8: [delta: INT8 +.br + \ string: STRING8] +.TE +.LP +Errors: +.PN Drawable , +.PN Font , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +The x and y coordinates are relative to the drawable's origin +and specify the baseline starting position (the initial character origin). +Each text item is processed in turn. +A font item causes the font to be stored in gc +and to be used for subsequent text. +Switching among fonts does not affect the next character origin. +A text element delta specifies an additional change in the position +along the x axis before the string is drawn; +the delta is always added to the character origin. +Each character image, as defined by the font in gc, +is treated as an additional mask for a fill operation on the drawable. +.LP +All contained FONTs are always transmitted most significant byte first. +.LP +If a +.PN Font +error is generated for an item, +the previous items may have been drawn. +.LP +For fonts defined with 2-byte matrix indexing, +each STRING8 byte is interpreted as a byte2 value of a CHAR2B with a byte1 +value of zero. +.LP +GC components: function, plane-mask, fill-style, font, +subwindow-mode, clip-x-origin, clip-y-origin, clip-mask +.LP +GC mode-dependent components: foreground, background, tile, stipple, +tile-stipple-x-origin, tile-stipple-y-origin +.sp +.LP +.sM +.IN "PolyText16" "" "@DEF@" +.PN PolyText16 +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIitems\fP\^: LISTofTEXTITEM16 +.LP +where: +.TS +r l. +TEXTITEM16: TEXTELT16 or FONT +.br +TEXTELT16: [delta: INT8 +.br + \ string: STRING16] +.TE +.LP +Errors: +.PN Drawable , +.PN Font , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +This request is similar to +.PN PolyText8 , +except 2-byte (or 16-bit) characters are used. +For fonts defined with linear indexing rather than 2-byte matrix indexing, +the server will interpret each CHAR2B as a 16-bit number that +has been transmitted most significant byte first (that is, byte1 of the +CHAR2B is taken as the most significant byte). +.sp +.LP +.sM +.IN "ImageText8" "" "@DEF@" +.PN ImageText8 +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIstring\fP\^: STRING8 +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +The x and y coordinates are relative to the drawable's origin +and specify the baseline starting position (the initial character origin). +The effect is first to fill a destination rectangle with the background +pixel defined in gc and then to paint the text with the foreground pixel. +The upper-left corner of the filled rectangle is at: +.DS +[x, y \- font-ascent] +.DE +.LP +the width is: +.DS +overall-width +.DE +.LP +and the height is: +.DS +font-ascent + font-descent +.DE +.LP +The overall-width, font-ascent, and font-descent are as +they would be returned by a +.PN QueryTextExtents +call using gc and string. +.LP +The function and fill-style defined in gc are ignored for this request. +The effective function is +.PN Copy , +and the effective fill-style +.PN Solid . +.LP +For fonts defined with 2-byte matrix indexing, +each STRING8 byte is interpreted as a byte2 value of a CHAR2B with a byte1 +value of zero. +.LP +GC components: plane-mask, foreground, background, font, +subwindow-mode, clip-x-origin, clip-y-origin, clip-mask +.sp +.LP +.sM +.IN "ImageText16" "" "@DEF@" +.PN ImageText16 +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIgc\fP\^: GCONTEXT +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIstring\fP\^: STRING16 +.LP +Errors: +.PN Drawable , +.PN GContext , +.PN Match +.in -.2i +.eM +.LP +This request is similar to +.PN ImageText8 , +except 2-byte (or 16-bit) characters are used. +For fonts defined with linear indexing rather than 2-byte matrix indexing, +the server will interpret each CHAR2B as a 16-bit number that +has been transmitted most significant byte first (that is, byte1 of the +CHAR2B is taken as the most significant byte). +.sp +.LP +.sM +.IN "CreateColormap" "" "@DEF@" +.PN CreateColormap +.in +.2i +.LP +\fImid\fP\^: COLORMAP +.br +\fIvisual\fP\^: VISUALID +.br +\fIwindow\fP\^: WINDOW +.br +\fIalloc\fP\^: +.Pn { None , +.PN All } +.LP +Errors: +.PN Alloc , +.PN IDChoice , +.PN Match , +.PN Value , +.PN Window +.in -.2i +.eM +.LP +This request creates a colormap of the specified visual type for the screen +on which the window resides and associates the identifier mid with it. +The visual type must be one supported by the screen (or a +.PN Match +error results). +The initial values of the colormap entries are undefined for classes +.PN GrayScale , +.PN PseudoColor , +and +.PN DirectColor . +For +.PN StaticGray , +.PN StaticColor , +and +.PN TrueColor , +the entries will have defined values, +but those values are specific to the visual and are not defined +by the core protocol. +For +.PN StaticGray , +.PN StaticColor , +and +.PN TrueColor , +alloc must be specified as +.PN None +(or a +.PN Match +error results). +For the other classes, if alloc is +.PN None , +the colormap initially has no allocated entries, +and clients can allocate entries. +.LP +If alloc is +.PN All , +then the entire colormap is allocated writable. +The initial values of all allocated entries are undefined. +For +.PN GrayScale +and +.PN PseudoColor , +the effect is as if an +.PN AllocColorCells +request returned all pixel values from zero to N \- 1, +where N is the colormap-entries value in the specified visual. +For +.PN DirectColor , +the effect is as if an +.PN AllocColorPlanes +request returned a pixel value of zero and red-mask, +green-mask, and blue-mask values containing the same bits as the +corresponding masks in the specified visual. +However, +in all cases, none of these entries can be freed with +.PN FreeColors . +.sp +.LP +.sM +.IN "FreeColormap" "" "@DEF@" +.PN FreeColormap +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.LP +Errors: +.PN Colormap +.in -.2i +.eM +.LP +This request deletes the association between the resource ID and the colormap +and frees the colormap storage. +If the colormap is an installed map for a screen, +it is uninstalled (see +.PN UninstallColormap +request). +If the colormap is defined as the colormap for a window (by means of +.PN CreateWindow +or +.PN ChangeWindowAttributes ), +the colormap for the window is changed to +.PN None , +and a +.PN ColormapNotify +event is generated. +The protocol does not define the colors displayed for a window with a colormap of +.PN None . +.LP +This request has no effect on a default colormap for a screen. +.sp +.LP +.sM +.IN "CopyColormapAndFree" "" "@DEF@" +.PN CopyColormapAndFree +.in +.2i +.LP +\fImid\fP, \fIsrc-cmap\fP\^: COLORMAP +.LP +Errors: +.PN Alloc , +.PN Colormap , +.PN IDChoice +.in -.2i +.eM +.LP +This request creates a colormap of the same visual type +and for the same screen as src-cmap, +and it associates identifier mid with it. +It also moves all of the client's existing allocations from src-cmap +to the new colormap with their color values intact +and their read-only or writable characteristics intact, +and it frees those entries in src-cmap. +Color values in other entries in the new colormap are undefined. +If src-cmap was created by the client with alloc +.PN All +(see +.PN CreateColormap +request), +then the new colormap is also created with alloc +.PN All , +all color values for all entries are copied from src-cmap, +and then all entries in src-cmap are freed. +If src-cmap was not created by the client with alloc +.PN All , +then the allocations to be moved are all those pixels and planes that have +been allocated by the client using either +.PN AllocColor , +.PN AllocNamedColor , +.PN AllocColorCells , +or +.PN AllocColorPlanes +and that have not been freed since they were allocated. +.sp +.LP +.sM +.IN "InstallColormap" "" "@DEF@" +.PN InstallColormap +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.LP +Errors: +.PN Colormap +.in -.2i +.eM +.LP +This request makes this colormap an installed map for its screen. +All windows associated with this colormap immediately display with true colors. +As a side effect, +additional colormaps might be implicitly installed +or uninstalled by the server. +Which other colormaps get installed or uninstalled is server-dependent +except that the required list must remain installed. +.LP +If cmap is not already an installed map, a +.PN ColormapNotify +event is generated on every window having cmap as an attribute. +In addition, +for every other colormap that is installed or uninstalled as a result +of the request, a +.PN ColormapNotify +event is generated on every window having that colormap as an attribute. +.LP +At any time, there is a subset of the installed maps that are viewed as an +ordered list and are called the required list. +The length of the required list is at most M, +where M is the min-installed-maps specified for the screen in the +connection setup. +The required list is maintained as follows. +When a colormap is an explicit argument to +.PN InstallColormap , +it is added to the head of the list; the list is truncated at the +tail, if necessary, to keep the length of the list to at most M. +When a colormap is an explicit argument to +.PN UninstallColormap +and it is in the required list, it is removed from the list. +A colormap is not added to the required list when it is installed implicitly +by the server, and the server cannot implicitly uninstall a colormap that is +in the required list. +.LP +Initially the default colormap for a screen is installed (but is not in +the required list). +.sp +.LP +.sM +.IN "UninstallColormap" "" "@DEF@" +.PN UninstallColormap +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.LP +Errors: +.PN Colormap +.in -.2i +.eM +.LP +If cmap is on the required list for its screen (see +.PN InstallColormap +request), +it is removed from the list. +As a side effect, +cmap might be uninstalled, +and additional colormaps might be implicitly installed or uninstalled. +Which colormaps get installed or uninstalled is server-dependent +except that the required list must remain installed. +.LP +If cmap becomes uninstalled, a +.PN ColormapNotify +event is generated on every window having cmap as an attribute. +In addition, +for every other colormap that is installed or uninstalled as a result of +the request, a +.PN ColormapNotify +event is generated on every window having that colormap as an attribute. +.sp +.LP +.sM +.IN "ListInstalledColormaps" "" "@DEF@" +.PN ListInstalledColormaps +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.in -.2i +.LP + \(-> +.in +.2i +.LP +cmaps: LISTofCOLORMAP +.LP +Errors: +.PN Window +.in -.2i +.eM +.LP +This request returns a list of the currently installed colormaps for the +screen of the specified window. +The order of colormaps is not significant, +and there is no explicit indication of the required list (see +.PN InstallColormap +request). +.sp +.LP +.sM +.IN "AllocColor" "" "@DEF@" +.PN AllocColor +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIred\fP, \fIgreen\fP, \fIblue\fP\^: CARD16 +.in -.2i +.LP + \(-> +.in +.2i +.LP +pixel: CARD32 +.br +red, green, blue: CARD16 +.LP +Errors: +.PN Alloc , +.PN Colormap +.in -.2i +.eM +.LP +This request allocates a read-only colormap entry corresponding to the closest +RGB values provided by the hardware. +It also returns the pixel and the RGB values actually used. +Multiple clients requesting the same effective RGB values can be assigned +the same read-only entry, allowing entries to be shared. +.sp +.LP +.sM +.IN "AllocNamedColor" "" "@DEF@" +.PN AllocNamedColor +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIname\fP\^: STRING8 +.in -.2i +.LP + \(-> +.in +.2i +.LP +pixel: CARD32 +.br +exact-red, exact-green, exact-blue: CARD16 +.br +visual-red, visual-green, visual-blue: CARD16 +.LP +Errors: +.PN Alloc , +.PN Colormap , +.PN Name +.in -.2i +.eM +.LP +This request looks up the named color with respect to the screen associated +with the colormap. +Then, it does an +.PN AllocColor +on cmap. +The name should use the ISO Latin-1 encoding, +and uppercase and lowercase do not matter. +The exact RGB values specify the true values for the color, +and the visual values specify the values actually used in the colormap. +.sp +.LP +.sM +.IN "AllocColorCells" "" "@DEF@" +.PN AllocColorCells +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIcolors\fP, \fIplanes\fP\^: CARD16 +.br +\fIcontiguous\fP\^: BOOL +.in -.2i +.LP + \(-> +.in +.2i +.LP +pixels, masks: LISTofCARD32 +.LP +Errors: +.PN Alloc , +.PN Colormap , +.PN Value +.in -.2i +.eM +.LP +The number of colors must be positive, +and the number of planes must be nonnegative (or a +.PN Value +error results). +If C colors and P planes are requested, +then C pixels and P masks are returned. +No mask will have any bits in common with any other mask +or with any of the pixels. +By ORing together masks and pixels, +C*%2 sup P% distinct pixels can be produced; +all of these are allocated writable by the request. +For +.PN GrayScale +or +.PN PseudoColor , +each mask will have exactly one bit set to 1; for +.PN DirectColor , +each will have exactly three bits set to 1. +If contiguous is +.PN True +and if all masks are ORed together, +a single contiguous set of bits will be formed for +.PN GrayScale +or +.PN PseudoColor , +and three contiguous sets of bits (one within each pixel subfield) for +.PN DirectColor . +The RGB values of the allocated entries are undefined. +.sp +.LP +.sM +.IN "AllocColorPlanes" "" "@DEF@" +.PN AllocColorPlanes +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIcolors\fP, \fIreds\fP, \fIgreens\fP, \fIblues\fP\^: CARD16 +.br +\fIcontiguous\fP\^: BOOL +.in -.2i +.LP + \(-> +.in +.2i +.LP +pixels: LISTofCARD32 +.br +red-mask, green-mask, blue-mask: CARD32 +.LP +Errors: +.PN Alloc , +.PN Colormap , +.PN Value +.in -.2i +.eM +.LP +The number of colors must be positive, +and the reds, greens, and blues must be nonnegative (or a +.PN Value +error results). +If C colors, R reds, G greens, and B blues are requested, +then C pixels are returned, and the masks have R, G, and B bits set, +respectively. +If contiguous is +.PN True , +then each mask will have a contiguous set of bits. +No mask will have any bits in common with any other mask +or with any of the pixels. +For +.PN DirectColor , +each mask will lie within the corresponding pixel subfield. +By ORing together subsets of masks with pixels, +C*%2 sup R+G+B% distinct pixels can be produced; +all of these are allocated writable by the request. +The initial RGB values of the allocated entries are undefined. +In the colormap, +there are only C*%2 sup R% independent red entries, +C*%2 sup G% independent green entries, +and C*%2 sup B% independent blue entries. +This is true even for +.PN PseudoColor . +When the colormap entry for a pixel value is changed using +.PN StoreColors +or +.PN StoreNamedColor , +the pixel is decomposed according to the masks and the +corresponding independent entries are updated. +.sp +.LP +.sM +.IN "FreeColors" "" "@DEF@" +.PN FreeColors +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIpixels\fP\^: LISTofCARD32 +.br +\fIplane-mask\fP\^: CARD32 +.LP +Errors: +.PN Access , +.PN Colormap , +.PN Value +.in -.2i +.eM +.LP +The plane-mask should not have any bits in common with any of the +pixels. +The set of all pixels is produced by ORing together subsets of +plane-mask with the pixels. +The request frees all of these pixels that +were allocated by the client (using +.PN AllocColor , +.PN AllocNamedColor , +.PN AllocColorCells , +and +.PN AllocColorPlanes ). +Note that freeing an +individual pixel obtained from +.PN AllocColorPlanes +may not actually allow it to be reused until all of its related pixels +are also freed. +Similarly, a read-only entry is not actually freed until it has been +freed by all clients, and if a client allocates the same read-only entry +multiple times, it must free the entry that many times before the +entry is actually freed. +.LP +All specified pixels that are allocated by the client in cmap are freed, +even if one or more pixels produce an error. +A +.PN Value +error is generated if a specified pixel is not a valid index into cmap. +An +.PN Access +error is generated if a specified pixel is not allocated by the +client (that is, is unallocated or is only allocated by another client) +or if the colormap was created with all entries writable (using an alloc +value of +.PN All +in +.PN CreateColormap ). +If more than one pixel is in error, +it is arbitrary as to which pixel is reported. +.sp +.LP +.sM +.IN "StoreColors" "" "@DEF@" +.PN StoreColors +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIitems\fP\^: LISTofCOLORITEM +.LP +where: +.TS +l l. +COLORITEM: [pixel: CARD32 +.br + \ do-red, do-green, do-blue: BOOL +.br + \ red, green, blue: CARD16] +.TE +.LP +Errors: +.PN Access , +.PN Colormap , +.PN Value +.in -.2i +.eM +.LP +This request changes the colormap entries of the specified pixels. +The do-red, do-green, and do-blue fields indicate which components +should actually be changed. +If the colormap is an installed map for its screen, +the changes are visible immediately. +.LP +All specified pixels that are allocated writable in cmap (by any client) +are changed, even if one or more pixels produce an error. +A +.PN Value +error is generated if a specified pixel is not a valid index into cmap, and an +.PN Access +error is generated if a specified pixel is unallocated or is allocated +read-only. +If more than one pixel is in error, +it is arbitrary as to which pixel is reported. +.sp +.LP +.sM +.IN "StoreNamedColor" "" "@DEF@" +.PN StoreNamedColor +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIpixel\fP\^: CARD32 +.br +\fIname\fP\^: STRING8 +.br +\fIdo-red\fP, \fIdo-green\fP\^, \fIdo-blue\fP\^: BOOL +.LP +Errors: +.PN Access , +.PN Colormap , +.PN Name , +.PN Value +.in -.2i +.eM +.LP +This request looks up the named color with respect to the screen associated +with cmap and then does a +.PN StoreColors +in cmap. +The name should use the ISO Latin-1 encoding, +and uppercase and lowercase do not matter. +The +.PN Access +and +.PN Value +errors are the same as in +.PN StoreColors . +.sp +.LP +.sM +.IN "QueryColors" "" "@DEF@" +.PN QueryColors +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIpixels\fP\^: LISTofCARD32 +.in -.2i +.LP + \(-> +.in +.2i +.LP +colors: LISTofRGB +.LP +where: +.LP +.DS 0 +RGB: [red, green, blue: CARD16] +.DE +Errors: +.PN Colormap , +.PN Value +.in -.2i +.eM +.LP +This request returns the hardware-specific color values stored in cmap for +the specified pixels. +The values returned for an unallocated entry are undefined. +A +.PN Value +error is generated if a pixel is not a valid index into cmap. +If more than one pixel is in error, +it is arbitrary as to which pixel is reported. +.sp +.LP +.sM +.IN "LookupColor" "" "@DEF@" +.PN LookupColor +.in +.2i +.LP +\fIcmap\fP\^: COLORMAP +.br +\fIname\fP\^: STRING8 +.in -.2i +.LP + \(-> +.in +.2i +.LP +exact-red, exact-green, exact-blue: CARD16 +.br +visual-red, visual-green, visual-blue: CARD16 +.LP +Errors: +.PN Colormap , +.PN Name +.in -.2i +.eM +.LP +This request looks up the string name of a color with respect to the screen +associated with cmap and returns both the exact color values and +the closest values provided by the hardware with respect to the visual +type of cmap. +The name should use the ISO Latin-1 encoding, +and uppercase and lowercase do not matter. +.sp +.LP +.sM +.IN "CreateCursor" "" "@DEF@" +.PN CreateCursor +.in +.2i +.LP +\fIcid\fP\^: CURSOR +.br +\fIsource\fP\^: PIXMAP +.br +\fImask\fP\^: PIXMAP or +.PN None +.br +\fIfore-red\fP, \fIfore-green\fP, \fIfore-blue\fP\^: CARD16 +.br +\fIback-red\fP, \fIback-green\fP, \fIback-blue\fP\^: CARD16 +.br +\fIx\fP, \fIy\fP\^: CARD16 +.LP +Errors: +.PN Alloc , +.PN IDChoice , +.PN Match , +.PN Pixmap +.in -.2i +.eM +.LP +This request creates a cursor and associates identifier cid with it. +The foreground and background RGB values must be specified, +even if the server only has a +.PN StaticGray +or +.PN GrayScale +screen. +The foreground is used for the bits set to 1 in the source, +and the background is used for the bits set to 0. +Both source and mask (if specified) must have depth one (or a +.PN Match +error results), but they can have any root. +The mask pixmap defines the shape of the cursor. +That is, +the bits set to 1 in the mask define which source pixels will be displayed, +and where the mask has bits set to 0, +the corresponding bits of the source pixmap are ignored. +If no mask is given, +all pixels of the source are displayed. +The mask, if present, must be the same size as the source (or a +.PN Match +error results). +The x and y coordinates define the hotspot relative to the source's origin +and must be a point within the source (or a +.PN Match +error results). +.LP +The components of the cursor may be transformed arbitrarily to meet +display limitations. +.LP +The pixmaps can be freed immediately if no further explicit references +to them are to be made. +.LP +Subsequent drawing in the source or mask pixmap has an undefined effect +on the cursor. +The server might or might not make a copy of the pixmap. +.sp +.LP +.sM +.IN "CreateGlyphCursor" "" "@DEF@" +.PN CreateGlyphCursor +.in +.2i +.LP +\fIcid\fP\^: CURSOR +.br +\fIsource-font\fP\^: FONT +.br +\fImask-font\fP\^: FONT or +.PN None +.br +\fIsource-char\fP, \fImask-char\fP\^: CARD16 +.br +\fIfore-red\fP, \fIfore-green\fP, \fIfore-blue\fP\^: CARD16 +.br +\fIback-red\fP, \fIback-green\fP, \fIback-blue\fP\^: CARD16 +.LP +Errors: +.PN Alloc , +.PN Font , +.PN IDChoice , +.PN Value +.in -.2i +.eM +.LP +This request is similar to +.PN CreateCursor , +except the source and mask bitmaps are obtained from the specified font glyphs. +The source-char must be a defined glyph in source-font, +and if mask-font is given, mask-char must be a defined glyph in mask-font +(or a +.PN Value +error results). +The mask font and character are optional. +The origins of the source and mask (if it is defined) glyphs +are positioned coincidently and define the hotspot. +The source and mask need not have the same bounding box metrics, +and there is no restriction on the placement of the hotspot relative +to the bounding boxes. +If no mask is given, +all pixels of the source are displayed. +Note that source-char and mask-char are CARD16, not CHAR2B. +For 2-byte matrix fonts, +the 16-bit value should be formed with byte1 in the most significant byte +and byte2 in the least significant byte. +.LP +The components of the cursor may be transformed arbitrarily to meet +display limitations. +.LP +The fonts can be freed immediately if no further explicit references to +them are to be made. +.sp +.LP +.sM +.IN "FreeCursor" "" "@DEF@" +.PN FreeCursor +.in +.2i +.LP +\fIcursor\fP\^: CURSOR +.LP +Errors: +.PN Cursor +.in -.2i +.eM +.LP +This request deletes the association between the resource ID and the cursor. +The cursor storage will be freed when no other resource references it. +.sp +.LP +.sM +.IN "RecolorCursor" "" "@DEF@" +.PN RecolorCursor +.in +.2i +.LP +\fIcursor\fP\^: CURSOR +.br +\fIfore-red\fP, \fIfore-green\fP, \fIfore-blue\fP\^: CARD16 +.br +\fIback-red\fP, \fIback-green\fP, \fIback-blue\fP\^: CARD16 +.LP +Errors: +.PN Cursor +.in -.2i +.eM +.LP +This request changes the color of a cursor. +If the cursor is being displayed on a screen, +the change is visible immediately. +.sp +.LP +.sM +.IN "QueryBestSize" "" "@DEF@" +.PN QueryBestSize +.in +.2i +.LP +\fIclass\fP: +.Pn { Cursor , +.PN Tile , +.PN Stipple } +.br +\fIdrawable\fP\^: DRAWABLE +.br +\fIwidth\fP, \fIheight\fP\^: CARD16 +.in -.2i +.LP + \(-> +.in +.2i +.LP +width, height: CARD16 +.LP +Errors: +.PN Drawable , +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request returns the best size that is closest to the argument size. +For +.PN Cursor , +this is the largest size that can be fully displayed. +For +.PN Tile , +this is the size that can be tiled fastest. +For +.PN Stipple , +this is the size that can be stippled fastest. +.LP +For +.PN Cursor , +the drawable indicates the desired screen. +For +.PN Tile +and +.PN Stipple , +the drawable indicates the screen and also possibly the window class and depth. +An +.PN InputOnly +window cannot be used as the drawable for +.PN Tile +or +.PN Stipple +(or a +.PN Match +error results). +.sp +.LP +.sM +.IN "QueryExtension" "" "@DEF@" +.PN QueryExtension +.in +.2i +.LP +\fIname\fP\^: STRING8 +.in -.2i +.LP + \(-> +.in +.2i +.LP +present: BOOL +.br +major-opcode: CARD8 +.br +first-event: CARD8 +.br +first-error: CARD8 +.in -.2i +.eM +.LP +This request determines if the named extension is present. +If so, +the major opcode for the extension is returned, if it has one. +Otherwise, zero is returned. +Any minor opcode and the request formats are specific to the extension. +If the extension involves additional event types, +the base event type code is returned. +Otherwise, zero is returned. +The format of the events is specific to the extension. +If the extension involves additional error codes, +the base error code is returned. +Otherwise, zero is returned. +The format of additional data in the errors is specific to the extension. +.LP +The extension name should use the ISO Latin-1 encoding, +and uppercase and lowercase matter. +.sp +.LP +.sM +.IN "ListExtensions" "" "@DEF@" +.PN ListExtensions +.LP + \(-> +.in +.2i +.LP +names: LISTofSTRING8 +.in -.2i +.eM +.LP +This request returns a list of all extensions supported by the server. +.LP +.sM +.IN "SetModifierMapping" "" "@DEF@" +.PN SetModifierMapping +.in +.2i +.LP +\fIkeycodes-per-modifier\fP\^: CARD8 +.br +\fIkeycodes\fP\^: LISTofKEYCODE +.in -.2i +.LP + \(-> +.in +.2i +.LP +status: +.Pn { Success , +.PN Busy , +.PN Failed } +.LP +Errors: +.PN Alloc , +.PN Value +.in -.2i +.eM +.LP +This request specifies the keycodes (if any) of the keys to be used as +modifiers. +The number of keycodes in the list must be 8*keycodes-per-modifier (or a +.PN Length +error results). +The keycodes are divided into eight sets, +with each set containing keycodes-per-modifier elements. +The sets are assigned to the modifiers +.PN Shift , +.PN Lock , +.PN Control , +.PN Mod1 , +.PN Mod2 , +.PN Mod3 , +.PN Mod4 , +and +.PN Mod5 , +in order. +Only nonzero keycode values are used within each set; +zero values are ignored. +All of the nonzero keycodes must be in the range specified by min-keycode +and max-keycode in the connection setup (or a +.PN Value +error results). +The order of keycodes within a set does not matter. +If no nonzero values are specified in a set, +the use of the corresponding modifier is disabled, +and the modifier bit will always be zero. +Otherwise, the modifier bit will be one whenever +at least one of the keys in the corresponding set is in the down +position. +.LP +A server can impose restrictions on how modifiers can be changed (for example, +if certain keys do not generate up transitions in hardware, +if auto-repeat cannot be disabled on certain keys, +or if multiple keys per modifier are not supported). +The status reply is +.PN Failed +if some such restriction is violated, +and none of the modifiers is changed. +.LP +If the new nonzero keycodes specified for a modifier differ from those +currently defined and any (current or new) keys for that modifier are +logically in the down state, then the status reply is +.PN Busy , +and none of the modifiers is changed. +.LP +This request generates a +.PN MappingNotify +event on a +.PN Success +status. +.sp +.LP +.sM +.IN "GetModifierMapping" "" "@DEF@" +.PN GetModifierMapping +.LP + \(-> +.in +.2i +.LP +keycodes-per-modifier: CARD8 +.br +keycodes: LISTofKEYCODE +.in -.2i +.eM +.LP +This request returns the keycodes of the keys being used as modifiers. +The number of keycodes in the list is 8*keycodes-per-modifier. +The keycodes are divided into eight sets, +with each set containing keycodes-per-modifier elements. +The sets are assigned to the modifiers +.PN Shift , +.PN Lock , +.PN Control , +.PN Mod1 , +.PN Mod2 , +.PN Mod3 , +.PN Mod4 , +and +.PN Mod5 , +in order. +The keycodes-per-modifier value is chosen arbitrarily by the server; +zeroes are used to fill in unused elements within each set. +If only zero values are given in a set, +the use of the corresponding modifier has been disabled. +The order of keycodes within each set is chosen arbitrarily by the server. +.sp +.LP +.sM +.IN "ChangeKeyboardMapping" "" "@DEF@" +.PN ChangeKeyboardMapping +.in +.2i +.LP +\fIfirst-keycode\fP\^: KEYCODE +.br +\fIkeysyms-per-keycode\fP\^: CARD8 +.br +\fIkeysyms\fP\^: LISTofKEYSYM +.LP +Errors: +.PN Alloc , +.PN Value +.in -.2i +.eM +.LP +This request defines the symbols for the specified number of keycodes, +starting with the specified keycode. +The symbols for keycodes outside this range remained unchanged. +The number of elements in the keysyms list must be a multiple of +keysyms-per-keycode (or a +.PN Length +error results). +The first-keycode must be greater than or equal to min-keycode as returned +in the connection setup (or a +.PN Value +error results) and: +.DS +first-keycode + (keysyms-length / keysyms-per-keycode) \- 1 +.DE +.LP +must be less than or equal to max-keycode as returned in the connection +setup (or a +.PN Value +error results). +KEYSYM number N (counting from zero) for keycode K has an index +(counting from zero) of: +.DS +(K \- first-keycode) * keysyms-per-keycode + N +.DE +.LP +in keysyms. +The keysyms-per-keycode can be chosen arbitrarily by the client +to be large enough to hold all desired symbols. +A special KEYSYM value of +.PN NoSymbol +should be used to fill in unused elements for individual keycodes. +It is legal for +.PN NoSymbol +to appear in nontrailing positions of the effective list for a keycode. +.LP +This request generates a +.PN MappingNotify +event. +.LP +There is no requirement that the server interpret this mapping; +it is merely stored for reading and writing by clients (see section 5). +.sp +.LP +.sM +.IN "GetKeyboardMapping" "" "@DEF@" +.PN GetKeyboardMapping +.in +.2i +.LP +\fIfirst-keycode\fP\^: KEYCODE +.br +\fIcount\fP\^: CARD8 +.in -.2i +.LP + \(-> +.in +.2i +.LP +keysyms-per-keycode: CARD8 +.br +keysyms: LISTofKEYSYM +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +This request returns the symbols for the specified number of keycodes, +starting with the specified keycode. +The first-keycode must be greater than or equal to +min-keycode as returned in the connection setup (or a +.PN Value +error results), and: +.DS +first-keycode + count \- 1 +.DE +.LP +must be less than or equal to max-keycode as returned in the connection setup +(or a +.PN Value +error results). +The number of elements in the keysyms list is: +.DS +count * keysyms-per-keycode +.DE +.LP +and KEYSYM number N (counting from zero) for keycode K has an index +(counting from zero) of: +.DS +(K \- first-keycode) * keysyms-per-keycode + N +.DE +.LP +in keysyms. +The keysyms-per-keycode value is chosen arbitrarily by the server +to be large enough to report all requested symbols. +A special KEYSYM value of +.PN NoSymbol +is used to fill in unused elements for individual keycodes. +.sp +.LP +.sM +.IN "ChangeKeyboardControl" "" "@DEF@" +.PN ChangeKeyboardControl +.in +.2i +.LP +\fIvalue-mask\fP\^: BITMASK +.br +\fIvalue-list\fP\^: LISTofVALUE +.LP +Errors: +.PN Match , +.PN Value +.in -.2i +.eM +.LP +This request controls various aspects of the keyboard. +The value-mask and value-list specify which controls are to be changed. +The possible values are: +.TS H +l l. +_ +.sp 6p +.B +Control Type +.sp 6p +_ +.TH +.R +.sp 6p +T{ +key-click-percent +T} T{ +INT8 +T} +T{ +bell-percent +T} T{ +INT8 +T} +T{ +bell-pitch +T} T{ +INT16 +T} +T{ +bell-duration +T} T{ +INT16 +T} +T{ +led +T} T{ +CARD8 +T} +T{ +led-mode +T} T{ +.Pn { On , +.PN Off } +T} +T{ +key +T} T{ +KEYCODE +T} +T{ +auto-repeat-mode +T} T{ +.Pn { On , +.PN Off , +.PN Default } +T} +.sp 6p +_ +.TE +.LP +The key-click-percent sets the volume for key clicks between 0 (off) and +100 (loud) inclusive, if possible. +Setting to \-1 restores the default. +Other negative values generate a +.PN Value +error. +.LP +The bell-percent sets the base volume for the bell between 0 (off) and 100 +(loud) inclusive, if possible. +Setting to \-1 restores the default. +Other negative values generate a +.PN Value +error. +.LP +The bell-pitch sets the pitch (specified in Hz) of the bell, if possible. +Setting to \-1 restores the default. +Other negative values generate a +.PN Value +error. +.LP +The bell-duration sets the duration of the bell (specified in milliseconds), +if possible. +Setting to \-1 restores the default. +Other negative values generate a +.PN Value +error. +.LP +If both led-mode and led are specified, +then the state of that LED is changed, if possible. +If only led-mode is specified, +then the state of all LEDs are changed, if possible. +At most 32 LEDs, numbered from one, are supported. +No standard interpretation of LEDs is defined. +It is a +.PN Match +error if an led is specified without an led-mode. +.LP +If both auto-repeat-mode and key are specified, +then the auto-repeat mode of that key is changed, if possible. +If only auto-repeat-mode is specified, +then the global auto-repeat mode for the entire keyboard is changed, +if possible, without affecting the per-key settings. +It is a +.PN Match +error if a key is specified without an auto-repeat-mode. +Each key has an individual mode of whether or not it should auto-repeat +and a default setting for that mode. +In addition, there is a global mode of whether auto-repeat should be +enabled or not and a default setting for that mode. +When the global mode is +.PN On , +keys should obey their individual auto-repeat modes. +When the global mode is +.PN Off , +no keys should auto-repeat. +An auto-repeating key generates alternating +.PN KeyPress +and +.PN KeyRelease +events. +When a key is used as a modifier, +it is desirable for the key not to auto-repeat, +regardless of the auto-repeat setting for that key. +.LP +A bell generator connected with the console but not directly on the +keyboard is treated as if it were part of the keyboard. +.LP +The order in which controls are verified and altered is server-dependent. +If an error is generated, +a subset of the controls may have been altered. +.sp +.LP +.sM +.IN "GetKeyboardControl" "" "@DEF@" +.PN GetKeyboardControl +.LP + \(-> +.in +.2i +.LP +key-click-percent: CARD8 +.br +bell-percent: CARD8 +.br +bell-pitch: CARD16 +.br +bell-duration: CARD16 +.br +led-mask: CARD32 +.br +global-auto-repeat: +.Pn { On , +.PN Off } +.br +auto-repeats: LISTofCARD8 +.in -.2i +.eM +.LP +This request returns the current control values for the keyboard. +For the LEDs, +the least significant bit of led-mask corresponds to LED one, +and each one bit in led-mask indicates an LED that is lit. +The auto-repeats is a bit vector; +each one bit indicates that auto-repeat is enabled for the corresponding key. +The vector is represented as 32 bytes. +Byte N (from 0) contains the bits for keys 8N to 8N + 7, +with the least significant bit in the byte representing key 8N. +.sp +.LP +.sM +.IN "Bell" "" "@DEF@" +.PN Bell +.in +.2i +.LP +\fIpercent\fP\^: INT8 +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +This request rings the bell on the keyboard at a volume relative to the +base volume for the keyboard, if possible. +Percent can range from \-100 to 100 inclusive (or a +.PN Value +error results). +The volume at which the bell is rung when percent is nonnegative is: +.DS +base \- [(base * percent) / 100] + percent +.DE +.LP +When percent is negative, it is: +.DS +base + [(base * percent) / 100] +.DE +.sp +.LP +.sM +.IN "SetPointerMapping" "" "@DEF@" +.PN SetPointerMapping +.in +.2i +.LP +\fImap\fP\^: LISTofCARD8 +.in -.2i +.LP + \(-> +.in +.2i +.LP +status: +.Pn { Success , +.PN Busy } +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +This request sets the mapping of the pointer. +Elements of the list are indexed starting from one. +The length of the list must be the same as +.PN GetPointerMapping +would return (or a +.PN Value +error results). +The index is a core button number, +and the element of the list defines the effective number. +.LP +A zero element disables a button. +Elements are not restricted in value by the number of physical buttons, +but no two elements can have the same nonzero value (or a +.PN Value +error results). +.LP +If any of the buttons to be altered are logically in the down state, +the status reply is +.PN Busy , +and the mapping is not changed. +.LP +This request generates a +.PN MappingNotify +event on a +.PN Success +status. +.sp +.LP +.sM +.IN "GetPointerMapping" "" "@DEF@" +.PN GetPointerMapping +.LP + \(-> +.in +.2i +.LP +map: LISTofCARD8 +.in -.2i +.eM +.LP +This request returns the current mapping of the pointer. +Elements of the list are indexed starting from one. +The length of the list indicates the number of physical buttons. +.LP +The nominal mapping for a pointer is the identity mapping: map[i]=i. +.sp +.LP +.sM +.IN "ChangePointerControl" "" "@DEF@" +.PN ChangePointerControl +.in +.2i +.LP +\fIdo-acceleration\fP, \fIdo-threshold\fP\^: BOOL +.br +\fIacceleration-numerator\fP, \fIacceleration-denominator\fP\^: INT16 +.br +\fIthreshold\fP\^: INT16 +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +This request defines how the pointer moves. +The acceleration is a multiplier for movement expressed as a fraction. +For example, +specifying 3/1 means the pointer moves three times as fast as normal. +The fraction can be rounded arbitrarily by the server. +Acceleration only takes effect if the pointer moves more than threshold +number of pixels at once and only applies to the amount beyond the threshold. +Setting a value to \-1 restores the default. +Other negative values generate a +.PN Value +error, as does a zero value for acceleration-denominator. +.sp +.LP +.sM +.IN "GetPointerControl" "" "@DEF@" +.PN GetPointerControl +.LP + \(-> +.in +.2i +.LP +acceleration-numerator, acceleration-denominator: CARD16 +.br +threshold: CARD16 +.in -.2i +.eM +.LP +This request returns the current acceleration and threshold for the pointer. +.sp +.LP +.sM +.IN "SetScreenSaver" "" "@DEF@" +.PN SetScreenSaver +.in +.2i +.LP +\fItimeout\fP, \fIinterval\fP\^: INT16 +.br +\fIprefer-blanking\fP\^: +.Pn { Yes , +.PN No , +.PN Default } +.br +\fIallow-exposures\fP\^: +.Pn { Yes , +.PN No , +.PN Default } +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +The timeout and interval are specified in seconds; +setting a value to \-1 restores the default. +Other negative values generate a +.PN Value +error. +If the timeout value is zero, +screen-saver is disabled (but an activated screen-saver is not deactivated). +If the timeout value is nonzero, +screen-saver is enabled. +Once screen-saver is enabled, +if no input from the keyboard or pointer is generated for timeout seconds, +screen-saver is activated. +For each screen, +if blanking is preferred and the hardware supports video blanking, +the screen will simply go blank. +Otherwise, +if either exposures are allowed or the screen can be regenerated without +sending exposure events to clients, +the screen is changed in a server-dependent fashion to avoid phosphor burn. +Otherwise, +the state of the screens does not change, and screen-saver is not activated. +At the next keyboard or pointer input or at the next +.PN ForceScreenSaver +with mode +.PN Reset , +screen-saver is deactivated, and all screen states are restored. +.LP +If the server-dependent screen-saver method is amenable to periodic change, +interval serves as a hint about how long the change period should be, +with zero hinting that no periodic change should be made. +Examples of ways to change the screen include scrambling the color map +periodically, moving an icon image about the screen periodically, or +tiling the screen with the root window background tile, +randomly reorigined periodically. +.sp +.LP +.sM +.IN "GetScreenSaver" "" "@DEF@" +.PN GetScreenSaver +.LP + \(-> +.in +.2i +.LP +timeout, interval: CARD16 +.br +prefer-blanking: +.Pn { Yes , +.PN No } +.br +allow-exposures: +.Pn { Yes , +.PN No } +.in -.2i +.eM +.LP +This request returns the current screen-saver control values. +.sp +.LP +.sM +.IN "ForceScreenSaver" "" "@DEF@" +.PN ForceScreenSaver +.in +.2i +.LP +\fImode\fP\^: +.Pn { Activate , +.PN Reset } +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +If the mode is +.PN Activate +and screen-saver is currently deactivated, +then screen-saver is activated (even if screen-saver has been disabled with +a timeout value of zero). +If the mode is +.PN Reset +and screen-saver is currently enabled, +then screen-saver is deactivated (if it was activated), +and the activation timer is reset to its initial state +as if device input had just been received. +.sp +.LP +.sM +.IN "ChangeHosts" "" "@DEF@" +.PN ChangeHosts +.in +.2i +.LP +\fImode\fP\^: +.Pn { Insert , +.PN Delete } +.br +\fIhost\fP: HOST +.LP +Errors: +.PN Access , +.PN Value +.in -.2i +.eM +.LP +This request adds or removes the specified host from the access control list. +When the access control mechanism is enabled and a client attempts to +establish a connection to the server, +the host on which the client resides must be in the access control list, +or the client must have been granted permission by a server-dependent +method, or the server will refuse the connection. +.LP +The client must reside on the same host as the server and/or have been granted +permission by a server-dependent method to execute this request (or an +.PN Access +error results). +.LP +An initial access control list can usually be specified, +typically by naming a file that the server reads at startup and reset. +.LP +The following address families are defined. +A server is not required to support these families +and may support families not listed here. +Use of an unsupported family, an improper address format, +or an improper address length within a supported family results in a +.PN Value +error. +.LP +For the Internet family, +the address must be four bytes long. +The address bytes are in standard IP order; +the server performs no automatic swapping on the address bytes. +For a Class A address, +the network number is the first byte in the address, +and the host number is the remaining three bytes, most significant byte first. +For a Class B address, +the network number is the first two bytes and the host number +is the last two bytes, each most significant byte first. +For a Class C address, +the network number is the first three bytes, most significant byte first, +and the last byte is the host number. +.LP +For the DECnet family, +the server performs no automatic swapping on the address bytes. +A Phase IV address is two bytes long: +the first byte contains the least significant eight bits of the node number, +and the second byte contains the most significant two bits of the node number in +the least significant two bits of the byte and the area in the most +significant six bits of the byte. +.LP +For the Chaos family, +the address must be two bytes long. +The host number is always the first byte in the address, +and the subnet number is always the second byte. +The server performs no automatic swapping on the address bytes. +.sp +.LP +.sM +.IN "ListHosts" "" "@DEF@" +.PN ListHosts +.LP + \(-> +.in +.2i +.LP +mode: +.Pn { Enabled , +.PN Disabled } +.br +hosts: LISTofHOST +.in -.2i +.eM +.LP +This request returns the hosts on the access control list +and whether use of the list at connection setup is currently +enabled or disabled. +.LP +Each HOST is padded to a multiple of four bytes. +.sp +.LP +.sM +.IN "SetAccessControl" "" "@DEF@" +.PN SetAccessControl +.in +.2i +.LP +\fImode\fP\^: +.Pn { Enable , +.PN Disable } +.LP +Errors: +.PN Access , +.PN Value +.in -.2i +.eM +.LP +This request enables or disables the use of the access control list +at connection setups. +.LP +The client must reside on the same host as the server +and/or have been granted permission by a server-dependent method +to execute this request (or an +.PN Access +error results). +.sp +.LP +.sM +.IN "SetCloseDownMode" "" "@DEF@" +.PN SetCloseDownMode +.in +.2i +.LP +\fImode\fP: +.Pn { Destroy , +.PN RetainPermanent , +.PN RetainTemporary } +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +This request defines what will happen to the client's resources +at connection close. +A connection starts in +.PN Destroy +mode. +The meaning of the close-down mode is described in section 10. +.sp +.LP +.sM +.IN "KillClient" "" "@DEF@" +.PN KillClient +.in +.2i +.LP +\fIresource\fP\^: CARD32 or +.PN AllTemporary +.LP +Errors: +.PN Value +.in -.2i +.eM +.LP +If a valid resource is specified, +.PN KillClient +forces a close-down of the client that created the resource. +If the client has already terminated in either +.PN RetainPermanent +or +.PN RetainTemporary +mode, all of the client's resources are destroyed (see section 10). +If +.PN AllTemporary +is specified, +then the resources of all clients that have terminated in +.PN RetainTemporary +are destroyed. +.sp +.LP +.sM +.IN "NoOperation" "" "@DEF@" +.PN NoOperation +.eM +.LP +This request has no arguments and no results, +but the request length field +allows the request to be any multiple of four bytes in length. +The bytes contained in the request are uninterpreted by the server. +.LP +This request can be used in its minimum four byte form as padding where +necessary by client libraries that find it convenient to force requests +to begin on 64-bit boundaries. +.NH 1 +Connection Close +.XS +\*(SN Connection Close +.XE +.LP +At connection close, +all event selections made by the client are discarded. +If the client has the pointer actively grabbed, an +.PN UngrabPointer +is performed. +If the client has the keyboard actively grabbed, an +.PN UngrabKeyboard +is performed. +All passive grabs by the client are released. +If the client has the server grabbed, an +.PN UngrabServer +is performed. +All selections (see +.PN SetSelectionOwner +request) +owned by the client are disowned. +If close-down mode (see +.PN SetCloseDownMode +request) is +.PN RetainPermanent +or +.PN RetainTemporary , +then all resources (including colormap entries) +allocated by the client are marked as permanent or temporary, +respectively (but this does not prevent other clients from explicitly +destroying them). +If the mode is +.PN Destroy , +all of the client's resources are destroyed. +.LP +When a client's resources are destroyed, +for each window in the client's save-set, +if the window is an inferior of a window created by the client, +the save-set window is reparented to the closest ancestor such that +the save-set window is not an inferior of a window created by the client. +If the save-set window is unmapped, a +.PN MapWindow +request is performed on it (even if it was not an inferior +of a window created by the client). +The reparenting leaves unchanged the absolute coordinates +(with respect to the root window) of the upper-left outer corner of the +save-set window. +After save-set processing, +all windows created by the client are destroyed. +For each nonwindow resource created by the client, +the appropriate +.PN Free +request is performed. +All colors and colormap entries allocated by the client are freed. +.LP +A server goes through a cycle of having no connections and having some +connections. +At every transition to the state of having no connections +as a result of a connection closing with a +.PN Destroy +close-down mode, +the server resets its state as if it had just been started. +This starts by destroying all lingering resources from clients +that have terminated in +.PN RetainPermanent +or +.PN RetainTemporary +mode. +It additionally includes deleting all but the predefined atom identifiers, +deleting all properties on all root windows, resetting all device maps and +attributes (key click, bell volume, acceleration), resetting the access +control list, restoring the standard root tiles and cursors, restoring +the default font path, and restoring the input focus to state +.PN PointerRoot . +.LP +Note that closing a connection with a close-down mode of +.PN RetainPermanent +or +.PN RetainTemporary +will not cause the server to reset. +.NH 1 +Events +.XS +\*(SN Events +.XE +.LP +When a button press is processed with the pointer in some window W +and no active pointer grab is in progress, +the ancestors of W are searched from the root down, +looking for a passive grab to activate. +If no matching passive grab on the button exists, +then an active grab is started automatically for the client receiving the event, +and the last-pointer-grab time is set to the current server time. +The effect is essentially equivalent to a +.PN GrabButton +with arguments: +.TS H +lw(2.25i) lw(3.25i). +_ +.sp 6p +.B +Argument Value +.sp 6p +_ +.TH +.R +.sp 6p +T{ +event-window +T} T{ +Event window +T} +T{ +event-mask +T} T{ +Client's selected pointer events on the event window +T} +T{ +pointer-mode and keyboard-mode +T} T{ +.PN Asynchronous +T} +T{ +owner-events +T} T{ +.PN True +if the client has +.PN OwnerGrabButton +selected on the event window, otherwise +.PN False +T} +T{ +confine-to +T} T{ +.PN None +T} +T{ +cursor +T} T{ +.PN None +T} +.sp 6p +_ +.TE +.LP +The grab is terminated automatically when the logical state of the pointer +has all buttons released. +.PN UngrabPointer +and +.PN ChangeActivePointerGrab +can both be used to modify the active grab. +.sp +.LP +.sM +.IN "KeyPress" "" "@DEF@" +.PN KeyPress +.br +.IN "KeyRelease" "" "@DEF@" +.PN KeyRelease +.br +.IN "ButtonPress" "" "@DEF@" +.PN ButtonPress +.br +.IN "ButtonRelease" "" "@DEF@" +.PN ButtonRelease +.br +.IN "MotionNotify" "" "@DEF@" +.PN MotionNotify +.in +.2i +.LP +\fIroot\fP, \fIevent\fP\^: WINDOW +.br +\fIchild\fP\^: WINDOW or +.PN None +.br +\fIsame-screen\fP\^: BOOL +.br +\fIroot-x\fP, \fIroot-y\fP, \fIevent-x\fP, \fIevent-y\fP\^: INT16 +.br +\fIdetail\fP\^: <see below> +.br +\fIstate\fP\^: SETofKEYBUTMASK +.br +\fItime\fP\^: TIMESTAMP +.in -.2i +.eM +.LP +These events are generated either when a key or button logically changes state +or when the pointer logically moves. +The generation of these logical changes may lag the physical changes +if device event processing is frozen. +Note that +.PN KeyPress +and +.PN KeyRelease +are generated for all keys, even those mapped to modifier bits. +The source of the event is the window the pointer is in. +The window the event is reported with respect to is called the event window. +The event window is found by starting with the source window and +looking up the hierarchy for the first window on which any client has selected +interest in the event (provided no intervening window prohibits event +generation by including the event type in its do-not-propagate-mask). +The actual window used for reporting can be modified by active grabs and, +in the case of keyboard events, can be modified by the focus window. +.LP +The root is the root window of the source window, +and root-x and root-y are the pointer coordinates relative to root's origin +at the time of the event. +Event is the event window. +If the event window is on the same screen as root, +then event-x and event-y are the pointer coordinates relative to the +event window's origin. +Otherwise, event-x and event-y are zero. +If the source window is an inferior of the event window, +then child is set to the child of the event window that is an +ancestor of (or is) the source window. +Otherwise, it is set to +.PN None . +The state component gives the logical state of the buttons and modifier keys +just before the event. +The detail component type varies with the event type: +.TS H +l l. +_ +.sp 6p +.B +Event Component +.sp 6p +_ +.TH +.R +.sp 6p +T{ +.PN KeyPress , +.PN KeyRelease +T} T{ +KEYCODE +T} +T{ +.PN ButtonPress , +.PN ButtonRelease +T} T{ +BUTTON +T} +T{ +.PN MotionNotify +T} T{ +.Pn { Normal , +.PN Hint } +T} +.sp 6p +_ +.TE +.LP +.PN MotionNotify +events are only generated when the motion begins and ends in the window. +The granularity of motion events is not guaranteed, +but a client selecting for motion events is guaranteed to get at least one +event when the pointer moves and comes to rest. +Selecting +.PN PointerMotion +receives events independent of the state of the pointer buttons. +By selecting some subset of +.PN Button[1-5]Motion +instead, +.PN MotionNotify +events will only be received when one or more of the +specified buttons are pressed. +By selecting +.PN ButtonMotion , +.PN MotionNotify +events will be received only when at least one button is pressed. +The events are always of type +.PN MotionNotify , +independent of the selection. +If +.PN PointerMotionHint +is selected, +the server is free to send only one +.PN MotionNotify +event (with detail +.PN Hint ) +to the client for the event window until +either the key or button state changes, +the pointer leaves the event window, +or the client issues a +.PN QueryPointer +or +.PN GetMotionEvents +request. +.sp +.LP +.sM +.IN "EnterNotify" "" "@DEF@" +.PN EnterNotify +.br +.IN "LeaveNotify" "" "@DEF@" +.PN LeaveNotify +.in +.2i +.LP +\fIroot\fP, \fIevent\fP\^: WINDOW +.br +\fIchild\fP\^: WINDOW or +.PN None +.br +\fIsame-screen\fP\^: BOOL +.br +\fIroot-x\fP, \fIroot-y\fP, \fIevent-x\fP, \fIevent-y\fP\^: INT16 +.br +\fImode\fP\^: +.Pn { Normal , +.PN Grab , +.PN Ungrab } +.br +\fIdetail\fP\^: +.Pn { Ancestor , +.PN Virtual , +.PN Inferior , +.PN Nonlinear , +.PN NonlinearVirtual } +.br +\fIfocus\fP\^: BOOL +.br +\fIstate\fP\^: SETofKEYBUTMASK +.br +\fItime\fP\^: TIMESTAMP +.in -.2i +.eM +.LP +If pointer motion or window hierarchy change causes the pointer to be +in a different window than before, +.PN EnterNotify +and +.PN LeaveNotify +events are generated instead of a +.PN MotionNotify +event. +Only clients selecting +.PN EnterWindow +on a window receive +.PN EnterNotify +events, and only clients selecting +.PN LeaveWindow +receive +.PN LeaveNotify +events. +The pointer position reported in the event is always the final position, +not the initial position of the pointer. +The root is the root window for this position, +and root-x and root-y are the pointer coordinates relative to root's +origin at the time of the event. +Event is the event window. +If the event window is on the same screen as root, +then event-x and event-y are the pointer coordinates relative +to the event window's origin. +Otherwise, event-x and event-y are zero. +In a +.PN LeaveNotify +event, if a child of the event window contains the initial position of the +pointer, then the child component is set to that child. +Otherwise, it is +.PN None . +For an +.PN EnterNotify +event, if a child of the event window contains the final pointer position, +then the child component is set to that child. +Otherwise, it is +.PN None . +If the event window is the focus window or an inferior of the focus window, +then focus is +.PN True . +Otherwise, focus is +.PN False . +.LP +Normal pointer motion events have mode +.PN Normal . +Pseudo-motion events when a grab activates have mode +.PN Grab , +and pseudo-motion events when a grab deactivates have mode +.PN Ungrab . +.LP +All +.PN EnterNotify +and +.PN LeaveNotify +events caused by a hierarchy change are generated after any hierarchy event +caused by that change (that is, +.PN UnmapNotify , +.PN MapNotify , +.PN ConfigureNotify , +.PN GravityNotify , +.PN CirculateNotify ), +but the ordering of +.PN EnterNotify +and +.PN LeaveNotify +events with respect to +.PN FocusOut , +.PN VisibilityNotify , +and +.PN Expose +events is not constrained. +.LP +Normal events are generated as follows: +.LP +When the pointer moves from window A to window B and A is an inferior +of B: +.IP \(bu 5 +.PN LeaveNotify +with detail +.PN Ancestor +is generated on A. +.IP \(bu 5 +.PN LeaveNotify +with detail +.PN Virtual +is generated on each window between A and B exclusive (in that order). +.IP \(bu 5 +.PN EnterNotify +with detail +.PN Inferior +is generated on B. +.LP +When the pointer moves from window A to window B and B is an inferior +of A: +.IP \(bu 5 +.PN LeaveNotify +with detail +.PN Inferior +is generated on A. +.IP \(bu 5 +.PN EnterNotify +with detail +.PN Virtual +is generated on each window between A and B exclusive (in that order). +.IP \(bu 5 +.PN EnterNotify +with detail +.PN Ancestor +is generated on B. +.LP +When the pointer moves from window A to window B and window C is +their least common ancestor: +.IP \(bu 5 +.PN LeaveNotify +with detail +.PN Nonlinear +is generated on A. +.IP \(bu 5 +.PN LeaveNotify +with detail +.PN NonlinearVirtual +is generated on each window between A and C exclusive (in that order). +.IP \(bu 5 +.PN EnterNotify +with detail +.PN NonlinearVirtual +is generated on each window between C and B exclusive (in that order). +.IP \(bu 5 +.PN EnterNotify +with detail +.PN Nonlinear +is generated on B. +.LP +When the pointer moves from window A to window B on different screens: +.IP \(bu 5 +.PN LeaveNotify +with detail +.PN Nonlinear +is generated on A. +.IP \(bu 5 +If A is not a root window, +.PN LeaveNotify +with detail +.PN NonlinearVirtual +is generated on each window above A up to and including its root (in order). +.IP \(bu 5 +If B is not a root window, +.PN EnterNotify +with detail +.PN NonlinearVirtual +is generated on each window from B's root down to but not including B +(in order). +.IP \(bu 5 +.PN EnterNotify +with detail +.PN Nonlinear +is generated on B. +.LP +When a pointer grab activates (but after any initial warp into a confine-to +window and before generating any actual +.PN ButtonPress +event that activates the grab), +G is the grab-window for the grab, and P is the window the pointer is in: +.IP \(bu 5 +.PN EnterNotify +and +.PN LeaveNotify +events with mode +.PN Grab +are generated (as for +.PN Normal +above) as if the pointer were to suddenly warp from its current +position in P to some position in G. +However, the pointer does not warp, +and the pointer position is used as both the initial +and final positions for the events. +.LP +When a pointer grab deactivates (but after generating any actual +.PN ButtonRelease +event that deactivates the grab), G is the grab-window for +the grab, and P is the window the pointer is in: +.IP \(bu 5 +.PN EnterNotify +and +.PN LeaveNotify +events with mode +.PN Ungrab +are generated (as for +.PN Normal +above) as if the pointer were to suddenly warp from +some position in G to its current position in P. +However, the pointer does not warp, +and the current pointer position is used as both the initial +and final positions for the events. +.sp +.LP +.sM +.IN "FocusIn" "" "@DEF@" +.PN FocusIn +.br +.IN "FocusOut" "" "@DEF@" +.PN FocusOut +.in +.2i +.LP +\fIevent\fP\^: WINDOW +.br +\fImode\fP\^: +.Pn { Normal , +.PN WhileGrabbed , +.PN Grab , +.PN Ungrab } +.br +\fIdetail\fP\^: +.Pn { Ancestor , +.PN Virtual , +.PN Inferior , +.PN Nonlinear , +.PN NonlinearVirtual , +.PN Pointer , +.br +\ \ \ \ \ \ \ \ \ \ \ +.PN PointerRoot , +.PN None } +.in -.2i +.eM +.LP +These events are generated when the input focus changes +and are reported to clients selecting +.PN FocusChange +on the window. +Events generated by +.PN SetInputFocus +when the keyboard is not grabbed have mode +.PN Normal . +Events generated by +.PN SetInputFocus +when the keyboard is grabbed have mode +.PN WhileGrabbed . +Events generated when a keyboard grab activates have mode +.PN Grab , +and events generated when a keyboard grab deactivates have mode +.PN Ungrab . +.LP +All +.PN FocusOut +events caused by a window unmap are generated after any +.PN UnmapNotify +event, but the ordering of +.PN FocusOut +with respect to generated +.PN EnterNotify , +.PN LeaveNotify , +.PN VisibilityNotify , +and +.PN Expose +events is not constrained. +.LP +.PN Normal +and +.PN WhileGrabbed +events are generated as follows: +.LP +When the focus moves from window A to window B, A is an inferior of B, +and the pointer is in window P: +.IP \(bu 5 +.PN FocusOut +with detail +.PN Ancestor +is generated on A. +.IP \(bu 5 +.PN FocusOut +with detail +.PN Virtual +is generated on each window between A and B exclusive (in order). +.IP \(bu 5 +.PN FocusIn +with detail +.PN Inferior +is generated on B. +.IP \(bu 5 +If P is an inferior of B +but P is not A or an inferior of A or an ancestor of A, +.PN FocusIn +with detail +.PN Pointer +is generated on each window below B down to and including P (in order). +.LP +When the focus moves from window A to window B, B is an inferior of A, +and the pointer is in window P: +.IP \(bu 5 +If P is an inferior of A +but P is not an inferior of B or an ancestor of B, +.PN FocusOut +with detail +.PN Pointer +is generated on each window from P up to but not including A (in order). +.IP \(bu 5 +.PN FocusOut +with detail +.PN Inferior +is generated on A. +.IP \(bu 5 +.PN FocusIn +with detail +.PN Virtual +is generated on each window between A and B exclusive (in order). +.IP \(bu 5 +.PN FocusIn +with detail +.PN Ancestor +is generated on B. +.LP +When the focus moves from window A to window B, window C is their +least common ancestor, and the pointer is in window P: +.IP \(bu 5 +If P is an inferior of A, +.PN FocusOut +with detail +.PN Pointer +is generated on each window from P up to but not including A (in order). +.IP \(bu 5 +.PN FocusOut +with detail +.PN Nonlinear +is generated on A. +.IP \(bu 5 +.PN FocusOut +with detail +.PN NonlinearVirtual +is generated on each window between A and C exclusive (in order). +.IP \(bu 5 +.PN FocusIn +with detail +.PN NonlinearVirtual +is generated on each window between C and B exclusive (in order). +.IP \(bu 5 +.PN FocusIn +with detail +.PN Nonlinear +is generated on B. +.IP \(bu 5 +If P is an inferior of B, +.PN FocusIn +with detail +.PN Pointer +is generated on each window below B down to and including P (in order). +.LP +When the focus moves from window A to window B on different screens +and the pointer is in window P: +.IP \(bu 5 +If P is an inferior of A, +.PN FocusOut +with detail +.PN Pointer +is generated on each window from P up to but not including A (in order). +.IP \(bu 5 +.PN FocusOut +with detail +.PN Nonlinear +is generated on A. +.IP \(bu 5 +If A is not a root window, +.PN FocusOut +with detail +.PN NonlinearVirtual +is generated on each window above A up to and including its root (in order). +.IP \(bu 5 +If B is not a root window, +.PN FocusIn +with detail +.PN NonlinearVirtual +is generated on each window from B's root down to but not including B +(in order). +.IP \(bu 5 +.PN FocusIn +with detail +.PN Nonlinear +is generated on B. +.IP \(bu 5 +If P is an inferior of B, +.PN FocusIn +with detail +.PN Pointer +is generated on each window below B down to and including P (in order). +.LP +When the focus moves from window A to +.PN PointerRoot +(or +.PN None ) +and the pointer is in window P: +.IP \(bu 5 +If P is an inferior of A, +.PN FocusOut +with detail +.PN Pointer +is generated on each window from P up to but not including A (in order). +.IP \(bu 5 +.PN FocusOut +with detail +.PN Nonlinear +is generated on A. +.IP \(bu 5 +If A is not a root window, +.PN FocusOut +with detail +.PN NonlinearVirtual +is generated on each window above A up to and including its root (in order). +.IP \(bu 5 +.PN FocusIn +with detail +.PN PointerRoot +(or +.PN None ) +is generated on all root windows. +.IP \(bu 5 +If the new focus is +.PN PointerRoot , +.PN FocusIn +with detail +.PN Pointer +is generated on each window from P's root down to and including P (in order). +.LP +When the focus moves from +.PN PointerRoot +(or +.PN None ) +to window A and the pointer is in window P: +.IP \(bu 5 +If the old focus is +.PN PointerRoot , +.PN FocusOut +with detail +.PN Pointer +is generated on each window from P up to and including P's root (in order). +.IP \(bu 5 +.PN FocusOut +with detail +.PN PointerRoot +(or +.PN None ) +is generated on all root windows. +.IP \(bu 5 +If A is not a root window, +.PN FocusIn +with detail +.PN NonlinearVirtual +is generated on each window from A's root down to but not including A +(in order). +.IP \(bu 5 +.PN FocusIn +with detail +.PN Nonlinear +is generated on A. +.IP \(bu 5 +If P is an inferior of A, +.PN FocusIn +with detail +.PN Pointer +is generated on each window below A down to and including P (in order). +.LP +When the focus moves from +.PN PointerRoot +to +.PN None +(or vice versa) and the pointer is in window P: +.IP \(bu 5 +If the old focus is +.PN PointerRoot , +.PN FocusOut +with detail +.PN Pointer +is generated on each window from P up to and including P's root (in order). +.IP \(bu 5 +.PN FocusOut +with detail +.PN PointerRoot +(or +.PN None ) +is generated on all root windows. +.IP \(bu 5 +.PN FocusIn +with detail +.PN None +(or +.PN PointerRoot ) +is generated on all root windows. +.IP \(bu 5 +If the new focus is +.PN PointerRoot , +.PN FocusIn +with detail +.PN Pointer +is generated on each window from P's root down to and including P (in order). +.LP +When a keyboard grab activates (but before generating any actual +.PN KeyPress +event that activates the grab), G is the grab-window for the grab, +and F is the current focus: +.IP \(bu 5 +.PN FocusIn +and +.PN FocusOut +events with mode +.PN Grab +are generated (as for +.PN Normal +above) as if the focus were to change from F to G. +.LP +When a keyboard grab deactivates (but after generating any actual +.PN KeyRelease +event that deactivates the grab), G is the grab-window for the grab, +and F is the current focus: +.IP \(bu 5 +.PN FocusIn +and +.PN FocusOut +events with mode +.PN Ungrab +are generated (as for +.PN Normal +above) as if the focus were to change from G to F. +.sp +.LP +.sM +.IN "KeymapNotify" "" "@DEF@" +.PN KeymapNotify +.in +.2i +.LP +\fIkeys\fP\^: LISTofCARD8 +.in -.2i +.eM +.LP +The value is a bit vector as described in +.PN QueryKeymap . +This event is reported to clients selecting +.PN KeymapState +on a window and is generated immediately after every +.PN EnterNotify +and +.PN FocusIn . +.sp +.LP +.sM +.IN "Expose" "" "@DEF@" +.PN Expose +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP\^: CARD16 +.br +\fIcount\fP\^: CARD16 +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN Exposure +on the window. +It is generated when no valid contents are available for regions of a window, +and either the regions are visible, the regions are viewable +and the server is (perhaps newly) maintaining backing store on the window, +or the window is not viewable but the server is (perhaps newly) honoring +window's backing-store attribute of +.PN Always +or +.PN WhenMapped . +The regions are decomposed into an arbitrary set of rectangles, +and an +.PN Expose +event is generated for each rectangle. +.LP +For a given action causing exposure events, +the set of events for a given window are guaranteed to be reported contiguously. +If count is zero, +then no more +.PN Expose +events for this window follow. +If count is nonzero, +then at least that many more +.PN Expose +events for this window follow (and possibly more). +.LP +The x and y coordinates are relative to window's origin +and specify the upper-left corner of a rectangle. +The width and height specify the extent of the rectangle. +.LP +.PN Expose +events are never generated on +.PN InputOnly +windows. +.LP +All +.PN Expose +events caused by a hierarchy change are generated after any +hierarchy event caused by that change (for example, +.PN UnmapNotify , +.PN MapNotify , +.PN ConfigureNotify , +.PN GravityNotify , +.PN CirculateNotify ). +All +.PN Expose +events on a given window are generated after any +.PN VisibilityNotify +event on that window, +but it is not required that all +.PN Expose +events on all windows be generated after all +.PN Visibilitity +events on all windows. +The ordering of +.PN Expose +events with respect to +.PN FocusOut , +.PN EnterNotify , +and +.PN LeaveNotify +events is not constrained. +.sp +.LP +.sM +.IN "GraphicsExposure" "" "@DEF@" +.PN GraphicsExposure +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP\^: CARD16 +.br +\fIcount\fP\^: CARD16 +.br +\fImajor-opcode\fP\^: CARD8 +.br +\fIminor-opcode\fP\^: CARD16 +.in -.2i +.eM +.LP +This event is reported to a client using a graphics context +with graphics-exposures selected +and is generated when a destination region could not be computed due +to an obscured or out-of-bounds source region. +All of the regions exposed by a given graphics request +are guaranteed to be reported contiguously. +If count is zero then no more +.PN GraphicsExposure +events for this window follow. +If count is nonzero, +then at least that many more +.PN GraphicsExposure +events for this window follow (and possibly more). +.LP +The x and y coordinates are relative to drawable's origin +and specify the upper-left corner of a rectangle. +The width and height specify the extent of the rectangle. +.LP +The major and minor opcodes identify the graphics request used. +For the core protocol, +major-opcode is always +.PN CopyArea +or +.PN CopyPlane , +and minor-opcode is always zero. +.sp +.LP +.sM +.IN "NoExposure" "" "@DEF@" +.PN NoExposure +.in +.2i +.LP +\fIdrawable\fP\^: DRAWABLE +.br +\fImajor-opcode\fP\^: CARD8 +.br +\fIminor-opcode:\fP\^ CARD16 +.in -.2i +.eM +.LP +This event is reported to a client using a graphics context +with graphics-exposures selected +and is generated when a graphics request +that might produce +.PN GraphicsExposure +events does not produce any. +The drawable specifies the destination used for the graphics request. +.LP +The major and minor opcodes identify the graphics request used. +For the core protocol, +major-opcode is always +.PN CopyArea +or +.PN CopyPlane , +and the minor-opcode is always zero. +.sp +.LP +.sM +.IN "VisibilityNotify" "" "@DEF@" +.PN VisibilityNotify +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIstate\fP\^: +.Pn { Unobscured , +.PN PartiallyObscured , +.PN FullyObscured } +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN VisibilityChange +on the window. +In the following, +the state of the window is calculated ignoring all of the window's subwindows. +When a window changes state from partially or fully obscured or +not viewable to viewable and completely unobscured, +an event with +.PN Unobscured +is generated. +When a window changes state from viewable and completely unobscured, +from viewable and completely obscured, +or from not viewable, to viewable and partially obscured, +an event with +.PN PartiallyObscured +is generated. +When a window changes state from viewable and completely unobscured, +from viewable and partially obscured, +or from not viewable to viewable and fully obscured, +an event with +.PN FullyObscured +is generated. +.LP +.PN VisibilityNotify +events are never generated on +.PN InputOnly +windows. +.LP +All +.PN VisibilityNotify +events caused by a hierarchy change are generated after any hierarchy event +caused by that change (for example, +.PN UnmapNotify , +.PN MapNotify , +.PN ConfigureNotify , +.PN GravityNotify , +.PN CirculateNotify ). +Any +.PN VisibilityNotify +event on a given window is generated before any +.PN Expose +events on that window, +but it is not required that all +.PN VisibilityNotify +events on all windows be generated before all +.PN Expose +events on all windows. +The ordering of +.PN VisibilityNotify +events with respect to +.PN FocusOut , +.PN EnterNotify , +and +.PN LeaveNotify +events is not constrained. +.sp +.LP +.sM +.IN "CreateNotify" "" "@DEF@" +.PN CreateNotify +.in +.2i +.LP +\fIparent\fP, \fIwindow\fP\^: WINDOW +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIwidth\fP, \fIheight\fP, \fIborder-width\fP\^: CARD16 +.br +\fIoverride-redirect\fP\^: BOOL +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN SubstructureNotify +on the parent +and is generated when the window is created. +The arguments are as in the +.PN CreateWindow +request. +.sp +.LP +.sM +.IN "DestroyNotify" "" "@DEF@" +.PN DestroyNotify +.in +.2i +.LP +\fIevent\fP, \fIwindow\fP\^: WINDOW +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN StructureNotify +on the window and to clients selecting +.PN SubstructureNotify +on the parent. +It is generated when the window is destroyed. +The event is the window on which the event was generated, +and the window is the window that is destroyed. +.LP +The ordering of the +.PN DestroyNotify +events is such that for any given window, +.PN DestroyNotify +is generated on all inferiors of the window +before being generated on the window itself. +The ordering among siblings and across subhierarchies is not +otherwise constrained. +.sp +.LP +.sM +.IN "UnmapNotify" "" "@DEF@" +.PN UnmapNotify +.in +.2i +.LP +\fIevent\fP, \fIwindow\fP\^: WINDOW +.br +\fIfrom-configure\fP\^: BOOL +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN StructureNotify +on the window and to clients selecting +.PN SubstructureNotify +on the parent. +It is generated when the window changes state from mapped to unmapped. +The event is the window on which the event was generated, +and the window is the window that is unmapped. +The from-configure flag is +.PN True +if the event was generated as a result of the window's parent being resized +when the window itself had a win-gravity of +.PN Unmap . +.sp +.LP +.sM +.IN "MapNotify" "" "@DEF@" +.PN MapNotify +.in +.2i +.LP +\fIevent\fP, \fIwindow\fP\^: WINDOW +.br +\fIoverride-redirect\fP\^: BOOL +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN StructureNotify +on the window and to clients selecting +.PN SubstructureNotify +on the parent. +It is generated when the window changes state from unmapped to mapped. +The event is the window on which the event was generated, +and the window is the window that is mapped. +The override-redirect flag is from the window's attribute. +.sp +.LP +.sM +.IN "MapRequest" "" "@DEF@" +.PN MapRequest +.in +.2i +.LP +\fIparent\fP, \fIwindow\fP\^: WINDOW +.in -.2i +.eM +.LP +This event is reported to the client selecting +.PN SubstructureRedirect +on the parent and is generated when a +.PN MapWindow +request is issued on an unmapped window with an override-redirect attribute of +.PN False . +.sp +.LP +.sM +.IN "ReparentNotify" "" "@DEF@" +.PN ReparentNotify +.in +.2i +.LP +\fIevent\fP, \fIwindow\fP, \fIparent\fP\^: WINDOW +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIoverride-redirect\fP\^: BOOL +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN SubstructureNotify +on either the old or the new parent and to clients selecting +.PN StructureNotify +on the window. +It is generated when the window is reparented. +The event is the window on which the event was generated. +The window is the window that has been rerooted. +The parent specifies the new parent. +The x and y coordinates are relative to the new parent's origin +and specify the position of the upper-left outer corner of the window. +The override-redirect flag is from the window's attribute. +.sp +.LP +.sM +.IN "ConfigureNotify" "" "@DEF@" +.PN ConfigureNotify +.in +.2i +.LP +\fIevent\fP, \fIwindow\fP\^: WINDOW +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIwidth\fP, \fIheight\fP, \fIborder-width\fP\^: CARD16 +.br +\fIabove-sibling\fP\^: WINDOW or +.PN None +.br +\fIoverride-redirect\fP\^: BOOL +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN StructureNotify +on the window and to clients selecting +.PN SubstructureNotify +on the parent. +It is generated when a +.PN ConfigureWindow +request actually changes the state of the window. +The event is the window on which the event was generated, +and the window is the window that is changed. +The x and y coordinates are relative to the new parent's origin +and specify the position of the upper-left outer corner of the window. +The width and height specify the inside size, not including the border. +If above-sibling is +.PN None , +then the window is on the bottom of the stack with respect to siblings. +Otherwise, the window is immediately on top of the specified sibling. +The override-redirect flag is from the window's attribute. +.sp +.LP +.sM +.IN "GravityNotify" "" "@DEF@" +.PN GravityNotify +.in +.2i +.LP +\fIevent\fP, \fIwindow\fP\^: WINDOW +.br +\fIx\fP, \fIy\fP\^: INT16 +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN SubstructureNotify +on the parent and to clients selecting +.PN StructureNotify +on the window. +It is generated when a window is moved because of a change in size +of the parent. +The event is the window on which the event was generated, +and the window is the window that is moved. +The x and y coordinates are relative to the new parent's origin +and specify the position of the upper-left outer corner of the window. +.sp +.LP +.sM +.IN "ResizeRequest" "" "@DEF@" +.PN ResizeRequest +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIwidth\fP, \fIheight\fP\^: CARD16 +.in -.2i +.eM +.LP +This event is reported to the client selecting +.PN ResizeRedirect +on the window and is generated when a +.PN ConfigureWindow +request by some other client on the window attempts to change the size +of the window. +The width and height are the requested inside size, not including the border. +.sp +.LP +.sM +.IN "ConfigureRequest" "" "@DEF@" +.PN ConfigureRequest +.in +.2i +.LP +\fIparent\fP, \fIwindow\fP\^: WINDOW +.br +\fIx\fP, \fIy\fP\^: INT16 +.br +\fIwidth\fP, \fIheight\fP, \fIborder-width\fP\^: CARD16 +.br +\fIsibling\fP\^: WINDOW or +.PN None +.br +\fIstack-mode\fP\^: +.Pn { Above , +.PN Below , +.PN TopIf , +.PN BottomIf , +.PN Opposite } +.br +\fIvalue-mask\fP\^: BITMASK +.in -.2i +.eM +.LP +This event is reported to the client selecting +.PN SubstructureRedirect +on the parent and is generated when a +.PN ConfigureWindow +request is issued on the window by some other client. +The value-mask indicates which components were specified in the request. +The value-mask and the corresponding values are reported as given +in the request. +The remaining values are filled in from the current geometry of the window, +except in the case of sibling and stack-mode, +which are reported as +.PN None +and +.PN Above +(respectively) if not given in the request. +.sp +.LP +.sM +.IN "CirculateNotify" "" "@DEF@" +.PN CirculateNotify +.in +.2i +.LP +\fIevent\fP, \fIwindow\fP\^: WINDOW +.br +\fIplace\fP\^: +.Pn { Top , +.PN Bottom } +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN StructureNotify +on the window and to clients selecting +.PN SubstructureNotify +on the parent. +It is generated when the window is actually restacked from a +.PN CirculateWindow +request. +The event is the window on which the event was generated, +and the window is the window that is restacked. +If place is +.PN Top , +the window is now on top of all siblings. +Otherwise, it is below all siblings. +.sp +.LP +.sM +.IN "CirculateRequest" "" "@DEF@" +.PN CirculateRequest +.in +.2i +.LP +\fIparent\fP, \fIwindow\fP\^: WINDOW +.br +\fIplace\fP: +.Pn { Top , +.PN Bottom } +.in -.2i +.eM +.LP +This event is reported to the client selecting +.PN SubstructureRedirect +on the parent and is generated when a +.PN CirculateWindow +request is issued on the parent and a window actually needs to be restacked. +The window specifies the window to be restacked, +and the place specifies what the new position in the stacking order should be. +.sp +.LP +.sM +.IN "PropertyNotify" "" "@DEF@" +.PN PropertyNotify +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIatom\fP\^: ATOM +.br +\fIstate\fP\^: +.Pn { NewValue , +.PN Deleted } +.br +\fItime\fP\^: TIMESTAMP +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN PropertyChange +on the window and is generated with state +.PN NewValue +when a property of the window is changed using +.PN ChangeProperty +or +.PN RotateProperties , +even when adding zero-length data using +.PN ChangeProperty +and when replacing all or part of a property with identical data using +.PN ChangeProperty +or +.PN RotateProperties . +It is generated with state +.PN Deleted +when a property of the +window is deleted using request +.PN DeleteProperty +or +.PN GetProperty . +The timestamp indicates the server time when the property was changed. +.sp +.LP +.sM +.IN "SelectionClear" "" "@DEF@" +.PN SelectionClear +.in +.2i +.LP +\fIowner\fP\^: WINDOW +.br +\fIselection\fP\^: ATOM +.br +\fItime\fP\^: TIMESTAMP +.in -.2i +.eM +.LP +This event is reported to the current owner of a selection +and is generated when a new owner is being defined by means of +.PN SetSelectionOwner . +The timestamp is the last-change time recorded for the selection. +The owner argument is the window that was specified by the current owner in its +.PN SetSelectionOwner +request. +.sp +.LP +.sM +.IN "SelectionRequest" "" "@DEF@" +.PN SelectionRequest +.in +.2i +.LP +\fIowner\fP\^: WINDOW +.br +\fIselection\fP\^: ATOM +.br +\fItarget\fP\^: ATOM +.br +\fIproperty\fP\^: ATOM or +.PN None +.br +\fIrequestor\fP\^: WINDOW +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.in -.2i +.eM +.LP +This event is reported to the owner of a selection +and is generated when a client issues a +.PN ConvertSelection +request. +The owner argument is the window that was specified in the +.PN SetSelectionOwner +request. +The remaining arguments are as in the +.PN ConvertSelection +request. +.LP +The owner should convert the selection based on the specified target type +and send a +.PN SelectionNotify +back to the requestor. +A complete specification for using selections is given in the X Consortium +standard \fIInter-Client Communication Conventions Manual\fP. +.sp +.LP +.sM +.IN "SelectionNotify" "" "@DEF@" +.PN SelectionNotify +.in +.2i +.LP +\fIrequestor\fP\^: WINDOW +.br +\fIselection\fP, \fItarget\fP\^: ATOM +.br +\fIproperty\fP\^: ATOM or +.PN None +.br +\fItime\fP\^: TIMESTAMP or +.PN CurrentTime +.in -.2i +.eM +.LP +This event is generated by the server in response to a +.PN ConvertSelection +request when there is no owner for the selection. +When there is an owner, +it should be generated by the owner using +.PN SendEvent . +The owner of a selection should send this event to a requestor either +when a selection has been converted and stored as a property +or when a selection conversion could not be performed (indicated with property +.PN None ). +.sp +.LP +.sM +.IN "ColormapNotify" "" "@DEF@" +.PN ColormapNotify +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fIcolormap\fP\^: COLORMAP or +.PN None +.br +\fInew\fP\^: BOOL +.br +\fIstate\fP\^: +.Pn { Installed , +.PN Uninstalled } +.in -.2i +.eM +.LP +This event is reported to clients selecting +.PN ColormapChange +on the window. +It is generated with value +.PN True +for new when the colormap attribute of the window is changed +and is generated with value +.PN False +for new when the colormap of a window is installed or uninstalled. +In either case, +the state indicates whether the colormap is currently installed. +.sp +.LP +.sM +.IN "MappingNotify" "" "@DEF@" +.PN MappingNotify +.in +.2i +.LP +\fIrequest\fP: +.Pn { Modifier , +.PN Keyboard , +.PN Pointer } +.br +\fIfirst-keycode\fP, \fIcount\fP\^: CARD8 +.in -.2i +.eM +.LP +This event is sent to all clients. +There is no mechanism to express disinterest in this event. +The detail indicates the kind of change that occurred: +.PN Modifiers +for a successful +.PN SetModifierMapping , +.PN Keyboard +for a successful +.PN ChangeKeyboardMapping , +and +.PN Pointer +for a successful +.PN SetPointerMapping . +If the detail is +.PN Keyboard , +then first-keycode and count indicate the range of altered keycodes. +.sp +.LP +.sM +.IN "ClientMessage" "" "@DEF@" +.PN ClientMessage +.in +.2i +.LP +\fIwindow\fP\^: WINDOW +.br +\fItype\fP\^: ATOM +.br +\fIformat\fP\^: {8, 16, 32} +.br +\fIdata\fP\^: LISTofINT8 or LISTofINT16 or LISTofINT32 +.in -.2i +.eM +.LP +This event is only generated by clients using +.PN SendEvent . +The type specifies how the data is to be interpreted by the receiving client; +the server places no interpretation on the type or the data. +The format specifies whether the data should be viewed as a list of 8-bit, +16-bit, or 32-bit quantities, so that the server can correctly +byte-swap, as necessary. +The data always consists of either 20 8-bit values or 10 16-bit values +or 5 32-bit values, although particular message types might not make use +of all of these values. +.NH 1 +Flow Control and Concurrency +.XS +\*(SN Flow Control and Concurrency +.XE +.LP +Whenever the server is writing to a given connection, +it is permissible for the server to stop reading from that connection +(but if the writing would block, it must continue to service other connections). +The server is not required to buffer more than a single request per connection +at one time. +For a given connection to the server, +a client can block while reading from the connection +but should undertake to read (events and errors) when writing would block. +Failure on the part of a client to obey this rule could result +in a deadlocked connection, +although deadlock is probably unlikely unless either +the transport layer has very little buffering or the client attempts to +send large numbers of requests without ever reading replies or checking for +errors and events. +.LP +Whether or not a server is implemented with internal concurrency, +the overall effect must be as if individual requests are executed to completion +in some serial order, +and requests from a given connection must be executed in delivery order +(that is, the total execution order is a shuffle of the individual streams). +The execution of a request includes validating all arguments, +collecting all data for any reply, +and generating and queueing all required events. +However, +it does not include the actual transmission of the reply and the events. +In addition, the effect of any other cause that can generate multiple events +(for example, activation of a grab or pointer motion) must effectively generate +and queue all required events indivisibly with respect to all other causes +and requests. +For a request from a given client, +any events destined for that client that are caused by executing the request +must be sent to the client before any reply or error is sent. +.bp |