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

[Carl Worth]

On Sun, 13 Mar 2005 14:30:17 -0500, Owen Taylor wrote:
> ? Or maybe the cairo_create_<blah>_ convenience functions are just a bad 
> idea. 
> 
> (See earlier cairo_create_and_own() proposal, which I'd like more
> if I could come up with a better name for it. cairo_create_take_ownership()? 
> Long names for functions that are in hello-world examples and are meant to 
> be use nested are unpleasant...)

As I just mentioned, I'm about to implement the new cairo_create_
stuff.

I've been puzzling over this naming problem for some time. I recently
read over Andrew Tridgell's talloc library which has a naming idea we
might steal. It has:

	void *talloc_steal(const void *new_ctx, const void *ptr);

	The talloc_steal() function changes the parent context of a talloc
	pointer. It is typically used when the context that the pointer is
	currently a child of is going to be freed and you wish to keep the
	memory for a longer time.

So perhaps just cairo_create_steal() ? Perhaps cairo_create_and_steal() 
is more clear, but might push the limits of taste with inconveniently
long names for convenience functions once again.

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:

    cr = cairo_create_for_image (CAIRO_FORMAT_ARGB32, 256, 256);

    cr = cairo_create_with_image (CAIRO_FORMAT_ARGB32, 256, 256);

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