[Xcb] tutorials/sample code

[Alan Coopersmith]

first last wrote:
> i hate to send this email but i can't find any good tutorials on xcb.
> 
> any kind of sample code, manuals, description of methods and usage
> patterns would be helpful.

As mentioned already, there is a tutorial and reference manual on the
website, and the apps already ported provide some sample code.

But I also agree we need better docs, and others have expressed similar
desires - one of the comments on my recent blog on the xwininfo port to xcb
was from Havoc, who recently provided some patches to improve the docs, but
those still need to be incorporated:
	https://bugs.freedesktop.org/show_bug.cgi?id=29655

(For those who haven't seen it yet, this was one of the items from his
 " XCB ENHANCEMENTS " blog post at http://log.ometer.com/2010-08.html#22 )

I've also been thinking lately that we should have an "XCB Cookbook" (if
you're familiar with any of the O'Reilly books with "____ Cookbook" names,
then you should have a good idea what I'm thinking of).

So while the reference manual describes all the parameters and return values
of a function like xcb_connect(), the cookbook would provide example code
utilizing our current recommended best practices, and an explanation of why
it's done that way.   For instance:

- Connecting to the X server:

    char *displayname = NULL;
    int screen_number = 0;
    xcb_connection_t *dpy;

    /* command line option parsing may set displayname to the argument
       to a -display option */

    dpy = xcb_connect(displayname, &screen_number);
    if (xcb_connection_has_error(dpy)) {
        char *name = displayname;
        if (!name)
            name = getenv("DISPLAY");
        if (!name)
            name = "";
        fprintf (stderr, "%s:  unable to open display \"%s\"\r\n",
                 ProgramName, name);
        exit (1);
    }

    This code connects to a X server and reports an error if it cannot.
    If the user does not provide a -display option, the NULL value for
    displayname causes the library to check the traditional DISPLAY
    environment variable.   In the failure case though, we have to
    implement this check ourselves in order to print an error message,
    and must ensure we don't try to call printf with a NULL argument
    for the displayname string, since that may segfault on some systems
    (such as Solaris 10 and older).

If we find code is being repeated a lot, it may suggest things that
belong in an xcb-util API.   (For instance, shouldn't there be an
xcb_get_display_name so that programs don't have to replicate this
logic and keep it updated if support is ever added for another
environment variable or other method of finding the display?)

-- 
	-Alan Coopersmith-        alan.coopersmith at oracle.com
	 Oracle Solaris Platform Engineering: X Window System