[cairo] API Shakeup: cairo_begin_group, cairo_end_group, cairo_get_group

[Owen Taylor]

Carl Worth wrote:

> So, to avoid the invalid object, and to still have a name that clearly
> indicates the need to destroy the object, I propose the following:
> 
> 	/* Begin creating a group. */
> 	void
> 	cairo_create_group_begin (cairo_t *cr);
> 
> 	/* Begin creating a group with a specific format. */
> 	void
> 	cairo_create_group_begin_format (cairo_t *cr, cairo_format_t format);
> 
> 	/* Complete the creation of a group, and return it. */
> 	cairo_pattern_t *
> 	cairo_create_group_end (cairo_t *cr);
> 
> With this, the user doesn't get a handle on the object until it is
> valid.

These are pretty clumsy names, especially
cairo_create_group_begin_format().

The question I have is whether the "create" group actually helps
here. It's actually not immediately obvious to me that

   cairo_create_group_begin(cr);
   [...]
   pattern = cairo_create_group_end(cr);

Looks more like creating a new pattern than:

   cairo_create_begin_group(cr);
   [...]
   pattern = cairo_end_group(cr);

After all, what we created (from the names) was a "group" not a
"pattern".

Also, introducing "create" in an unnatural place to indicate memory
management is going to make  language bindings ugly for no good reason.

I think that the knowledge that end_group() returns a new pattern
is a small piece of information that a) most people are going to guess
right initially and b) we can reasonably expect the rest to learn.

So, even if we kill stashing in the pattern, I think the
begin_group()/end_group() names are better.

Regards,
					Owen