- XML-XCB
+ xcb/proto
Description
===========
-XML-XCB generates C bindings to the X Window System protocol based on XML
-descriptions of the protocol. It is designed for use with XCB, the X C
-binding <http://xcb.freedesktop.org>. XML-XCB consists of:
+xcb/proto is a set of XML files describing the X Window System protocol
+It is designed for use with libxcb, the X C binding
+<http://xcb.freedesktop.org/>. xcb/proto consists of:
xcb.xsd An XML Schema defining the data format for describing the X
- protocol. Included in xcb-proto.
+ protocol.
-c-client.xsl An XSLT code generator that transforms the protocol descriptions
- into C bindings. Included in xcb.
+*.py Code generator helpers that read the protocol descriptions
+ into python structures. See libxcb for example usage.
*.xml XML descriptions of the core X protocol and many extensions.
- Included in xcb-proto.
-
-
-Dependencies
-============
-
-c-client.xsl requires an XSLT processor that supports XSLT 1.0
-<http://www.w3.org/TR/1999/REC-xslt-19991116> and the EXSLT node-set extension
-<http://www.exslt.org/exsl/functions/node-set/index.html>. The XCB build
-system currently uses xsltproc. You can get xsltproc through your
-distribution's packaging system, or from <http://xmlsoft.org/XSLT/>.
Generating C bindings
=====================
-The C bindings for the core protocol and all the currently supported
-extensions are built as part of the xcb build system. However, for the
-purposes of creating and debugging new protocol descriptions, it can be useful
-to generate the bindings directly by invoking c-client.xsl to the XML protocol
-description.
-
-You must provide several parameters to c-client.xsl:
-
-mode: header or source; specifies which part of the C bindings to generate.
-base-path: path to the core X protocol descriptions.
-extension-path: path to the extension descriptions.
-
-For example, using xsltproc, you can generate the header for a protocol
-description "protocol.xml" with the command:
-
-xsltproc --stringparam base-path /path/to/xcb-proto/src \
- --stringparam extension-path /path/to/xcb-proto/src/extensions \
- --stringparam mode header /path/to/xcb/src/c-client.xsl protocol.xml
+See libxcb <http://cgit.freedesktop.org/xcb/libxcb/>.
Protocol Description Format
requests of the same type may be combined into a single request without
affecting the semantics of the requests.
-<event name="identifier" number="integer" [no-sequence-number="true"]>
+<event name="identifier" number="integer"
+ [[no-sequence-number="true"] | [xge="true"]]>
structure contents
</event>
include a sequence number. This is a special-case for the KeymapNotify
event in the core protocol, and should not be used in any other event.
+ If the optional xge attribute is true, the event is an X Generic Event and
+ will be treated as such.
+
+ The no-sequence-number and xge attribute can not be combined.
+
<error name="identifier" number="integer">
structure contents
</error>
in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
than type="PIXMAP".
+Note: Most of the below may optionally contain an enum, altenum, mask or altmask
+attribute, which follows the above rules for "type". "enum" is an exhaustive
+enum; the value is restricted to one of the constants named in the enum.
+"altenum" may be one of the values contained in the enum, but it need not be.
+"mask" refers to an exhaustive enum to be used as a bitmask.
+"altmask" may be a mask from the referred enum, but it need not be.
+
<pad bytes="integer" />
This element declares some padding in a data structure. The bytes
declares the data type of the field, and the name attribute gives the name
of the field.
+<fd name="identifier" />
+
+ This element represents a file descriptor field passed with the request. The
+ name attribute gives the name of the field.
+
+ While ordinary fields are encoded as part of the request, file descriptor
+ fields are generally passed via an out-of-band mechanism.
+
<list type="identifier" name="identifier">expression</list>
This element represents an array or list of fields in a data structure. The
defining the set of values included, and a list containing these values.
value-mask-type gives the type of the bitmask; this must be CARD16 or
CARD32. value-mask-name gives the field name of the bitmask, and
- value-list-name gives the field name of the list of values.
+ value-list-name gives the field name of the list of values. Please use
+ <switch> instead for new protocol definitions.
+
+<switch name="identifier"> switch expression
+ <bitcase> bitcase expression(s), fields </bitcase>
+ <case> case expression(s), fields </case>
+</switch>
+
+ This element represents conditional inclusion of fields. It can be viewed
+ as sequence of multiple ifs:
+
+ <bitcase>:
+ if ( switch expression & bitcase expression ) is non-zero,
+ bitcase fields are included in structure.
+
+ <case>:
+ if ( switch expression == case expression ) is true,
+ then case fields are included in structure.
+
+ It can be used only as the last field of a structure.
+
+ When a bitcase or case includes multiple <enumref> clauses, the contents
+ of the bitcase or case are only present once regardless of the number of
+ bitcase or case expressions that match.
+
+ <enumref> inside <bitcase> can only refer to an enum's <bit> members.
+ <enumref> inside <case> can only refer to an enum's <value> members.
+
+ A switch may contain multiple <bitcase> or <case> elements.
+ Usually it will only contain <bitcase> elements
+ or only contain <case> elements.
+ That is, mixing of <case> and <bitcase> usually doesn't make any sense.
+
+ The same value may appear in multiple <case> or <bitcase> elements.
+
+ New protocol definitions should prefer to use this instead of <valueparam>
+ and instead of <union>.
Expressions
The bit element represents a literal bitmask value in an expression.
The integer must be in the range 0..31, expanding to (1<<n) in C.
+
+<enumref ref="identifier">enum item identifier</enumref>
+
+ This element represents a reference to item of enum.
+
+<unop op="operator">expression</unop>
+
+ This element represents a unary operator, with the op attribute specifying
+ which operator. The only supported operation so far is ~, and its semantic
+ is identical to the corresponding operator in C.
+
+<sumof ref="identifier" />
+
+ This element represents a sumation of the elements of the referenced list.
+
+<sumof ref="identifier" >expression</sumof>
+
+ The expression is evaluated for each element of the referenced list,
+ in the context of this element.
+ This sumof element then represents a sumation of the results of these
+ evaluations.
+
+ expression will usually be a fieldref which references a field of
+ a list-element or an expression containing a fieldref,
+ such as popcount of a fieldref.
+
+<popcount>expression</popcount>
+
+ This element represents the number of bits set in the expression.
+
+Documentation
+-------------
+
+ Documentation for each request, reply or event is stored in the appropriate
+ element using a <doc> element. The <doc> element can contain the following
+ elements:
+
+<brief>brief description</brief>
+
+ A short description of the request, reply or event. For example "makes a
+ window visible" for MapWindow. This will end up in the manpage NAME section
+ and in the doxygen @brief description.
+
+<description><![CDATA[longer description]]></description>
+
+ The full description. Use `` to highlight words, such as "Draws
+ `points_len`-1 lines between each pair of points…"
+
+<example><![CDATA[example code]]</description>
+
+ Example C code illustrating the usage of the particular request, reply or
+ event.
+
+<field name="name">field description</field>
+
+ The full description for the specified field. Depending on the context, this
+ is either a request parameter or a reply/event datastructure field.
+
+<error type="type">error description</field>
+
+ The full description for an error which can occur due to this request.
+
+<see type="request" name="name" />
+
+ A reference to another relevant program, function, request or event.
projects / free-sw / xcb / proto / blobdiff