[Xcb] Milestone: API is stable

[Jeremy A. Kolb]

On Wed, 7 Dec 2005, Jamey Sharp wrote:

> On Wed, Dec 07, 2005 at 08:08:43PM -0800, Jamey Sharp wrote:
> > This is one of the API warts I've been meaning to clean up for months.
> 
> I've just fixed my last complaints about the XCB API, by removing
> unproven interfaces from the specification and fixing the functions that
> remain, and I'm now declaring XCB's API *stable*.
> 
> This means that unless something unexpected happens, all code written to
> the API as implemented in CVS right now will both compile and run with
> XCB 1.0, whenever that is released. New functions may be added before
> then, but the current ones won't change.
> 
> This also means that the XcbApi page on the wiki actually documents
> XCB's real implementation now, instead of what the implementation would
> look like if it were cool. Code written to the old API will still work
> for a while, but I reserve the right to break the old stuff whenever I
> feel like it, so fix your code. :-)
> 
> Most applications should now use a pattern like this to get an
> XCBConnection:
> 	int screen;
> 	XCBConnection *c = XCBConnect(0, &screen);
> If your application accepts a --display parameter or has some other
> source of a display name, you can pass that string instead of 0. If you
> don't ever need a screen number, you can pass 0 instead of &screen.
> 
> The following functions are now deprecated and will be removed from the
> public API before XCB's 1.0 release. If you are using them, post to the
> list so we can figure out what to do for you.
>  * XCBConnectBasic (see XCBConnect)
>  * XCBWaitEvent (renamed to XCBWaitForEvent)
>  * XCBGetAuthInfo
>  * XCBOpen
>  * XCBOpenTCP
>  * XCBOpenUnix
> These functions are marked with GCC's deprecated attribute, so if you
> compile using GCC it will tell you whether and where you're calling
> them.
> 
> Not yet done: I'm going to make XCBFlush return something sensible. But
> probably nobody's checking the return value of XCBFlush right now, so
> nobody will care.
> 
> 
> I've renamed XCBConnect to XCBConnectToFD, and implemented XCBConnect
> and XCBConnectToDisplayWithAuthInfo. I provide a trivial implementation
> of the now-deprecated XCBConnectBasic for backwards compatibility, which
> I've tested. I also fixed XCBParseDisplay to accept a null screen
> pointer. Finally, I renamed XCBWaitEvent to XCBWaitForEvent and wrote a
> trivial implementation of the old function that just calls the new one.
> 
> Making XCBConnect follow the API documentation meant that a ton of code
> in xcbrandr just went away: if you want the Xlib-style DefaultScreen,
> the XCBConnect function will hand it to you. xcbrandr had been
> duplicating all of the code from XCBConnectBasic in order to achieve the
> same effect.
> 
> Connection creation in Xlib also will get simpler, as soon as I fix it,
> because XCBConnectToDisplayWithAuthInfo directly supports Xlib's needs
> (and is useful to display managers, and perhaps other applications). In
> the meantime Xlib/XCB won't compile and old versions won't run against
> new XCB.
> 
> --Jamey
> 

That's awesome.  Great job Jamey! I'm very pleased about all that ugly 
code in xcbrandr going away :)

Jeremy