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

   1 .TH xcb-requests __libmansuffix__ __xorgversion__ "XCB examples"
   2 .ad l
   3 .SH NAME
   4 xcb-requests \- about request manpages
   5 .SH DESCRIPTION
   6 Every request in X11, like \fIMapWindow\fP, corresponds to a number of
   7 functions and data structures in XCB. For \fIMapWindow\fP, XCB provides the
   8 function \fIxcb_map_window\fP, which fills the \fIxcb_map_window_request_t\fP
   9 data structure and writes that to the X11 connection. Since the \fIMapWindow\fP
  10 request does not have a reply, this is the most simple case.
  11
  12 .SH REPLIES
  13
  14 Many requests have replies. For each reply, XCB provides at least a
  15 corresponding data structure and a function to return a pointer to a filled
  16 data structure. Let's take the \fIInternAtom\fP request as an example: XCB
  17 provides the \fIxcb_intern_atom_reply_t\fP data structure and
  18 \fIxcb_intern_atom_reply\fP function. For replies which are more complex (for
  19 example lists, such as in \fIxcb_list_fonts\fP), accessor functions are
  20 provided.
  21
  22 .SH COOKIES
  23
  24 XCB returns a cookie for each request you send. This is an XCB-specific data
  25 structure containing the sequence number with which the request was sent to the
  26 X11 server. To get any reply, you have to provide that cookie (so that XCB
  27 knows which of the waiting replies you want). Here is an example to illustrate
  28 the use of cookies:
  29
  30 .nf
  31 .sp
  32 void my_example(xcb_connection *conn) {
  33     xcb_intern_atom_cookie_t cookie;
  34     xcb_intern_atom_reply_t *reply;
  35
  36     cookie = xcb_intern_atom(conn, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
  37     /* ... do other work here if possible ... */
  38     if ((reply = xcb_intern_atom_reply(conn, cookie, NULL))) {
  39         printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
  40     }
  41     free(reply);
  42 }
  43 .fi
  44
  45 .SH CHECKED VS. UNCHECKED
  46
  47 The checked and unchecked suffixes for functions determine which kind of error
  48 handling is used for this specific request.
  49
  50 For requests which have no reply (for example \fIxcb_map_window\fP), errors
  51 will be delivered to the event loop (you will receive an X11 event of type 0
  52 when calling \fIxcb_poll_for_event\fP).
  53 If you want to explicitly check for errors in a blocking fashion, call the
  54 _checked version of the function (for example \fIxcb_map_window_checked\fP) and
  55 use \fIxcb_request_check\fP.
  56
  57 For requests which have a reply (for example \fIxcb_intern_atom\fP), errors
  58 will be checked when calling the reply function. To get errors in the event
  59 loop instead, use the _unchecked version of the function (for example
  60 \fIxcb_intern_atom_unchecked\fP).
  61
  62 Here is an example which illustrates the four different ways of handling errors:
  63
  64 .nf
  65 .sp
  66 /*
  67  * Request without a reply, handling errors in the event loop (default)
  68  *
  69  */
  70 void my_example(xcb_connection *conn, xcb_window_t window) {
  71     /* This is a request without a reply. Errors will be delivered to the event
  72      * loop. Getting an error to xcb_map_window most likely is a bug in our
  73      * program, so we don't need to check for that in a blocking way. */
  74     xcb_map_window(conn, window);
  75
  76     /* ... of course your event loop would not be in the same function ... */
  77     while ((event = xcb_wait_for_event(conn)) != NULL) {
  78         if (event->response_type == 0) {
  79             fprintf("Received X11 error %d\\n", error->error_code);
  80             free(event);
  81             continue;
  82         }
  83
  84         /* ... handle a normal event ... */
  85     }
  86 }
  87
  88 /*
  89  * Request without a reply, handling errors directly
  90  *
  91  */
  92 void my_example(xcb_connection *conn, xcb_window_t deco, xcb_window_t window) {
  93     /* A reparenting window manager wants to know whether a new window was
  94      * successfully reparented. If not (because the window got destroyed
  95      * already, for example), it does not make sense to map an empty window
  96      * decoration at all, so we need to know this right now. */
  97     xcb_void_cookie_t cookie = xcb_reparent_window_checked(conn, window,
  98                                                            deco, 0, 0);
  99     xcb_generic_error_t *error;
 100     if ((error = xcb_request_check(conn, cookie))) {
 101         fprintf(stderr, "Could not reparent the window\\n");
 102         free(error);
 103         return;
 104     }
 105
 106     /* ... do window manager stuff here ... */
 107 }
 108
 109 /*
 110  * Request with a reply, handling errors directly (default)
 111  *
 112  */
 113 void my_example(xcb_connection *conn, xcb_window_t window) {
 114     xcb_intern_atom_cookie_t cookie;
 115     xcb_intern_atom_reply_t *reply;
 116     xcb_generic_error_t *error;
 117
 118     cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
 119     /* ... do other work here if possible ... */
 120     if ((reply = xcb_intern_atom_reply(c, cookie, &error))) {
 121         printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
 122         free(reply);
 123     } else {
 124         fprintf(stderr, "X11 Error %d\\n", error->error_code);
 125         free(error);
 126     }
 127 }
 128
 129 /*
 130  * Request with a reply, handling errors in the event loop
 131  *
 132  */
 133 void my_example(xcb_connection *conn, xcb_window_t window) {
 134     xcb_intern_atom_cookie_t cookie;
 135     xcb_intern_atom_reply_t *reply;
 136
 137     cookie = xcb_intern_atom_unchecked(c, 0, strlen("_NET_WM_NAME"),
 138                                        "_NET_WM_NAME");
 139     /* ... do other work here if possible ... */
 140     if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) {
 141         printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
 142         free(reply);
 143     }
 144
 145     /* ... of course your event loop would not be in the same function ... */
 146     while ((event = xcb_wait_for_event(conn)) != NULL) {
 147         if (event->response_type == 0) {
 148             fprintf("Received X11 error %d\\n", error->error_code);
 149             free(event);
 150             continue;
 151         }
 152
 153         /* ... handle a normal event ... */
 154     }
 155 }
 156 .fi
 157
 158 .SH SEE ALSO
 159 .BR xcb_map_window (__libmansuffix__),
 160 .BR xcb_intern_atom (__libmansuffix__),
 161 .BR xcb_list_fonts (__libmansuffix__),
 162 .BR xcb_poll_for_event (__libmansuffix__),
 163 .BR xcb_request_check (__libmansuffix__)
 164 .SH AUTHOR
 165 Michael Stapelberg <michael+xcb at stapelberg dot de>