X-Git-Url: http://git.demorecorder.com/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fxml-xcb.txt;h=d47b12c9f7ac6dd4078d7da0bf7879cbfda55432;hb=1dabbc999755762dbb910132cbea1bef2ea34bc8;hp=51e641bfb6eae8c8305b6ce551674769bbcbd643;hpb=28875a37f5bdc933476bb06950e15f4443138c8e;p=free-sw%2Fxcb%2Fproto diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt index 51e641b..d47b12c 100644 --- a/doc/xml-xcb.txt +++ b/doc/xml-xcb.txt @@ -1,53 +1,25 @@ - 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 . 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 +. 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 - and the EXSLT node-set extension -. The XCB build -system currently uses xsltproc. You can get xsltproc through your -distribution's packaging system, or from . 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 . Protocol Description Format @@ -86,8 +58,8 @@ Top-Level Elements 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. structure contents @@ -156,7 +128,8 @@ Top-Level Elements requests of the same type may be combined into a single request without affecting the semantics of the requests. - + structure contents @@ -170,6 +143,11 @@ Top-Level Elements 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. + structure contents @@ -197,14 +175,21 @@ Structure Contents ------------------ 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. @@ -217,6 +202,14 @@ type="glx:PIXMAP" rather than type="PIXMAP". declares the data type of the field, and the name attribute gives the name of the field. + + + 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. + expression This element represents an array or list of fields in a data structure. The @@ -247,7 +240,43 @@ type="glx:PIXMAP" rather than type="PIXMAP". 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 + instead for new protocol definitions. + + switch expression + bitcase expression(s), fields + case expression(s), fields + + + This element represents conditional inclusion of fields. It can be viewed + as sequence of multiple ifs: + + : + if ( switch expression & bitcase expression ) is non-zero, + bitcase fields are included in structure. + + : + 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 clauses, the contents + of the bitcase or case are only present once regardless of the number of + bitcase or case expressions that match. + + inside can only refer to an enum's members. + inside can only refer to an enum's members. + + A switch may contain multiple or elements. + Usually it will only contain elements + or only contain elements. + That is, mixing of and usually doesn't make any sense. + + The same value may appear in multiple or elements. + + New protocol definitions should prefer to use this instead of + and instead of . Expressions @@ -259,9 +288,9 @@ Expressions expression expression The op element represents an operator, with the op attribute specifying - which operator. The supported operations are *, /, &, and <<, and - their semantics are identical to the corresponding operators in C. The two - operand expressions may be fieldref, value, or op elements. + which operator. The supported operations are +, -, *, /, &, and + <<, and their semantics are identical to the corresponding operators + in C. The two operand expressions may be other expression elements. identifier @@ -273,3 +302,73 @@ Expressions The value element represents a literal integer value in an expression. The integer may be expressed in decimal or hexadecimal. + +integer + + The bit element represents a literal bitmask value in an expression. + The integer must be in the range 0..31, expanding to (1<enum item identifier + + This element represents a reference to item of enum. + +expression + + 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. + + + + This element represents a sumation of the elements of the referenced list. + +expression + + 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. + +expression + + 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 element. The element can contain the following + elements: + +brief description + + 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. + + + + The full description. Use `` to highlight words, such as "Draws + `points_len`-1 lines between each pair of points…" + + + + Example C code illustrating the usage of the particular request, reply or + event. + +field description + + The full description for the specified field. Depending on the context, this + is either a request parameter or a reply/event datastructure field. + +error description + + The full description for an error which can occur due to this request. + + + + A reference to another relevant program, function, request or event.