Language binding appendix (was Re: [cairo] cairo-java API review)

[Owen Taylor]

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
> documentation.

This can now be seen at:

  http://cairographics.org/~otaylor/manual/

(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:

   cairo_pattern_t
       cairo_solid_pattern_t
       cairo_surface_pattern_t
       cairo_gradient_t
          cairo_linear_gradient_t
          cairo_radial_gradient_t 

   But internally things are named more like:

       cairo_gradient_pattern_t
          cairo_linear_pattern_t
          cairo_radial_pattern_t 

   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 
   for cairo.

   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 
   different.

   (An argument could be made for a *no overloading* stance, but
   I think that would come across as very artificial in some 
   languages)

 - 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
   binding's iterators".

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
or Context.

Regards,
					Owen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050508/0887a468/attachment.pgp