xinput: struct FeedbackState: full support

[free-sw/xcb/proto] / doc / xml-xcb.txt

diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
index 7311911..d47b12c 100644 (file)
--- a/doc/xml-xcb.txt
+++ b/doc/xml-xcb.txt
@@ -184,11 +184,12 @@ 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".
 
 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, or mask
+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.
 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 enum to be used as a bitmask.
+"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" />
 
 
 <pad bytes="integer" />
 


@@ -201,6 +202,14 @@ enum; the value is restricted to one of the constants named in the enum.
   declares the data type of the field, and the name attribute gives the name
   of the field.
 
   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
 <list type="identifier" name="identifier">expression</list>
 
   This element represents an array or list of fields in a data structure.  The


@@ -235,18 +244,40 @@ enum; the value is restricted to one of the constants named in the enum.
   <switch> instead for new protocol definitions.
 
 <switch name="identifier"> switch expression
   <switch> instead for new protocol definitions.
 
 <switch name="identifier"> switch expression

-    <bitcase> bitcase expression(s), fields </bitcase> </switch>
+    <bitcase> bitcase expression(s), fields </bitcase>
+    <case> case expression(s), fields </case>
+</switch>

 
   This element represents conditional inclusion of fields. It can be viewed
 
   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.  It can be used only
-  as the last field of a structure.
+  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.

 
 

-  When a bitcase includes multiple <enumref> clauses, the contents of the
-  bitcase are only present once regardless of the number of bitcase 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>.

 
 

-  New protocol definitions should prefer to use this instead of <valueparam>.

 
 Expressions
 -----------
 
 Expressions
 -----------


@@ -291,6 +322,17 @@ Expressions
 
   This element represents a sumation of the elements of the referenced list.
 
 
   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.
 <popcount>expression</popcount>
 
   This element represents the number of bits set in the expression.