Gdk/Cairo integration thought

[Owen Taylor <otaylor redhat com>]

I've been struggling for a while with naming issues for GDK/Cairo
integration. I've had a motley collection of functions:

  cairo_t *gdk_drawable_create_cairo_context (GdkDrawable *drawable);

  void gdk_pixbuf_set_as_cairo_source (GdkPixbuf *pixbuf,
                                        cairo_t   *cr,
                                        double     pixbuf_x,
                                        double     pixbuf_y);  

  void gdk_cairo_set_source_color (cairo_t  *cr,
                                   GdkColor *color); 

The general attempt is to keep stuff as methods on GDK objects
for language binding convenience, but that is inconvenient for
the above and worse for things I'd like to add like:

 void gdk_rectangle_add_to_cairo_path (GdkRectangle *rectangle,
                                       cairo_t      *cr);

Not only is it bad in C, but you lose the natural parallelism,
gdk_rectangle_add_to_cairo_path() is just another form of
cairo_rectangle (double x, double y, double width, double height);

Tonight I had the idea (Java pseudocode)

 public class org.gtk.gdk.Context (org.cairographics.Context) {
    public void Context (Drawable drawable);

    public void setSource  (Color      color);
    public void setSource  (Pixbuf     pixbuf,
                            double     pixbuf_x, 
                            double     pixbuf_y);

    public void rectangle   (Rectangle rectangle); 
 }

And in C:

 cairo_t *gdk_cairo_create (GdkDrawable *drawable);

 void gdk_cairo_set_source_color  (cairo_t     *cr,
                                   GdkColor    *color);
 void gdk_cairo_set_source_pixbuf (cairo_t     *cr,
                                   GdkPixbuf   *pixbuf,
                                   double       pixbuf_x,
                                   double       pixbuf_y);

 void gdk_cairo_rectangle        (cairo_t      *cr,
                                  GdkRectangle *rectangle);

So, we map convenience functions in C into derivation in an
object-oriented language. For those not familiar with Cairo
language bindings, note that cairo_t maps into

 Cairo.Context

in language bindings, not Cairo.<oops> or Cairo.Cairo 
I think this works quite nicely for convenience and naturalness
in both GTK+ and Cairo.

Possible problems:

 - Having Cairo.Context, Gdk.Context, and Pango.Context may be 
   annoying in some object oriented languages. A saving grace
   for Java is that Pango.Context is fairly rare to manipulate
   directly, and you'll usually use Gdk.Context rather than
   Cairo.Context in a GDK program, so you should only have to
   import one in a source file.

   Alternate names I can come up with: Gdk.GdkContext,
   Gdk.CairoContext and Gdk.Cairo all have their own problems.

 - Manual intervention will be needed for language bindings ...
   there is no way to derive a GObject from a non-GObject, even
   if I wanted people to write:

    gdk_cairo_rectangle (GDK_CONTEXT (cr), rectangle);

 - Similarly, things won't be great for introspection; it
   probably will be necessary to present everything as 
   standalone functions.

 - Most or all of the gdk_cairo_* functions actually work fine
   on *any* cairo_t. Though I don't think people will want to
   use them that way very often.

   For the functions that are less just convenience it might be
   good to preserve the opposite version - 

     drawable.createContext (drawable);

   as a parallel API, though that adds unpleasant duplication in the
   C API.

Anyways, I'd be interested to here reactions about the above proposal,
especially from language binding authors. I'm pretty happy with it,
but it clearly diverges a bit from the straight-and-narrow of bindable
GTK+ APIs.

Thanks,
					Owen

Attachment: signature.asc
Description: This is a digitally signed message part