veejay/sandbox/gtkcairo-0.3

GtkCairo
========

GtkCairo is an extension of GtkWidget that can paint itself using the
cairo api using a few backends (xlib w/Render acceleration, and glitz
w/open gl acceleration).

NOTE: GTK+ 2.7+ supports creating cairo contexts for GDK drawables,
making GtkCairo obsolete; see gdk_drawable_get_cairo().
GtkCairo can still be used as a convenient interface to cairo for
earlier GTK+ versions.

Synopsis
========

GtkWidget *gtk_cairo_new (void);
cairo_t   *gtk_cairo_get_cairo (GtkCairo *gtkcairo);

Signal prototypes
=================

"paint"
     void user_function (GtkWidget *widget,
                         cairo_t   *cr,
                         gpointer   user_data)

Object Hierarchy
================

GObject
+---GtkObject
    +----GtkWidget
         +----GtkCairo

Usage
=====

Hook up to the widgets "paint" signal with your custom drawing code,
queue redraw of the widget using gtk_widget_queue_draw (widget);

The interesting bits are the operations you can perform on the Cairo
surface, the documentation of which is outside the scope of GtkCairo.

To use GtkCairo in your code, add the package "gtkcairo" to the list
of packages you pull in via pkg-config.

Backend selection
=================

GtkCairo should choose a reasonable cairo backend by default, at the
moment this means the xlib backend since it provides AA at all times,
setting the backend can be done through the enviroment variable

export GTKCAIRO_BACKEND=gl
export GTKCAIRO_BACKEND=xlib
export GTKCAIRO_BACKEND=image (not implemented yet)

before starting an application.

Todo
====

* Make it possible to switch backend on the fly using a property,
* Implement the image backend, probably using gdkpixbuf.

Dependencies
============

GtkCairo depends on the obvious two:
 - GTK 2: http://www.gtk.org
 - Cairo: http://www.cairographics.org


vim: tw=70