cairo_create_ naming (was Re: [cairo] API Shakeup: cairo_output_stream_t and cairo_surface_finish())

[Owen Taylor]

On Wed, 2005-05-04 at 11:35 -0400, Carl Worth wrote:

> Let's see how that looks:
> 
>     cr = cairo_create_steal (cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
>                                                          256, 256));
> 
> I don't really mind that API too much, but I'm not convinced that
> that's what I want users to see as their first line of cairo code in
> the documentation. Either of the following do look quite a bit better
> to me:

I think it's important for a hello world to *look* fairly obvious.
And the "steal" above intrudes into the readers space in a way
that even
 
 surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, 256, 256);
 cr = cairo_create (surface);
 cairo_destroy (surface);

Doesn't. (Especially if you move the destroy() to the end of the
example so the user doesn't have to learn about reference counting)

>     cr = cairo_create_for_image (CAIRO_FORMAT_ARGB32, 256, 256);
> 
>     cr = cairo_create_with_image (CAIRO_FORMAT_ARGB32, 256, 256);

One possibility would be to say that we *only* have ImageSurface 
convenience constructors, and not add the Xlib, etc, versions
which have no real utility for compact "Hello Worlds" and cause
much more problems for language bindings.

But even there I'd argue against. The reason why I think we are
having trouble naming this operation is that the operation:

 Create an image, then create a cairo context using it

Is just not a natural one. Honestly, I think we should bite the bullet 
and just have cairo_create().

After all, to actually make any use of your context, you'll
have to extract the surface back out, and what you save in
the example in elegance by not having a cairo_surface_t 
variable is lost when you need to do:

 cairo_surface_write_png (cairo_get_target_surface (cr),
                          ...);

as compared to 

 cairo_surface_write_png (surface, ...);
 cairo_destroy (surface);

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/20050504/caf7e0e1/attachment.pgp