diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/.gitignore | 1 | ||||
| -rw-r--r-- | man/Makefile.am | 18 | ||||
| -rw-r--r-- | man/xcb-examples.man | 59 | ||||
| -rw-r--r-- | man/xcb-requests.man | 165 |
4 files changed, 243 insertions, 0 deletions
diff --git a/man/.gitignore b/man/.gitignore new file mode 100644 index 0000000..181f314 --- /dev/null +++ b/man/.gitignore @@ -0,0 +1 @@ +*.[0-9] diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..16bf51c --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,18 @@ + +libmandir = $(LIB_MAN_DIR) + +libman_PRE = \ + xcb-examples.man \ + xcb-requests.man + +libman_DATA = $(libman_PRE:man=$(LIB_MAN_SUFFIX)) + +EXTRA_DIST = $(libman_PRE) + +CLEANFILES = $(libman_DATA) + +# String replacements in MAN_SUBSTS now come from xorg-macros.m4 via configure +SUFFIXES = .$(LIB_MAN_SUFFIX) .man + +.man.$(LIB_MAN_SUFFIX): + $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@ diff --git a/man/xcb-examples.man b/man/xcb-examples.man new file mode 100644 index 0000000..87a71f2 --- /dev/null +++ b/man/xcb-examples.man @@ -0,0 +1,59 @@ +.TH xcb-examples __libmansuffix__ __xorgversion__ "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 indentation. + +Comments are in asterisks, like /* this */. + +No line is longer than 80 characters (including indentation). + +.SH SEE ALSO +.BR xcb_connect (__libmansuffix__), +.BR xcb_get_property (__libmansuffix__), +.BR xcb_flush (__libmansuffix__) +.SH AUTHOR +Michael Stapelberg <michael+xcb at stapelberg dot de> diff --git a/man/xcb-requests.man b/man/xcb-requests.man new file mode 100644 index 0000000..8d4a1dc --- /dev/null +++ b/man/xcb-requests.man @@ -0,0 +1,165 @@ +.TH xcb-requests __libmansuffix__ __xorgversion__ "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 (__libmansuffix__), +.BR xcb_intern_atom (__libmansuffix__), +.BR xcb_list_fonts (__libmansuffix__), +.BR xcb_poll_for_event (__libmansuffix__), +.BR xcb_request_check (__libmansuffix__) +.SH AUTHOR +Michael Stapelberg <michael+xcb at stapelberg dot de> |