home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-07-30 | 241.6 KB | 10,110 lines |
- .EH ''''
- .OH ''''
- .EF ''''
- .OF ''''
- .ps 11
- .nr PS 11
- \&
- .sp 8
- .ce 4
- \s+2\fBX Window System Protocol\fP\s-2
-
- \s+1\fBMIT X Consortium Standard\fP\s-1
-
- \s+1\fBX Version 11, Release 5\fP\s-1
- .sp 6
- .ce 5
- \s-1Robert W. Scheifler
- .sp 6p
- Massachusetts Institute of Technology
- Laboratory for Computer Science\s+1
- .bp
- \&
- .ps 9
- .nr PS 9
- .sp 8
- .LP
- X Window System is a trademark of M.I.T.
- .LP
- Copyright \(co 1986, 1987, 1988
- Massachusetts Institute of Technology
- .LP
- Permission to use, copy, modify, and distribute this document
- for any purpose and without fee is hereby granted, provided
- that the above copyright notice appear in all copies and
- that both that copyright notice and this permission
- notice are retained, and that the name of M.I.T. not be used
- in advertising or publicity pertaining to this document without
- specific, written prior permission.
- M.I.T. makes no representations about the suitability of this
- document or the protocol defined in this document for any purpose.
- It is provided ``as is'' without express or implied warranty.
- .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
- Massachusetts Institute of Technology
- Laboratory for Computer Science
- .De
- .bp 1
- .EH '\fBX Protocol\fP''\fBX11, Release 5\fP'
- .OH '\fBX Protocol\fP''\fBX11, Release 5\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 ``spare'' 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
- 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 2-D 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,
- and Hebrew 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 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 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 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 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 Mod1 through 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
- Within a group, the modifier state determines which KEYSYM to use. The
- first KEYSYM is used when the Shift and Lock modifiers are off. The second
- KEYSYM is used when the Shift modifier is on, or when the Lock modifier is on
- and the second KEYSYM is uppercase alphabetic, or when the Lock modifier is on
- and is interpreted as ShiftLock. Otherwise, when the Lock modifier is on and
- is interpreted as CapsLock, the state of the Shift modifier is applied first to
- select a KEYSYM; but if that KEYSYM is lowercase alphabetic, then the
- corresponding uppercase KEYSYM is used instead.
- .LP
- The mapping between KEYCODEs and KEYSYMs is not used directly by the server;
- it is merely stored for reading and writing by clients.
- .LP
- The KEYMASK modifier named Lock is intended to be mapped to either a CapsLock
- or a ShiftLock key, but which one is left as application-specific
- and/or user-specific.
- However, it is suggested that the determination be made according to the
- associated KEYSYM(s) of the corresponding KEYCODE.
- .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 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.
- It is hoped that eventually one authorization protocol will be agreed upon.
- In the meantime,
- a server that implements a different protocol than 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: BOOL
- .br
- protocol-major-version: CARD16
- .br
- protocol-minor-version: CARD16
- .br
- length: CARD16
- .LP
- Length is the amount of additional data to follow, in units of four bytes.
- The 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 client receives the following additional data if authorization fails:
- .IP
- reason: STRING8
- .LP
- The client receives the following additional data if authorization is accepted:
- .IP
- 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 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, but this should not be necessary.
- 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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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.
- 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.
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "DestroyWindow" "" "@DEF@"
- .PN DestroyWindow
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .LP
- Errors:
- .PN Window
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "DestroySubwindows" "" "@DEF@"
- .PN DestroySubwindows
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .LP
- Errors:
- .PN Window
- .\" End marker code here
- .in -.2i
- .LP
- This request performs a
- .PN DestroyWindow
- request on all children of the window, in bottom-to-top stacking order.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .LP
- .in -.2i
- 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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "MapWindow" "" "@DEF@"
- .PN MapWindow
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .LP
- Errors:
- .PN Window
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "MapSubwindows" "" "@DEF@"
- .PN MapSubwindows
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .LP
- Errors:
- .PN Window
- .\" End marker code here
- .in -.2i
- .LP
- This request performs a
- .PN MapWindow
- request on all unmapped children of the window,
- in top-to-bottom stacking order.
- .sp
- .LP
- .\" Start marker code here
- .IN "UnmapWindow" "" "@DEF@"
- .PN UnmapWindow
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .LP
- Errors:
- .PN Window
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "UnmapSubwindows" "" "@DEF@"
- .PN UnmapSubwindows
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .LP
- Errors:
- .PN Window
- .\" End marker code here
- .in -.2i
- .LP
- This request performs an
- .PN UnmapWindow
- request on all mapped children of the window,
- in bottom-to-top stacking order.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- _
- .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
- .\" Start marker code here
- .IN "CirculateWindow" "" "@DEF@"
- .PN CirculateWindow
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .br
- \fIdirection\fP\^:
- .Pn { RaiseLowest ,
- .PN LowerHighest }
- .LP
- Errors:
- .PN Value ,
- .PN Window
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "GetAtomName" "" "@DEF@"
- .PN GetAtomName
- .in +.2i
- .LP
- \fIatom\fP\^: ATOM
- .in -.2i
- .LP
- =>
- .in +.2i
- .LP
- name: STRING8
- .LP
- Errors:
- .PN Atom
- .\" End marker code here
- .in -.2i
- .LP
- This request returns the name for the given atom.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "DeleteProperty" "" "@DEF@"
- .PN DeleteProperty
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .br
- \fIproperty\fP\^: ATOM
- .LP
- Errors:
- .PN Atom ,
- .PN Window
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "ListProperties" "" "@DEF@"
- .PN ListProperties
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .in -.2i
- .LP
- =>
- .in +.2i
- .LP
- atoms: LISTofATOM
- .LP
- Errors:
- .PN Window
- .\" End marker code here
- .in -.2i
- .LP
- This request returns the atoms of properties currently defined on the window.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "GetSelectionOwner" "" "@DEF@"
- .PN GetSelectionOwner
- .in +.2i
- .LP
- \fIselection\fP\^: ATOM
- .in -.2i
- .LP
- =>
- .in +.2i
- .LP
- owner: WINDOW or
- .PN None
- .IP
- Errors:
- .PN Atom
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "UngrabPointer" "" "@DEF@"
- .PN UngrabPointer
- .in +.2i
- .LP
- \fItime\fP\^: TIMESTAMP or
- .PN CurrentTime
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "UngrabKeyboard" "" "@DEF@"
- .PN UngrabKeyboard
- .in +.2i
- .LP
- \fItime\fP\^: TIMESTAMP or
- .PN CurrentTime
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "GrabServer" "" "@DEF@"
- .PN GrabServer
- .\" End marker code here
- .LP
- This request disables processing of requests and close-downs on all
- connections other than the one this request arrived on.
- .sp
- .LP
- .\" Start marker code here
- .IN "UngrabServer" "" "@DEF@"
- .PN UngrabServer
- .\" End marker code here
- .LP
- This request restarts processing of requests and close-downs
- on other connections.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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 }
- .\" End marker code here
- .in -.2i
- .LP
- This request returns the current focus state.
- .sp
- .LP
- .\" Start marker code here
- .IN "QueryKeymap" "" "@DEF@"
- .PN QueryKeymap
- .LP
- =>
- .in +.2i
- .LP
- keys: LISTofCARD8
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "OpenFont" "" "@DEF@"
- .PN OpenFont
- .in +.2i
- .LP
- \fIfid\fP\^: FONT
- .br
- \fIname\fP\^: STRING8
- .LP
- Errors:
- .PN Alloc ,
- .PN IDChoice ,
- .PN Name
- .\" End marker code here
- .in -.2i
- .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.
- The interpretation of characters ``?'' (octal value 77) and ``*''
- (octal value 52) in the name is not defined by the core protocol,
- but is reserved for future definition.
- 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
- .\" Start marker code here
- .IN "CloseFont" "" "@DEF@"
- .PN CloseFont
- .in +.2i
- .LP
- \fIfont\fP\^: FONT
- .LP
- Errors:
- .PN Font
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "ListFonts" "" "@DEF@"
- .PN ListFonts
- .in +.2i
- .LP
- \fIpattern\fP\^: STRING8
- .br
- \fImax-names\fP\^: CARD16
- .in -.2i
- .LP
- =>
- .in +.2i
- .LP
- names: LISTofSTRING8
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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 >
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "SetFontPath" "" "@DEF@"
- .PN SetFontPath
- .in +.2i
- .LP
- \fIpath\fP\^: LISTofSTRING8
- .LP
- Errors:
- .PN Value
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "GetFontPath" "" "@DEF@"
- .PN GetFontPath
- .LP
- =>
- .in +.2i
- .LP
- path: LISTofSTRING8
- .\" End marker code here
- .in -.2i
- .LP
- This request returns the current search path for fonts.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "FreePixmap" "" "@DEF@"
- .PN FreePixmap
- .in +.2i
- .LP
- \fIpixmap\fP\^: PIXMAP
- .LP
- Errors:
- .PN Pixmap
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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 ``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 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 2D 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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "FreeGC" "" "@DEF@"
- .PN FreeGC
- .in +.2i
- .LP
- \fIgc\fP\^: GCONTEXT
- .LP
- Errors:
- .PN GContext
- .\" End marker code here
- .in -.2i
- .LP
- This request deletes the association between the resource ID and the gcontext
- and destroys the gcontext.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- 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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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 can be fractional;
- that is, they are not truncated to discrete coordinates.
- The path should be defined by the ideal mathematical path.
- For a wide line with line-width lw,
- the bounding outlines for filling are given by the two infinitely thin paths
- consisting of all points whose perpendicular distance from the path of the
- circle/ellipse is equal to lw/2 (which may be a fractional value).
- The cap-style and join-style are applied the same as for a line corresponding
- to the tangent of the circle/ellipse at the endpoint.
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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.
- The arcs are as specified in the
- .PN PolyArc
- request.
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "FreeColormap" "" "@DEF@"
- .PN FreeColormap
- .in +.2i
- .LP
- \fIcmap\fP\^: COLORMAP
- .LP
- Errors:
- .PN Colormap
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "CopyColormapAndFree" "" "@DEF@"
- .PN CopyColormapAndFree
- .in +.2i
- .LP
- \fImid\fP, \fIsrc-cmap\fP\^: COLORMAP
- .LP
- Errors:
- .PN Alloc ,
- .PN Colormap ,
- .PN IDChoice
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "InstallColormap" "" "@DEF@"
- .PN InstallColormap
- .in +.2i
- .LP
- \fIcmap\fP\^: COLORMAP
- .LP
- Errors:
- .PN Colormap
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "UninstallColormap" "" "@DEF@"
- .PN UninstallColormap
- .in +.2i
- .LP
- \fIcmap\fP\^: COLORMAP
- .LP
- Errors:
- .PN Colormap
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "ListInstalledColormaps" "" "@DEF@"
- .PN ListInstalledColormaps
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .in -.2i
- .LP
- =>
- .in +.2i
- .LP
- cmaps: LISTofCOLORMAP
- .LP
- Errors:
- .PN Window
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" Start marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "FreeCursor" "" "@DEF@"
- .PN FreeCursor
- .in +.2i
- .LP
- \fIcursor\fP\^: CURSOR
- .LP
- Errors:
- .PN Cursor
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "ListExtensions" "" "@DEF@"
- .PN ListExtensions
- .LP
- =>
- .in +.2i
- .LP
- names: LISTofSTRING8
- .\" End marker code here
- .in -.2i
- .LP
- This request returns a list of all extensions supported by the server.
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "GetModifierMapping" "" "@DEF@"
- .PN GetModifierMapping
- .LP
- =>
- .in +.2i
- .LP
- keycodes-per-modifier: CARD8
- .br
- keycodes: LISTofKEYCODE
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "ChangeKeyboardControl" "" "@DEF@"
- .PN ChangeKeyboardControl
- .in +.2i
- .LP
- \fIvalue-mask\fP\^: BITMASK
- .br
- \fIvalue-list\fP\^: LISTofVALUE
- .LP
- Errors:
- .PN Match ,
- .PN Value
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "Bell" "" "@DEF@"
- .PN Bell
- .in +.2i
- .LP
- \fIpercent\fP\^: INT8
- .LP
- Errors:
- .PN Value
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "GetPointerMapping" "" "@DEF@"
- .PN GetPointerMapping
- .LP
- =>
- .in +.2i
- .LP
- map: LISTofCARD8
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "GetPointerControl" "" "@DEF@"
- .PN GetPointerControl
- .LP
- =>
- .in +.2i
- .LP
- acceleration-numerator, acceleration-denominator: CARD16
- .br
- threshold: CARD16
- .\" End marker code here
- .in -.2i
- .LP
- This request returns the current acceleration and threshold for the pointer.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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 }
- .\" End marker code here
- .in -.2i
- .LP
- This request returns the current screen-saver control values.
- .sp
- .LP
- .\" Start marker code here
- .IN "ForceScreenSaver" "" "@DEF@"
- .PN ForceScreenSaver
- .in +.2i
- .LP
- \fImode\fP\^:
- .Pn { Activate ,
- .PN Reset }
- .LP
- Errors:
- .PN Value
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "ChangeHosts" "" "@DEF@"
- .PN ChangeHosts
- .in +.2i
- .LP
- \fImode\fP\^:
- .Pn { Insert ,
- .PN Delete }
- .br
- \fIhost\fP: HOST
- .LP
- Errors:
- .PN Access ,
- .PN Value
- .\" End marker code here
- .in -.2i
- .LP
- This request adds or removes the specified host from the access control list.
- When the access control mechanism is enabled and a host attempts to
- establish a connection to the server,
- the host must be in this list, 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
- .\" Start marker code here
- .IN "ListHosts" "" "@DEF@"
- .PN ListHosts
- .LP
- =>
- .in +.2i
- .LP
- mode:
- .Pn { Enabled ,
- .PN Disabled }
- .br
- hosts: LISTofHOST
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "SetAccessControl" "" "@DEF@"
- .PN SetAccessControl
- .in +.2i
- .LP
- \fImode\fP\^:
- .Pn { Enable ,
- .PN Disable }
- .LP
- Errors:
- .PN Access ,
- .PN Value
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "SetCloseDownMode" "" "@DEF@"
- .PN SetCloseDownMode
- .in +.2i
- .LP
- \fImode\fP:
- .Pn { Destroy ,
- .PN RetainPermanent ,
- .PN RetainTemporary }
- .LP
- Errors:
- .PN Value
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "KillClient" "" "@DEF@"
- .PN KillClient
- .in +.2i
- .LP
- \fIresource\fP\^: CARD32 or
- .PN AllTemporary
- .LP
- Errors:
- .PN Value
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "NoOperation" "" "@DEF@"
- .PN NoOperation
- .\" End marker code here
- .LP
- This request has no arguments and no results,
- but the request length field can be nonzero,
- which 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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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 }
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "KeymapNotify" "" "@DEF@"
- .PN KeymapNotify
- .in +.2i
- .LP
- \fIkeys\fP\^: LISTofCARD8
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .LP
- This event is reported to clients selecting graphics-exposures in a graphics
- context 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
- .\" Start marker code here
- .IN "NoExposure" "" "@DEF@"
- .PN NoExposure
- .in +.2i
- .LP
- \fIdrawable\fP\^: DRAWABLE
- .br
- \fImajor-opcode\fP\^: CARD8
- .br
- \fIminor-opcode:\fP\^ CARD16
- .\" End marker code here
- .in -.2i
- .LP
- This event is reported to clients selecting graphics-exposures
- in a graphics context 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
- .\" Start marker code here
- .IN "VisibilityNotify" "" "@DEF@"
- .PN VisibilityNotify
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .br
- \fIstate\fP\^:
- .Pn { Unobscured ,
- .PN PartiallyObscured ,
- .PN FullyObscured }
- .\" End marker code here
- .in -.2i
- .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
- or 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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "DestroyNotify" "" "@DEF@"
- .PN DestroyNotify
- .in +.2i
- .LP
- \fIevent\fP, \fIwindow\fP\^: WINDOW
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "UnmapNotify" "" "@DEF@"
- .PN UnmapNotify
- .in +.2i
- .LP
- \fIevent\fP, \fIwindow\fP\^: WINDOW
- .br
- \fIfrom-configure\fP\^: BOOL
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "MapNotify" "" "@DEF@"
- .PN MapNotify
- .in +.2i
- .LP
- \fIevent\fP, \fIwindow\fP\^: WINDOW
- .br
- \fIoverride-redirect\fP\^: BOOL
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "MapRequest" "" "@DEF@"
- .PN MapRequest
- .in +.2i
- .LP
- \fIparent\fP, \fIwindow\fP\^: WINDOW
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "GravityNotify" "" "@DEF@"
- .PN GravityNotify
- .in +.2i
- .LP
- \fIevent\fP, \fIwindow\fP\^: WINDOW
- .br
- \fIx\fP, \fIy\fP\^: INT16
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "ResizeRequest" "" "@DEF@"
- .PN ResizeRequest
- .in +.2i
- .LP
- \fIwindow\fP\^: WINDOW
- .br
- \fIwidth\fP, \fIheight\fP\^: CARD16
- .\" End marker code here
- .in -.2i
- .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 inside size, not including the border.
- .sp
- .LP
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "CirculateNotify" "" "@DEF@"
- .PN CirculateNotify
- .in +.2i
- .LP
- \fIevent\fP, \fIwindow\fP\^: WINDOW
- .br
- \fIplace\fP\^:
- .Pn { Top ,
- .PN Bottom }
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "CirculateRequest" "" "@DEF@"
- .PN CirculateRequest
- .in +.2i
- .LP
- \fIparent\fP, \fIwindow\fP\^: WINDOW
- .br
- \fIplace\fP:
- .Pn { Top ,
- .PN Bottom }
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "SelectionClear" "" "@DEF@"
- .PN SelectionClear
- .in +.2i
- .LP
- \fIowner\fP\^: WINDOW
- .br
- \fIselection\fP\^: ATOM
- .br
- \fItime\fP\^: TIMESTAMP
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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 }
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .IN "MappingNotify" "" "@DEF@"
- .PN MappingNotify
- .in +.2i
- .LP
- \fIrequest\fP:
- .Pn { Modifier ,
- .PN Keyboard ,
- .PN Pointer }
- .br
- \fIfirst-keycode\fP, \fIcount\fP\^: CARD8
- .\" End marker code here
- .in -.2i
- .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
- .\" Start marker code here
- .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
- .\" End marker code here
- .in -.2i
- .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.
-