[cairo] Docs for Python bindings to Cairo

[Steve]

On Sun, 2008-04-20 at 12:00 -0700, cairo-request at cairographics.org
wrote:
> I'm writing a Python program that uses the Cairo API.  The C++ API
> docs 
> (http://cairographics.org/manual) have a rather loose correspondence
> to 
> the Python bindings.  The Python binding for Cairo doesn't seem to
> have 
> any documentation, at least I haven't been able to find any.

Which PyCairo distribution or source are you using?
There are a few useful files in CVS (a 'docs' directory with a 'NOTES'
file and a very short 'FAQ'; and an 'examples' directory), but some
distributions (e.g. Fedora) do not distribute these files.

Having comprehensive PyCairo documentation would be good. There was a
discussion on the mailing list a long time ago about writing the cairo C
documentation in a text markup language. That would have been very
useful for language bindings (like PyCairo) because they could take the
original text and modify it to create their own documentation. But so
far it has not happened.

>     * Is this an appropriate list to discuss Cairo for Python?
Yes, but GTK+/PyGTK-specific questions may be better suited to the GTK
+/PyGTK mailing lists.

>     * I have some working code, and would like to contribute whatever
>       docs I can generate ... with whom should I correspond to get
>       started? I'd like to start by writing some docs for the Python
> API
>       for Cairo.

There were two good tutorials here:
http://www.tortall.net/mu/wiki/CairoTutorial
http://www.tortall.net/mu/wiki/PyGTKCairoTutorial
But I can't connect to the website today.

It would be good to have PyCairo API docs. But it would be very tedious
and time consuming to have have to write them from scratch and duplicate
about 90% of the content of the C API. Its probably better to
automatically generate them from the C API docs (but I don't know how).

> I used Glade to create the GUI, and libglade and PyGtk to bring it to 
> life.  Currently my Cairo code is invoked from expose_event.  I need
> to 
> develop a better understanding of how Cairo works.  The scant sample 
> programs that currently exist are not enough.  I'd be willing to 
> correspond with those who know, but aren't interested in spending
> much 
> time writing, so that I can write up more comprehensive docs for
> myself 
> and others.

Are you assuming that cairo is part of GTK+?
Cairo works independently to GTK+. GTK+ can use cairo, but cairo does
not need to use GTK+.

> Some issues I'd like to address in the docs, with Python sample code,
> are:
>     * What does Cairo provide that we didn't have before?
Where were you before! Do you mean what does GTK+ and cairo provide that
GTK+ and GDK graphics did not provide? If so - Anti-aliasing,
PNG/PS/PSF/SVG output, a new vector graphics drawing model as opposed to
the GDK raster graphics, alpha-compositing, gradients, maybe a few other
things too.

>     * How is PangoCairo related to Cairo?
Cairo has a minimal 'toy' text/font system. Pango is a much more
powerful font rendering system, and PangoCairo allows you to use Pango
to render to cairo surfaces.

>     * How does the Cairo event model relate to GTK?
There is no cairo event model. GTK uses the glib event-loop, cairo is
independent of GTK+ and has no concept of events.

>     * General structure of various types of programs that use Cairo
>     * What guidelines should one follow when writing Cairo animations?
>           o Timers and GObject
>           o Reducing flicker
>           o Resizing GTK components
>           o Context lifespan
>           o Pixbufs
>           o Layers
>           o User space / device space mapping

>     * Which GTK events relate specifically to Cairo?

>     * Are there any special considerations for using Glade when
> working
>       with Cairo?
I think most of these are PyGTK-specific questions.

Regards,
Steve