[Xcb] put description of valueparams in xml files

[Ian Osgood]

It sounds like Mark and Tom are trying to patch one of the biggest  
type-safety holes in the protocol. I heartily approve!

One thing to note: in some requests, the valueparam data items may be  
unions of types (i.e. None or a Window; some enum or a Pixmap; two  
different enums). This is true for parameters in general, not just  
valueparam items.

We should also try implementing XKB and the other remaining  
unimplemented extensions before settling on a mechanism like this.

Ian

On Jun 11, 2007, at 4:17 PM, Barton C Massey wrote:

> I'm not sure what to think, and I've been sitting on this
> for a while, so I should hit send.  Seaborn's "bitfield"
> thing seems like a good idea.  I'm not sure I quite
> understand your thing.
>
> Anybody else have any opinions?
>
> 	Bart
>
> In message <200706070016.42662.hto at arcor.de> you wrote:
>> Hello,
>>
>> Mark Seaborn wrote a protocol-tracer, see:
>> http://lists.freedesktop.org/archives/xcb/2007-May/002790.html
>>
>> To allow for readable output of the valueparam argument he introduced
>> an additional attribute "bitfield" in the valueparam:
>>
>>   <valueparam value-mask-type="CARD32"
>>               value-mask-name="value_mask"
>>               value-list-name="value_list"
>>               bitfield="window_attributes" />
>>
>> "bitfield" references another xml-list like this:
>>
>>   <bitfield name="window_attributes">
>>     <bit number="0"
>>          type="PIXMAP / 0=None 1=ParentRelative"  
>> name="back_pixmap" />
>>     <bit number="1" type="CARD32" name="back_pixel" />
>>     <bit number="2"
>>          type="PIXMAP / 0=CopyFromParent" name="border_pixmap" />
>>     ....
>>   </bitfield>
>>
>> This can be useful for other things besides tracers: validation or
>> languages with named parameters (e.g. Python). It also serves as
>> documentation.
>>
>> It has some overlap with the enumeration which describes the bits for
>> the value-mask (in this case the enum CW) though.
>>
>> I have the following two-part idea: An extra tag for valueparam- 
>> enums.
>> E.g. replace:
>>
>>   <enum name="CW">
>>     <item name="BackPixmap">      <bit>0</bit></item>
>>
>> with
>>
>>   <valueparam_enum name="CW">
>>     <item name="BackPixmap" type="PIXMAP">      <bit>0</bit></item>
>>
>> In addition to that we allow fields which have enum values to
>> reference these values. E.g.:
>>
>> <valueparam enum_ref="CW" ...>
>> <item type="CARD32" name="WinGravity" enum_ref="Gravity"/>
>> <field type="CARD8" name="image_byte_order" enum_ref="ImageOrder"/>
>> ...
>>
>> What do you think?
>>
>> Tom
>> _______________________________________________
>> Xcb mailing list
>> Xcb at lists.freedesktop.org
>> http://lists.freedesktop.org/mailman/listinfo/xcb
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb
>