Language binding appendix (was Re: [cairo] cairo-java API review)
otaylor at redhat.com
Sun May 8 13:35:16 PDT 2005
On Tue, 2005-05-03 at 00:23 -0400, Owen Taylor wrote:
> I've started writing an appendix to the Cairo manual to cover this
> stuff; I'm not quite ready to commit to CVS, but I should be able to get
> something done in the next few days.
> Once something is initially in place, I hope that language binding
> authors will take an active role in maintaining this part of the
This can now be seen at:
(the main API doc build isn't working at the moment ... probably
needs the old cvs checkout blown away to fix conflicts)
It's written in a proscriptive style. "do this" "do that". I'd like
to see active pushback rather than silent divergence.
Parts that might be controversial:
- I've suggested the hierarchy for patterns as:
But internally things are named more like:
So, I may just be imposing my own personal preference rather than
faithfully echoing the way things are.
In any case, we should consider whether we should do renaming
in the C API
cairo_pattern_create_surface() => cairo_surface_pattern_create()
cairo_pattern_add_color_stop() => cairo_gradient_[pattern_]_add_color_stop()
To better reflect the underlying OO model.
- I've suggested that cairo_fill_extents() should return a
(x,y,width,height) rectangle rather than a (p1,p2) box. Again,
this may reflect my disagreement with the C API rather than
good binding practice.
- I've taken the stance "no use of function overloading unless the
overload is listed here", since I consider appropriate function
overloading use to involve judgments about future plans
This is to some extent personal preference ... I hate C++
(Java) APIs with big piles of overloaded functions where
every combination of arguments does something slightly
(An argument could be made for a *no overloading* stance, but
I think that would come across as very artificial in some
- The suggested cairo_path_t API is perhaps an uncomfortable
compromise between specifying it and leaving it up to the
language binding. It might be better to nail down a a fixed
iterator API rather than saying "make it match the language
The error handling section is pretty sketchy, partly because the
C API isn't really finalized yet. One thing I'm really uncertain
about is how to handle errors for the stream PDF API ...
with that API, any Cairo call can suddenly result in a
READ/WRITE being set on on the context. But I don't think
public void moveTo (double x, double y) throws IOException;
is sensible. At what point do you throw the exception? It
really has to be some method on PDFSurface, not on Surface
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050508/0887a468/attachment.pgp
More information about the cairo