[Xcb] Milestone: API is stable

[Jamey Sharp]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20051207/4c390e0e/attachment.pgp