From b02b7f8dcf92f2b0e7c1edc91f48d2e388d4b8c3 Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Sun, 27 Nov 2011 10:35:06 +0000 Subject: [PATCH] xproto: add doc tags, xcbgen: handle doc tags Signed-off-by: Julien Danjou --- doc/xml-xcb.txt | 35 + src/xcb.xsd | 63 +- src/xproto.xml | 2796 +++++++++++++++++++++++++++++++++++++++++++++- xcbgen/expr.py | 4 +- xcbgen/xtypes.py | 72 +- 5 files changed, 2950 insertions(+), 20 deletions(-) diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt index 3c6a155..7057727 100644 --- a/doc/xml-xcb.txt +++ b/doc/xml-xcb.txt @@ -284,3 +284,38 @@ Expressions 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. diff --git a/src/xcb.xsd b/src/xcb.xsd index 7fdf125..cfa90c9 100644 --- a/src/xcb.xsd +++ b/src/xcb.xsd @@ -201,7 +201,9 @@ authorization from the authors. - + + + @@ -225,6 +227,59 @@ authorization from the authors. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -248,9 +303,11 @@ authorization from the authors. + + @@ -262,6 +319,9 @@ authorization from the authors. + + + @@ -296,6 +356,7 @@ authorization from the authors. + diff --git a/src/xproto.xml b/src/xproto.xml index 42a6852..bf4dcbf 100644 --- a/src/xproto.xml +++ b/src/xproto.xml @@ -307,6 +307,44 @@ authorization from the authors. + + a key was pressed/released + + + + + + + + + + + + @@ -333,6 +371,44 @@ authorization from the authors. + + a mouse button was pressed/released + + + + + + + + + + + + @@ -356,6 +432,44 @@ authorization from the authors. + + a key was pressed + + + + + + + + + + + + @@ -389,6 +503,34 @@ authorization from the authors. + + the pointer is in a different window + + + + + + + + + @@ -398,6 +540,16 @@ authorization from the authors. + + NOT YET DOCUMENTED + + + + + @@ -415,6 +567,32 @@ authorization from the authors. + + NOT YET DOCUMENTED + + + + + + + @@ -468,6 +646,17 @@ authorization from the authors. + + a window is destroyed + + + + @@ -476,6 +665,21 @@ authorization from the authors. + + a window is unmapped + + + + + @@ -484,12 +688,36 @@ authorization from the authors. + + a window was mapped + + + + + + + window wants to be mapped + + + + @@ -515,6 +743,42 @@ authorization from the authors. + + NOT YET DOCUMENTED + + + + + + + + + + + @@ -548,6 +812,14 @@ authorization from the authors. 0 1 + + + + @@ -557,6 +829,19 @@ authorization from the authors. + + NOT YET DOCUMENTED + + + + + + @@ -573,6 +858,21 @@ authorization from the authors. + + a window property changed + + + + + + + @@ -681,6 +981,14 @@ authorization from the authors. 0 1 + + + + @@ -694,6 +1002,22 @@ authorization from the authors. + + the colormap for some window changed + + + + + + + @@ -709,6 +1033,26 @@ authorization from the authors. + + NOT YET DOCUMENTED + + + + + + @@ -723,6 +1067,17 @@ authorization from the authors. + + keyboard mapping changed + + + + + @@ -791,6 +1146,106 @@ authorization from the authors. 12 13 14 + + + + + + + + + + + + + + + + + @@ -827,6 +1282,79 @@ authorization from the authors. + + Creates a window + + + + + + + + + + + + + + + + + + + + + + + @@ -835,6 +1363,43 @@ authorization from the authors. + + change window attributes + + + + + + + + + + + + + @@ -863,12 +1428,79 @@ authorization from the authors. + + + + + + + + + + + + + + + + + + + Gets window attributes + + + + + + + + Destroys a window + + + + + + + @@ -884,6 +1516,28 @@ authorization from the authors. + + Changes a client's save set + + + + + + + + @@ -892,11 +1546,78 @@ authorization from the authors. + + Reparents a window + + + + + + + + + + + + + Makes a window visible + + + + + + + @@ -907,6 +1628,25 @@ authorization from the authors. + + Makes a window invisible + + + + + + + @@ -940,6 +1680,55 @@ authorization from the authors. + + Configures window attributes + + + + + + + + + + + @@ -950,6 +1739,27 @@ authorization from the authors. + + Change window stacking order + + + + + + + @@ -964,7 +1774,67 @@ authorization from the authors. + + + + + + + + + + + Get current window geometry + + x, reply->y); + } + free(reply); +} + ]]> + + + + + @@ -979,7 +1849,51 @@ authorization from the authors. children_len + + + + + + + query the window tree + + root); + printf("parent = 0x%08x\\n", reply->parent); + + xcb_window_t *children = xcb_query_tree_children(reply); + for (int i = 0; i < xcb_query_tree_children_length(reply); i++) + printf("child window = 0x%08x\\n", children[i]); + + free(reply); + } +} + ]]> + + + @@ -993,6 +1907,53 @@ authorization from the authors. + + Get atom identifier by name + + atom); + free(reply); + } +} + ]]> + + + + + + + + + @@ -1012,6 +1973,21 @@ authorization from the authors. 0 1 2 + + + + + @@ -1031,6 +2007,71 @@ authorization from the authors. 8 + + Changes a window property + + + + + + + + + + + + + + + + + + @@ -1057,15 +2098,110 @@ authorization from the authors. - - value_len - - format - 8 - - + + value_len + + format + 8 + + + + + + + + + + Gets a window property + + + + + + + + + + + + + + @@ -1086,6 +2222,38 @@ authorization from the authors. + + Sets the owner of a selection + + + + + + + + @@ -1094,7 +2262,27 @@ authorization from the authors. + + + + + Gets the owner of a selection + + + + + @@ -1116,11 +2304,97 @@ authorization from the authors. 32 + + send an event + + event = window; + event->window = window; + event->response_type = XCB_CONFIGURE_NOTIFY; + + event->x = 0; + event->y = 0; + event->width = 800; + event->height = 600; + + event->border_width = 0; + event->above_sibling = XCB_NONE; + event->override_redirect = false; + + xcb_send_event(conn, false, window, XCB_EVENT_MASK_STRUCTURE_NOTIFY, + (char*)event); + xcb_flush(conn); + free(event); +} + ]]> + + + + + + + + 0 1 + + + + @@ -1147,11 +2421,118 @@ authorization from the authors. + + Grab the pointer + + root, /* grab the root window */ + XCB_NONE, /* which events to let through */ + XCB_GRAB_MODE_ASYNC, /* pointer events should continue as normal */ + XCB_GRAB_MODE_ASYNC, /* keyboard mode */ + XCB_NONE, /* confine_to = in which window should the cursor stay */ + cursor, /* we change the cursor to whatever the user wanted */ + XCB_CURRENT_TIME + ); + + if ((reply = xcb_grab_pointer_reply(conn, cookie, NULL))) { + if (reply->status == XCB_GRAB_STATUS_SUCCESS) + printf("successfully grabbed the pointer\\n"); + free(preply); + } +} + ]]> + + + + + + + + + + + + + + + + release the pointer + + + + + + + + + @@ -1161,6 +2542,26 @@ authorization from the authors. 3 4 5 + + + + + + + + @@ -1174,6 +2575,92 @@ authorization from the authors. + + Grab pointer button(s) + + + + + + + + + + + + + + + + @@ -1201,6 +2688,70 @@ authorization from the authors. + + Grab the keyboard + + root, /* grab the root window */ + XCB_CURRENT_TIME, + XCB_GRAB_MODE_ASYNC, /* process events as normal, do not require sync */ + XCB_GRAB_MODE_ASYNC + ); + + if ((reply = xcb_grab_keyboard_reply(conn, cookie, NULL))) { + if (reply->status == XCB_GRAB_STATUS_SUCCESS) + printf("successfully grabbed the keyboard\\n"); + + free(reply); + } +} + ]]> + + + + + + + + + + @@ -1221,6 +2772,78 @@ authorization from the authors. + + Grab keyboard key(s) + + + + + + + + + + + + + + @@ -1228,6 +2851,35 @@ authorization from the authors. + + release a key combination + + + + + + + + + @@ -1239,11 +2891,106 @@ authorization from the authors. 5 6 7 + + + + + + + + + + + + release queued events + + + + + + @@ -1263,7 +3010,56 @@ authorization from the authors. + + + + + + + + + + + + get pointer coordinates + + + + @@ -1311,6 +3107,38 @@ authorization from the authors. + + move mouse pointer + + + + + + @@ -1319,12 +3147,71 @@ authorization from the authors. 1 2 3 + + + + + + + + Sets input focus + + + + + + + + + + + @@ -1349,6 +3236,28 @@ authorization from the authors. name_len + + opens a font + + + + + + + @@ -1401,7 +3310,48 @@ authorization from the authors. char_infos_len + + + + + + + + + + + + + + + query font metrics + + + + @@ -1420,6 +3370,47 @@ authorization from the authors. + + get text extents + + + + + + + @@ -1443,7 +3434,31 @@ authorization from the authors. names_len + + + + + get matching font names + + + + + @@ -1476,7 +3491,66 @@ authorization from the authors. name_len + + + + + + + + + + + + + + + + + get matching font names and information + + + + + + @@ -1505,11 +3579,55 @@ authorization from the authors. + + Creates a pixmap + + + + + + + + + + + + + Destroys a pixmap + + + + @@ -1536,6 +3654,154 @@ authorization from the authors. 20 21 22 + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -1606,6 +3872,39 @@ authorization from the authors. + + Creates a graphics context + + + + + + + + + + + @@ -1614,6 +3913,62 @@ authorization from the authors. + + change graphics context components + + + + + + + + + + + + + @@ -1651,6 +4006,16 @@ authorization from the authors. + + Destroys a graphics context + + + + @@ -1673,6 +4038,48 @@ authorization from the authors. + + copy areas + + + + + + + + + + + + + + @@ -1692,6 +4099,14 @@ authorization from the authors. 0 1 + + + + @@ -1707,6 +4122,56 @@ authorization from the authors. + + draw lines + + + + + + + + + + + + + @@ -1721,6 +4186,43 @@ authorization from the authors. + + draw lines + + + + + + + + + @@ -1763,6 +4265,42 @@ authorization from the authors. + + Fills rectangles + + + + + + + + + @@ -1841,6 +4379,52 @@ authorization from the authors. string_len + + Draws text + + + + + + + + + + + + @@ -1852,6 +4436,53 @@ authorization from the authors. string_len + + Draws text + + + + + + + + + + + + @@ -1915,6 +4546,31 @@ authorization from the authors. + + Allocate a color + + + + + + + @@ -2092,11 +4748,82 @@ authorization from the authors. + + create cursor + + + + + + + + + + + + + + + + + + + Deletes a cursor + + + + + @@ -2141,7 +4868,44 @@ authorization from the authors. + + + + + + + + check if extension is present + + + + + + @@ -2349,6 +5113,24 @@ authorization from the authors. + + kills a client + + + + + + diff --git a/xcbgen/expr.py b/xcbgen/expr.py index 274c290..4f8af6f 100644 --- a/xcbgen/expr.py +++ b/xcbgen/expr.py @@ -11,11 +11,13 @@ class Field(object): visible is true iff the field should be in the request API. wire is true iff the field should be in the request structure. auto is true iff the field is on the wire but not in the request API (e.g. opcode) + enum is the enum name this field refers to, if any. ''' - def __init__(self, type, field_type, field_name, visible, wire, auto): + def __init__(self, type, field_type, field_name, visible, wire, auto, enum=None): self.type = type self.field_type = field_type self.field_name = field_name + self.enum = enum self.visible = visible self.wire = wire self.auto = auto diff --git a/xcbgen/xtypes.py b/xcbgen/xtypes.py index c789158..f6d4634 100644 --- a/xcbgen/xtypes.py +++ b/xcbgen/xtypes.py @@ -56,7 +56,7 @@ class Type(object): ''' raise Exception('abstract fixed_size method not overridden!') - def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto): + def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None): ''' Default method for making a data type a member of a structure. Extend this if the data type needs to add an additional length field or something. @@ -65,7 +65,7 @@ class Type(object): complex_type is the structure object. see Field for the meaning of the other parameters. ''' - new_field = Field(self, field_type, field_name, visible, wire, auto) + new_field = Field(self, field_type, field_name, visible, wire, auto, enum) # We dump the _placeholder_byte if any fields are added. for (idx, field) in enumerate(complex_type.fields): @@ -123,7 +123,11 @@ class Enum(SimpleType): SimpleType.__init__(self, name, 4) self.values = [] self.bits = [] + self.doc = None for item in list(elt): + if item.tag == 'doc': + self.doc = Doc(name, item) + # First check if we're using a default value if len(list(item)) == 0: self.values.append((item.get('name'), '')) @@ -170,7 +174,7 @@ class ListType(Type): self.size = member.size if member.fixed_size() else None self.nmemb = self.expr.nmemb if self.expr.fixed_size() else None - def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto): + def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None): if not self.fixed_size(): # We need a length field. # Ask our Expression object for it's name, type, and whether it's on the wire. @@ -189,10 +193,10 @@ class ListType(Type): if needlen: type = module.get_type(lenfid) lenfield_type = module.get_type_name(lenfid) - type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False) + type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False, enum) # Add ourself to the structure by calling our original method. - Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto) + Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum) def resolve(self, module): if self.resolved: @@ -278,6 +282,7 @@ class ComplexType(Type): if self.resolved: return pads = 0 + enum = None # Resolve all of our field datatypes. for child in list(self.elt): @@ -289,6 +294,7 @@ class ComplexType(Type): visible = False elif child.tag == 'field': field_name = child.get('name') + enum = child.get('enum') fkey = child.get('type') type = module.get_type(fkey) visible = True @@ -323,7 +329,7 @@ class ComplexType(Type): # Get the full type name for the field field_type = module.get_type_name(fkey) # Add the field to ourself - type.make_member_of(module, self, field_type, field_name, visible, True, False) + type.make_member_of(module, self, field_type, field_name, visible, True, False, enum) # Recursively resolve the type (could be another structure, list) type.resolve(module) @@ -413,7 +419,7 @@ class SwitchType(ComplexType): self.calc_size() # Figure out how big we are self.resolved = True - def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto): + def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None): if not self.fixed_size(): # We need a length field. # Ask our Expression object for it's name, type, and whether it's on the wire. @@ -432,10 +438,10 @@ class SwitchType(ComplexType): if needlen: type = module.get_type(lenfid) lenfield_type = module.get_type_name(lenfid) - type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False) + type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False, enum) # Add ourself to the structure by calling our original method. - Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto) + Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum) # size for switch can only be calculated at runtime def calc_size(self): @@ -483,7 +489,7 @@ class BitcaseType(ComplexType): self.parents = list(parent) self.is_bitcase = True - def make_member_of(self, module, switch_type, field_type, field_name, visible, wire, auto): + def make_member_of(self, module, switch_type, field_type, field_name, visible, wire, auto, enum=None): ''' register BitcaseType with the corresponding SwitchType @@ -491,7 +497,7 @@ class BitcaseType(ComplexType): complex_type is the structure object. see Field for the meaning of the other parameters. ''' - new_field = Field(self, field_type, field_name, visible, wire, auto) + new_field = Field(self, field_type, field_name, visible, wire, auto, enum) # We dump the _placeholder_byte if any bitcases are added. for (idx, field) in enumerate(switch_type.bitcases): @@ -518,6 +524,11 @@ class Reply(ComplexType): def __init__(self, name, elt): ComplexType.__init__(self, name, elt) self.is_reply = True + self.doc = None + + for child in list(elt): + if child.tag == 'doc': + self.doc = Doc(name, child) def resolve(self, module): if self.resolved: @@ -541,11 +552,14 @@ class Request(ComplexType): def __init__(self, name, elt): ComplexType.__init__(self, name, elt) self.reply = None + self.doc = None self.opcode = elt.get('opcode') for child in list(elt): if child.tag == 'reply': self.reply = Reply(name, child) + if child.tag == 'doc': + self.doc = Doc(name, child) def resolve(self, module): if self.resolved: @@ -581,6 +595,11 @@ class Event(ComplexType): tmp = elt.get('no-sequence-number') self.has_seq = (tmp == None or tmp.lower() == 'false' or tmp == '0') + + self.doc = None + for item in list(elt): + if item.tag == 'doc': + self.doc = Doc(name, item) def add_opcode(self, opcode, name, main): self.opcodes[name] = opcode @@ -629,4 +648,35 @@ class Error(ComplexType): out = __main__.output['error'] + +class Doc(object): + ''' + Class representing a tag. + ''' + def __init__(self, name, elt): + self.name = name + self.description = None + self.brief = 'BRIEF DESCRIPTION MISSING' + self.fields = {} + self.errors = {} + self.see = {} + self.example = None + + for child in list(elt): + text = child.text if child.text else '' + if child.tag == 'description': + self.description = text.strip() + if child.tag == 'brief': + self.brief = text.strip() + if child.tag == 'field': + self.fields[child.get('name')] = text.strip() + if child.tag == 'error': + self.errors[child.get('type')] = text.strip() + if child.tag == 'see': + self.see[child.get('name')] = child.get('type') + if child.tag == 'example': + self.example = text.strip() + + + _placeholder_byte = Field(PadType(None), tcard8.name, 'pad0', False, True, False) -- 2.34.1