git.demorecorder.com Git - free-sw/xcb/libxcb/blob - man/xcb-examples.man

   1 .TH xcb-examples __libmansuffix__ __xorgversion__ "XCB examples"
   2 .ad l
   3 .SH NAME
   4 xcb-examples \- manpage examples
   5 .SH DESCRIPTION
   6 Many of the XCB manpages contain example code. These examples intend to explain
   7 how to use one particular part of XCB. They almost never represent a standalone
   8 (or even useful) program - X11 programs are relatively involved and
   9 thus beyond the scope of a manpage example.
  10
  11 .SH ENVIRONMENT
  12
  13 Every example assumes you have an \fIxcb_connection\fP and possibly other
  14 variables at hand. For illustrating how \fIxcb_get_property\fP works, you need
  15 the window of which you want to get the property, for example. To make it clear
  16 that these variables are your responsibility, these examples consist of a
  17 single function which takes the necessary variables as parameters.
  18
  19 .SH FLUSHING
  20
  21 Flushing means calling \fIxcb_flush\fP to clear the XCB-internal write buffer
  22 and send all pending requests to the X11 server. You don't explicitly need to
  23 flush before using a reply function (like \fIxcb_query_pointer_reply\fP), but
  24 you do need to flush before entering the event loop of your program.
  25
  26 There are only two cases when XCB flushes by itself. The first case is when
  27 its write buffer becomes full, the second case is when you are asking for
  28 the reply of a request which wasn't flushed out yet (like
  29 \fIxcb_query_pointer_reply\fP). This last point also includes
  30 xcb_request_check(). Please note that waiting for an event does \fBNOT\fP
  31 flush.
  32
  33 Examples generally include the \fIxcb_flush\fP call where appropriate (for
  34 example after setting a property). Therefore, including these functions and
  35 calling them in your application should just work. However, you might get
  36 better results when flushing outside of the function, depending on the
  37 architecture of your program.
  38
  39 .SH COMPILATION
  40
  41 If an example does not compile (without warnings) when using \fI-std=c99\fP,
  42 that is considered a documentation bug. Similarly, not handling errors or
  43 leaking memory is also considered a documentation bug. Please inform us about
  44 it on xcb@lists.freedesktop.org.
  45
  46 .SH CODING STYLE
  47
  48 Every example uses 4 spaces for indentation.
  49
  50 Comments are in asterisks, like /* this */.
  51
  52 No line is longer than 80 characters (including indentation).
  53
  54 .SH SEE ALSO
  55 .BR xcb_connect (__libmansuffix__),
  56 .BR xcb_get_property (__libmansuffix__),
  57 .BR xcb_flush (__libmansuffix__)
  58 .SH AUTHOR
  59 Michael Stapelberg <michael+xcb at stapelberg dot de>