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

[Keith Packard]

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

>     cr = cairo_create_steal (cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
>                                                          256, 256));

I think this is confusing; I don't mind the 'steal' verb, but it seems
like we should reserve it for an unusual operation instead of the
primary one.  In the talloc example you provided, the 'steal' operation
is invoked only in obscure circumstances where the data is being
re-parented after allocation.

You could write this as:

	cairo_surface_destroy (cairo_get_target_surface (cr =  cairo_create
(cairo_image_surface_create (CAIRO_FORMAT_ARGB32, 256, 256)));

but, I admit this is obscure at best...

One possibility is to have 'cairo_create' always transfer surface
ownership and have something like 'cairo_create_another' or some such
add a reference to the provided surface.  This is bad as it breaks the
usual model.

This leaves us with needing to name this function in a way which doesn't
scare people away like 'cairo_create_steal' might and yet which clearly
indicates that a reference to the surface is effectively lost in the
process.

cairo_create_for_surface_and_then_dereference_said_surface
cairo_create_and_own
cairo_marry
cairo_create_and_destroy
cairo_create_and_assume_ownership
cairo_create_for_new_surface
cairo_make
cairo_new
cairo_create_initial

As you can see, my naming skills remain limited in utility.

> 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:
> 
>     cr = cairo_create_for_image (CAIRO_FORMAT_ARGB32, 256, 256);
> 
>     cr = cairo_create_with_image (CAIRO_FORMAT_ARGB32, 256, 256);

Let's see how those compare with the similar functions used with
existing external objects:

    cr = cairo_xlib_create_for_drawable (Display *, Drawable)

vs

    cr = cairo_xlib_create_with_drawable (Display *, Drawable)

Yes, I know these perform different functions and we could distinguish
their operation with different prepositions, but that's unfair to the
poor user who has to try and remember them.

I suggest using 'for' in both cases (and in all other cases as well) as
it looks better in the xlib case while not looking completely out of
place in the image case.

-keith

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