- 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
The import element allows the protocol description to reference types
declared in another extension. The content is be the basename of the
extension XML file, which is also the header attribute of the extension's
- root node. Note that types from xcb_types and xproto are automatically
- available, without explicitly importing them.
+ root node. Note that types from xproto are automatically available, without
+ explicitly importing them.
<struct name="identifier">structure contents</struct>
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>
------------------
Note: "type" attributes below refer to types defined by previous elements,
-either in the current extension, xproto, xcb_types, or one of the imported
-extensions. The type name must refer to only one possible type; if more than
-one type matches, an error occurs. To avoid this, the type may be explicitly
-prefixed with a namespace, which should be the value of the header attribute
-on the protocol description containing the desired type. The namespace and
-type are separated by a single colon. For example, to refer to the PIXMAP
-type defined in glx rather than the one defined in xcb_types, use
-type="glx:PIXMAP" rather than type="PIXMAP".
+either in the current extension, xproto, or one of the imported extensions.
+The type name must refer to only one possible type; if more than one type
+matches, an error occurs. To avoid this, the type may be explicitly prefixed
+with a namespace, which should be the value of the header attribute on the
+protocol description containing the desired type. The namespace and type are
+separated by a single colon. For example, to refer to the PIXMAP type defined
+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" />
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