aboutsummaryrefslogtreecommitdiff
path: root/libxcb
diff options
context:
space:
mode:
Diffstat (limited to 'libxcb')
-rw-r--r--libxcb/src/Makefile.am10
-rw-r--r--libxcb/src/c_client.py600
-rw-r--r--libxcb/src/man/xcb-examples.359
-rw-r--r--libxcb/src/man/xcb-requests.3165
-rw-r--r--libxcb/xcb-proto/doc/xml-xcb.txt35
-rw-r--r--libxcb/xcb-proto/src/xcb.xsd689
-rw-r--r--libxcb/xcb-proto/src/xproto.xml2796
-rw-r--r--libxcb/xcb-proto/xcbgen/expr.py256
-rw-r--r--libxcb/xcb-proto/xcbgen/xtypes.py72
9 files changed, 4217 insertions, 465 deletions
diff --git a/libxcb/src/Makefile.am b/libxcb/src/Makefile.am
index 950de5c14..fed691447 100644
--- a/libxcb/src/Makefile.am
+++ b/libxcb/src/Makefile.am
@@ -225,8 +225,14 @@ endif
nodist_xcbinclude_HEADERS = $(EXTHEADERS)
noinst_HEADERS = xcbint.h
-BUILT_SOURCES = $(EXTSOURCES)
-CLEANFILES = $(EXTSOURCES) $(EXTHEADERS)
+STATIC_MANS = man/xcb-examples.3 man/xcb-requests.3
+BUILT_MANS = man/xcb_*.3
+man_MANS = = $(STATIC_MANS) $(BUILT_MANS)
+
+BUILT_SOURCES = $(EXTSOURCES) $(BUILT_MANS)
+CLEANFILES = $(EXTSOURCES) $(EXTHEADERS) $(BUILT_MANS)
$(EXTSOURCES): c_client.py
$(PYTHON) $(srcdir)/c_client.py -p $(XCBPROTO_XCBPYTHONDIR) $(XCBPROTO_XCBINCLUDEDIR)/$(@:.c=.xml)
+
+$(man_MANS): $(EXTSOURCES)
diff --git a/libxcb/src/c_client.py b/libxcb/src/c_client.py
index 0f9974899..cbd235659 100644
--- a/libxcb/src/c_client.py
+++ b/libxcb/src/c_client.py
@@ -3,7 +3,9 @@ from xml.etree.cElementTree import *
from os.path import basename
from functools import reduce
import getopt
+import os
import sys
+import time
import re
# Jump to the bottom of this file for the main routine
@@ -31,6 +33,11 @@ finished_serializers = []
finished_sizeof = []
finished_switch = []
+# keeps enum objects so that we can refer to them when generating manpages.
+enums = {}
+
+manpaths = False
+
def _h(fmt, *args):
'''
Writes the given line to the header file.
@@ -248,6 +255,8 @@ def c_enum(self, name):
Exported function that handles enum declarations.
'''
+ enums[name] = self
+
tname = _t(name)
if namecount[tname] > 1:
tname = _t(name + ('enum',))
@@ -262,7 +271,10 @@ def c_enum(self, name):
count = count - 1
equals = ' = ' if eval != '' else ''
comma = ',' if count > 0 else ''
- _h(' %s%s%s%s', _n(name + (enam,)).upper(), equals, eval, comma)
+ doc = ''
+ if hasattr(self, "doc") and self.doc and enam in self.doc.fields:
+ doc = '\n/**< %s */\n' % self.doc.fields[enam]
+ _h(' %s%s%s%s%s', _n(name + (enam,)).upper(), equals, eval, comma, doc)
_h('} %s;', tname)
@@ -1879,11 +1891,58 @@ def _c_request_helper(self, name, cookie_type, void, regular, aux=False):
_c_setlevel(1)
_h('')
_h('/**')
- _h(' * Delivers a request to the X server')
+ if hasattr(self, "doc") and self.doc:
+ if self.doc.brief:
+ _h(' * @brief ' + self.doc.brief)
+ else:
+ _h(' * No brief doc yet')
+
+ _h(' *')
_h(' * @param c The connection')
+ param_names = [f.c_field_name for f in param_fields]
+ if hasattr(self, "doc") and self.doc:
+ for field in param_fields:
+ # XXX: hard-coded until we fix xproto.xml
+ base_func_name = self.c_request_name if not aux else self.c_aux_name
+ if base_func_name == 'xcb_change_gc' and field.c_field_name == 'value_mask':
+ field.enum = 'GC'
+ elif base_func_name == 'xcb_change_window_attributes' and field.c_field_name == 'value_mask':
+ field.enum = 'CW'
+ elif base_func_name == 'xcb_create_window' and field.c_field_name == 'value_mask':
+ field.enum = 'CW'
+ if field.enum:
+ # XXX: why the 'xcb' prefix?
+ key = ('xcb', field.enum)
+
+ tname = _t(key)
+ if namecount[tname] > 1:
+ tname = _t(key + ('enum',))
+ _h(' * @param %s A bitmask of #%s values.' % (field.c_field_name, tname))
+
+ if self.doc and field.field_name in self.doc.fields:
+ desc = self.doc.fields[field.field_name]
+ for name in param_names:
+ desc = desc.replace('`%s`' % name, '\\a %s' % (name))
+ desc = desc.split("\n")
+ desc = [line if line != '' else '\\n' for line in desc]
+ _h(' * @param %s %s' % (field.c_field_name, "\n * ".join(desc)))
+ # If there is no documentation yet, we simply don't generate an
+ # @param tag. Doxygen will then warn about missing documentation.
+
_h(' * @return A cookie')
_h(' *')
- _h(' * Delivers a request to the X server.')
+
+ if hasattr(self, "doc") and self.doc:
+ if self.doc.description:
+ desc = self.doc.description
+ for name in param_names:
+ desc = desc.replace('`%s`' % name, '\\a %s' % (name))
+ desc = desc.split("\n")
+ _h(' * ' + "\n * ".join(desc))
+ else:
+ _h(' * No description yet')
+ else:
+ _h(' * Delivers a request to the X server.')
_h(' * ')
if checked:
_h(' * This form can be used only if the request will not cause')
@@ -2202,6 +2261,523 @@ def _c_cookie(self, name):
_h(' unsigned int sequence; /**< */')
_h('} %s;', self.c_cookie_type)
+def _man_request(self, name, cookie_type, void, aux):
+ param_fields = [f for f in self.fields if f.visible]
+
+ func_name = self.c_request_name if not aux else self.c_aux_name
+
+ def create_link(linkname):
+ name = 'man/%s.3' % linkname
+ if manpaths:
+ sys.stdout.write(name)
+ f = open(name, 'w')
+ f.write('.so man3/%s.3' % func_name)
+ f.close()
+
+ if manpaths:
+ sys.stdout.write('man/%s.3 ' % func_name)
+ # Our CWD is src/, so this will end up in src/man/
+ f = open('man/%s.3' % func_name, 'w')
+ f.write('.TH %s 3 %s "XCB" "XCB Requests"\n' % (func_name, today))
+ # Left-adjust instead of adjusting to both sides
+ f.write('.ad l\n')
+ f.write('.SH NAME\n')
+ brief = self.doc.brief if hasattr(self, "doc") and self.doc else ''
+ f.write('%s \\- %s\n' % (func_name, brief))
+ f.write('.SH SYNOPSIS\n')
+ # Don't split words (hyphenate)
+ f.write('.hy 0\n')
+ f.write('.B #include <xcb/%s.h>\n' % _ns.header)
+
+ # function prototypes
+ prototype = ''
+ count = len(param_fields)
+ for field in param_fields:
+ count = count - 1
+ c_field_const_type = field.c_field_const_type
+ c_pointer = field.c_pointer
+ if c_pointer == ' ':
+ c_pointer = ''
+ if field.type.need_serialize and not aux:
+ c_field_const_type = "const void"
+ c_pointer = '*'
+ comma = ', ' if count else ');'
+ prototype += '%s\\ %s\\fI%s\\fP%s' % (c_field_const_type, c_pointer, field.c_field_name, comma)
+
+ f.write('.SS Request function\n')
+ f.write('.HP\n')
+ base_func_name = self.c_request_name if not aux else self.c_aux_name
+ f.write('%s \\fB%s\\fP(xcb_connection_t\\ *\\fIconn\\fP, %s\n' % (cookie_type, base_func_name, prototype))
+ create_link('%s_%s' % (base_func_name, ('checked' if void else 'unchecked')))
+ if not void:
+ f.write('.PP\n')
+ f.write('.SS Reply datastructure\n')
+ f.write('.nf\n')
+ f.write('.sp\n')
+ f.write('typedef %s %s {\n' % (self.reply.c_container, self.reply.c_type))
+ struct_fields = []
+ maxtypelen = 0
+
+ for field in self.reply.fields:
+ if not field.type.fixed_size() and not self.is_switch and not self.is_union:
+ continue
+ if field.wire:
+ struct_fields.append(field)
+
+ for field in struct_fields:
+ length = len(field.c_field_type)
+ # account for '*' pointer_spec
+ if not field.type.fixed_size():
+ length += 1
+ maxtypelen = max(maxtypelen, length)
+
+ def _c_complex_field(self, field, space=''):
+ if (field.type.fixed_size() or
+ # in case of switch with switch children, don't make the field a pointer
+ # necessary for unserialize to work
+ (self.is_switch and field.type.is_switch)):
+ spacing = ' ' * (maxtypelen - len(field.c_field_type))
+ f.write('%s %s%s \\fI%s\\fP%s;\n' % (space, field.c_field_type, spacing, field.c_field_name, field.c_subscript))
+ else:
+ spacing = ' ' * (maxtypelen - (len(field.c_field_type) + 1))
+ f.write('ELSE %s = %s\n' % (field.c_field_type, field.c_field_name))
+ #_h('%s %s%s *%s%s; /**< */', space, field.c_field_type, spacing, field.c_field_name, field.c_subscript)
+
+ if not self.is_switch:
+ for field in struct_fields:
+ _c_complex_field(self, field)
+ else:
+ for b in self.bitcases:
+ space = ''
+ if b.type.has_name:
+ space = ' '
+ for field in b.type.fields:
+ _c_complex_field(self, field, space)
+ if b.type.has_name:
+ print >> sys.stderr, 'ERROR: New unhandled documentation case'
+ pass
+
+ f.write('} \\fB%s\\fP;\n' % self.reply.c_type)
+ f.write('.fi\n')
+
+ f.write('.SS Reply function\n')
+ f.write('.HP\n')
+ f.write(('%s *\\fB%s\\fP(xcb_connection_t\\ *\\fIconn\\fP, %s\\ '
+ '\\fIcookie\\fP, xcb_generic_error_t\\ **\\fIe\\fP);\n') %
+ (self.c_reply_type, self.c_reply_name, self.c_cookie_type))
+ create_link('%s' % self.c_reply_name)
+
+ has_accessors = False
+ for field in self.reply.fields:
+ if field.type.is_list and not field.type.fixed_size():
+ has_accessors = True
+ elif field.prev_varsized_field is not None or not field.type.fixed_size():
+ has_accessors = True
+
+ if has_accessors:
+ f.write('.SS Reply accessors\n')
+
+ def _c_accessors_field(self, field):
+ '''
+ Declares the accessor functions for a non-list field that follows a variable-length field.
+ '''
+ c_type = self.c_type
+
+ # special case: switch
+ switch_obj = self if self.is_switch else None
+ if self.is_bitcase:
+ switch_obj = self.parents[-1]
+ if switch_obj is not None:
+ c_type = switch_obj.c_type
+
+ if field.type.is_simple:
+ f.write('%s %s (const %s *reply)\n' % (field.c_field_type, field.c_accessor_name, c_type))
+ create_link('%s' % field.c_accessor_name)
+ else:
+ f.write('%s *%s (const %s *reply)\n' % (field.c_field_type, field.c_accessor_name, c_type))
+ create_link('%s' % field.c_accessor_name)
+
+ def _c_accessors_list(self, field):
+ '''
+ Declares the accessor functions for a list field.
+ Declares a direct-accessor function only if the list members are fixed size.
+ Declares length and get-iterator functions always.
+ '''
+ list = field.type
+ c_type = self.reply.c_type
+
+ # special case: switch
+ # in case of switch, 2 params have to be supplied to certain accessor functions:
+ # 1. the anchestor object (request or reply)
+ # 2. the (anchestor) switch object
+ # the reason is that switch is either a child of a request/reply or nested in another switch,
+ # so whenever we need to access a length field, we might need to refer to some anchestor type
+ switch_obj = self if self.is_switch else None
+ if self.is_bitcase:
+ switch_obj = self.parents[-1]
+ if switch_obj is not None:
+ c_type = switch_obj.c_type
+
+ params = []
+ fields = {}
+ parents = self.parents if hasattr(self, 'parents') else [self]
+ # 'R': parents[0] is always the 'toplevel' container type
+ params.append(('const %s *\\fIreply\\fP' % parents[0].c_type, parents[0]))
+ fields.update(_c_helper_field_mapping(parents[0], [('R', '->', parents[0])], flat=True))
+ # auxiliary object for 'R' parameters
+ R_obj = parents[0]
+
+ if switch_obj is not None:
+ # now look where the fields are defined that are needed to evaluate
+ # the switch expr, and store the parent objects in accessor_params and
+ # the fields in switch_fields
+
+ # 'S': name for the 'toplevel' switch
+ toplevel_switch = parents[1]
+ params.append(('const %s *S' % toplevel_switch.c_type, toplevel_switch))
+ fields.update(_c_helper_field_mapping(toplevel_switch, [('S', '->', toplevel_switch)], flat=True))
+
+ # initialize prefix for everything "below" S
+ prefix_str = '/* %s */ S' % toplevel_switch.name[-1]
+ prefix = [(prefix_str, '->', toplevel_switch)]
+
+ # look for fields in the remaining containers
+ for p in parents[2:] + [self]:
+ # the separator between parent and child is always '.' here,
+ # because of nested switch statements
+ if not p.is_bitcase or (p.is_bitcase and p.has_name):
+ prefix.append((p.name[-1], '.', p))
+ fields.update(_c_helper_field_mapping(p, prefix, flat=True))
+
+ # auxiliary object for 'S' parameter
+ S_obj = parents[1]
+
+ if list.member.fixed_size():
+ idx = 1 if switch_obj is not None else 0
+ f.write('.HP\n')
+ f.write('%s *\\fB%s\\fP(%s);\n' %
+ (field.c_field_type, field.c_accessor_name, params[idx][0]))
+ create_link('%s' % field.c_accessor_name)
+
+ f.write('.HP\n')
+ f.write('int \\fB%s\\fP(const %s *\\fIreply\\fP);\n' %
+ (field.c_length_name, c_type))
+ create_link('%s' % field.c_length_name)
+
+ if field.type.member.is_simple:
+ f.write('.HP\n')
+ f.write('xcb_generic_iterator_t \\fB%s\\fP(const %s *\\fIreply\\fP);\n' %
+ (field.c_end_name, c_type))
+ create_link('%s' % field.c_end_name)
+ else:
+ f.write('.HP\n')
+ f.write('%s \\fB%s\\fP(const %s *\\fIreply\\fP);\n' %
+ (field.c_iterator_type, field.c_iterator_name,
+ c_type))
+ create_link('%s' % field.c_iterator_name)
+
+ for field in self.reply.fields:
+ if field.type.is_list and not field.type.fixed_size():
+ _c_accessors_list(self, field)
+ elif field.prev_varsized_field is not None or not field.type.fixed_size():
+ _c_accessors_field(self, field)
+
+
+ f.write('.br\n')
+ # Re-enable hyphenation and adjusting to both sides
+ f.write('.hy 1\n')
+
+ # argument reference
+ f.write('.SH REQUEST ARGUMENTS\n')
+ f.write('.IP \\fI%s\\fP 1i\n' % 'conn')
+ f.write('The XCB connection to X11.\n')
+ for field in param_fields:
+ f.write('.IP \\fI%s\\fP 1i\n' % (field.c_field_name))
+ printed_enum = False
+ # XXX: hard-coded until we fix xproto.xml
+ if base_func_name == 'xcb_change_gc' and field.c_field_name == 'value_mask':
+ field.enum = 'GC'
+ elif base_func_name == 'xcb_change_window_attributes' and field.c_field_name == 'value_mask':
+ field.enum = 'CW'
+ elif base_func_name == 'xcb_create_window' and field.c_field_name == 'value_mask':
+ field.enum = 'CW'
+ if hasattr(field, "enum") and field.enum:
+ # XXX: why the 'xcb' prefix?
+ key = ('xcb', field.enum)
+ if key in enums:
+ f.write('One of the following values:\n')
+ f.write('.RS 1i\n')
+ enum = enums[key]
+ count = len(enum.values)
+ for (enam, eval) in enum.values:
+ count = count - 1
+ f.write('.IP \\fI%s\\fP 1i\n' % (_n(key + (enam,)).upper()))
+ if hasattr(enum, "doc") and enum.doc and enam in enum.doc.fields:
+ desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', enum.doc.fields[enam])
+ f.write('%s\n' % desc)
+ else:
+ f.write('TODO: NOT YET DOCUMENTED.\n')
+ f.write('.RE\n')
+ f.write('.RS 1i\n')
+ printed_enum = True
+
+ if hasattr(self, "doc") and self.doc and field.field_name in self.doc.fields:
+ desc = self.doc.fields[field.field_name]
+ desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+ if printed_enum:
+ f.write('\n')
+ f.write('%s\n' % desc)
+ else:
+ f.write('TODO: NOT YET DOCUMENTED.\n')
+ if printed_enum:
+ f.write('.RE\n')
+
+ # Reply reference
+ if not void:
+ f.write('.SH REPLY FIELDS\n')
+ # These fields are present in every reply:
+ f.write('.IP \\fI%s\\fP 1i\n' % 'response_type')
+ f.write(('The type of this reply, in this case \\fI%s\\fP. This field '
+ 'is also present in the \\fIxcb_generic_reply_t\\fP and can '
+ 'be used to tell replies apart from each other.\n') %
+ _n(self.reply.name).upper())
+ f.write('.IP \\fI%s\\fP 1i\n' % 'sequence')
+ f.write('The sequence number of the last request processed by the X11 server.\n')
+ f.write('.IP \\fI%s\\fP 1i\n' % 'length')
+ f.write('The length of the reply, in words (a word is 4 bytes).\n')
+ for field in self.reply.fields:
+ if (field.c_field_name in frozenset(['response_type', 'sequence', 'length']) or
+ field.c_field_name.startswith('pad')):
+ continue
+
+ if field.type.is_list and not field.type.fixed_size():
+ continue
+ elif field.prev_varsized_field is not None or not field.type.fixed_size():
+ continue
+ f.write('.IP \\fI%s\\fP 1i\n' % (field.c_field_name))
+ printed_enum = False
+ if hasattr(field, "enum") and field.enum:
+ # XXX: why the 'xcb' prefix?
+ key = ('xcb', field.enum)
+ if key in enums:
+ f.write('One of the following values:\n')
+ f.write('.RS 1i\n')
+ enum = enums[key]
+ count = len(enum.values)
+ for (enam, eval) in enum.values:
+ count = count - 1
+ f.write('.IP \\fI%s\\fP 1i\n' % (_n(key + (enam,)).upper()))
+ if enum.doc and enam in enum.doc.fields:
+ desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', enum.doc.fields[enam])
+ f.write('%s\n' % desc)
+ else:
+ f.write('TODO: NOT YET DOCUMENTED.\n')
+ f.write('.RE\n')
+ f.write('.RS 1i\n')
+ printed_enum = True
+
+ if hasattr(self.reply, "doc") and self.reply.doc and field.field_name in self.reply.doc.fields:
+ desc = self.reply.doc.fields[field.field_name]
+ desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+ if printed_enum:
+ f.write('\n')
+ f.write('%s\n' % desc)
+ else:
+ f.write('TODO: NOT YET DOCUMENTED.\n')
+ if printed_enum:
+ f.write('.RE\n')
+
+
+
+ # text description
+ f.write('.SH DESCRIPTION\n')
+ if hasattr(self, "doc") and self.doc and self.doc.description:
+ desc = self.doc.description
+ desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+ lines = desc.split('\n')
+ f.write('\n'.join(lines) + '\n')
+
+ f.write('.SH RETURN VALUE\n')
+ if void:
+ f.write(('Returns an \\fIxcb_void_cookie_t\\fP. Errors (if any) '
+ 'have to be handled in the event loop.\n\nIf you want to '
+ 'handle errors directly with \\fIxcb_request_check\\fP '
+ 'instead, use \\fI%s_checked\\fP. See '
+ '\\fBxcb-requests(3)\\fP for details.\n') % (base_func_name))
+ else:
+ f.write(('Returns an \\fI%s\\fP. Errors have to be handled when '
+ 'calling the reply function \\fI%s\\fP.\n\nIf you want to '
+ 'handle errors in the event loop instead, use '
+ '\\fI%s_unchecked\\fP. See \\fBxcb-requests(3)\\fP for '
+ 'details.\n') %
+ (cookie_type, self.c_reply_name, base_func_name))
+ f.write('.SH ERRORS\n')
+ if hasattr(self, "doc") and self.doc:
+ for errtype, errtext in self.doc.errors.iteritems():
+ f.write('.IP \\fI%s\\fP 1i\n' % (_t(('xcb', errtype, 'error'))))
+ errtext = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', errtext)
+ f.write('%s\n' % (errtext))
+ if not hasattr(self, "doc") or not self.doc or len(self.doc.errors) == 0:
+ f.write('This request does never generate any errors.\n')
+ if hasattr(self, "doc") and self.doc and self.doc.example:
+ f.write('.SH EXAMPLE\n')
+ f.write('.nf\n')
+ f.write('.sp\n')
+ lines = self.doc.example.split('\n')
+ f.write('\n'.join(lines) + '\n')
+ f.write('.fi\n')
+ f.write('.SH SEE ALSO\n')
+ if hasattr(self, "doc") and self.doc:
+ see = ['.BR %s (3)' % 'xcb-requests']
+ if self.doc.example:
+ see.append('.BR %s (3)' % 'xcb-examples')
+ for seename, seetype in self.doc.see.iteritems():
+ if seetype == 'program':
+ see.append('.BR %s (1)' % seename)
+ elif seetype == 'event':
+ see.append('.BR %s (3)' % _t(('xcb', seename, 'event')))
+ elif seetype == 'request':
+ see.append('.BR %s (3)' % _n(('xcb', seename)))
+ elif seetype == 'function':
+ see.append('.BR %s (3)' % seename)
+ else:
+ see.append('TODO: %s (type %s)' % (seename, seetype))
+ f.write(',\n'.join(see) + '\n')
+ f.write('.SH AUTHOR\n')
+ f.write('Generated from %s.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.\n' % _ns.header)
+ f.close()
+
+def _man_event(self, name):
+ if manpaths:
+ sys.stdout.write('man/%s.3 ' % self.c_type)
+ # Our CWD is src/, so this will end up in src/man/
+ f = open('man/%s.3' % self.c_type, 'w')
+ f.write('.TH %s 3 %s "XCB" "XCB Events"\n' % (self.c_type, today))
+ # Left-adjust instead of adjusting to both sides
+ f.write('.ad l\n')
+ f.write('.SH NAME\n')
+ brief = self.doc.brief if hasattr(self, "doc") and self.doc else ''
+ f.write('%s \\- %s\n' % (self.c_type, brief))
+ f.write('.SH SYNOPSIS\n')
+ # Don't split words (hyphenate)
+ f.write('.hy 0\n')
+ f.write('.B #include <xcb/%s.h>\n' % _ns.header)
+
+ f.write('.PP\n')
+ f.write('.SS Event datastructure\n')
+ f.write('.nf\n')
+ f.write('.sp\n')
+ f.write('typedef %s %s {\n' % (self.c_container, self.c_type))
+ struct_fields = []
+ maxtypelen = 0
+
+ for field in self.fields:
+ if not field.type.fixed_size() and not self.is_switch and not self.is_union:
+ continue
+ if field.wire:
+ struct_fields.append(field)
+
+ for field in struct_fields:
+ length = len(field.c_field_type)
+ # account for '*' pointer_spec
+ if not field.type.fixed_size():
+ length += 1
+ maxtypelen = max(maxtypelen, length)
+
+ def _c_complex_field(self, field, space=''):
+ if (field.type.fixed_size() or
+ # in case of switch with switch children, don't make the field a pointer
+ # necessary for unserialize to work
+ (self.is_switch and field.type.is_switch)):
+ spacing = ' ' * (maxtypelen - len(field.c_field_type))
+ f.write('%s %s%s \\fI%s\\fP%s;\n' % (space, field.c_field_type, spacing, field.c_field_name, field.c_subscript))
+ else:
+ print >> sys.stderr, 'ERROR: New unhandled documentation case'
+
+ if not self.is_switch:
+ for field in struct_fields:
+ _c_complex_field(self, field)
+ else:
+ for b in self.bitcases:
+ space = ''
+ if b.type.has_name:
+ space = ' '
+ for field in b.type.fields:
+ _c_complex_field(self, field, space)
+ if b.type.has_name:
+ print >> sys.stderr, 'ERROR: New unhandled documentation case'
+ pass
+
+ f.write('} \\fB%s\\fP;\n' % self.c_type)
+ f.write('.fi\n')
+
+
+ f.write('.br\n')
+ # Re-enable hyphenation and adjusting to both sides
+ f.write('.hy 1\n')
+
+ # argument reference
+ f.write('.SH EVENT FIELDS\n')
+ f.write('.IP \\fI%s\\fP 1i\n' % 'response_type')
+ f.write(('The type of this event, in this case \\fI%s\\fP. This field is '
+ 'also present in the \\fIxcb_generic_event_t\\fP and can be used '
+ 'to tell events apart from each other.\n') % _n(name).upper())
+ f.write('.IP \\fI%s\\fP 1i\n' % 'sequence')
+ f.write('The sequence number of the last request processed by the X11 server.\n')
+
+ if not self.is_switch:
+ for field in struct_fields:
+ # Skip the fields which every event has, we already documented
+ # them (see above).
+ if field.c_field_name in ('response_type', 'sequence'):
+ continue
+ if isinstance(field.type, PadType):
+ continue
+ f.write('.IP \\fI%s\\fP 1i\n' % (field.c_field_name))
+ if hasattr(self, "doc") and self.doc and field.field_name in self.doc.fields:
+ desc = self.doc.fields[field.field_name]
+ desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+ f.write('%s\n' % desc)
+ else:
+ f.write('NOT YET DOCUMENTED.\n')
+
+ # text description
+ f.write('.SH DESCRIPTION\n')
+ if hasattr(self, "doc") and self.doc and self.doc.description:
+ desc = self.doc.description
+ desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+ lines = desc.split('\n')
+ f.write('\n'.join(lines) + '\n')
+
+ if hasattr(self, "doc") and self.doc and self.doc.example:
+ f.write('.SH EXAMPLE\n')
+ f.write('.nf\n')
+ f.write('.sp\n')
+ lines = self.doc.example.split('\n')
+ f.write('\n'.join(lines) + '\n')
+ f.write('.fi\n')
+ f.write('.SH SEE ALSO\n')
+ if hasattr(self, "doc") and self.doc:
+ see = ['.BR %s (3)' % 'xcb_generic_event_t']
+ if self.doc.example:
+ see.append('.BR %s (3)' % 'xcb-examples')
+ for seename, seetype in self.doc.see.iteritems():
+ if seetype == 'program':
+ see.append('.BR %s (1)' % seename)
+ elif seetype == 'event':
+ see.append('.BR %s (3)' % _t(('xcb', seename, 'event')))
+ elif seetype == 'request':
+ see.append('.BR %s (3)' % _n(('xcb', seename)))
+ elif seetype == 'function':
+ see.append('.BR %s (3)' % seename)
+ else:
+ see.append('TODO: %s (type %s)' % (seename, seetype))
+ f.write(',\n'.join(see) + '\n')
+ f.write('.SH AUTHOR\n')
+ f.write('Generated from %s.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.\n' % _ns.header)
+ f.close()
+
+
def c_request(self, name):
'''
Exported function that handles request declarations.
@@ -2239,6 +2815,10 @@ def c_request(self, name):
_c_request_helper(self, name, 'xcb_void_cookie_t', True, False, True)
_c_request_helper(self, name, 'xcb_void_cookie_t', True, True, True)
+ # We generate the manpage afterwards because _c_type_setup has been called.
+ # TODO: what about aux helpers?
+ cookie_type = self.c_cookie_type if self.reply else 'xcb_void_cookie_t'
+ _man_request(self, name, cookie_type, not self.reply, False)
def c_event(self, name):
'''
@@ -2257,6 +2837,8 @@ def c_event(self, name):
_h('')
_h('typedef %s %s;', _t(self.name + ('event',)), _t(name + ('event',)))
+ _man_event(self, name)
+
def c_error(self, name):
'''
Exported function that handles error declarations.
@@ -2293,7 +2875,7 @@ output = {'open' : c_open,
# Check for the argument that specifies path to the xcbgen python package.
try:
- opts, args = getopt.getopt(sys.argv[1:], 'p:')
+ opts, args = getopt.getopt(sys.argv[1:], 'p:m')
except getopt.GetoptError as err:
print(err)
print('Usage: c_client.py [-p path] file.xml')
@@ -2302,10 +2884,14 @@ except getopt.GetoptError as err:
for (opt, arg) in opts:
if opt == '-p':
sys.path.insert(1, arg)
+ elif opt == '-m':
+ manpaths = True
+ sys.stdout.write('man_MANS = ')
# Import the module class
try:
from xcbgen.state import Module
+ from xcbgen.xtypes import *
except ImportError:
print('''
Failed to load the xcbgen Python package!
@@ -2316,6 +2902,12 @@ Refer to the README file in xcb/proto for more info.
''')
raise
+# Ensure the man subdirectory exists
+if not os.path.exists('man'):
+ os.mkdir('man')
+
+today = time.strftime('%Y-%m-%d', time.gmtime(os.path.getmtime(args[0])))
+
# Parse the xml header
module = Module(args[0], output)
diff --git a/libxcb/src/man/xcb-examples.3 b/libxcb/src/man/xcb-examples.3
new file mode 100644
index 000000000..291af37d0
--- /dev/null
+++ b/libxcb/src/man/xcb-examples.3
@@ -0,0 +1,59 @@
+.TH xcb-examples 3 2011-12-11 "XCB" "XCB examples"
+.ad l
+.SH NAME
+xcb-examples \- manpage examples
+.SH DESCRIPTION
+Many of the XCB manpages contain example code. These examples intend to explain
+how to use one particular part of XCB. They almost never represent a standalone
+(or even useful) program - X11 programs are relatively involved and
+thus beyond the scope of a manpage example.
+
+.SH ENVIRONMENT
+
+Every example assumes you have an \fIxcb_connection\fP and possibly other
+variables at hand. For illustrating how \fIxcb_get_property\fP works, you need
+the window of which you want to get the property, for example. To make it clear
+that these variables are your responsibility, these examples consist of a
+single function which takes the necessary variables as parameters.
+
+.SH FLUSHING
+
+Flushing means calling \fIxcb_flush\fP to clear the XCB-internal write buffer
+and send all pending requests to the X11 server. You don't explicitly need to
+flush before using a reply function (like \fIxcb_query_pointer_reply\fP), but
+you do need to flush before entering the event loop of your program.
+
+There are only two cases when XCB flushes by itself. The first case is when
+its write buffer becomes full, the second case is when you are asking for
+the reply of a request which wasn't flushed out yet (like
+\fIxcb_query_pointer_reply\fP). This last point also includes
+xcb_request_check(). Please note that waiting for an event does \fBNOT\fP
+flush.
+
+Examples generally include the \fIxcb_flush\fP call where appropriate (for
+example after setting a property). Therefore, including these functions and
+calling them in your application should just work. However, you might get
+better results when flushing outside of the function, depending on the
+architecture of your program.
+
+.SH COMPILATION
+
+If an example does not compile (without warnings) when using \fI-std=c99\fP,
+that is considered a documentation bug. Similarly, not handling errors or
+leaking memory is also considered a documentation bug. Please inform us about
+it on xcb@lists.freedesktop.org.
+
+.SH CODING STYLE
+
+Every example uses 4 spaces for indention.
+
+Comments are in asterisks, like /* this */.
+
+No line is longer than 80 characters (including indention).
+
+.SH SEE ALSO
+.BR xcb_connect (3),
+.BR xcb_get_property (3),
+.BR xcb_flush (3)
+.SH AUTHOR
+Michael Stapelberg <michael+xcb at stapelberg dot de>
diff --git a/libxcb/src/man/xcb-requests.3 b/libxcb/src/man/xcb-requests.3
new file mode 100644
index 000000000..278bcff13
--- /dev/null
+++ b/libxcb/src/man/xcb-requests.3
@@ -0,0 +1,165 @@
+.TH xcb-requests 3 2011-12-11 "XCB" "XCB examples"
+.ad l
+.SH NAME
+xcb-requests \- about request manpages
+.SH DESCRIPTION
+Every request in X11, like \fIMapWindow\fP, corresponds to a number of
+functions and data structures in XCB. For \fIMapWindow\fP, XCB provides the
+function \fIxcb_map_window\fP, which fills the \fIxcb_map_window_request_t\fP
+data structure and writes that to the X11 connection. Since the \fIMapWindow\fP
+request does not have a reply, this is the most simple case.
+
+.SH REPLIES
+
+Many requests have replies. For each reply, XCB provides at least a
+corresponding data structure and a function to return a pointer to a filled
+data structure. Let's take the \fIInternAtom\fP request as an example: XCB
+provides the \fIxcb_intern_atom_reply_t\fP data structure and
+\fIxcb_intern_atom_reply\fP function. For replies which are more complex (for
+example lists, such as in \fIxcb_list_fonts\fP), accessor functions are
+provided.
+
+.SH COOKIES
+
+XCB returns a cookie for each request you send. This is an XCB-specific data
+structure containing the sequence number with which the request was sent to the
+X11 server. To get any reply, you have to provide that cookie (so that XCB
+knows which of the waiting replies you want). Here is an example to illustrate
+the use of cookies:
+
+.nf
+.sp
+void my_example(xcb_connection *conn) {
+ xcb_intern_atom_cookie_t cookie;
+ xcb_intern_atom_reply_t *reply;
+
+ cookie = xcb_intern_atom(conn, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
+ /* ... do other work here if possible ... */
+ if ((reply = xcb_intern_atom_reply(conn, cookie, NULL))) {
+ printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
+ }
+ free(reply);
+}
+.fi
+
+.SH CHECKED VS. UNCHECKED
+
+The checked and unchecked suffixes for functions determine which kind of error
+handling is used for this specific request.
+
+For requests which have no reply (for example \fIxcb_map_window\fP), errors
+will be delivered to the event loop (you will receive an X11 event of type 0
+when calling \fIxcb_poll_for_event\fP).
+If you want to explicitly check for errors in a blocking fashion, call the
+_checked version of the function (for example \fIxcb_map_window_checked\fP) and
+use \fIxcb_request_check\fP.
+
+For requests which have a reply (for example \fIxcb_intern_atom\fP), errors
+will be checked when calling the reply function. To get errors in the event
+loop instead, use the _unchecked version of the function (for example
+\fIxcb_intern_atom_unchecked\fP).
+
+Here is an example which illustrates the four different ways of handling errors:
+
+.nf
+.sp
+/*
+ * Request without a reply, handling errors in the event loop (default)
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+ /* This is a request without a reply. Errors will be delivered to the event
+ * loop. Getting an error to xcb_map_window most likely is a bug in our
+ * program, so we don't need to check for that in a blocking way. */
+ xcb_map_window(conn, window);
+
+ /* ... of course your event loop would not be in the same function ... */
+ while ((event = xcb_wait_for_event(conn)) != NULL) {
+ if (event->response_type == 0) {
+ fprintf("Received X11 error %d\\n", error->error_code);
+ free(event);
+ continue;
+ }
+
+ /* ... handle a normal event ... */
+ }
+}
+
+/*
+ * Request without a reply, handling errors directly
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t deco, xcb_window_t window) {
+ /* A reparenting window manager wants to know whether a new window was
+ * successfully reparented. If not (because the window got destroyed
+ * already, for example), it does not make sense to map an empty window
+ * decoration at all, so we need to know this right now. */
+ xcb_void_cookie_t cookie = xcb_reparent_window_checked(conn, window,
+ deco, 0, 0);
+ xcb_generic_error_t *error;
+ if ((error = xcb_request_check(conn, cookie))) {
+ fprintf(stderr, "Could not reparent the window\\n");
+ free(error);
+ return;
+ }
+
+ /* ... do window manager stuff here ... */
+}
+
+/*
+ * Request with a reply, handling errors directly (default)
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+ xcb_intern_atom_cookie_t cookie;
+ xcb_intern_atom_reply_t *reply;
+ xcb_generic_error_t *error;
+
+ cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
+ /* ... do other work here if possible ... */
+ if ((reply = xcb_intern_atom_reply(c, cookie, &error))) {
+ printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
+ free(reply);
+ } else {
+ fprintf(stderr, "X11 Error %d\\n", error->error_code);
+ free(error);
+ }
+}
+
+/*
+ * Request with a reply, handling errors in the event loop
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+ xcb_intern_atom_cookie_t cookie;
+ xcb_intern_atom_reply_t *reply;
+
+ cookie = xcb_intern_atom_unchecked(c, 0, strlen("_NET_WM_NAME"),
+ "_NET_WM_NAME");
+ /* ... do other work here if possible ... */
+ if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) {
+ printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
+ free(reply);
+ }
+
+ /* ... of course your event loop would not be in the same function ... */
+ while ((event = xcb_wait_for_event(conn)) != NULL) {
+ if (event->response_type == 0) {
+ fprintf("Received X11 error %d\\n", error->error_code);
+ free(event);
+ continue;
+ }
+
+ /* ... handle a normal event ... */
+ }
+}
+.fi
+
+.SH SEE ALSO
+.BR xcb_map_window (3),
+.BR xcb_intern_atom (3),
+.BR xcb_list_fonts (3),
+.BR xcb_poll_for_event (3),
+.BR xcb_request_check (3)
+.SH AUTHOR
+Michael Stapelberg <michael+xcb at stapelberg dot de>
diff --git a/libxcb/xcb-proto/doc/xml-xcb.txt b/libxcb/xcb-proto/doc/xml-xcb.txt
index 3c6a15519..705772736 100644
--- a/libxcb/xcb-proto/doc/xml-xcb.txt
+++ b/libxcb/xcb-proto/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 <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.
diff --git a/libxcb/xcb-proto/src/xcb.xsd b/libxcb/xcb-proto/src/xcb.xsd
index 89e27846f..cfa90c9c2 100644
--- a/libxcb/xcb-proto/src/xcb.xsd
+++ b/libxcb/xcb-proto/src/xcb.xsd
@@ -1,314 +1,375 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!--
-Copyright (C) 2004 Josh Triplett. All Rights Reserved.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
-ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-Except as contained in this notice, the names of the authors or their
-institutions shall not be used in advertising or otherwise to promote the
-sale, use or other dealings in this Software without prior written
-authorization from the authors.
--->
-<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
-
- <!-- The root element -->
- <xsd:element name="xcb">
- <xsd:complexType>
- <xsd:group ref="macro" minOccurs="0" maxOccurs="unbounded" />
- <xsd:attribute name="header" type="xsd:string" use="required" />
- <xsd:attribute name="extension-xname" type="xsd:string" use="optional" />
- <xsd:attribute name="extension-name" type="xsd:string" use="optional" />
- <xsd:attribute name="extension-multiword" type="xsd:boolean" use="optional" default="false" />
- <xsd:attribute name="major-version" type="xsd:integer" use="optional" />
- <xsd:attribute name="minor-version" type="xsd:integer" use="optional" />
- </xsd:complexType>
- </xsd:element>
-
- <!-- Padding -->
- <xsd:element name="pad">
- <xsd:complexType>
- <xsd:attribute name="bytes" type="xsd:integer" use="required" />
- </xsd:complexType>
- </xsd:element>
-
- <!-- Type for fields or parameters with attributes "name" and "type" -->
- <xsd:complexType name="var">
- <xsd:attribute name="name" type="xsd:string" use="required" />
- <xsd:attribute name="type" type="xsd:string" use="required" />
- <xsd:attribute name="enum" type="xsd:string" use="optional" />
- <xsd:attribute name="altenum" type="xsd:string" use="optional" />
- <xsd:attribute name="mask" type="xsd:string" use="optional" />
- </xsd:complexType>
-
- <!-- case expression -->
- <xsd:complexType name="caseexpr">
- <xsd:sequence>
- <!-- case expression: -->
- <xsd:group ref="expression" minOccurs="1" maxOccurs="1" />
- <!-- match -->
- <xsd:group ref="fields" minOccurs="1" maxOccurs="unbounded" />
- <xsd:choice>
- <xsd:element ref="switch" minOccurs="0" maxOccurs="unbounded" />
- </xsd:choice>
- </xsd:sequence>
- <xsd:attribute name="name" type="xsd:string" use="optional" />
- </xsd:complexType>
-
- <!-- switch expression -->
- <xsd:complexType name="switchexpr">
- <xsd:sequence>
- <!-- switch(expression) -->
- <xsd:group ref="expression" minOccurs="1" maxOccurs="1" />
- <xsd:choice>
- <!-- bitcase expression - bit test -->
- <xsd:element name="bitcase" type="caseexpr" minOccurs="1" maxOccurs="unbounded" />
- </xsd:choice>
- <!-- default: -->
- <xsd:group ref="fields" minOccurs="0" maxOccurs="1" />
- </xsd:sequence>
- <xsd:attribute name="name" type="xsd:string" use="required" />
- </xsd:complexType>
-
- <xsd:element name="switch" type="switchexpr" />
-
- <!-- field replaces FIELD, PARAM, and REPLY. -->
- <xsd:element name="field" type="var" />
-
- <!-- list replaces ARRAYFIELD, LISTPARAM, and ARRAYREPLY. The name and type
- are specified as attributes. The content is an expression giving the
- length. -->
- <xsd:element name="list">
- <xsd:complexType>
- <xsd:complexContent>
- <xsd:extension base="var">
- <xsd:group ref="expression" minOccurs="0" maxOccurs="1" />
- </xsd:extension>
- </xsd:complexContent>
- </xsd:complexType>
- </xsd:element>
-
- <!-- Expressions -->
- <xsd:group name="expression">
- <xsd:choice>
- <xsd:element name="op">
- <xsd:complexType>
- <xsd:sequence>
- <xsd:group ref="expression" />
- <xsd:group ref="expression" />
- </xsd:sequence>
- <xsd:attribute name="op" use="required">
- <xsd:simpleType>
- <xsd:restriction base="xsd:string">
- <xsd:pattern value="\+|-|\*|/|&amp;|&lt;&lt;" />
- </xsd:restriction>
- </xsd:simpleType>
- </xsd:attribute>
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="unop">
- <xsd:complexType>
- <xsd:sequence>
- <xsd:group ref="expression" />
- </xsd:sequence>
- <xsd:attribute name="op" use="required">
- <xsd:simpleType>
- <xsd:restriction base="xsd:string">
- <xsd:pattern value="~" />
- </xsd:restriction>
- </xsd:simpleType>
- </xsd:attribute>
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="fieldref" type="xsd:string" />
- <xsd:element name="enumref">
- <xsd:complexType>
- <xsd:simpleContent>
- <xsd:extension base="xsd:string">
- <xsd:attribute name="ref" use="required" type="xsd:string" />
- </xsd:extension>
- </xsd:simpleContent>
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="popcount">
- <xsd:complexType>
- <xsd:group ref="expression" />
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="sumof">
- <xsd:complexType>
- <xsd:attribute name="ref" use="required" type="xsd:string" />
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="value" type="dec-or-hex-integer" />
- <xsd:element name="bit" type="xsd:integer" />
- </xsd:choice>
- </xsd:group>
-
- <!-- Fields in requests that are calculated from other information, not
- supplied by the caller. -->
- <xsd:element name="exprfield" >
- <xsd:complexType>
- <xsd:complexContent>
- <xsd:extension base="var">
- <xsd:group ref="expression" />
- </xsd:extension>
- </xsd:complexContent>
- </xsd:complexType>
- </xsd:element>
-
- <!-- BITMASK/LISTofVALUE parameter pairs. -->
- <xsd:element name="valueparam">
- <xsd:complexType>
- <xsd:attribute name="value-mask-type" type="xsd:string" use="required" />
- <xsd:attribute name="value-mask-name" type="xsd:string" use="required" />
- <xsd:attribute name="value-list-name" type="xsd:string" use="required" />
- </xsd:complexType>
- </xsd:element>
-
- <xsd:group name="fields">
- <xsd:choice>
- <xsd:element ref="pad" />
- <xsd:element ref="field" />
- <xsd:element ref="list" />
- </xsd:choice>
- </xsd:group>
-
- <!-- Type for a structure -->
- <xsd:complexType name="struct">
- <xsd:sequence>
- <xsd:group ref="fields" minOccurs="1" maxOccurs="unbounded" />
- <xsd:choice minOccurs="0" maxOccurs="1">
- <xsd:element ref="switch" />
- </xsd:choice>
- </xsd:sequence>
- <xsd:attribute name="name" type="xsd:string" use="required" />
- </xsd:complexType>
-
- <!-- Type for a packet structure -->
- <xsd:complexType name="packet-struct">
- <xsd:group ref="fields" minOccurs="0" maxOccurs="unbounded" />
- <xsd:attribute name="name" type="xsd:string" use="required" />
- <xsd:attribute name="number" type="xsd:integer" use="required" />
- </xsd:complexType>
-
- <!-- Type for a packet structure copy -->
- <xsd:complexType name="packet-struct-copy">
- <xsd:attribute name="name" type="xsd:string" use="required" />
- <xsd:attribute name="number" type="xsd:integer" use="required" />
- <xsd:attribute name="ref" type="xsd:string" use="required" />
- </xsd:complexType>
-
- <!-- Type for hex integers -->
- <xsd:simpleType name="hex-integer">
- <xsd:restriction base="xsd:string">
- <xsd:pattern value="0x[0-9a-fA-F]+" />
- </xsd:restriction>
- </xsd:simpleType>
-
- <!-- Type for integers in either decimal or hex -->
- <xsd:simpleType name="dec-or-hex-integer">
- <xsd:union memberTypes="xsd:integer hex-integer" />
- </xsd:simpleType>
-
- <xsd:group name="macro">
- <xsd:choice>
- <xsd:element name="request">
- <xsd:complexType>
- <xsd:sequence>
- <xsd:choice minOccurs="0" maxOccurs="unbounded">
- <xsd:group ref="fields" />
- <xsd:element ref="exprfield" />
- <xsd:element ref="valueparam" />
- </xsd:choice>
- <xsd:choice minOccurs="0" maxOccurs="1">
- <xsd:element ref="switch" />
- </xsd:choice>
- <xsd:element name="reply" minOccurs="0" maxOccurs="1">
- <xsd:complexType>
- <xsd:sequence>
- <xsd:choice minOccurs="1" maxOccurs="unbounded">
- <xsd:group ref="fields" />
- <xsd:element ref="valueparam" />
- </xsd:choice>
- <xsd:choice minOccurs="0" maxOccurs="1">
- <xsd:element ref="switch" />
- </xsd:choice>
- </xsd:sequence>
- </xsd:complexType>
- </xsd:element>
- </xsd:sequence>
- <xsd:attribute name="name" type="xsd:string" use="required" />
- <xsd:attribute name="opcode" type="xsd:integer" use="required" />
- <xsd:attribute name="combine-adjacent" type="xsd:boolean"
- use="optional"/>
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="event">
- <xsd:complexType>
- <xsd:complexContent>
- <xsd:extension base="packet-struct">
- <xsd:attribute name="no-sequence-number" type="xsd:boolean"
- use="optional" />
- </xsd:extension>
- </xsd:complexContent>
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="eventcopy" type="packet-struct-copy" />
- <xsd:element name="error" type="packet-struct" />
- <xsd:element name="errorcopy" type="packet-struct-copy" />
- <xsd:element name="struct" type="struct" />
- <xsd:element name="union" type="struct" />
- <xsd:element name="xidtype">
- <xsd:complexType>
- <xsd:attribute name="name" type="xsd:string" use="required" />
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="xidunion">
- <xsd:complexType>
- <xsd:sequence>
- <xsd:element name="type" type="xsd:string"
- minOccurs="1" maxOccurs="unbounded" />
- </xsd:sequence>
- <xsd:attribute name="name" type="xsd:string" use="required" />
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="enum">
- <xsd:complexType>
- <xsd:sequence minOccurs="1" maxOccurs="unbounded">
- <xsd:element name="item">
- <xsd:complexType>
- <xsd:group ref="expression" minOccurs="0" maxOccurs="1" />
- <xsd:attribute name="name" type="xsd:string" use="required" />
- </xsd:complexType>
- </xsd:element>
- </xsd:sequence>
- <xsd:attribute name="name" type="xsd:string" use="required" />
- </xsd:complexType>
- </xsd:element>
- <xsd:element name="typedef">
- <xsd:complexType>
- <xsd:attribute name="oldname" type="xsd:string" use="required" />
- <xsd:attribute name="newname" type="xsd:string" use="required" />
- </xsd:complexType>
- </xsd:element>
- <!-- The import element allows a protocol description to reference the
- declarations of another protocol description. -->
- <xsd:element name="import" type="xsd:string" />
- </xsd:choice>
- </xsd:group>
-</xsd:schema>
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (C) 2004 Josh Triplett. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the names of the authors or their
+institutions shall not be used in advertising or otherwise to promote the
+sale, use or other dealings in this Software without prior written
+authorization from the authors.
+-->
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
+ <!-- The root element -->
+ <xsd:element name="xcb">
+ <xsd:complexType>
+ <xsd:group ref="macro" minOccurs="0" maxOccurs="unbounded" />
+ <xsd:attribute name="header" type="xsd:string" use="required" />
+ <xsd:attribute name="extension-xname" type="xsd:string" use="optional" />
+ <xsd:attribute name="extension-name" type="xsd:string" use="optional" />
+ <xsd:attribute name="extension-multiword" type="xsd:boolean" use="optional" default="false" />
+ <xsd:attribute name="major-version" type="xsd:integer" use="optional" />
+ <xsd:attribute name="minor-version" type="xsd:integer" use="optional" />
+ </xsd:complexType>
+ </xsd:element>
+
+ <!-- Padding -->
+ <xsd:element name="pad">
+ <xsd:complexType>
+ <xsd:attribute name="bytes" type="xsd:integer" use="required" />
+ </xsd:complexType>
+ </xsd:element>
+
+ <!-- Type for fields or parameters with attributes "name" and "type" -->
+ <xsd:complexType name="var">
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ <xsd:attribute name="type" type="xsd:string" use="required" />
+ <xsd:attribute name="enum" type="xsd:string" use="optional" />
+ <xsd:attribute name="altenum" type="xsd:string" use="optional" />
+ <xsd:attribute name="mask" type="xsd:string" use="optional" />
+ </xsd:complexType>
+
+ <!-- case expression -->
+ <xsd:complexType name="caseexpr">
+ <xsd:sequence>
+ <!-- case expression: -->
+ <xsd:group ref="expression" minOccurs="1" maxOccurs="1" />
+ <!-- match -->
+ <xsd:group ref="fields" minOccurs="1" maxOccurs="unbounded" />
+ <xsd:choice>
+ <xsd:element ref="switch" minOccurs="0" maxOccurs="unbounded" />
+ </xsd:choice>
+ </xsd:sequence>
+ <xsd:attribute name="name" type="xsd:string" use="optional" />
+ </xsd:complexType>
+
+ <!-- switch expression -->
+ <xsd:complexType name="switchexpr">
+ <xsd:sequence>
+ <!-- switch(expression) -->
+ <xsd:group ref="expression" minOccurs="1" maxOccurs="1" />
+ <xsd:choice>
+ <!-- bitcase expression - bit test -->
+ <xsd:element name="bitcase" type="caseexpr" minOccurs="1" maxOccurs="unbounded" />
+ </xsd:choice>
+ <!-- default: -->
+ <xsd:group ref="fields" minOccurs="0" maxOccurs="1" />
+ </xsd:sequence>
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ </xsd:complexType>
+
+ <xsd:element name="switch" type="switchexpr" />
+
+ <!-- field replaces FIELD, PARAM, and REPLY. -->
+ <xsd:element name="field" type="var" />
+
+ <!-- list replaces ARRAYFIELD, LISTPARAM, and ARRAYREPLY. The name and type
+ are specified as attributes. The content is an expression giving the
+ length. -->
+ <xsd:element name="list">
+ <xsd:complexType>
+ <xsd:complexContent>
+ <xsd:extension base="var">
+ <xsd:group ref="expression" minOccurs="0" maxOccurs="1" />
+ </xsd:extension>
+ </xsd:complexContent>
+ </xsd:complexType>
+ </xsd:element>
+
+ <!-- Expressions -->
+ <xsd:group name="expression">
+ <xsd:choice>
+ <xsd:element name="op">
+ <xsd:complexType>
+ <xsd:sequence>
+ <xsd:group ref="expression" />
+ <xsd:group ref="expression" />
+ </xsd:sequence>
+ <xsd:attribute name="op" use="required">
+ <xsd:simpleType>
+ <xsd:restriction base="xsd:string">
+ <xsd:pattern value="\+|-|\*|/|&amp;|&lt;&lt;" />
+ </xsd:restriction>
+ </xsd:simpleType>
+ </xsd:attribute>
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="unop">
+ <xsd:complexType>
+ <xsd:sequence>
+ <xsd:group ref="expression" />
+ </xsd:sequence>
+ <xsd:attribute name="op" use="required">
+ <xsd:simpleType>
+ <xsd:restriction base="xsd:string">
+ <xsd:pattern value="~" />
+ </xsd:restriction>
+ </xsd:simpleType>
+ </xsd:attribute>
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="fieldref" type="xsd:string" />
+ <xsd:element name="enumref">
+ <xsd:complexType>
+ <xsd:simpleContent>
+ <xsd:extension base="xsd:string">
+ <xsd:attribute name="ref" use="required" type="xsd:string" />
+ </xsd:extension>
+ </xsd:simpleContent>
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="popcount">
+ <xsd:complexType>
+ <xsd:group ref="expression" />
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="sumof">
+ <xsd:complexType>
+ <xsd:attribute name="ref" use="required" type="xsd:string" />
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="value" type="dec-or-hex-integer" />
+ <xsd:element name="bit" type="xsd:integer" />
+ </xsd:choice>
+ </xsd:group>
+
+ <!-- Fields in requests that are calculated from other information, not
+ supplied by the caller. -->
+ <xsd:element name="exprfield" >
+ <xsd:complexType>
+ <xsd:complexContent>
+ <xsd:extension base="var">
+ <xsd:group ref="expression" />
+ </xsd:extension>
+ </xsd:complexContent>
+ </xsd:complexType>
+ </xsd:element>
+
+ <!-- BITMASK/LISTofVALUE parameter pairs. -->
+ <xsd:element name="valueparam">
+ <xsd:complexType>
+ <xsd:attribute name="value-mask-type" type="xsd:string" use="required" />
+ <xsd:attribute name="value-mask-name" type="xsd:string" use="required" />
+ <xsd:attribute name="value-list-name" type="xsd:string" use="required" />
+ </xsd:complexType>
+ </xsd:element>
+
+ <xsd:group name="fields">
+ <xsd:choice>
+ <xsd:element ref="pad" />
+ <xsd:element ref="field" />
+ <xsd:element ref="list" />
+ </xsd:choice>
+ </xsd:group>
+
+ <!-- Type for a structure -->
+ <xsd:complexType name="struct">
+ <xsd:sequence>
+ <xsd:group ref="fields" minOccurs="1" maxOccurs="unbounded" />
+ <xsd:choice minOccurs="0" maxOccurs="1">
+ <xsd:element ref="switch" />
+ </xsd:choice>
+ </xsd:sequence>
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ </xsd:complexType>
+
+ <!-- Type for a packet structure -->
+ <xsd:complexType name="packet-struct">
+ <xsd:sequence>
+ <xsd:group ref="fields" minOccurs="0" maxOccurs="unbounded" />
+ </xsd:sequence>
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ <xsd:attribute name="number" type="xsd:integer" use="required" />
+ </xsd:complexType>
+
+ <!-- Type for a packet structure copy -->
+ <xsd:complexType name="packet-struct-copy">
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ <xsd:attribute name="number" type="xsd:integer" use="required" />
+ <xsd:attribute name="ref" type="xsd:string" use="required" />
+ </xsd:complexType>
+
+ <!-- Type for hex integers -->
+ <xsd:simpleType name="hex-integer">
+ <xsd:restriction base="xsd:string">
+ <xsd:pattern value="0x[0-9a-fA-F]+" />
+ </xsd:restriction>
+ </xsd:simpleType>
+
+ <!-- Type for integers in either decimal or hex -->
+ <xsd:simpleType name="dec-or-hex-integer">
+ <xsd:union memberTypes="xsd:integer hex-integer" />
+ </xsd:simpleType>
+
+ <!-- Type for documentation -->
+ <xsd:group name="doc-fields">
+ <xsd:sequence>
+ <xsd:element name="field">
+ <xsd:complexType>
+ <xsd:simpleContent>
+ <xsd:extension base="xsd:string">
+ <xsd:attribute name="name" type="xsd:string" />
+ </xsd:extension>
+ </xsd:simpleContent>
+ </xsd:complexType>
+ </xsd:element>
+ </xsd:sequence>
+ </xsd:group>
+
+ <xsd:group name="error-fields">
+ <xsd:sequence>
+ <xsd:element name="error">
+ <xsd:complexType>
+ <xsd:simpleContent>
+ <xsd:extension base="xsd:string">
+ <xsd:attribute name="type" type="xsd:string" />
+ </xsd:extension>
+ </xsd:simpleContent>
+ </xsd:complexType>
+ </xsd:element>
+ </xsd:sequence>
+ </xsd:group>
+
+ <xsd:group name="see-fields">
+ <xsd:sequence>
+ <xsd:element name="see">
+ <xsd:complexType>
+ <xsd:attribute name="name" type="xsd:string" />
+ <xsd:attribute name="type" type="xsd:string" />
+ </xsd:complexType>
+ </xsd:element>
+ </xsd:sequence>
+ </xsd:group>
+
+ <xsd:element name="doc">
+ <xsd:complexType mixed="true">
+ <xsd:sequence>
+ <xsd:element name="brief" type="xsd:string" minOccurs="0" maxOccurs="1" />
+ <xsd:element name="description" type="xsd:string" minOccurs="0" maxOccurs="1" />
+ <xsd:element name="example" type="xsd:string" minOccurs="0" maxOccurs="1" />
+ <xsd:group ref="doc-fields" minOccurs="0" maxOccurs="unbounded" />
+ <xsd:group ref="error-fields" minOccurs="0" maxOccurs="unbounded" />
+ <xsd:group ref="see-fields" minOccurs="0" maxOccurs="unbounded" />
+ </xsd:sequence>
+ </xsd:complexType>
+ </xsd:element>
+
+ <xsd:group name="macro">
+ <xsd:choice>
+ <xsd:element name="request">
+ <xsd:complexType>
+ <xsd:sequence>
+ <xsd:choice minOccurs="0" maxOccurs="unbounded">
+ <xsd:group ref="fields" />
+ <xsd:element ref="exprfield" />
+ <xsd:element ref="valueparam" />
+ </xsd:choice>
+ <xsd:choice minOccurs="0" maxOccurs="1">
+ <xsd:element ref="switch" />
+ </xsd:choice>
+ <xsd:element name="reply" minOccurs="0" maxOccurs="1">
+ <xsd:complexType>
+ <xsd:sequence>
+ <xsd:choice minOccurs="1" maxOccurs="unbounded">
+ <xsd:group ref="fields" />
+ <xsd:element ref="valueparam" />
+ </xsd:choice>
+ <xsd:choice minOccurs="0" maxOccurs="1">
+ <xsd:element ref="switch" />
+ </xsd:choice>
+ <xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
+ </xsd:sequence>
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
+ </xsd:sequence>
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ <xsd:attribute name="opcode" type="xsd:integer" use="required" />
+ <xsd:attribute name="combine-adjacent" type="xsd:boolean"
+ use="optional"/>
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="event">
+ <xsd:complexType>
+ <xsd:complexContent>
+ <xsd:extension base="packet-struct">
+ <xsd:sequence>
+ <xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
+ </xsd:sequence>
+ <xsd:attribute name="no-sequence-number" type="xsd:boolean"
+ use="optional" />
+ </xsd:extension>
+ </xsd:complexContent>
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="eventcopy" type="packet-struct-copy" />
+ <xsd:element name="error" type="packet-struct" />
+ <xsd:element name="errorcopy" type="packet-struct-copy" />
+ <xsd:element name="struct" type="struct" />
+ <xsd:element name="union" type="struct" />
+ <xsd:element name="xidtype">
+ <xsd:complexType>
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="xidunion">
+ <xsd:complexType>
+ <xsd:sequence>
+ <xsd:element name="type" type="xsd:string"
+ minOccurs="1" maxOccurs="unbounded" />
+ </xsd:sequence>
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="enum">
+ <xsd:complexType>
+ <xsd:sequence minOccurs="1" maxOccurs="unbounded">
+ <xsd:element name="item">
+ <xsd:complexType>
+ <xsd:group ref="expression" minOccurs="0" maxOccurs="1" />
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
+ </xsd:sequence>
+ <xsd:attribute name="name" type="xsd:string" use="required" />
+ </xsd:complexType>
+ </xsd:element>
+ <xsd:element name="typedef">
+ <xsd:complexType>
+ <xsd:attribute name="oldname" type="xsd:string" use="required" />
+ <xsd:attribute name="newname" type="xsd:string" use="required" />
+ </xsd:complexType>
+ </xsd:element>
+ <!-- The import element allows a protocol description to reference the
+ declarations of another protocol description. -->
+ <xsd:element name="import" type="xsd:string" />
+ </xsd:choice>
+ </xsd:group>
+</xsd:schema>
diff --git a/libxcb/xcb-proto/src/xproto.xml b/libxcb/xcb-proto/src/xproto.xml
index 42a6852a1..bf4dcbf0f 100644
--- a/libxcb/xcb-proto/src/xproto.xml
+++ b/libxcb/xcb-proto/src/xproto.xml
@@ -307,6 +307,44 @@ authorization from the authors.
<field type="CARD16" name="state" mask="KeyButMask" />
<field type="BOOL" name="same_screen" />
<pad bytes="1" />
+ <doc>
+ <brief>a key was pressed/released</brief>
+ <field name="detail"><![CDATA[
+The keycode (a number representing a physical key on the keyboard) of the key
+which was pressed.
+ ]]></field>
+ <field name="time"><![CDATA[
+Time when the event was generated (in milliseconds).
+ ]]></field>
+ <field name="root"><![CDATA[
+The root window of `child`.
+ ]]></field>
+ <field name="same_screen"><![CDATA[
+Whether the `event` window is on the same screen as the `root` window.
+ ]]></field>
+ <field name="event_x"><![CDATA[
+If `same_screen` is true, this is the X coordinate relative to the `event`
+window's origin. Otherwise, `event_x` will be set to zero.
+ ]]></field>
+ <field name="event_y"><![CDATA[
+If `same_screen` is true, this is the Y coordinate relative to the `event`
+window's origin. Otherwise, `event_y` will be set to zero.
+ ]]></field>
+ <field name="root_x"><![CDATA[
+The X coordinate of the pointer relative to the `root` window at the time of
+the event.
+ ]]></field>
+ <field name="root_y"><![CDATA[
+The Y coordinate of the pointer relative to the `root` window at the time of
+the event.
+ ]]></field>
+ <field name="state"><![CDATA[
+The logical state of the pointer buttons and modifier keys just prior to the
+event.
+ ]]></field>
+ <see type="request" name="GrabKey" />
+ <see type="request" name="GrabKeyboard" />
+ </doc>
</event>
<eventcopy name="KeyRelease" number="3" ref="KeyPress" />
@@ -333,6 +371,44 @@ authorization from the authors.
<field type="CARD16" name="state" mask="KeyButMask" />
<field type="BOOL" name="same_screen" />
<pad bytes="1" />
+ <doc>
+ <brief>a mouse button was pressed/released</brief>
+ <field name="detail"><![CDATA[
+The keycode (a number representing a physical key on the keyboard) of the key
+which was pressed.
+ ]]></field>
+ <field name="time"><![CDATA[
+Time when the event was generated (in milliseconds).
+ ]]></field>
+ <field name="root"><![CDATA[
+The root window of `child`.
+ ]]></field>
+ <field name="same_screen"><![CDATA[
+Whether the `event` window is on the same screen as the `root` window.
+ ]]></field>
+ <field name="event_x"><![CDATA[
+If `same_screen` is true, this is the X coordinate relative to the `event`
+window's origin. Otherwise, `event_x` will be set to zero.
+ ]]></field>
+ <field name="event_y"><![CDATA[
+If `same_screen` is true, this is the Y coordinate relative to the `event`
+window's origin. Otherwise, `event_y` will be set to zero.
+ ]]></field>
+ <field name="root_x"><![CDATA[
+The X coordinate of the pointer relative to the `root` window at the time of
+the event.
+ ]]></field>
+ <field name="root_y"><![CDATA[
+The Y coordinate of the pointer relative to the `root` window at the time of
+the event.
+ ]]></field>
+ <field name="state"><![CDATA[
+The logical state of the pointer buttons and modifier keys just prior to the
+event.
+ ]]></field>
+ <see type="request" name="GrabButton" />
+ <see type="request" name="GrabPointer" />
+ </doc>
</event>
<eventcopy name="ButtonRelease" number="5" ref="ButtonPress" />
@@ -356,6 +432,44 @@ authorization from the authors.
<field type="CARD16" name="state" mask="KeyButMask" />
<field type="BOOL" name="same_screen" />
<pad bytes="1" />
+ <doc>
+ <brief>a key was pressed</brief>
+ <field name="detail"><![CDATA[
+The keycode (a number representing a physical key on the keyboard) of the key
+which was pressed.
+ ]]></field>
+ <field name="time"><![CDATA[
+Time when the event was generated (in milliseconds).
+ ]]></field>
+ <field name="root"><![CDATA[
+The root window of `child`.
+ ]]></field>
+ <field name="same_screen"><![CDATA[
+Whether the `event` window is on the same screen as the `root` window.
+ ]]></field>
+ <field name="event_x"><![CDATA[
+If `same_screen` is true, this is the X coordinate relative to the `event`
+window's origin. Otherwise, `event_x` will be set to zero.
+ ]]></field>
+ <field name="event_y"><![CDATA[
+If `same_screen` is true, this is the Y coordinate relative to the `event`
+window's origin. Otherwise, `event_y` will be set to zero.
+ ]]></field>
+ <field name="root_x"><![CDATA[
+The X coordinate of the pointer relative to the `root` window at the time of
+the event.
+ ]]></field>
+ <field name="root_y"><![CDATA[
+The Y coordinate of the pointer relative to the `root` window at the time of
+the event.
+ ]]></field>
+ <field name="state"><![CDATA[
+The logical state of the pointer buttons and modifier keys just prior to the
+event.
+ ]]></field>
+ <see type="request" name="GrabKey" />
+ <see type="request" name="GrabKeyboard" />
+ </doc>
</event>
<enum name="NotifyDetail">
@@ -389,6 +503,34 @@ authorization from the authors.
<field type="CARD16" name="state" mask="KeyButMask" />
<field type="BYTE" name="mode" enum="NotifyMode" />
<field type="BYTE" name="same_screen_focus" />
+ <doc>
+ <brief>the pointer is in a different window</brief>
+ <field name="event"><![CDATA[
+The reconfigured window or its parent, depending on whether `StructureNotify`
+or `SubstructureNotify` was selected.
+ ]]></field>
+ <field name="window"><![CDATA[
+The window that was unmapped.
+ ]]></field>
+ <field name="root"><![CDATA[
+The root window for the final cursor position.
+ ]]></field>
+ <field name="root_x"><![CDATA[
+The pointer X coordinate relative to `root`'s origin at the time of the event.
+ ]]></field>
+ <field name="root_y"><![CDATA[
+The pointer Y coordinate relative to `root`'s origin at the time of the event.
+ ]]></field>
+ <field name="event_x"><![CDATA[
+If `event` is on the same screen as `root`, this is the pointer X coordinate
+relative to the event window's origin.
+ ]]></field>
+ <field name="event_y"><![CDATA[
+If `event` is on the same screen as `root`, this is the pointer Y coordinate
+relative to the event window's origin.
+ ]]></field>
+ <field name="mode" />
+ </doc>
</event>
<eventcopy name="LeaveNotify" number="8" ref="EnterNotify" />
@@ -398,6 +540,16 @@ authorization from the authors.
<field type="WINDOW" name="event" />
<field type="BYTE" name="mode" enum="NotifyMode" />
<pad bytes="3" />
+ <doc>
+ <brief>NOT YET DOCUMENTED</brief>
+ <field name="event"><![CDATA[
+The window on which the focus event was generated. This is the window used by
+the X server to report the event.
+ ]]></field>
+ <!-- enum documentation is sufficient -->
+ <field name="detail" />
+ <field name="mode" />
+ </doc>
</event>
<eventcopy name="FocusOut" number="10" ref="FocusIn" />
@@ -415,6 +567,32 @@ authorization from the authors.
<field type="CARD16" name="height" />
<field type="CARD16" name="count" />
<pad bytes="2" />
+ <doc>
+ <brief>NOT YET DOCUMENTED</brief>
+ <field name="window"><![CDATA[
+The exposed (damaged) window.
+ ]]></field>
+ <field name="x"><![CDATA[
+The X coordinate of the left-upper corner of the exposed rectangle, relative to
+the `window`'s origin.
+ ]]></field>
+ <field name="y"><![CDATA[
+The Y coordinate of the left-upper corner of the exposed rectangle, relative to
+the `window`'s origin.
+ ]]></field>
+ <field name="width"><![CDATA[
+The width of the exposed rectangle.
+ ]]></field>
+ <field name="height"><![CDATA[
+The height of the exposed rectangle.
+ ]]></field>
+ <field name="count"><![CDATA[
+The amount of `Expose` events following this one. Simple applications that do
+not want to optimize redisplay by distinguishing between subareas of its window
+can just ignore all Expose events with nonzero counts and perform full
+redisplays on events with zero counts.
+ ]]></field>
+ </doc>
</event>
<event name="GraphicsExposure" number="13">
@@ -468,6 +646,17 @@ authorization from the authors.
<pad bytes="1" />
<field type="WINDOW" name="event" />
<field type="WINDOW" name="window" />
+ <doc>
+ <brief>a window is destroyed</brief>
+ <field name="event"><![CDATA[
+The reconfigured window or its parent, depending on whether `StructureNotify`
+or `SubstructureNotify` was selected.
+ ]]></field>
+ <field name="window"><![CDATA[
+The window that is destroyed.
+ ]]></field>
+ <see type="request" name="DestroyWindow" />
+ </doc>
</event>
<event name="UnmapNotify" number="18">
@@ -476,6 +665,21 @@ authorization from the authors.
<field type="WINDOW" name="window" />
<field type="BOOL" name="from_configure" />
<pad bytes="3" />
+ <doc>
+ <brief>a window is unmapped</brief>
+ <field name="event"><![CDATA[
+The reconfigured window or its parent, depending on whether `StructureNotify`
+or `SubstructureNotify` was selected.
+ ]]></field>
+ <field name="window"><![CDATA[
+The window that was unmapped.
+ ]]></field>
+ <field name="from_configure"><![CDATA[
+Set to 1 if the event was generated as a result of a resizing of the window's
+parent when `window` had a win_gravity of `UnmapGravity`.
+ ]]></field>
+ <see type="request" name="UnmapWindow" />
+ </doc>
</event>
<event name="MapNotify" number="19">
@@ -484,12 +688,36 @@ authorization from the authors.
<field type="WINDOW" name="window" />
<field type="BOOL" name="override_redirect" />
<pad bytes="3" />
+ <doc>
+ <brief>a window was mapped</brief>
+ <field name="event"><![CDATA[
+The window which was mapped or its parent, depending on whether
+`StructureNotify` or `SubstructureNotify` was selected.
+ ]]></field>
+ <field name="window"><![CDATA[
+The window that was mapped.
+ ]]></field>
+ <field name="override_redirect"><![CDATA[
+Window managers should ignore this window if `override_redirect` is 1.
+ ]]></field>
+ <see type="request" name="MapWindow" />
+ </doc>
</event>
<event name="MapRequest" number="20">
<pad bytes="1" />
<field type="WINDOW" name="parent" />
<field type="WINDOW" name="window" />
+ <doc>
+ <brief>window wants to be mapped</brief>
+ <field name="parent"><![CDATA[
+The parent of `window`.
+ ]]></field>
+ <field name="window"><![CDATA[
+The window to be mapped.
+ ]]></field>
+ <see type="request" name="MapWindow" />
+ </doc>
</event>
<event name="ReparentNotify" number="21">
@@ -515,6 +743,42 @@ authorization from the authors.
<field type="CARD16" name="border_width" />
<field type="BOOL" name="override_redirect" />
<pad bytes="1" />
+ <doc>
+ <brief>NOT YET DOCUMENTED</brief>
+ <field name="event"><![CDATA[
+The reconfigured window or its parent, depending on whether `StructureNotify`
+or `SubstructureNotify` was selected.
+ ]]></field>
+ <field name="window"><![CDATA[
+The window whose size, position, border, and/or stacking order was changed.
+ ]]></field>
+ <field name="above_sibling"><![CDATA[
+If `XCB_NONE`, the `window` is on the bottom of the stack with respect to
+sibling windows. However, if set to a sibling window, the `window` is placed on
+top of this sibling window.
+ ]]></field>
+ <field name="x"><![CDATA[
+The X coordinate of the upper-left outside corner of `window`, relative to the
+parent window's origin.
+ ]]></field>
+ <field name="y"><![CDATA[
+The Y coordinate of the upper-left outside corner of `window`, relative to the
+parent window's origin.
+ ]]></field>
+ <field name="width"><![CDATA[
+The inside width of `window`, not including the border.
+ ]]></field>
+ <field name="height"><![CDATA[
+The inside height of `window`, not including the border.
+ ]]></field>
+ <field name="border_width"><![CDATA[
+The border width of `window`.
+ ]]></field>
+ <field name="override_redirect"><![CDATA[
+Window managers should ignore this window if `override_redirect` is 1.
+ ]]></field>
+ <see type="request" name="FreeColormap" />
+ </doc>
</event>
<event name="ConfigureRequest" number="23">
@@ -548,6 +812,14 @@ authorization from the authors.
<enum name="Place">
<item name="OnTop"> <value>0</value></item>
<item name="OnBottom"><value>1</value></item>
+ <doc>
+ <field name="OnTop"><![CDATA[
+The window is now on top of all siblings.
+ ]]></field>
+ <field name="OnBottom"><![CDATA[
+The window is now below all siblings.
+ ]]></field>
+ </doc>
</enum>
<event name="CirculateNotify" number="26">
@@ -557,6 +829,19 @@ authorization from the authors.
<pad bytes="4" />
<field type="BYTE" name="place" enum="Place" />
<pad bytes="3" />
+ <doc>
+ <brief>NOT YET DOCUMENTED</brief>
+ <field name="event"><![CDATA[
+Either the restacked window or its parent, depending on whether
+`StructureNotify` or `SubstructureNotify` was selected.
+ ]]></field>
+ <field name="window"><![CDATA[
+The restacked window.
+ ]]></field>
+ <!-- the enum doc is sufficient -->
+ <field name="place" />
+ <see type="request" name="CirculateWindow" />
+ </doc>
</event>
<eventcopy name="CirculateRequest" number="27" ref="CirculateNotify" />
@@ -573,6 +858,21 @@ authorization from the authors.
<field type="TIMESTAMP" name="time" />
<field type="BYTE" name="state" enum="Property" />
<pad bytes="3" />
+ <doc>
+ <brief>a window property changed</brief>
+ <field name="window"><![CDATA[
+The window whose associated property was changed.
+ ]]></field>
+ <field name="atom"><![CDATA[
+The property's atom, to indicate which property was changed.
+ ]]></field>
+ <field name="time"><![CDATA[
+A timestamp of the server time when the property was changed.
+ ]]></field>
+ <!-- enum documentation is sufficient -->
+ <field name="state" />
+ <see type="request" name="ChangeProperty" />
+ </doc>
</event>
<event name="SelectionClear" number="29">
@@ -681,6 +981,14 @@ authorization from the authors.
<enum name="ColormapState">
<item name="Uninstalled"><value>0</value></item>
<item name="Installed"> <value>1</value></item>
+ <doc>
+ <field name="Uninstalled"><![CDATA[
+The colormap was uninstalled.
+ ]]></field>
+ <field name="Installed"><![CDATA[
+The colormap was installed.
+ ]]></field>
+ </doc>
</enum>
<enum name="Colormap">
@@ -694,6 +1002,22 @@ authorization from the authors.
<field type="BOOL" name="new" />
<field type="BYTE" name="state" enum="ColormapState" />
<pad bytes="2" />
+ <doc>
+ <brief>the colormap for some window changed</brief>
+ <field name="window"><![CDATA[
+The window whose associated colormap is changed, installed or uninstalled.
+ ]]></field>
+ <field name="colormap"><![CDATA[
+The colormap which is changed, installed or uninstalled. This is `XCB_NONE`
+when the colormap is changed by a call to `FreeColormap`.
+ ]]></field>
+ <field name="_new"><![CDATA[
+Indicates whether the colormap was changed (1) or installed/uninstalled (0).
+ ]]></field>
+ <!-- enum doc is sufficient -->
+ <field name="state" />
+ <see type="request" name="FreeColormap" />
+ </doc>
</event>
<union name="ClientMessageData">
@@ -709,6 +1033,26 @@ authorization from the authors.
<field type="WINDOW" name="window" />
<field type="ATOM" name="type" />
<field type="ClientMessageData" name="data" />
+ <doc>
+ <brief>NOT YET DOCUMENTED</brief>
+ <description><![CDATA[
+This event represents a ClientMessage, sent by another X11 client. An example
+is a client sending the `_NET_WM_STATE` ClientMessage to the root window
+to indicate the fullscreen window state, effectively requesting that the window
+manager puts it into fullscreen mode.
+ ]]></description>
+ <field name="format"><![CDATA[
+Specifies how to interpret `data`. Can be either 8, 16 or 32.
+ ]]></field>
+ <field name="type"><![CDATA[
+An atom which indicates how the data should be interpreted by the receiving
+client.
+ ]]></field>
+ <field name="data"><![CDATA[
+The data itself (20 bytes max).
+ ]]></field>
+ <see type="request" name="SendEvent" />
+ </doc>
</event>
<enum name="Mapping">
@@ -723,6 +1067,17 @@ authorization from the authors.
<field type="KEYCODE" name="first_keycode" />
<field type="CARD8" name="count" />
<pad bytes="1" />
+ <doc>
+ <brief>keyboard mapping changed</brief>
+ <!-- enum documentation is sufficient -->
+ <field name="request" />
+ <field name="first_keycode"><![CDATA[
+The first number in the range of the altered mapping.
+ ]]></field>
+ <field name="count"><![CDATA[
+The number of keycodes altered.
+ ]]></field>
+ </doc>
</event>
@@ -791,6 +1146,106 @@ authorization from the authors.
<item name="DontPropagate"> <bit>12</bit></item>
<item name="Colormap"> <bit>13</bit></item>
<item name="Cursor"> <bit>14</bit></item>
+ <doc>
+ <field name="BackPixmap"><![CDATA[
+Overrides the default background-pixmap. The background pixmap and window must
+have the same root and same depth. Any size pixmap can be used, although some
+sizes may be faster than others.
+
+If `XCB_BACK_PIXMAP_NONE` is specified, the window has no defined background.
+The server may fill the contents with the previous screen contents or with
+contents of its own choosing.
+
+If `XCB_BACK_PIXMAP_PARENT_RELATIVE` is specified, the parent's background is
+used, but the window must have the same depth as the parent (or a Match error
+results). The parent's background is tracked, and the current version is
+used each time the window background is required.
+ ]]></field>
+ <field name="BackPixel"><![CDATA[
+Overrides `BackPixmap`. A pixmap of undefined size filled with the specified
+background pixel is used for the background. Range-checking is not performed,
+the background pixel is truncated to the appropriate number of bits.
+ ]]></field>
+ <field name="BorderPixmap"><![CDATA[
+Overrides the default border-pixmap. The border pixmap and window must have the
+same root and the same depth. Any size pixmap can be used, although some sizes
+may be faster than others.
+
+The special value `XCB_COPY_FROM_PARENT` means the parent's border pixmap is
+copied (subsequent changes to the parent's border attribute do not affect the
+child), but the window must have the same depth as the parent.
+ ]]></field>
+ <field name="BorderPixel"><![CDATA[
+Overrides `BorderPixmap`. A pixmap of undefined size filled with the specified
+border pixel is used for the border. Range checking is not performed on the
+border-pixel value, it is truncated to the appropriate number of bits.
+ ]]></field>
+ <field name="BitGravity"><![CDATA[
+Defines which region of the window should be retained if the window is resized.
+ ]]></field>
+ <field name="WinGravity"><![CDATA[
+Defines how the window should be repositioned if the parent is resized (see
+`ConfigureWindow`).
+ ]]></field>
+ <field name="BackingStore"><![CDATA[
+A backing-store of `WhenMapped` advises the server that maintaining contents of
+obscured regions when the window is mapped would be beneficial. A backing-store
+of `Always` advises the server that maintaining contents even when the window
+is unmapped would be beneficial. In this case, the server may generate an
+exposure event when the window is created. A value of `NotUseful` advises the
+server that maintaining contents is unnecessary, although a server may still
+choose to maintain contents while the window is mapped. Note that if the server
+maintains contents, then the server should maintain complete contents not just
+the region within the parent boundaries, even if the window is larger than its
+parent. While the server maintains contents, exposure events will not normally
+be generated, but the server may stop maintaining contents at any time.
+ ]]></field>
+ <field name="BackingPlanes"><![CDATA[
+The backing-planes indicates (with bits set to 1) which bit planes of the
+window hold dynamic data that must be preserved in backing-stores and during
+save-unders.
+ ]]></field>
+ <field name="BackingPixel"><![CDATA[
+The backing-pixel specifies what value to use in planes not covered by
+backing-planes. The server is free to save only the specified bit planes in the
+backing-store or save-under and regenerate the remaining planes with the
+specified pixel value. Any bits beyond the specified depth of the window in
+these values are simply ignored.
+ ]]></field>
+ <field name="OverrideRedirect"><![CDATA[
+The override-redirect specifies whether map and configure requests on this
+window should override a SubstructureRedirect on the parent, typically to
+inform a window manager not to tamper with the window.
+ ]]></field>
+ <field name="SaveUnder"><![CDATA[
+If 1, the server is advised that when this window is mapped, saving the
+contents of windows it obscures would be beneficial.
+ ]]></field>
+ <field name="EventMask"><![CDATA[
+The event-mask defines which events the client is interested in for this window
+(or for some event types, inferiors of the window).
+ ]]></field>
+ <field name="DontPropagate"><![CDATA[
+The do-not-propagate-mask defines which events should not be propagated to
+ancestor windows when no client has the event type selected in this window.
+ ]]></field>
+ <field name="Colormap"><![CDATA[
+The colormap specifies the colormap that best reflects the true colors of the window. Servers
+capable of supporting multiple hardware colormaps may use this information, and window man-
+agers may use it for InstallColormap requests. The colormap must have the same visual type
+and root as the window (or a Match error results). If CopyFromParent is specified, the parent's
+colormap is copied (subsequent changes to the parent's colormap attribute do not affect the child).
+However, the window must have the same visual type as the parent (or a Match error results),
+and the parent must not have a colormap of None (or a Match error results). For an explanation
+of None, see FreeColormap request. The colormap is copied by sharing the colormap object
+between the child and the parent, not by making a complete copy of the colormap contents.
+ ]]></field>
+ <field name="Cursor"><![CDATA[
+If a cursor is specified, it will be used whenever the pointer is in the window. If None is speci-
+fied, the parent's cursor will be used when the pointer is in the window, and any change in the
+parent's cursor will cause an immediate change in the displayed cursor.
+ ]]></field>
+ </doc>
</enum>
<enum name="BackPixmap">
@@ -827,6 +1282,79 @@ authorization from the authors.
<valueparam value-mask-type="CARD32"
value-mask-name="value_mask"
value-list-name="value_list" />
+ <doc>
+ <brief>Creates a window</brief>
+ <description><![CDATA[
+Creates an unmapped window as child of the specified `parent` window. A
+CreateNotify event will be generated. The new window is placed on top in the
+stacking order with respect to siblings.
+
+The coordinate system has the X axis horizontal and the Y axis vertical with
+the origin [0, 0] at the upper-left corner. Coordinates are integral, in terms
+of pixels, and coincide with pixel centers. Each window and pixmap has its own
+coordinate system. For a window, the origin is inside the border at the inside,
+upper-left corner.
+
+The created window is not yet displayed (mapped), call `xcb_map_window` to
+display it.
+
+The created window will initially use the same cursor as its parent.
+ ]]></description>
+ <field name="wid"><![CDATA[
+The ID with which you will refer to the new window, created by
+`xcb_generate_id`.
+ ]]></field>
+ <field name="depth"><![CDATA[
+Specifies the new window's depth (TODO: what unit?).
+
+The special value `XCB_COPY_FROM_PARENT` means the depth is taken from the
+`parent` window.
+ ]]></field>
+ <field name="visual"><![CDATA[
+Specifies the id for the new window's visual.
+
+The special value `XCB_COPY_FROM_PARENT` means the visual is taken from the
+`parent` window.
+ ]]></field>
+ <field name="class"></field>
+ <field name="parent"><![CDATA[
+The parent window of the new window.
+ ]]></field>
+ <field name="border_width"><![CDATA[
+ TODO:
+
+Must be zero if the `class` is `InputOnly` or a `xcb_match_error_t` occurs.
+ ]]></field>
+ <field name="x"><![CDATA[The X coordinate of the new window.]]></field>
+ <field name="y"><![CDATA[The Y coordinate of the new window.]]></field>
+ <field name="width"><![CDATA[The width of the new window.]]></field>
+ <field name="height"><![CDATA[The height of the new window.]]></field>
+ <error type="Colormap"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Cursor"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Pixmap"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Window"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+ ]]></error>
+ <see type="function" name="xcb_generate_id" />
+ <see type="request" name="MapWindow" />
+ <see type="event" name="CreateNotify" />
+ </doc>
+
</request>
<request name="ChangeWindowAttributes" opcode="2">
@@ -835,6 +1363,43 @@ authorization from the authors.
<valueparam value-mask-type="CARD32"
value-mask-name="value_mask"
value-list-name="value_list" />
+ <doc>
+ <brief>change window attributes</brief>
+ <description><![CDATA[
+Changes the attributes specified by `value_mask` for the specified `window`.
+ ]]></description>
+ <field name="window"><![CDATA[
+The window to change.
+ ]]></field>
+ <!-- the enum documentation is good enough. -->
+ <field name="value_mask" />
+ <field name="value_list"><![CDATA[
+Values for each of the attributes specified in the bitmask `value_mask`. The
+order has to correspond to the order of possible `value_mask` bits. See the
+example.
+ ]]></field>
+ <error type="Access"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Colormap"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Cursor"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Pixmap"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ </doc>
</request>
<enum name="MapState">
@@ -863,12 +1428,79 @@ authorization from the authors.
<field type="CARD32" name="your_event_mask" mask="EventMask" />
<field type="CARD16" name="do_not_propagate_mask" mask="EventMask" />
<pad bytes="2" />
+ <doc>
+ <field name="override_redirect"><![CDATA[
+Window managers should ignore this window if `override_redirect` is 1.
+ ]]></field>
+ <field name="visual"><![CDATA[
+The associated visual structure of `window`.
+ ]]></field>
+ <field name="backing_planes"><![CDATA[
+Planes to be preserved if possible.
+ ]]></field>
+ <field name="backing_pixel"><![CDATA[
+Value to be used when restoring planes.
+ ]]></field>
+ <field name="save_under"><![CDATA[
+Boolean, should bits under be saved?
+ ]]></field>
+ <field name="colormap"><![CDATA[
+Color map to be associated with window.
+ ]]></field>
+ <field name="all_event_masks"><![CDATA[
+Set of events all people have interest in.
+ ]]></field>
+ <field name="your_event_mask"><![CDATA[
+My event mask.
+ ]]></field>
+ <field name="do_not_propagate_mask"><![CDATA[
+Set of events that should not propagate.
+ ]]></field>
+ <!-- enum documentation is sufficient for these fields -->
+ <field name="backing_store" />
+ <field name="class" />
+ <field name="bit_gravity" />
+ <field name="win_gravity" />
+ <field name="map_state" />
+ </doc>
</reply>
+ <doc>
+ <brief>Gets window attributes</brief>
+ <description><![CDATA[
+Gets the current attributes for the specified `window`.
+ ]]></description>
+ <field name="window"><![CDATA[The window to get the attributes from.]]></field>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ <error type="Drawable"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ </doc>
+
</request>
<request name="DestroyWindow" opcode="4">
<pad bytes="1" />
<field type="WINDOW" name="window" />
+ <doc>
+ <brief>Destroys a window</brief>
+ <description><![CDATA[
+Destroys the specified window and all of its subwindows. A DestroyNotify event
+is generated for each destroyed window (a DestroyNotify event is first generated
+for any given window's inferiors). If the window was mapped, it will be
+automatically unmapped before destroying.
+
+Calling DestroyWindow on the root window will do nothing.
+ ]]></description>
+ <field name="window"><![CDATA[The window to destroy.]]></field>
+ <error type="Window"><![CDATA[
+The specified window does not exist.
+ ]]></error>
+ <see type="event" name="DestroyNotify" />
+ <see type="request" name="MapWindow" />
+ <see type="request" name="UnmapWindow" />
+ </doc>
</request>
<request name="DestroySubwindows" opcode="5">
@@ -884,6 +1516,28 @@ authorization from the authors.
<request name="ChangeSaveSet" opcode="6">
<field type="BYTE" name="mode" enum="SetMode" />
<field type="WINDOW" name="window" />
+ <doc>
+ <brief>Changes a client's save set</brief>
+ <description><![CDATA[
+TODO: explain what the save set is for.
+
+This function either adds or removes the specified window to the client's (your
+application's) save set.
+ ]]></description>
+ <field name="mode"><![CDATA[Insert to add the specified window to the save set or Delete to delete it from the save set.]]></field>
+ <field name="window"><![CDATA[The window to add or delete to/from your save set.]]></field>
+ <error type="Match"><![CDATA[
+You created the specified window. This does not make sense, you can only add
+windows created by other clients to your save set.
+ ]]></error>
+ <error type="Value"><![CDATA[
+You specified an invalid mode.
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified window does not exist.
+ ]]></error>
+ <see type="request" name="ReparentWindow" />
+ </doc>
</request>
<request name="ReparentWindow" opcode="7">
@@ -892,11 +1546,78 @@ authorization from the authors.
<field type="WINDOW" name="parent" />
<field type="INT16" name="x" />
<field type="INT16" name="y" />
+ <doc>
+ <brief>Reparents a window</brief>
+ <description><![CDATA[
+Makes the specified window a child of the specified parent window. If the
+window is mapped, it will automatically be unmapped before reparenting and
+re-mapped after reparenting. The window is placed in the stacking order on top
+with respect to sibling windows.
+
+After reparenting, a ReparentNotify event is generated.
+ ]]></description>
+ <field name="window"><![CDATA[The window to reparent.]]></field>
+ <field name="parent"><![CDATA[The new parent of the window.]]></field>
+ <field name="x"><![CDATA[
+The X position of the window within its new parent.
+ ]]></field>
+ <field name="y"><![CDATA[
+The Y position of the window within its new parent.
+ ]]></field>
+ <error type="Match"><![CDATA[
+The new parent window is not on the same screen as the old parent window.
+
+The new parent window is the specified window or an inferior of the specified window.
+
+The new parent is InputOnly and the window is not.
+
+The specified window has a ParentRelative background and the new parent window is not the same depth as the specified window.
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified window does not exist.
+ ]]></error>
+ <see type="event" name="ReparentNotify" />
+ <see type="request" name="MapWindow" />
+ <see type="request" name="UnmapWindow" />
+ </doc>
</request>
<request name="MapWindow" opcode="8">
<pad bytes="1" />
<field type="WINDOW" name="window" />
+ <doc>
+ <brief>Makes a window visible</brief>
+ <description><![CDATA[
+Maps the specified window. This means making the window visible (as long as its
+parent is visible).
+
+This MapWindow request will be translated to a MapRequest request if a window
+manager is running. The window manager then decides to either map the window or
+not. Set the override-redirect window attribute to true if you want to bypass
+this mechanism.
+
+If the window manager decides to map the window (or if no window manager is
+running), a MapNotify event is generated.
+
+If the window becomes viewable and no earlier contents for it are remembered,
+the X server tiles the window with its background. If the window's background
+is undefined, the existing screen contents are not altered, and the X server
+generates zero or more Expose events.
+
+If the window type is InputOutput, an Expose event will be generated when the
+window becomes visible. The normal response to an Expose event should be to
+repaint the window.
+ ]]></description>
+ <field name="window"><![CDATA[
+The window to make visible.
+]]></field>
+ <error type="Match"><![CDATA[
+The specified window does not exist.
+ ]]></error>
+ <see type="event" name="MapNotify" />
+ <see type="event" name="Expose" />
+ <see type="request" name="UnmapWindow" />
+ </doc>
</request>
<request name="MapSubwindows" opcode="9">
@@ -907,6 +1628,25 @@ authorization from the authors.
<request name="UnmapWindow" opcode="10">
<pad bytes="1" />
<field type="WINDOW" name="window" />
+ <doc>
+ <brief>Makes a window invisible</brief>
+ <description><![CDATA[
+Unmaps the specified window. This means making the window invisible (and all
+its child windows).
+
+Unmapping a window leads to the `UnmapNotify` event being generated. Also,
+`Expose` events are generated for formerly obscured windows.
+ ]]></description>
+ <field name="window"><![CDATA[
+The window to make invisible.
+]]></field>
+ <error type="Window"><![CDATA[
+The specified window does not exist.
+ ]]></error>
+ <see type="event" name="UnmapNotify" />
+ <see type="event" name="Expose" />
+ <see type="request" name="MapWindow" />
+ </doc>
</request>
<request name="UnmapSubwindows" opcode="11">
@@ -940,6 +1680,55 @@ authorization from the authors.
<valueparam value-mask-type="CARD16"
value-mask-name="value_mask"
value-list-name="value_list" />
+ <doc>
+ <brief>Configures window attributes</brief>
+ <description><![CDATA[
+Configures a window's size, position, border width and stacking order.
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Configures the given window to the left upper corner
+ * with a size of 1024x768 pixels.
+ *
+ */
+void my_example(xcb_connection *c, xcb_window_t window) {
+ uint16_t mask = 0;
+
+ mask |= XCB_CONFIG_WINDOW_X;
+ mask |= XCB_CONFIG_WINDOW_Y;
+ mask |= XCB_CONFIG_WINDOW_WIDTH;
+ mask |= XCB_CONFIG_WINDOW_HEIGHT;
+
+ const uint32_t values[] = {
+ 0, /* x */
+ 0, /* y */
+ 1024, /* width */
+ 768 /* height */
+ };
+
+ xcb_configure_window(c, window, mask, values);
+ xcb_flush(c);
+}
+ ]]></example>
+ <field name="window"><![CDATA[The window to configure.]]></field>
+ <field name="value_mask"><![CDATA[Bitmask of attributes to change.]]></field>
+ <field name="value_list"><![CDATA[
+New values, corresponding to the attributes in value_mask. The order has to
+correspond to the order of possible `value_mask` bits. See the example.
+ ]]></field>
+ <error type="Match"><![CDATA[
+You specified a Sibling without also specifying StackMode or the window is not
+actually a Sibling.
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified window does not exist. TODO: any other reason?
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <see type="event" name="MapNotify" />
+ <see type="event" name="Expose" />
+ </doc>
</request>
<enum name="Circulate">
@@ -950,6 +1739,27 @@ authorization from the authors.
<request name="CirculateWindow" opcode="13">
<field type="CARD8" name="direction" enum="Circulate" />
<field type="WINDOW" name="window" />
+ <doc>
+ <brief>Change window stacking order</brief>
+ <description><![CDATA[
+If `direction` is `XCB_CIRCULATE_RAISE_LOWEST`, the lowest mapped child (if
+any) will be raised to the top of the stack.
+
+If `direction` is `XCB_CIRCULATE_LOWER_HIGHEST`, the highest mapped child will
+be lowered to the bottom of the stack.
+ ]]></description>
+ <!-- The enums are documented, we have nothing to add. -->
+ <field name="direction" />
+ <field name="window"><![CDATA[
+The window to raise/lower (depending on `direction`).
+ ]]></field>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ <error type="Value"><![CDATA[
+The specified `direction` is invalid.
+ ]]></error>
+ </doc>
</request>
<request name="GetGeometry" opcode="14">
@@ -964,7 +1774,67 @@ authorization from the authors.
<field type="CARD16" name="height" />
<field type="CARD16" name="border_width" />
<pad bytes="2" />
+ <doc>
+ <field name="root"><![CDATA[
+Root window of the screen containing `drawable`.
+ ]]></field>
+ <field name="x"><![CDATA[
+The X coordinate of `drawable`. If `drawable` is a window, the coordinate
+specifies the upper-left outer corner relative to its parent's origin. If
+`drawable` is a pixmap, the X coordinate is always 0.
+ ]]></field>
+ <field name="y"><![CDATA[
+The Y coordinate of `drawable`. If `drawable` is a window, the coordinate
+specifies the upper-left outer corner relative to its parent's origin. If
+`drawable` is a pixmap, the Y coordinate is always 0.
+ ]]></field>
+ <field name="width"><![CDATA[
+The width of `drawable`.
+ ]]></field>
+ <field name="height"><![CDATA[
+The height of `drawable`.
+ ]]></field>
+ <field name="border_width"><![CDATA[
+The border width (in pixels).
+ ]]></field>
+ <field name="depth"><![CDATA[
+The depth of the drawable (bits per pixel for the object).
+ ]]></field>
+ </doc>
</reply>
+ <doc>
+ <brief>Get current window geometry</brief>
+ <description><![CDATA[
+Gets the current geometry of the specified drawable (either `Window` or `Pixmap`).
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Displays the x and y position of the given window.
+ *
+ */
+void my_example(xcb_connection *c, xcb_window_t window) {
+ xcb_get_geometry_cookie_t cookie;
+ xcb_get_geometry_reply_t *reply;
+
+ cookie = xcb_get_geometry(c, window);
+ /* ... do other work here if possible ... */
+ if ((reply = xcb_get_geometry_reply(c, cookie, NULL))) {
+ printf("This window is at %d, %d\\n", reply->x, reply->y);
+ }
+ free(reply);
+}
+ ]]></example>
+ <field name="drawable"><![CDATA[
+The drawable (`Window` or `Pixmap`) of which the geometry will be received.
+ ]]></field>
+ <error type="Drawable"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Window"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <see type="program" name="xwininfo" />
+ </doc>
</request>
<request name="QueryTree" opcode="15">
@@ -979,7 +1849,51 @@ authorization from the authors.
<list type="WINDOW" name="children">
<fieldref>children_len</fieldref>
</list>
+ <doc>
+ <field name="root"><![CDATA[
+The root window of `window`.
+ ]]></field>
+ <field name="parent"><![CDATA[
+The parent window of `window`.
+ ]]></field>
+ <field name="children_len"><![CDATA[
+The number of child windows.
+ ]]></field>
+ </doc>
</reply>
+ <doc>
+ <brief>query the window tree</brief>
+ <description><![CDATA[
+Gets the root window ID, parent window ID and list of children windows for the
+specified `window`. The children are listed in bottom-to-top stacking order.
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Displays the root, parent and children of the specified window.
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+ xcb_query_tree_cookie_t cookie;
+ xcb_query_tree_reply_t *reply;
+
+ cookie = xcb_query_tree(conn, window);
+ if ((reply = xcb_query_tree_reply(conn, cookie, NULL))) {
+ printf("root = 0x%08x\\n", reply->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);
+ }
+}
+ ]]></example>
+ <field name="window"><![CDATA[
+The `window` to query.
+ ]]></field>
+ <see type="program" name="xwininfo" />
+ </doc>
</request>
<request name="InternAtom" opcode="16">
@@ -993,6 +1907,53 @@ authorization from the authors.
<pad bytes="1" />
<field type="ATOM" name="atom" altenum="Atom" />
</reply>
+ <doc>
+ <brief>Get atom identifier by name</brief>
+ <description><![CDATA[
+Retrieves the identifier (xcb_atom_t TODO) for the atom with the specified
+name. Atoms are used in protocols like EWMH, for example to store window titles
+(`_NET_WM_NAME` atom) as property of a window.
+
+If `only_if_exists` is 0, the atom will be created if it does not already exist.
+If `only_if_exists` is 1, `XCB_ATOM_NONE` will be returned if the atom does
+not yet exist.
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Resolves the _NET_WM_NAME atom.
+ *
+ */
+void my_example(xcb_connection *c) {
+ xcb_intern_atom_cookie_t cookie;
+ xcb_intern_atom_reply_t *reply;
+
+ cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
+ /* ... do other work here if possible ... */
+ if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) {
+ printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
+ free(reply);
+ }
+}
+ ]]></example>
+ <field name="name_len"><![CDATA[
+The length of the following `name`.
+ ]]></field>
+ <field name="name"><![CDATA[
+The name of the atom.
+ ]]></field>
+ <field name="only_if_exists"><![CDATA[
+Return a valid atom id only if the atom already exists.
+ ]]></field>
+ <error type="Alloc"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Value"><![CDATA[
+A value other than 0 or 1 was specified for `only_if_exists`.
+ ]]></error>
+ <see type="program" name="xlsatoms" />
+ <see type="request" name="GetAtomName" />
+ </doc>
+
</request>
<request name="GetAtomName" opcode="17">
@@ -1012,6 +1973,21 @@ authorization from the authors.
<item name="Replace"><value>0</value></item>
<item name="Prepend"><value>1</value></item>
<item name="Append"> <value>2</value></item>
+ <doc>
+ <field name="Replace"><![CDATA[
+Discard the previous property value and store the new data.
+ ]]></field>
+ <field name="Prepend"><![CDATA[
+Insert the new data before the beginning of existing data. The `format` must
+match existing property value. If the property is undefined, it is treated as
+defined with the correct type and format with zero-length data.
+ ]]></field>
+ <field name="Append"><![CDATA[
+Insert the new data after the beginning of existing data. The `format` must
+match existing property value. If the property is undefined, it is treated as
+defined with the correct type and format with zero-length data.
+ ]]></field>
+ </doc>
</enum>
<request name="ChangeProperty" opcode="18">
@@ -1031,6 +2007,71 @@ authorization from the authors.
<value>8</value>
</op>
</list>
+ <doc>
+ <brief>Changes a window property</brief>
+ <description><![CDATA[
+Sets or updates a property on the specified `window`. Properties are for
+example the window title (`WM_NAME`) or its minimum size (`WM_NORMAL_HINTS`).
+Protocols such as EWMH also use properties - for example EWMH defines the
+window title, encoded as UTF-8 string, in the `_NET_WM_NAME` property.
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Sets the WM_NAME property of the window to "XCB Example".
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+ xcb_change_property(conn,
+ XCB_PROP_MODE_REPLACE,
+ window,
+ XCB_ATOM_WM_NAME,
+ XCB_ATOM_STRING,
+ 8,
+ strlen("XCB Example"),
+ "XCB Example");
+ xcb_flush(conn);
+}
+ ]]></example>
+ <field name="window"><![CDATA[
+The window whose property you want to change.
+ ]]></field>
+ <!-- the enum doc is sufficient. -->
+ <field name="mode" />
+ <field name="property"><![CDATA[
+The property you want to change (an atom).
+ ]]></field>
+ <field name="type"><![CDATA[
+The type of the property you want to change (an atom).
+ ]]></field>
+ <field name="format"><![CDATA[
+Specifies whether the data should be viewed as a list of 8-bit, 16-bit or
+32-bit quantities. Possible values are 8, 16 and 32. This information allows
+the X server to correctly perform byte-swap operations as necessary.
+ ]]></field>
+ <field name="data_len"><![CDATA[
+Specifies the number of elements (see `format`).
+ ]]></field>
+ <field name="data"><![CDATA[
+The property data.
+ ]]></field>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ <error type="Atom"><![CDATA[
+`property` or `type` do not refer to a valid atom.
+ ]]></error>
+ <error type="Alloc"><![CDATA[
+The X server could not store the property (no memory?).
+ ]]></error>
+ <see type="request" name="InternAtom" />
+ <see type="program" name="xprop" />
+ </doc>
</request>
<request name="DeleteProperty" opcode="19">
@@ -1057,15 +2098,110 @@ authorization from the authors.
<field type="CARD32" name="value_len" />
<pad bytes="12" />
<list type="void" name="value">
- <op op="*">
- <fieldref>value_len</fieldref>
- <op op="/">
- <fieldref>format</fieldref>
- <value>8</value>
- </op>
- </op>
+ <op op="*">
+ <fieldref>value_len</fieldref>
+ <op op="/">
+ <fieldref>format</fieldref>
+ <value>8</value>
+ </op>
+ </op>
</list>
+ <doc>
+ <field name="format"><![CDATA[
+Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or
+32-bit quantities. Possible values are 8, 16, and 32. This information allows
+the X server to correctly perform byte-swap operations as necessary.
+ ]]></field>
+ <field name="type"><![CDATA[
+The actual type of the property (an atom).
+ ]]></field>
+ <field name="bytes_after"><![CDATA[
+The number of bytes remaining to be read in the property if a partial read was
+performed.
+ ]]></field>
+ <field name="value_len"><![CDATA[
+The length of value. You should use the corresponding accessor instead of this
+field.
+ ]]></field>
+ </doc>
</reply>
+ <doc>
+ <brief>Gets a window property</brief>
+ <description><![CDATA[
+Gets the specified `property` from the specified `window`. Properties are for
+example the window title (`WM_NAME`) or its minimum size (`WM_NORMAL_HINTS`).
+Protocols such as EWMH also use properties - for example EWMH defines the
+window title, encoded as UTF-8 string, in the `_NET_WM_NAME` property.
+
+TODO: talk about `type`
+
+TODO: talk about `delete`
+
+TODO: talk about the offset/length thing. what's a valid use case?
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Prints the WM_NAME property of the window.
+ *
+ */
+void my_example(xcb_connection *c, xcb_window_t window) {
+ xcb_get_property_cookie_t cookie;
+ xcb_get_property_reply_t *reply;
+
+ /* These atoms are predefined in the X11 protocol. */
+ xcb_atom_t property = XCB_ATOM_WM_NAME;
+ xcb_atom_t type = XCB_ATOM_STRING;
+
+ // TODO: a reasonable long_length for WM_NAME?
+ cookie = xcb_get_property(c, 0, window, property, type, 0, 0);
+ if ((reply = xcb_get_property_reply(c, cookie, NULL))) {
+ int len = xcb_get_property_value_length(reply);
+ if (len == 0) {
+ printf("TODO\\n");
+ free(reply);
+ return;
+ }
+ printf("WM_NAME is %.*s\\n", len,
+ (char*)xcb_get_property_value(reply));
+ }
+ free(reply);
+}
+ ]]></example>
+ <field name="window"><![CDATA[
+The window whose property you want to get.
+ ]]></field>
+ <field name="delete"><![CDATA[
+Whether the property should actually be deleted. For deleting a property, the
+specified `type` has to match the actual property type.
+ ]]></field>
+ <field name="property"><![CDATA[
+The property you want to get (an atom).
+ ]]></field>
+ <field name="type"><![CDATA[
+The type of the property you want to get (an atom).
+ ]]></field>
+ <field name="long_offset"><![CDATA[
+Specifies the offset (in 32-bit multiples) in the specified property where the
+data is to be retrieved.
+ ]]></field>
+ <field name="long_length"><![CDATA[
+Specifies how many 32-bit multiples of data should be retrieved (e.g. if you
+set `long_length` to 4, you will receive 16 bytes of data).
+ ]]></field>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ <error type="Atom"><![CDATA[
+`property` or `type` do not refer to a valid atom.
+ ]]></error>
+ <error type="Value"><![CDATA[
+The specified `long_offset` is beyond the actual property length (e.g. the
+property has a length of 3 bytes and you are setting `long_offset` to 1,
+resulting in a byte offset of 4).
+ ]]></error>
+ <see type="request" name="InternAtom" />
+ <see type="program" name="xprop" />
+ </doc>
</request>
<request name="ListProperties" opcode="21">
@@ -1086,6 +2222,38 @@ authorization from the authors.
<field type="WINDOW" name="owner" altenum="Window" />
<field type="ATOM" name="selection" />
<field type="TIMESTAMP" name="time" altenum="Time" />
+ <doc>
+ <brief>Sets the owner of a selection</brief>
+ <description><![CDATA[
+Makes `window` the owner of the selection `selection` and updates the
+last-change time of the specified selection.
+
+TODO: briefly explain what a selection is.
+ ]]></description>
+ <field name="selection"><![CDATA[
+The selection.
+ ]]></field>
+ <field name="owner"><![CDATA[
+The new owner of the selection.
+
+The special value `XCB_NONE` means that the selection will have no owner.
+ ]]></field>
+ <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The selection will not be changed if `time` is earlier than the current
+last-change time of the `selection` or is later than the current X server time.
+Otherwise, the last-change time is set to the specified time.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+ ]]></field>
+ <error type="Atom"><![CDATA[
+`selection` does not refer to a valid atom.
+ ]]></error>
+ <see type="request" name="SetSelectionOwner" />
+ </doc>
+
</request>
<request name="GetSelectionOwner" opcode="23">
@@ -1094,7 +2262,27 @@ authorization from the authors.
<reply>
<pad bytes="1" />
<field type="WINDOW" name="owner" altenum="Window" />
+ <doc>
+ <field name="owner"><![CDATA[
+The current selection owner window.
+ ]]></field>
+ </doc>
</reply>
+ <doc>
+ <brief>Gets the owner of a selection</brief>
+ <description><![CDATA[
+Gets the owner of the specified selection.
+
+TODO: briefly explain what a selection is.
+ ]]></description>
+ <field name="selection"><![CDATA[
+The selection.
+ ]]></field>
+ <error type="Atom"><![CDATA[
+`selection` does not refer to a valid atom.
+ ]]></error>
+ <see type="request" name="SetSelectionOwner" />
+ </doc>
</request>
<request name="ConvertSelection" opcode="24">
@@ -1116,11 +2304,97 @@ authorization from the authors.
<field type="WINDOW" name="destination" altenum="SendEventDest" />
<field type="CARD32" name="event_mask" mask="EventMask" />
<list type="char" name="event"><value>32</value></list>
+ <doc>
+ <brief>send an event</brief>
+ <description><![CDATA[
+Identifies the `destination` window, determines which clients should receive
+the specified event and ignores any active grabs.
+
+The `event` must be one of the core events or an event defined by an extension,
+so that the X server can correctly byte-swap the contents as necessary. The
+contents of `event` are otherwise unaltered and unchecked except for the
+`send_event` field which is forced to 'true'.
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Tell the given window that it was configured to a size of 800x600 pixels.
+ *
+ */
+void my_example(xcb_connection_t *conn, xcb_window_t window) {
+ /* Every X11 event is 32 bytes long. Therefore, XCB will copy 32 bytes.
+ * In order to properly initialize these bytes, we allocate 32 bytes even
+ * though we only need less for an xcb_configure_notify_event_t */
+ xcb_configure_notify_event_t *event = calloc(32, 1);
+
+ 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);
+}
+ ]]></example>
+ <field name="destination"><![CDATA[
+The window to send this event to. Every client which selects any event within
+`event_mask` on `destination` will get the event.
+
+The special value `XCB_SEND_EVENT_DEST_POINTER_WINDOW` refers to the window
+that contains the mouse pointer.
+
+The special value `XCB_SEND_EVENT_DEST_ITEM_FOCUS` refers to the window which
+has the keyboard focus.
+ ]]></field>
+ <field name="event_mask"><![CDATA[
+Event_mask for determining which clients should receive the specified event.
+See `destination` and `propagate`.
+ ]]></field>
+ <field name="propagate"><![CDATA[
+If `propagate` is true and no clients have selected any event on `destination`,
+the destination is replaced with the closest ancestor of `destination` for
+which some client has selected a type in `event_mask` and for which no
+intervening window has that type in its do-not-propagate-mask. If no such
+window exists or if the window is an ancestor of the focus window and
+`InputFocus` was originally specified as the destination, the event is not sent
+to any clients. Otherwise, the event is reported to every client selecting on
+the final destination any of the types specified in `event_mask`.
+ ]]></field>
+ <field name="event"><![CDATA[
+The event to send to the specified `destination`.
+ ]]></field>
+ <error type="Window"><![CDATA[
+The specified `destination` window does not exist.
+ ]]></error>
+ <error type="Value"><![CDATA[
+The given `event` is neither a core event nor an event defined by an extension.
+ ]]></error>
+ <see type="event" name="ConfigureNotify" />
+ </doc>
</request>
<enum name="GrabMode">
<item name="Sync"> <value>0</value></item>
<item name="Async"><value>1</value></item>
+ <doc>
+ <field name="Sync"><![CDATA[
+The state of the keyboard appears to freeze: No further keyboard events are
+generated by the server until the grabbing client issues a releasing
+`AllowEvents` request or until the keyboard grab is released.
+ ]]></field>
+ <field name="Async"><![CDATA[
+Keyboard event processing continues normally.
+ ]]></field>
+ </doc>
</enum>
<enum name="GrabStatus">
@@ -1147,11 +2421,118 @@ authorization from the authors.
<reply>
<field type="BYTE" name="status" enum="GrabStatus" />
</reply>
+ <doc>
+ <brief>Grab the pointer</brief>
+ <description><![CDATA[
+Actively grabs control of the pointer. Further pointer events are reported only to the grabbing client. Overrides any active pointer grab by this client.
+
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Grabs the pointer actively
+ *
+ */
+void my_example(xcb_connection *conn, xcb_screen_t *screen, xcb_cursor_t cursor) {
+ xcb_grab_pointer_cookie_t cookie;
+ xcb_grab_pointer_reply_t *reply;
+
+ cookie = xcb_grab_pointer(
+ conn,
+ false, /* get all pointer events specified by the following mask */
+ screen->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);
+ }
+}
+ ]]></example>
+ <field name="event_mask"><![CDATA[
+Specifies which pointer events are reported to the client.
+
+TODO: which values?
+ ]]></field>
+ <field name="confine_to"><![CDATA[
+Specifies the window to confine the pointer in (the user will not be able to
+move the pointer out of that window).
+
+The special value `XCB_NONE` means don't confine the pointer.
+ ]]></field>
+ <field name="cursor"><![CDATA[
+Specifies the cursor that should be displayed or `XCB_NONE` to not change the
+cursor.
+ ]]></field>
+ <field name="owner_events"><![CDATA[
+If 1, the `grab_window` will still get the pointer events. If 0, events are not
+reported to the `grab_window`.
+ ]]></field>
+ <field name="grab_window"><![CDATA[
+Specifies the window on which the pointer should be grabbed.
+ ]]></field>
+ <field name="time"><![CDATA[
+The time argument allows you to avoid certain circumstances that come up if
+applications take a long time to respond or if there are long network delays.
+Consider a situation where you have two applications, both of which normally
+grab the pointer when clicked on. If both applications specify the timestamp
+from the event, the second application may wake up faster and successfully grab
+the pointer before the first application. The first application then will get
+an indication that the other application grabbed the pointer before its request
+was processed.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+ ]]></field>
+ <!-- the enum doc is sufficient. -->
+ <field name="pointer_mode" />
+ <field name="keyboard_mode" />
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+
+ <see type="request" name="GrabKeyboard" />
+ </doc>
</request>
<request name="UngrabPointer" opcode="27">
<pad bytes="1" />
<field type="TIMESTAMP" name="time" altenum="Time" />
+ <doc>
+ <brief>release the pointer</brief>
+ <description><![CDATA[
+Releases the pointer and any queued events if you actively grabbed the pointer
+before using `xcb_grab_pointer`, `xcb_grab_button` or within a normal button
+press.
+
+EnterNotify and LeaveNotify events are generated.
+ ]]></description>
+ <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The pointer will not be released if `time` is earlier than the
+last-pointer-grab time or later than the current X server time.
+ ]]></field>
+ <field name="name_len"><![CDATA[
+Length (in bytes) of `name`.
+ ]]></field>
+ <field name="name"><![CDATA[
+A pattern describing an X core font.
+ ]]></field>
+ <see type="request" name="GrabPointer" />
+ <see type="request" name="GrabButton" />
+ <see type="event" name="EnterNotify" />
+ <see type="event" name="LeaveNotify" />
+ </doc>
</request>
<enum name="ButtonIndex">
@@ -1161,6 +2542,26 @@ authorization from the authors.
<item name="3"> <value>3</value></item>
<item name="4"> <value>4</value></item>
<item name="5"> <value>5</value></item>
+ <doc>
+ <field name="Any"><![CDATA[
+Any of the following (or none):
+ ]]></field>
+ <field name="1"><![CDATA[
+The left mouse button.
+ ]]></field>
+ <field name="2"><![CDATA[
+The right mouse button.
+ ]]></field>
+ <field name="3"><![CDATA[
+The middle mouse button.
+ ]]></field>
+ <field name="4"><![CDATA[
+Scroll wheel. TODO: direction?
+ ]]></field>
+ <field name="5"><![CDATA[
+Scroll wheel. TODO: direction?
+ ]]></field>
+ </doc>
</enum>
<request name="GrabButton" opcode="28">
@@ -1174,6 +2575,92 @@ authorization from the authors.
<field type="CARD8" name="button" enum="ButtonIndex" />
<pad bytes="1" />
<field type="CARD16" name="modifiers" mask="ModMask" />
+ <doc>
+ <brief>Grab pointer button(s)</brief>
+ <description><![CDATA[
+This request establishes a passive grab. The pointer is actively grabbed as
+described in GrabPointer, the last-pointer-grab time is set to the time at
+which the button was pressed (as transmitted in the ButtonPress event), and the
+ButtonPress event is reported if all of the following conditions are true:
+
+The pointer is not grabbed and the specified button is logically pressed when
+the specified modifier keys are logically down, and no other buttons or
+modifier keys are logically down.
+
+The grab-window contains the pointer.
+
+The confine-to window (if any) is viewable.
+
+A passive grab on the same button/key combination does not exist on any
+ancestor of grab-window.
+
+The interpretation of the remaining arguments is the same as for GrabPointer.
+The active grab is terminated automatically when the logical state of the
+pointer has all buttons released, independent of the logical state of modifier
+keys. Note that the logical state of a device (as seen by means of the
+protocol) may lag the physical state if device event processing is frozen. This
+request overrides all previous passive grabs by the same client on the same
+button/key combinations on the same window. A modifier of AnyModifier is
+equivalent to issuing the request for all possible modifier combinations
+(including the combination of no modifiers). It is not required that all
+specified modifiers have currently assigned keycodes. A button of AnyButton is
+equivalent to issuing the request for all possible buttons. Otherwise, it is
+not required that the button specified currently be assigned to a physical
+button.
+
+An Access error is generated if some other client has already issued a
+GrabButton request with the same button/key combination on the same window.
+When using AnyModifier or AnyButton, the request fails completely (no grabs are
+established), and an Access error is generated if there is a conflicting grab
+for any combination. The request has no effect on an active grab.
+
+ ]]></description>
+ <field name="owner_events"><![CDATA[
+If 1, the `grab_window` will still get the pointer events. If 0, events are not
+reported to the `grab_window`.
+ ]]></field>
+ <field name="grab_window"><![CDATA[
+Specifies the window on which the pointer should be grabbed.
+ ]]></field>
+ <field name="event_mask"><![CDATA[
+Specifies which pointer events are reported to the client.
+
+TODO: which values?
+ ]]></field>
+ <field name="confine_to"><![CDATA[
+Specifies the window to confine the pointer in (the user will not be able to
+move the pointer out of that window).
+
+The special value `XCB_NONE` means don't confine the pointer.
+ ]]></field>
+ <field name="cursor"><![CDATA[
+Specifies the cursor that should be displayed or `XCB_NONE` to not change the
+cursor.
+ ]]></field>
+ <field name="modifiers"><![CDATA[
+The modifiers to grab.
+
+Using the special value `XCB_MOD_MASK_ANY` means grab the pointer with all
+possible modifier combinations.
+ ]]></field>
+ <!-- the enum doc is sufficient. -->
+ <field name="pointer_mode" />
+ <field name="keyboard_mode" />
+ <field name="button" />
+ <error type="Access"><![CDATA[
+Another client has already issued a GrabButton with the same button/key
+combination on the same window.
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Cursor"><![CDATA[
+The specified `cursor` does not exist.
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ </doc>
</request>
<request name="UngrabButton" opcode="29">
@@ -1201,6 +2688,70 @@ authorization from the authors.
<reply>
<field type="BYTE" name="status" enum="GrabStatus" />
</reply>
+ <doc>
+ <brief>Grab the keyboard</brief>
+ <description><![CDATA[
+Actively grabs control of the keyboard and generates FocusIn and FocusOut
+events. Further key events are reported only to the grabbing client.
+
+Any active keyboard grab by this client is overridden. If the keyboard is
+actively grabbed by some other client, `AlreadyGrabbed` is returned. If
+`grab_window` is not viewable, `GrabNotViewable` is returned. If the keyboard
+is frozen by an active grab of another client, `GrabFrozen` is returned. If the
+specified `time` is earlier than the last-keyboard-grab time or later than the
+current X server time, `GrabInvalidTime` is returned. Otherwise, the
+last-keyboard-grab time is set to the specified time.
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Grabs the keyboard actively
+ *
+ */
+void my_example(xcb_connection *conn, xcb_screen_t *screen) {
+ xcb_grab_keyboard_cookie_t cookie;
+ xcb_grab_keyboard_reply_t *reply;
+
+ cookie = xcb_grab_keyboard(
+ conn,
+ true, /* report events */
+ screen->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);
+ }
+}
+ ]]></example>
+ <field name="owner_events"><![CDATA[
+If 1, the `grab_window` will still get the pointer events. If 0, events are not
+reported to the `grab_window`.
+ ]]></field>
+ <field name="grab_window"><![CDATA[
+Specifies the window on which the pointer should be grabbed.
+ ]]></field>
+ <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+ ]]></field>
+ <!-- the enum doc is sufficient. -->
+ <field name="pointer_mode" />
+ <field name="keyboard_mode" />
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ <see type="request" name="GrabPointer" />
+ </doc>
</request>
<request name="UngrabKeyboard" opcode="32">
@@ -1221,6 +2772,78 @@ authorization from the authors.
<field type="CARD8" name="pointer_mode" enum="GrabMode" />
<field type="CARD8" name="keyboard_mode" enum="GrabMode" />
<pad bytes="3" />
+ <doc>
+ <brief>Grab keyboard key(s)</brief>
+ <description><![CDATA[
+Establishes a passive grab on the keyboard. In the future, the keyboard is
+actively grabbed (as for `GrabKeyboard`), the last-keyboard-grab time is set to
+the time at which the key was pressed (as transmitted in the KeyPress event),
+and the KeyPress event is reported if all of the following conditions are true:
+
+The keyboard is not grabbed and the specified key (which can itself be a
+modifier key) is logically pressed when the specified modifier keys are
+logically down, and no other modifier keys are logically down.
+
+Either the grab_window is an ancestor of (or is) the focus window, or the
+grab_window is a descendant of the focus window and contains the pointer.
+
+A passive grab on the same key combination does not exist on any ancestor of
+grab_window.
+
+The interpretation of the remaining arguments is as for XGrabKeyboard. The active grab is terminated
+automatically when the logical state of the keyboard has the specified key released (independent of the
+logical state of the modifier keys), at which point a KeyRelease event is reported to the grabbing window.
+
+Note that the logical state of a device (as seen by client applications) may lag the physical state if
+device event processing is frozen.
+
+A modifiers argument of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified
+have currently assigned KeyCodes. A keycode argument of AnyKey is equivalent to issuing the request for
+all possible KeyCodes. Otherwise, the specified keycode must be in the range specified by min_keycode
+and max_keycode in the connection setup, or a BadValue error results.
+
+If some other client has issued a XGrabKey with the same key combination on the same window, a BadAccess
+error results. When using AnyModifier or AnyKey, the request fails completely, and a BadAccess error
+results (no grabs are established) if there is a conflicting grab for any combination.
+
+ ]]></description>
+ <field name="owner_events"><![CDATA[
+If 1, the `grab_window` will still get the pointer events. If 0, events are not
+reported to the `grab_window`.
+ ]]></field>
+ <field name="grab_window"><![CDATA[
+Specifies the window on which the pointer should be grabbed.
+ ]]></field>
+ <field name="key"><![CDATA[
+The keycode of the key to grab.
+
+The special value `XCB_GRAB_ANY` means grab any key.
+ ]]></field>
+ <field name="cursor"><![CDATA[
+Specifies the cursor that should be displayed or `XCB_NONE` to not change the
+cursor.
+ ]]></field>
+ <field name="modifiers"><![CDATA[
+The modifiers to grab.
+
+Using the special value `XCB_MOD_MASK_ANY` means grab the pointer with all
+possible modifier combinations.
+ ]]></field>
+ <!-- the enum doc is sufficient. -->
+ <field name="pointer_mode" />
+ <field name="keyboard_mode" />
+ <error type="Access"><![CDATA[
+Another client has already issued a GrabKey with the same button/key
+combination on the same window.
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ <see type="request" name="GrabKeyboard" />
+ </doc>
</request>
<request name="UngrabKey" opcode="34">
@@ -1228,6 +2851,35 @@ authorization from the authors.
<field type="WINDOW" name="grab_window" />
<field type="CARD16" name="modifiers" mask="ModMask" />
<pad bytes="2" />
+ <doc>
+ <brief>release a key combination</brief>
+ <description><![CDATA[
+Releases the key combination on `grab_window` if you grabbed it using
+`xcb_grab_key` before.
+ ]]></description>
+ <field name="key"><![CDATA[
+The keycode of the specified key combination.
+
+Using the special value `XCB_GRAB_ANY` means releasing all possible key codes.
+ ]]></field>
+ <field name="grab_window"><![CDATA[
+The window on which the grabbed key combination will be released.
+ ]]></field>
+ <field name="modifiers"><![CDATA[
+The modifiers of the specified key combination.
+
+Using the special value `XCB_MOD_MASK_ANY` means releasing the key combination
+with every possible modifier combination.
+ ]]></field>
+ <error type="Window"><![CDATA[
+The specified `grab_window` does not exist.
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <see type="request" name="GrabKey" />
+ <see type="program" name="xev" />
+ </doc>
</request>
<enum name="Allow">
@@ -1239,11 +2891,106 @@ authorization from the authors.
<item name="ReplayKeyboard"><value>5</value></item>
<item name="AsyncBoth"> <value>6</value></item>
<item name="SyncBoth"> <value>7</value></item>
+ <doc>
+ <field name="AsyncPointer"><![CDATA[
+For AsyncPointer, if the pointer is frozen by the client, pointer event
+processing continues normally. If the pointer is frozen twice by the client on
+behalf of two separate grabs, AsyncPointer thaws for both. AsyncPointer has no
+effect if the pointer is not frozen by the client, but the pointer need not be
+grabbed by the client.
+
+TODO: rewrite this in more understandable terms.
+ ]]></field>
+ <field name="SyncPointer"><![CDATA[
+For SyncPointer, if the pointer is frozen and actively grabbed by the client,
+pointer event processing continues normally until the next ButtonPress or
+ButtonRelease event is reported to the client, at which time the pointer again
+appears to freeze. However, if the reported event causes the pointer grab to be
+released, then the pointer does not freeze. SyncPointer has no effect if the
+pointer is not frozen by the client or if the pointer is not grabbed by the
+client.
+ ]]></field>
+ <field name="ReplayPointer"><![CDATA[
+For ReplayPointer, if the pointer is actively grabbed by the client and is
+frozen as the result of an event having been sent to the client (either from
+the activation of a GrabButton or from a previous AllowEvents with mode
+SyncPointer but not from a GrabPointer), then the pointer grab is released and
+that event is completely reprocessed, this time ignoring any passive grabs at
+or above (towards the root) the grab-window of the grab just released. The
+request has no effect if the pointer is not grabbed by the client or if the
+pointer is not frozen as the result of an event.
+ ]]></field>
+ <field name="AsyncKeyboard"><![CDATA[
+For AsyncKeyboard, if the keyboard is frozen by the client, keyboard event
+processing continues normally. If the keyboard is frozen twice by the client on
+behalf of two separate grabs, AsyncKeyboard thaws for both. AsyncKeyboard has
+no effect if the keyboard is not frozen by the client, but the keyboard need
+not be grabbed by the client.
+ ]]></field>
+ <field name="SyncKeyboard"><![CDATA[
+For SyncKeyboard, if the keyboard is frozen and actively grabbed by the client,
+keyboard event processing continues normally until the next KeyPress or
+KeyRelease event is reported to the client, at which time the keyboard again
+appears to freeze. However, if the reported event causes the keyboard grab to
+be released, then the keyboard does not freeze. SyncKeyboard has no effect if
+the keyboard is not frozen by the client or if the keyboard is not grabbed by
+the client.
+ ]]></field>
+ <field name="ReplayKeyboard"><![CDATA[
+For ReplayKeyboard, if the keyboard is actively grabbed by the client and is
+frozen as the result of an event having been sent to the client (either from
+the activation of a GrabKey or from a previous AllowEvents with mode
+SyncKeyboard but not from a GrabKeyboard), then the keyboard grab is released
+and that event is completely reprocessed, this time ignoring any passive grabs
+at or above (towards the root) the grab-window of the grab just released. The
+request has no effect if the keyboard is not grabbed by the client or if the
+keyboard is not frozen as the result of an event.
+ ]]></field>
+ <field name="SyncBoth"><![CDATA[
+For SyncBoth, if both pointer and keyboard are frozen by the client, event
+processing (for both devices) continues normally until the next ButtonPress,
+ButtonRelease, KeyPress, or KeyRelease event is reported to the client for a
+grabbed device (button event for the pointer, key event for the keyboard), at
+which time the devices again appear to freeze. However, if the reported event
+causes the grab to be released, then the devices do not freeze (but if the
+other device is still grabbed, then a subsequent event for it will still cause
+both devices to freeze). SyncBoth has no effect unless both pointer and
+keyboard are frozen by the client. If the pointer or keyboard is frozen twice
+by the client on behalf of two separate grabs, SyncBoth thaws for both (but a
+subsequent freeze for SyncBoth will only freeze each device once).
+ ]]></field>
+ <field name="AsyncBoth"><![CDATA[
+For AsyncBoth, if the pointer and the keyboard are frozen by the client, event
+processing for both devices continues normally. If a device is frozen twice by
+the client on behalf of two separate grabs, AsyncBoth thaws for both. AsyncBoth
+has no effect unless both pointer and keyboard are frozen by the client.
+ ]]></field>
+ </doc>
</enum>
<request name="AllowEvents" opcode="35">
<field type="CARD8" name="mode" enum="Allow" />
<field type="TIMESTAMP" name="time" altenum="Time" />
+ <doc>
+ <brief>release queued events</brief>
+ <description><![CDATA[
+Releases queued events if the client has caused a device (pointer/keyboard) to
+freeze due to grabbing it actively. This request has no effect if `time` is
+earlier than the last-grab time of the most recent active grab for this client
+or if `time` is later than the current X server time.
+ ]]></description>
+ <!-- the enum doc is sufficient. -->
+ <field name="mode" />
+ <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+ ]]></field>
+ <error type="Value"><![CDATA[
+You specified an invalid `mode`.
+ ]]></error>
+ </doc>
</request>
<request name="GrabServer" opcode="36" />
@@ -1263,7 +3010,56 @@ authorization from the authors.
<field type="INT16" name="win_y" />
<field type="CARD16" name="mask" mask="KeyButMask" />
<pad bytes="2" />
+ <doc>
+ <field name="same_screen"><![CDATA[
+If `same_screen` is False, then the pointer is not on the same screen as the
+argument window, `child` is None, and `win_x` and `win_y` are zero. If
+`same_screen` is True, then `win_x` and `win_y` are the pointer coordinates
+relative to the argument window's origin, and child is the child containing the
+pointer, if any.
+ ]]></field>
+ <field name="root"><![CDATA[
+The root window the pointer is logically on.
+ ]]></field>
+ <field name="child"><![CDATA[
+The child window containing the pointer, if any, if `same_screen` is true. If
+`same_screen` is false, `XCB_NONE` is returned.
+ ]]></field>
+ <field name="root_x"><![CDATA[
+The pointer X position, relative to `root`.
+ ]]></field>
+ <field name="root_y"><![CDATA[
+The pointer Y position, relative to `root`.
+ ]]></field>
+ <field name="win_x"><![CDATA[
+The pointer X coordinate, relative to `child`, if `same_screen` is true. Zero
+otherwise.
+ ]]></field>
+ <field name="win_y"><![CDATA[
+The pointer Y coordinate, relative to `child`, if `same_screen` is true. Zero
+otherwise.
+ ]]></field>
+ <field name="mask"><![CDATA[
+The current logical state of the modifier keys and the buttons. Note that the
+logical state of a device (as seen by means of the protocol) may lag the
+physical state if device event processing is frozen.
+ ]]></field>
+ </doc>
</reply>
+ <doc>
+ <brief>get pointer coordinates</brief>
+ <description><![CDATA[
+Gets the root window the pointer is logically on and the pointer coordinates
+relative to the root window's origin.
+ ]]></description>
+ <field name="window"><![CDATA[
+A window to check if the pointer is on the same screen as `window` (see the
+`same_screen` field in the reply).
+ ]]></field>
+ <error type="Window"><![CDATA[
+The specified `window` does not exist.
+ ]]></error>
+ </doc>
</request>
<struct name="TIMECOORD">
@@ -1311,6 +3107,38 @@ authorization from the authors.
<field type="CARD16" name="src_height" />
<field type="INT16" name="dst_x" />
<field type="INT16" name="dst_y" />
+ <doc>
+ <brief>move mouse pointer</brief>
+ <description><![CDATA[
+Moves the mouse pointer to the specified position.
+
+If `src_window` is not `XCB_NONE` (TODO), the move will only take place if the
+pointer is inside `src_window` and within the rectangle specified by (`src_x`,
+`src_y`, `src_width`, `src_height`). The rectangle coordinates are relative to
+`src_window`.
+
+If `dst_window` is not `XCB_NONE` (TODO), the pointer will be moved to the
+offsets (`dst_x`, `dst_y`) relative to `dst_window`. If `dst_window` is
+`XCB_NONE` (TODO), the pointer will be moved by the offsets (`dst_x`, `dst_y`)
+relative to the current position of the pointer.
+ ]]></description>
+ <field name="src_window"><![CDATA[
+If `src_window` is not `XCB_NONE` (TODO), the move will only take place if the
+pointer is inside `src_window` and within the rectangle specified by (`src_x`,
+`src_y`, `src_width`, `src_height`). The rectangle coordinates are relative to
+`src_window`.
+ ]]></field>
+ <field name="dst_window"><![CDATA[
+If `dst_window` is not `XCB_NONE` (TODO), the pointer will be moved to the
+offsets (`dst_x`, `dst_y`) relative to `dst_window`. If `dst_window` is
+`XCB_NONE` (TODO), the pointer will be moved by the offsets (`dst_x`, `dst_y`)
+relative to the current position of the pointer.
+ ]]></field>
+ <error type="Window"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <see type="request" name="SetInputFocus" />
+ </doc>
</request>
<!-- used for revert_to and focus -->
@@ -1319,12 +3147,71 @@ authorization from the authors.
<item name="PointerRoot"><value>1</value></item>
<item name="Parent"> <value>2</value></item> <!-- revert_to only -->
<item name="FollowKeyboard"><value>3</value></item> <!-- xinput extension only -->
+ <doc>
+ <field name="None"><![CDATA[
+The focus reverts to `XCB_NONE`, so no window will have the input focus.
+ ]]></field>
+ <field name="PointerRoot"><![CDATA[
+The focus reverts to `XCB_POINTER_ROOT` respectively. When the focus reverts,
+FocusIn and FocusOut events are generated, but the last-focus-change time is
+not changed.
+ ]]></field>
+ <field name="Parent"><![CDATA[
+The focus reverts to the parent (or closest viewable ancestor) and the new
+revert_to value is `XCB_INPUT_FOCUS_NONE`.
+ ]]></field>
+ <field name="FollowKeyboard"><![CDATA[
+NOT YET DOCUMENTED. Only relevant for the xinput extension.
+ ]]></field>
+ </doc>
</enum>
<request name="SetInputFocus" opcode="42">
<field type="CARD8" name="revert_to" enum="InputFocus" />
<field type="WINDOW" name="focus" altenum="InputFocus" />
<field type="TIMESTAMP" name="time" altenum="Time" />
+ <doc>
+ <brief>Sets input focus</brief>
+ <description><![CDATA[
+Changes the input focus and the last-focus-change time. If the specified `time`
+is earlier than the current last-focus-change time, the request is ignored (to
+avoid race conditions when running X over the network).
+
+A FocusIn and FocusOut event is generated when focus is changed.
+ ]]></description>
+ <field name="focus"><![CDATA[
+The window to focus. All keyboard events will be reported to this window. The
+window must be viewable (TODO), or a `xcb_match_error_t` occurs (TODO).
+
+If `focus` is `XCB_NONE` (TODO), all keyboard events are
+discarded until a new focus window is set.
+
+If `focus` is `XCB_POINTER_ROOT` (TODO), focus is on the root window of the
+screen on which the pointer is on currently.
+ ]]></field>
+ <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+ ]]></field>
+ <field name="revert_to"><![CDATA[
+Specifies what happens when the `focus` window becomes unviewable (if `focus`
+is neither `XCB_NONE` nor `XCB_POINTER_ROOT`).
+ ]]></field>
+ <error type="Window"><![CDATA[
+The specified `focus` window does not exist.
+ ]]></error>
+ <error type="Match"><![CDATA[
+The specified `focus` window is not viewable.
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: Reasons?
+ ]]></error>
+ <see type="event" name="FocusIn" />
+ <see type="event" name="FocusOut" />
+ </doc>
+
</request>
<request name="GetInputFocus" opcode="43">
@@ -1349,6 +3236,28 @@ authorization from the authors.
<list type="char" name="name">
<fieldref>name_len</fieldref>
</list>
+ <doc>
+ <brief>opens a font</brief>
+ <description><![CDATA[
+Opens any X core font matching the given `name` (for example "-misc-fixed-*").
+
+Note that X core fonts are deprecated (but still supported) in favor of
+client-side rendering using Xft.
+ ]]></description>
+ <field name="fid"><![CDATA[
+The ID with which you will refer to the font, created by `xcb_generate_id`.
+ ]]></field>
+ <field name="name_len"><![CDATA[
+Length (in bytes) of `name`.
+ ]]></field>
+ <field name="name"><![CDATA[
+A pattern describing an X core font.
+ ]]></field>
+ <error type="Name"><![CDATA[
+No font matches the given `name`.
+ ]]></error>
+ <see type="function" name="xcb_generate_id" />
+ </doc>
</request>
<request name="CloseFont" opcode="46">
@@ -1401,7 +3310,48 @@ authorization from the authors.
<list type="CHARINFO" name="char_infos">
<fieldref>char_infos_len</fieldref>
</list>
+ <doc>
+ <field name="min_bounds"><![CDATA[
+minimum bounds over all existing char
+ ]]></field>
+ <field name="max_bounds"><![CDATA[
+maximum bounds over all existing char
+ ]]></field>
+ <field name="min_char_or_byte2"><![CDATA[
+first character
+ ]]></field>
+ <field name="max_char_or_byte2"><![CDATA[
+last character
+ ]]></field>
+ <field name="default_char"><![CDATA[
+char to print for undefined character
+ ]]></field>
+ <field name="properties_len"><![CDATA[
+how many properties there are
+ ]]></field>
+ <field name="all_chars_exist"><![CDATA[
+flag if all characters have nonzero size
+ ]]></field>
+ <field name="font_ascent"><![CDATA[
+baseline to top edge of raster
+ ]]></field>
+ <field name="font_descent"><![CDATA[
+baseline to bottom edge of raster
+ ]]></field>
+ <!-- enum doc is sufficient -->
+ <field name="draw_direction" />
+ </doc>
</reply>
+ <doc>
+ <brief>query font metrics</brief>
+ <description><![CDATA[
+Queries information associated with the font.
+ ]]></description>
+ <field name="font"><![CDATA[
+The fontable (Font or Graphics Context) to query.
+ ]]></field>
+ <!-- TODO: example -->
+ </doc>
</request>
<request name="QueryTextExtents" opcode="48">
@@ -1420,6 +3370,47 @@ authorization from the authors.
<field type="INT32" name="overall_left" />
<field type="INT32" name="overall_right" />
</reply>
+ <doc>
+ <brief>get text extents</brief>
+ <description><![CDATA[
+Query text extents from the X11 server. This request returns the bounding box
+of the specified 16-bit character string in the specified `font` or the font
+contained in the specified graphics context.
+
+`font_ascent` is set to the maximum of the ascent metrics of all characters in
+the string. `font_descent` is set to the maximum of the descent metrics.
+`overall_width` is set to the sum of the character-width metrics of all
+characters in the string. For each character in the string, let W be the sum of
+the character-width metrics of all characters preceding it in the string. Let L
+be the left-side-bearing metric of the character plus W. Let R be the
+right-side-bearing metric of the character plus W. The lbearing member is set
+to the minimum L of all characters in the string. The rbearing member is set to
+the maximum R.
+
+For fonts defined with linear indexing rather than 2-byte matrix indexing, each
+`xcb_char2b_t` structure is interpreted as a 16-bit number with byte1 as the
+most significant byte. If the font has no defined default character, undefined
+characters in the string are taken to have all zero metrics.
+
+Characters with all zero metrics are ignored. If the font has no defined
+default_char, the undefined characters in the string are also ignored.
+ ]]></description>
+ <field name="font"><![CDATA[
+The `font` to calculate text extents in. You can also pass a graphics context.
+ ]]></field>
+ <field name="string_len"><![CDATA[
+The number of characters in `string`.
+ ]]></field>
+ <field name="string"><![CDATA[
+The text to get text extents for.
+ ]]></field>
+ <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+ ]]></error>
+ <error type="Font"><![CDATA[
+The specified `font` does not exist.
+ ]]></error>
+ </doc>
</request>
<struct name="STR">
@@ -1443,7 +3434,31 @@ authorization from the authors.
<list type="STR" name="names">
<fieldref>names_len</fieldref>
</list>
+ <doc>
+ <field name="names_len"><![CDATA[
+The number of font names.
+ ]]></field>
+ </doc>
</reply>
+ <doc>
+ <brief>get matching font names</brief>
+ <description><![CDATA[
+Gets a list of available font names which match the given `pattern`.
+ ]]></description>
+ <field name="pattern_len"><![CDATA[
+The length (in bytes) of `pattern`.
+ ]]></field>
+ <field name="pattern"><![CDATA[
+A font pattern, for example "-misc-fixed-*".
+
+The asterisk (*) is a wildcard for any number of characters. The question mark
+(?) is a wildcard for a single character. Use of uppercase or lowercase does
+not matter.
+ ]]></field>
+ <field name="max_names"><![CDATA[
+The maximum number of fonts to be returned.
+ ]]></field>
+ </doc>
</request>
<request name="ListFontsWithInfo" opcode="50">
@@ -1476,7 +3491,66 @@ authorization from the authors.
<list type="char" name="name">
<fieldref>name_len</fieldref>
</list>
+ <doc>
+ <field name="name_len"><![CDATA[
+The number of matched font names.
+ ]]></field>
+ <field name="min_bounds"><![CDATA[
+minimum bounds over all existing char
+ ]]></field>
+ <field name="max_bounds"><![CDATA[
+maximum bounds over all existing char
+ ]]></field>
+ <field name="min_char_or_byte2"><![CDATA[
+first character
+ ]]></field>
+ <field name="max_char_or_byte2"><![CDATA[
+last character
+ ]]></field>
+ <field name="default_char"><![CDATA[
+char to print for undefined character
+ ]]></field>
+ <field name="properties_len"><![CDATA[
+how many properties there are
+ ]]></field>
+ <field name="all_chars_exist"><![CDATA[
+flag if all characters have nonzero size
+ ]]></field>
+ <field name="font_ascent"><![CDATA[
+baseline to top edge of raster
+ ]]></field>
+ <field name="font_descent"><![CDATA[
+baseline to bottom edge of raster
+ ]]></field>
+ <field name="replies_hint"><![CDATA[
+An indication of how many more fonts will be returned. This is only a hint and
+may be larger or smaller than the number of fonts actually returned. A zero
+value does not guarantee that no more fonts will be returned.
+ ]]></field>
+ <!-- enum doc is sufficient -->
+ <field name="draw_direction" />
+ </doc>
</reply>
+ <doc>
+ <brief>get matching font names and information</brief>
+ <description><![CDATA[
+Gets a list of available font names which match the given `pattern`.
+ ]]></description>
+ <field name="pattern_len"><![CDATA[
+The length (in bytes) of `pattern`.
+ ]]></field>
+ <field name="pattern"><![CDATA[
+A font pattern, for example "-misc-fixed-*".
+
+The asterisk (*) is a wildcard for any number of characters. The question mark
+(?) is a wildcard for a single character. Use of uppercase or lowercase does
+not matter.
+ ]]></field>
+ <field name="max_names"><![CDATA[
+The maximum number of fonts to be returned.
+ ]]></field>
+ </doc>
+
</request>
<request name="SetFontPath" opcode="51">
@@ -1505,11 +3579,55 @@ authorization from the authors.
<field type="DRAWABLE" name="drawable" />
<field type="CARD16" name="width" />
<field type="CARD16" name="height" />
+ <doc>
+ <brief>Creates a pixmap</brief>
+ <description><![CDATA[
+Creates a pixmap. The pixmap can only be used on the same screen as `drawable`
+is on and only with drawables of the same `depth`.
+ ]]></description>
+ <field name="depth"><![CDATA[
+TODO
+ ]]></field>
+ <field name="pid"><![CDATA[
+The ID with which you will refer to the new pixmap, created by
+`xcb_generate_id`.
+ ]]></field>
+ <field name="drawable"><![CDATA[
+Drawable to get the screen from.
+ ]]></field>
+ <field name="width"><![CDATA[
+The width of the new pixmap.
+ ]]></field>
+ <field name="height"><![CDATA[
+The height of the new pixmap.
+ ]]></field>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+ ]]></error>
+ <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+ ]]></error>
+ <see type="function" name="xcb_generate_id" />
+ </doc>
</request>
<request name="FreePixmap" opcode="54">
<pad bytes="1" />
<field type="PIXMAP" name="pixmap" />
+ <doc>
+ <brief>Destroys a pixmap</brief>
+ <description><![CDATA[
+Deletes the association between the pixmap ID and the pixmap. The pixmap
+storage will be freed when there are no more references to it.
+ ]]></description>
+ <field name="pixmap"><![CDATA[The pixmap to destroy.]]></field>
+ <error type="Pixmap"><![CDATA[
+The specified pixmap does not exist.
+ ]]></error>
+ </doc>
</request>
<enum name="GC">
@@ -1536,6 +3654,154 @@ authorization from the authors.
<item name="DashOffset"> <bit>20</bit></item>
<item name="DashList"> <bit>21</bit></item>
<item name="ArcMode"> <bit>22</bit></item>
+ <doc>
+ <field name="Function"><![CDATA[
+TODO: Refer to GX
+ ]]></field>
+ <field name="PlaneMask"><![CDATA[
+In graphics operations, given a source and destination pixel, the result is
+computed bitwise on corresponding bits of the pixels; that is, a Boolean
+operation is performed in each bit plane. The plane-mask restricts the
+operation to a subset of planes, so the result is:
+
+ ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
+ ]]></field>
+ <field name="Foreground"><![CDATA[
+Foreground colorpixel.
+ ]]></field>
+ <field name="Background"><![CDATA[
+Background colorpixel.
+ ]]></field>
+ <field name="LineWidth"><![CDATA[
+The line-width is measured in pixels and can be greater than or equal to one, a wide line, or the
+special value zero, a thin line.
+ ]]></field>
+ <field name="LineStyle"><![CDATA[
+The line-style defines which sections of a line are drawn:
+Solid The full path of the line is drawn.
+DoubleDash The full path of the line is drawn, but the even dashes are filled differently
+ than the odd dashes (see fill-style), with Butt cap-style used where even and
+ odd dashes meet.
+OnOffDash Only the even dashes are drawn, and cap-style applies to all internal ends of
+ the individual dashes (except NotLast is treated as Butt).
+ ]]></field>
+ <field name="CapStyle"><![CDATA[
+The cap-style defines how the endpoints of a path are drawn:
+NotLast The result is equivalent to Butt, except that for a line-width of zero the final
+ endpoint is not drawn.
+Butt The result is square at the endpoint (perpendicular to the slope of the line)
+ with no projection beyond.
+Round The result is a circular arc with its diameter equal to the line-width, centered
+ on the endpoint; it is equivalent to Butt for line-width zero.
+Projecting The result is square at the end, but the path continues beyond the endpoint for
+ a distance equal to half the line-width; it is equivalent to Butt for line-width
+ zero.
+ ]]></field>
+ <field name="JoinStyle"><![CDATA[
+The join-style defines how corners are drawn for wide lines:
+Miter The outer edges of the two lines extend to meet at an angle. However, if the
+ angle is less than 11 degrees, a Bevel join-style is used instead.
+Round The result is a circular arc with a diameter equal to the line-width, centered
+ on the joinpoint.
+Bevel The result is Butt endpoint styles, and then the triangular notch is filled.
+ ]]></field>
+ <field name="FillStyle"><![CDATA[
+The fill-style defines the contents of the source for line, text, and fill requests. For all text and fill
+requests (for example, PolyText8, PolyText16, PolyFillRectangle, FillPoly, and PolyFillArc)
+as well as for line requests with line-style Solid, (for example, PolyLine, PolySegment,
+PolyRectangle, PolyArc) and for the even dashes for line requests with line-style OnOffDash
+or DoubleDash:
+Solid Foreground
+Tiled Tile
+OpaqueStippled A tile with the same width and height as stipple but with background
+ everywhere stipple has a zero and with foreground everywhere stipple
+ has a one
+Stippled Foreground masked by stipple
+For the odd dashes for line requests with line-style DoubleDash:
+Solid Background
+Tiled Same as for even dashes
+OpaqueStippled Same as for even dashes
+Stippled Background masked by stipple
+ ]]></field>
+ <field name="FillRule"><![CDATA[
+ ]]></field>
+ <field name="Tile"><![CDATA[
+The tile/stipple represents an infinite two-dimensional plane with the tile/stipple replicated in all
+dimensions. When that plane is superimposed on the drawable for use in a graphics operation,
+the upper-left corner of some instance of the tile/stipple is at the coordinates within the drawable
+specified by the tile/stipple origin. The tile/stipple and clip origins are interpreted relative to the
+origin of whatever destination drawable is specified in a graphics request.
+The tile pixmap must have the same root and depth as the gcontext (or a Match error results).
+The stipple pixmap must have depth one and must have the same root as the gcontext (or a
+Match error results). For fill-style Stippled (but not fill-style
+OpaqueStippled), the stipple pattern is tiled in a single plane and acts as an
+additional clip mask to be ANDed with the clip-mask.
+Any size pixmap can be used for tiling or stippling, although some sizes may be faster to use than
+others.
+ ]]></field>
+ <field name="Stipple"><![CDATA[
+The tile/stipple represents an infinite two-dimensional plane with the tile/stipple replicated in all
+dimensions. When that plane is superimposed on the drawable for use in a graphics operation,
+the upper-left corner of some instance of the tile/stipple is at the coordinates within the drawable
+specified by the tile/stipple origin. The tile/stipple and clip origins are interpreted relative to the
+origin of whatever destination drawable is specified in a graphics request.
+The tile pixmap must have the same root and depth as the gcontext (or a Match error results).
+The stipple pixmap must have depth one and must have the same root as the gcontext (or a
+Match error results). For fill-style Stippled (but not fill-style
+OpaqueStippled), the stipple pattern is tiled in a single plane and acts as an
+additional clip mask to be ANDed with the clip-mask.
+Any size pixmap can be used for tiling or stippling, although some sizes may be faster to use than
+others.
+ ]]></field>
+ <field name="TileStippleOriginX"><![CDATA[
+TODO
+ ]]></field>
+ <field name="TileStippleOriginY"><![CDATA[
+TODO
+ ]]></field>
+ <field name="Font"><![CDATA[
+Which font to use for the `ImageText8` and `ImageText16` requests.
+ ]]></field>
+ <field name="SubwindowMode"><![CDATA[
+For ClipByChildren, both source and destination windows are additionally
+clipped by all viewable InputOutput children. For IncludeInferiors, neither
+source nor destination window is
+clipped by inferiors. This will result in including subwindow contents in the source and drawing
+through subwindow boundaries of the destination. The use of IncludeInferiors with a source or
+destination window of one depth with mapped inferiors of differing depth is not illegal, but the
+semantics is undefined by the core protocol.
+ ]]></field>
+ <field name="GraphicsExposures"><![CDATA[
+Whether ExposureEvents should be generated (1) or not (0).
+
+The default is 1.
+ ]]></field>
+ <field name="ClipOriginX"><![CDATA[
+TODO
+ ]]></field>
+ <field name="ClipOriginY"><![CDATA[
+TODO
+ ]]></field>
+ <field name="ClipMask"><![CDATA[
+The clip-mask restricts writes to the destination drawable. Only pixels where the clip-mask has
+bits set to 1 are drawn. Pixels are not drawn outside the area covered by the clip-mask or where
+the clip-mask has bits set to 0. The clip-mask affects all graphics requests, but it does not clip
+sources. The clip-mask origin is interpreted relative to the origin of whatever destination drawable is specified in a graphics request. If a pixmap is specified as the clip-mask, it must have
+depth 1 and have the same root as the gcontext (or a Match error results). If clip-mask is None,
+then pixels are always drawn, regardless of the clip origin. The clip-mask can also be set with the
+SetClipRectangles request.
+ ]]></field>
+ <field name="DashOffset"><![CDATA[
+TODO
+ ]]></field>
+ <field name="DashList"><![CDATA[
+TODO
+ ]]></field>
+ <field name="ArcMode"><![CDATA[
+TODO
+ ]]></field>
+ </doc>
+
</enum>
<!-- GC Function values -->
@@ -1606,6 +3872,39 @@ authorization from the authors.
<valueparam value-mask-type="CARD32"
value-mask-name="value_mask"
value-list-name="value_list" />
+ <doc>
+ <brief>Creates a graphics context</brief>
+ <description><![CDATA[
+Creates a graphics context. The graphics context can be used with any drawable
+that has the same root and depth as the specified drawable.
+ ]]></description>
+ <field name="cid"><![CDATA[
+The ID with which you will refer to the graphics context, created by
+`xcb_generate_id`.
+ ]]></field>
+ <field name="drawable"><![CDATA[
+Drawable to get the root/depth from.
+ ]]></field>
+ <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Font"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Pixmap"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+ ]]></error>
+ <see type="function" name="xcb_generate_id" />
+ </doc>
</request>
<request name="ChangeGC" opcode="56">
@@ -1614,6 +3913,62 @@ authorization from the authors.
<valueparam value-mask-type="CARD32"
value-mask-name="value_mask"
value-list-name="value_list" />
+ <doc>
+ <brief>change graphics context components</brief>
+ <description><![CDATA[
+Changes the components specified by `value_mask` for the specified graphics context.
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Changes the foreground color component of the specified graphics context.
+ *
+ */
+void my_example(xcb_connection *conn, xcb_gcontext_t gc, uint32_t fg, uint32_t bg) {
+ /* C99 allows us to use a compact way of changing a single component: */
+ xcb_change_gc(conn, gc, XCB_GC_FOREGROUND, (uint32_t[]){ fg });
+
+ /* The more explicit way. Beware that the order of values is important! */
+ uint32_t mask = 0;
+ mask |= XCB_GC_FOREGROUND;
+ mask |= XCB_GC_BACKGROUND;
+
+ uint32_t values[] = {
+ fg,
+ bg
+ };
+ xcb_change_gc(conn, gc, mask, values);
+ xcb_flush(conn);
+}
+ ]]></example>
+ <field name="gc"><![CDATA[
+The graphics context to change.
+ ]]></field>
+ <!-- the enum documentation is good enough. -->
+ <field name="value_mask" />
+ <field name="value_list"><![CDATA[
+Values for each of the components specified in the bitmask `value_mask`. The
+order has to correspond to the order of possible `value_mask` bits. See the
+example.
+ ]]></field>
+ <error type="Font"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="GC"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Pixmap"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+ ]]></error>
+ </doc>
</request>
<request name="CopyGC" opcode="57">
@@ -1651,6 +4006,16 @@ authorization from the authors.
<request name="FreeGC" opcode="60">
<pad bytes="1" />
<field type="GCONTEXT" name="gc" />
+ <doc>
+ <brief>Destroys a graphics context</brief>
+ <description><![CDATA[
+Destroys the specified `gc` and all associated storage.
+ ]]></description>
+ <field name="gc"><![CDATA[The graphics context to destroy.]]></field>
+ <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+ ]]></error>
+ </doc>
</request>
<request name="ClearArea" opcode="61">
@@ -1673,6 +4038,48 @@ authorization from the authors.
<field type="INT16" name="dst_y" />
<field type="CARD16" name="width" />
<field type="CARD16" name="height" />
+ <doc>
+ <brief>copy areas</brief>
+ <description><![CDATA[
+Copies the specified rectangle from `src_drawable` to `dst_drawable`.
+ ]]></description>
+ <field name="dst_drawable"><![CDATA[
+The destination drawable (Window or Pixmap).
+ ]]></field>
+ <field name="src_drawable"><![CDATA[
+The source drawable (Window or Pixmap).
+ ]]></field>
+ <field name="gc"><![CDATA[
+The graphics context to use.
+ ]]></field>
+ <field name="src_x"><![CDATA[
+The source X coordinate.
+ ]]></field>
+ <field name="src_y"><![CDATA[
+The source Y coordinate.
+ ]]></field>
+ <field name="dst_x"><![CDATA[
+The destination X coordinate.
+ ]]></field>
+ <field name="dst_y"><![CDATA[
+The destination Y coordinate.
+ ]]></field>
+ <field name="width"><![CDATA[
+The width of the area to copy (in pixels).
+ ]]></field>
+ <field name="height"><![CDATA[
+The height of the area to copy (in pixels).
+ ]]></field>
+ <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+ ]]></error>
+ <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+ ]]></error>
+ <error type="Match"><![CDATA[
+`src_drawable` has a different root or depth than `dst_drawable`.
+ ]]></error>
+ </doc>
</request>
<request name="CopyPlane" opcode="63">
@@ -1692,6 +4099,14 @@ authorization from the authors.
<enum name="CoordMode">
<item name="Origin"> <value>0</value></item>
<item name="Previous"><value>1</value></item>
+ <doc>
+ <field name="Origin"><![CDATA[
+Treats all coordinates as relative to the origin.
+ ]]></field>
+ <field name="Previous"><![CDATA[
+Treats all coordinates after the first as relative to the previous coordinate.
+ ]]></field>
+ </doc>
</enum>
<!-- combine-adjacent doesn't work for mode==Relative -->
@@ -1707,6 +4122,56 @@ authorization from the authors.
<field type="DRAWABLE" name="drawable" />
<field type="GCONTEXT" name="gc" />
<list type="POINT" name="points" />
+ <doc>
+ <brief>draw lines</brief>
+ <description><![CDATA[
+Draws `points_len`-1 lines between each pair of points (point[i], point[i+1])
+in the `points` array. The lines are drawn in the order listed in the array.
+They join correctly at all intermediate points, and if the first and last
+points coincide, the first and last lines also join correctly. For any given
+line, a pixel is not drawn more than once. If thin (zero line-width) lines
+intersect, the intersecting pixels are drawn multiple times. If wide lines
+intersect, the intersecting pixels are drawn only once, as though the entire
+request were a single, filled shape.
+ ]]></description>
+ <example><![CDATA[
+/*
+ * Draw a straight line.
+ *
+ */
+void my_example(xcb_connection *conn, xcb_drawable_t drawable, xcb_gcontext_t gc) {
+ xcb_poly_line(conn, XCB_COORD_MODE_ORIGIN, drawable, gc, 2,
+ (xcb_point_t[]) { {10, 10}, {100, 10} });
+ xcb_flush(conn);
+}
+ ]]></example>
+ <field name="drawable"><![CDATA[
+The drawable to draw the line(s) on.
+ ]]></field>
+ <field name="gc"><![CDATA[
+The graphics context to use.
+ ]]></field>
+ <field name="points_len"><![CDATA[
+The number of `xcb_point_t` structures in `points`.
+ ]]></field>
+ <field name="points"><![CDATA[
+An array of points.
+ ]]></field>
+ <!-- the enum doc is sufficient. -->
+ <field name="coordinate_mode" />
+ <error type="Drawable"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="GC"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <error type="Value"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ </doc>
</request>
<struct name="SEGMENT">
@@ -1721,6 +4186,43 @@ authorization from the authors.
<field type="DRAWABLE" name="drawable" />
<field type="GCONTEXT" name="gc" />
<list type="SEGMENT" name="segments" />
+ <doc>
+ <brief>draw lines</brief>
+ <description><![CDATA[
+Draws multiple, unconnected lines. For each segment, a line is drawn between
+(x1, y1) and (x2, y2). The lines are drawn in the order listed in the array of
+`xcb_segment_t` structures and does not perform joining at coincident
+endpoints. For any given line, a pixel is not drawn more than once. If lines
+intersect, the intersecting pixels are drawn multiple times.
+
+TODO: include the xcb_segment_t data structure
+
+TODO: an example
+ ]]></description>
+ <field name="drawable"><![CDATA[
+A drawable (Window or Pixmap) to draw on.
+ ]]></field>
+ <field name="gc"><![CDATA[
+The graphics context to use.
+
+TODO: document which attributes of a gc are used
+ ]]></field>
+ <field name="segments_len"><![CDATA[
+The number of `xcb_segment_t` structures in `segments`.
+ ]]></field>
+ <field name="segments"><![CDATA[
+An array of `xcb_segment_t` structures.
+ ]]></field>
+ <error type="Drawable"><![CDATA[
+The specified `drawable` does not exist.
+ ]]></error>
+ <error type="GC"><![CDATA[
+The specified `gc` does not exist.
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ </doc>
</request>
<request name="PolyRectangle" opcode="67" combine-adjacent="true">
@@ -1763,6 +4265,42 @@ authorization from the authors.
<field type="DRAWABLE" name="drawable" />
<field type="GCONTEXT" name="gc" />
<list type="RECTANGLE" name="rectangles" />
+ <doc>
+ <brief>Fills rectangles</brief>
+ <description><![CDATA[
+Fills the specified rectangle(s) in the order listed in the array. For any
+given rectangle, each pixel is not drawn more than once. If rectangles
+intersect, the intersecting pixels are drawn multiple times.
+ ]]></description>
+ <field name="drawable"><![CDATA[
+The drawable (Window or Pixmap) to draw on.
+ ]]></field>
+ <field name="gc"><![CDATA[
+The graphics context to use.
+
+The following graphics context components are used: function, plane-mask,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+
+The following graphics context mode-dependent components are used:
+foreground, background, tile, stipple, tile-stipple-x-origin, and
+tile-stipple-y-origin.
+ ]]></field>
+ <field name="rectangles_len"><![CDATA[
+The number of `xcb_rectangle_t` structures in `rectangles`.
+ ]]></field>
+ <field name="rectangles"><![CDATA[
+The rectangles to fill.
+ ]]></field>
+ <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+ ]]></error>
+ <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ </doc>
</request>
<request name="PolyFillArc" opcode="71" combine-adjacent="true">
@@ -1841,6 +4379,52 @@ authorization from the authors.
<list type="char" name="string">
<fieldref>string_len</fieldref>
</list>
+ <doc>
+ <brief>Draws text</brief>
+ <description><![CDATA[
+Fills the destination rectangle with the background pixel from `gc`, then
+paints the text with the foreground pixel from `gc`. The upper-left corner of
+the filled rectangle is at [x, y - font-ascent]. The width is overall-width,
+the height is font-ascent + font-descent. The overall-width, font-ascent and
+font-descent are as returned by `xcb_query_text_extents` (TODO).
+
+Note that using X core fonts is deprecated (but still supported) in favor of
+client-side rendering using Xft.
+ ]]></description>
+ <field name="drawable"><![CDATA[
+The drawable (Window or Pixmap) to draw text on.
+ ]]></field>
+ <field name="string_len"><![CDATA[
+The length of the `string`. Note that this parameter limited by 255 due to
+using 8 bits!
+ ]]></field>
+ <field name="string"><![CDATA[
+The string to draw. Only the first 255 characters are relevant due to the data
+type of `string_len`.
+ ]]></field>
+ <field name="x"><![CDATA[
+The x coordinate of the first character, relative to the origin of `drawable`.
+ ]]></field>
+ <field name="y"><![CDATA[
+The y coordinate of the first character, relative to the origin of `drawable`.
+ ]]></field>
+ <field name="gc"><![CDATA[
+The graphics context to use.
+
+The following graphics context components are used: plane-mask, foreground,
+background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+ ]]></field>
+ <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+ ]]></error>
+ <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <see type="request" name="ImageText16" />
+ </doc>
</request>
<request name="ImageText16" opcode="77">
@@ -1852,6 +4436,53 @@ authorization from the authors.
<list type="CHAR2B" name="string">
<fieldref>string_len</fieldref>
</list>
+ <doc>
+ <brief>Draws text</brief>
+ <description><![CDATA[
+Fills the destination rectangle with the background pixel from `gc`, then
+paints the text with the foreground pixel from `gc`. The upper-left corner of
+the filled rectangle is at [x, y - font-ascent]. The width is overall-width,
+the height is font-ascent + font-descent. The overall-width, font-ascent and
+font-descent are as returned by `xcb_query_text_extents` (TODO).
+
+Note that using X core fonts is deprecated (but still supported) in favor of
+client-side rendering using Xft.
+ ]]></description>
+ <field name="drawable"><![CDATA[
+The drawable (Window or Pixmap) to draw text on.
+ ]]></field>
+ <field name="string_len"><![CDATA[
+The length of the `string` in characters. Note that this parameter limited by
+255 due to using 8 bits!
+ ]]></field>
+ <field name="string"><![CDATA[
+The string to draw. Only the first 255 characters are relevant due to the data
+type of `string_len`. Every character uses 2 bytes (hence the 16 in this
+request's name).
+ ]]></field>
+ <field name="x"><![CDATA[
+The x coordinate of the first character, relative to the origin of `drawable`.
+ ]]></field>
+ <field name="y"><![CDATA[
+The y coordinate of the first character, relative to the origin of `drawable`.
+ ]]></field>
+ <field name="gc"><![CDATA[
+The graphics context to use.
+
+The following graphics context components are used: plane-mask, foreground,
+background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+ ]]></field>
+ <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+ ]]></error>
+ <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+ ]]></error>
+ <error type="Match"><![CDATA[
+TODO: reasons?
+ ]]></error>
+ <see type="request" name="ImageText8" />
+ </doc>
</request>
<enum name= "ColormapAlloc">
@@ -1915,6 +4546,31 @@ authorization from the authors.
<pad bytes="2" />
<field type="CARD32" name="pixel" />
</reply>
+ <doc>
+ <brief>Allocate a color</brief>
+ <description><![CDATA[
+Allocates a read-only colormap entry corresponding to the closest RGB value
+supported by the hardware. If you are using TrueColor, you can take a shortcut
+and directly calculate the color pixel value to avoid the round trip. But, for
+example, on 16-bit color setups (VNC), you can easily get the closest supported
+RGB value to the RGB value you are specifying.
+ ]]></description>
+ <field name="cmap"><![CDATA[
+TODO
+ ]]></field>
+ <field name="red"><![CDATA[
+The red value of your color.
+ ]]></field>
+ <field name="green"><![CDATA[
+The green value of your color.
+ ]]></field>
+ <field name="blue"><![CDATA[
+The blue value of your color.
+ ]]></field>
+ <error type="Colormap"><![CDATA[
+The specified colormap `cmap` does not exist.
+ ]]></error>
+ </doc>
</request>
<request name="AllocNamedColor" opcode="85">
@@ -2092,11 +4748,82 @@ authorization from the authors.
<field type="CARD16" name="back_red" />
<field type="CARD16" name="back_green" />
<field type="CARD16" name="back_blue" />
+ <doc>
+ <brief>create cursor</brief>
+ <description><![CDATA[
+Creates a cursor from a font glyph. X provides a set of standard cursor shapes
+in a special font named cursor. Applications are encouraged to use this
+interface for their cursors because the font can be customized for the
+individual display type.
+
+All pixels which are set to 1 in the source will use the foreground color (as
+specified by `fore_red`, `fore_green` and `fore_blue`). All pixels set to 0
+will use the background color (as specified by `back_red`, `back_green` and
+`back_blue`).
+ ]]></description>
+ <field name="cid"><![CDATA[
+The ID with which you will refer to the cursor, created by `xcb_generate_id`.
+ ]]></field>
+ <field name="source_font"><![CDATA[
+In which font to look for the cursor glyph.
+ ]]></field>
+ <field name="mask_font"><![CDATA[
+In which font to look for the mask glyph.
+ ]]></field>
+ <field name="source_char"><![CDATA[
+The glyph of `source_font` to use.
+ ]]></field>
+ <field name="mask_char"><![CDATA[
+The glyph of `mask_font` to use as a mask: Pixels which are set to 1 define
+which source pixels are displayed. All pixels which are set to 0 are not
+displayed.
+ ]]></field>
+ <field name="fore_red"><![CDATA[
+The red value of the foreground color.
+ ]]></field>
+ <field name="fore_green"><![CDATA[
+The green value of the foreground color.
+ ]]></field>
+ <field name="fore_blue"><![CDATA[
+The blue value of the foreground color.
+ ]]></field>
+ <field name="back_red"><![CDATA[
+The red value of the background color.
+ ]]></field>
+ <field name="back_green"><![CDATA[
+The green value of the background color.
+ ]]></field>
+ <field name="back_blue"><![CDATA[
+The blue value of the background color.
+ ]]></field>
+ <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+ ]]></error>
+ <error type="Font"><![CDATA[
+The specified `source_font` or `mask_font` does not exist.
+ ]]></error>
+ <error type="Value"><![CDATA[
+Either `source_char` or `mask_char` are not defined in `source_font` or `mask_font`, respectively.
+ ]]></error>
+ <!-- TODO: example -->
+ </doc>
</request>
<request name="FreeCursor" opcode="95">
<pad bytes="1" />
<field type="CURSOR" name="cursor" />
+ <doc>
+ <brief>Deletes a cursor</brief>
+ <description><![CDATA[
+Deletes the association between the cursor resource ID and the specified
+cursor. The cursor is freed when no other resource references it.
+ ]]></description>
+ <field name="cursor"><![CDATA[The cursor to destroy.]]></field>
+ <error type="Cursor"><![CDATA[
+The specified cursor does not exist.
+ ]]></error>
+ </doc>
+
</request>
<request name="RecolorCursor" opcode="96">
@@ -2141,7 +4868,44 @@ authorization from the authors.
<field type="CARD8" name="major_opcode" />
<field type="CARD8" name="first_event" />
<field type="CARD8" name="first_error" />
+ <doc>
+ <field name="present"><![CDATA[
+Whether the extension is present on this X11 server.
+ ]]></field>
+ <field name="major_opcode"><![CDATA[
+The major opcode for requests.
+ ]]></field>
+ <field name="first_event"><![CDATA[
+The first event code, if any.
+ ]]></field>
+ <field name="first_error"><![CDATA[
+The first error code, if any.
+ ]]></field>
+ </doc>
</reply>
+ <doc>
+ <brief>check if extension is present</brief>
+ <description><![CDATA[
+Determines if the specified extension is present on this X11 server.
+
+Every extension has a unique `major_opcode` to identify requests, the minor
+opcodes and request formats are extension-specific. If the extension provides
+events and errors, the `first_event` and `first_error` fields in the reply are
+set accordingly.
+
+There should rarely be a need to use this request directly, XCB provides the
+`xcb_get_extension_data` function instead.
+ ]]></description>
+ <field name="name_len"><![CDATA[
+The length of `name` in bytes.
+ ]]></field>
+ <field name="name"><![CDATA[
+The name of the extension to query, for example "RANDR". This is case
+sensitive!
+ ]]></field>
+ <see type="program" name="xdpyinfo" />
+ <see type="function" name="xcb_get_extension_data" />
+ </doc>
</request>
<request name="ListExtensions" opcode="99">
@@ -2349,6 +5113,24 @@ authorization from the authors.
<request name="KillClient" opcode="113">
<pad bytes="1" />
<field type="CARD32" name="resource" altenum="Kill" />
+ <doc>
+ <brief>kills a client</brief>
+ <description><![CDATA[
+Forces a close down of the client that created the specified `resource`.
+ ]]></description>
+ <field name="resource"><![CDATA[
+Any resource belonging to the client (for example a Window), used to identify
+the client connection.
+
+The special value of `XCB_KILL_ALL_TEMPORARY`, the resources of all clients
+that have terminated in `RetainTemporary` (TODO) are destroyed.
+ ]]></field>
+ <error type="Value"><![CDATA[
+The specified `resource` does not exist.
+ ]]></error>
+ <see type="program" name="xkill" />
+ </doc>
+
</request>
<request name="RotateProperties" opcode="114">
diff --git a/libxcb/xcb-proto/xcbgen/expr.py b/libxcb/xcb-proto/xcbgen/expr.py
index bbc5a3fd7..4f8af6f83 100644
--- a/libxcb/xcb-proto/xcbgen/expr.py
+++ b/libxcb/xcb-proto/xcbgen/expr.py
@@ -1,127 +1,129 @@
-'''
-This module contains helper classes for structure fields and length expressions.
-'''
-class Field(object):
- '''
- Represents a field of a structure.
-
- type is the datatype object for the field.
- field_type is the name of the type (string tuple)
- field_name is the name of the structure field.
- 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)
- '''
- def __init__(self, type, field_type, field_name, visible, wire, auto):
- self.type = type
- self.field_type = field_type
- self.field_name = field_name
- self.visible = visible
- self.wire = wire
- self.auto = auto
-
-
-class Expression(object):
- '''
- Represents a mathematical expression for a list length or exprfield.
-
- Public fields:
- op is the operation (text +,*,/,<<,~) or None.
- lhs and rhs are the sub-Expressions if op is set.
- lenfield_name is the name of the length field, or None for request lists.
- lenfield is the Field object for the length field, or None.
- bitfield is True if the length field is a bitmask instead of a number.
- nmemb is the fixed size (value)of the expression, or None
- '''
- def __init__(self, elt, parent):
- self.parent = parent
-
- self.nmemb = None
-
- self.lenfield_name = None
- self.lenfield_type = None
- self.lenfield_parent = None
- self.lenfield = None
- self.lenwire = False
- self.bitfield = False
-
- self.op = None
- self.lhs = None
- self.rhs = None
-
- if elt.tag == 'list':
- # List going into a request, which has no length field (inferred by server)
- self.lenfield_name = elt.get('name') + '_len'
- self.lenfield_type = 'CARD32'
-
- elif elt.tag == 'fieldref':
- # Standard list with a fieldref
- self.lenfield_name = elt.text
-
- elif elt.tag == 'valueparam':
- # Value-mask. The length bitmask is described by attributes.
- self.lenfield_name = elt.get('value-mask-name')
- self.lenfield_type = elt.get('value-mask-type')
- self.lenwire = True
- self.bitfield = True
-
- elif elt.tag == 'op':
- # Op field. Need to recurse.
- self.op = elt.get('op')
- self.lhs = Expression(list(elt)[0], parent)
- self.rhs = Expression(list(elt)[1], parent)
-
- # Hopefully we don't have two separate length fields...
- self.lenfield_name = self.lhs.lenfield_name
- if self.lenfield_name == None:
- self.lenfield_name = self.rhs.lenfield_name
-
- elif elt.tag == 'unop':
- # Op field. Need to recurse.
- self.op = elt.get('op')
- self.rhs = Expression(list(elt)[0], parent)
-
- self.lenfield_name = self.rhs.lenfield_name
-
- elif elt.tag == 'value':
- # Constant expression
- self.nmemb = int(elt.text, 0)
-
- elif elt.tag == 'popcount':
- self.op = 'popcount'
- self.rhs = Expression(list(elt)[0], parent)
- self.lenfield_name = self.rhs.lenfield_name
- # xcb_popcount returns 'int' - handle the type in the language-specific part
-
- elif elt.tag == 'enumref':
- self.op = 'enumref'
- self.lenfield_name = (elt.get('ref'), elt.text)
-
- elif elt.tag == 'sumof':
- self.op = 'sumof'
- self.lenfield_name = elt.get('ref')
-
- else:
- # Notreached
- raise Exception("undefined tag '%s'" % elt.tag)
-
- def fixed_size(self):
- return self.nmemb != None
-
- def resolve(self, module, parents):
- if self.op == 'enumref':
- self.lenfield_type = module.get_type(self.lenfield_name[0])
- self.lenfield_name = self.lenfield_name[1]
- elif self.op == 'sumof':
- # need to find the field with lenfield_name
- for p in reversed(parents):
- fields = dict([(f.field_name, f) for f in p.fields])
- if self.lenfield_name in fields.keys():
- if p.is_bitcase:
- # switch is the anchestor
- self.lenfield_parent = p.parents[-1]
- else:
- self.lenfield_parent = p
- self.lenfield_type = fields[self.lenfield_name].field_type
- break
-
+'''
+This module contains helper classes for structure fields and length expressions.
+'''
+class Field(object):
+ '''
+ Represents a field of a structure.
+
+ type is the datatype object for the field.
+ field_type is the name of the type (string tuple)
+ field_name is the name of the structure field.
+ 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, 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
+
+
+class Expression(object):
+ '''
+ Represents a mathematical expression for a list length or exprfield.
+
+ Public fields:
+ op is the operation (text +,*,/,<<,~) or None.
+ lhs and rhs are the sub-Expressions if op is set.
+ lenfield_name is the name of the length field, or None for request lists.
+ lenfield is the Field object for the length field, or None.
+ bitfield is True if the length field is a bitmask instead of a number.
+ nmemb is the fixed size (value)of the expression, or None
+ '''
+ def __init__(self, elt, parent):
+ self.parent = parent
+
+ self.nmemb = None
+
+ self.lenfield_name = None
+ self.lenfield_type = None
+ self.lenfield_parent = None
+ self.lenfield = None
+ self.lenwire = False
+ self.bitfield = False
+
+ self.op = None
+ self.lhs = None
+ self.rhs = None
+
+ if elt.tag == 'list':
+ # List going into a request, which has no length field (inferred by server)
+ self.lenfield_name = elt.get('name') + '_len'
+ self.lenfield_type = 'CARD32'
+
+ elif elt.tag == 'fieldref':
+ # Standard list with a fieldref
+ self.lenfield_name = elt.text
+
+ elif elt.tag == 'valueparam':
+ # Value-mask. The length bitmask is described by attributes.
+ self.lenfield_name = elt.get('value-mask-name')
+ self.lenfield_type = elt.get('value-mask-type')
+ self.lenwire = True
+ self.bitfield = True
+
+ elif elt.tag == 'op':
+ # Op field. Need to recurse.
+ self.op = elt.get('op')
+ self.lhs = Expression(list(elt)[0], parent)
+ self.rhs = Expression(list(elt)[1], parent)
+
+ # Hopefully we don't have two separate length fields...
+ self.lenfield_name = self.lhs.lenfield_name
+ if self.lenfield_name == None:
+ self.lenfield_name = self.rhs.lenfield_name
+
+ elif elt.tag == 'unop':
+ # Op field. Need to recurse.
+ self.op = elt.get('op')
+ self.rhs = Expression(list(elt)[0], parent)
+
+ self.lenfield_name = self.rhs.lenfield_name
+
+ elif elt.tag == 'value':
+ # Constant expression
+ self.nmemb = int(elt.text, 0)
+
+ elif elt.tag == 'popcount':
+ self.op = 'popcount'
+ self.rhs = Expression(list(elt)[0], parent)
+ self.lenfield_name = self.rhs.lenfield_name
+ # xcb_popcount returns 'int' - handle the type in the language-specific part
+
+ elif elt.tag == 'enumref':
+ self.op = 'enumref'
+ self.lenfield_name = (elt.get('ref'), elt.text)
+
+ elif elt.tag == 'sumof':
+ self.op = 'sumof'
+ self.lenfield_name = elt.get('ref')
+
+ else:
+ # Notreached
+ raise Exception("undefined tag '%s'" % elt.tag)
+
+ def fixed_size(self):
+ return self.nmemb != None
+
+ def resolve(self, module, parents):
+ if self.op == 'enumref':
+ self.lenfield_type = module.get_type(self.lenfield_name[0])
+ self.lenfield_name = self.lenfield_name[1]
+ elif self.op == 'sumof':
+ # need to find the field with lenfield_name
+ for p in reversed(parents):
+ fields = dict([(f.field_name, f) for f in p.fields])
+ if self.lenfield_name in fields.keys():
+ if p.is_bitcase:
+ # switch is the anchestor
+ self.lenfield_parent = p.parents[-1]
+ else:
+ self.lenfield_parent = p
+ self.lenfield_type = fields[self.lenfield_name].field_type
+ break
+
diff --git a/libxcb/xcb-proto/xcbgen/xtypes.py b/libxcb/xcb-proto/xcbgen/xtypes.py
index c78915846..f6d463445 100644
--- a/libxcb/xcb-proto/xcbgen/xtypes.py
+++ b/libxcb/xcb-proto/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 <doc> 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)
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-01 01:48:05 +0000