[cairo] Cleaning up the PDF API

[Carl Worth]

On Mon, 16 May 2005 19:23:42 -0400, Owen Taylor wrote:
> The destroy function is there principally for language bindings. 

That sets off a red flag for me. The cairo_pdf_surface_create_for_stream 
function is also there for users, (and even fairly trivial programs
might have to use it instead of cairo_pdf_surface_create---think
support for "-" to mean "write to stdout).

I'd prefer it if functionality intended uniquely for language binding
authors could be done in separate functions.

> For, the language binding implementing:
>  
>  createFromPDF (InputStream stream)
> 
> suggested in the language binding appendix, say.
> 
> It's quite awkward if the language binding author has to insert code
> into the binding for cairo_surface_finish() that checks to see if 
> the surface is a PDF surface they created, and if so, frees the
> InputStream.

But why would the language binding author ever do that? If the user is
creating the InputStream to pass into createFromPDF, shouldn't the
user being doing any flush, close, free operations needed on that
stream?

> Not only that, there is no conceptual reason that the language binding
> couldn't hand off the object they created to some C code that
> actually calls finish().

Would we perhaps want some other way to register a finish-time
callback in addition to a destroy-time callback? I don't know, but at
least that would be an API addition, so a decision much easier to make
after we gain more experience.

> I'm fond of the idea that you should be able to bind each function
> in an API basically one by one. That the language binding shouldn't
> have to "understand" the relationship between different functions
> to create a correct binding of the API.

I agree. And I think that usage of cairo in some language other than C
should not have a model drastically different than usage of cairo in
C. But I don't see why cairo_pdf_surface_create_for_stream must accept
a finish-time callback in order to allow this.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050516/756b716d/attachment.pgp