NOTES

Design of Pycairo bindings
--------------------------
The Pycairo bindings are designed to match the cairo C API as closely as
possible, and to deviate only in cases which are clearly better implemented in
a more 'Pythonic' way. Subsequently the cairo C API documentation can be used
as a reference for writing Pycairo programs. Any differences to the C API are
listed below.


Features of the Pycairo bindings
--------------------------------
* Provides an OO interface to cairo, using Python 2.2 new style classes.

* Pycairo_Check_Status() is called to check the status of cairo operations,
and raise exceptions as appropriate.

* Includes the cairo.gtk module - a extension module with a single function
for creating a cairo context from a GdkDrawable.  This makes it possible to
use the Pycairo with PyGTK. However, this module is not needed when using PyGTK
2.8 and above.

* Provides a C API that can be used by other Python extensions.


cairo module attributes and functions
-------------------------------------
cairo.version                 # the pycairo version, as a string
cairo.version_info            # the pycairo version, as a tuple

cairo.cairo_version()         # calls cairo_version()
cairo.cairo_version_string()  # calls cairo_version_string()

The C API has many constant/enumeration values that are translated into
Python as follows:
C			Python
CAIRO_FORMAT_ARGB32	cairo.FORMAT_ARGB32


Pycairo classes
---------------
C functions which take a cairo object, for example
    cairo_fill_preserve (cairo_t *cr);
become methods of the corresponding pycairo object, for example
    Context.fill_preserve (self)

cairo_reference(), cairo_destroy(), cairo_surface_reference(),
cairo_surface_destroy() etc are not required - Pycairo handles cairo object
construction and destruction.

The Pycairo classes are listed below showing just the differences to the C API.
Use the cairo docs to get a full listing of available functions.
See the 'examples' directory for Pycairo examples.


cairo.Context
-------------
C : cr = cairo_create (surface);
Py: ctx = cairo.Context (surface)

C : cairo_set_dash (cairo_t *cr, double *dashes, int ndash, double offset);
Py: ctx.set_dash (dash_sequence, offset)

Methods supporting default argument values:
ctx.mask_surface (surface, x=0.0, y=0.0)
ctx.select_font_face (family, slant=cairo.FONT_SLANT_NORMAL)
                      weight=cairo.FONT_WEIGHT_NORMAL)
ctx.set_source_surface (surface, x=0.0, y=0.0)
ctx.set_source_rgba (r, g, b, a=1.0)


cairo.FontFace
--------------
ff = cairo.FontFace() # does not work, FontFace cannot be instantiated
                      # directly, instead use
ff = Context.get_font_face()


cairo.FontOptions
-----------------
C : fo = cairo_font_options_create();
Py: fo = cairo.FontOptions()


cairo.Matrix
------------
C : cairo_matrix_init (cairo_matrix_t *matrix, xx, yx, xy, yy, x0, y0);
    cairo_matrix_init_identity (cairo_matrix_t *matrix);
    cairo_matrix_init_translate (cairo_matrix_t *matrix, tx, ty);
    cairo_matrix_init_scale (cairo_matrix_t *matrix, sx, sy);
    cairo_matrix_init_rotate (cairo_matrix_t *matrix, radians);
    cairo_matrix_multiply (result, matrix1, matrix2)

Py: matrix = cairo.Matrix (xx, yx, xy, yy, x0, y0)
    matrix = cairo.Matrix ()
    matrix = cairo.Matrix (x0=tx, y0=ty)
    matrix = cairo.Matrix (xx=sy, yy=sy)
    matrix = cairo.Matrix.init_rotate (radians)
    result = matrix1 * matrix2

To read Matrix values:
xx, yx, xy, yy, x0, y0 = matrix

To compare Matrix values:
matrix1 == matrix2
matrix1 != matrix2

Methods supporting default argument values:
matrix = cairo.Matrix (xx=1.0, yx=0.0, xy=0.0, yy=1.0, x0=0.0, y0=0.0)


cairo.Path
----------
path = cairo.Path() # does not work, Path cannot be instantiated directly,
                    # instead use
path = ctx.copy_path()  # or
path = ctx.copy_path_flat()

Path is an iterator, see examples/warpedtext.py for example usage

Path.__str__ lists the path elements


cairo.Pattern
-------------
Patterns are implemented in a class hierarchy:
Pattern  - abstract base class
  SolidPattern (r, g, b, a=1.0)
  SurfacePattern (surface)
  Gradient  - abstract base class
    LinearGradient (x0, y0, x1, y1)
    RadialGradient (cx0, cy0, radius0, cx1, cy1, radius1)


cairo.ScaledFont
----------------


cairo.Surface
-------------
Surfaces are implemented in a class hierarchy:
Surface         - base class, contains methods applicable to all surfaces
  ImageSurface
  PDFSurface
  PSSurface
  SVGSurface
  Win32Surface
  XlibSurface - available when using pygtk

C:  cairo_surface_write_to_png (surface, filename);
    cairo_surface_write_to_png_stream (surface, write_func, closure);

Py: surface.write_to_png (f)
      where 'f' is a filename, a file object, or a file-like object (an object
      that has a "write" method, for example StringIO, cStringIO)

C : surface = cairo_image_surface_create (format, width, height);
    surface = cairo_image_surface_create_from_png (filename);
    surface = cairo_image_surface_create_from_png_stream (read_func, closure);
    surface = cairo_image_surface_create_for_data (data, format, w, h, stride)

Py: surface = cairo.ImageSurface (format, width, height)
    surface = cairo.ImageSurface.create_from_png (f)
      where 'f' is a filename, a file object, or a file-like object
    surface = cairo.ImageSurface.create_for_data (data, format, w, h, stride)
      where 'data' if a writable Python buffer object

    extra pycairo ImageSurface creation methods:
    surface = cairo.ImageSurface.create_for_array (array)
                where 'array' is a Numerical Python array

C:  surface = cairo_pdf_surface_create (filename, width_in_points,
				        height_in_points);
    surface = cairo_ps_surface_create (filename, width_in_points,
			               height_in_points);
    surface = cairo_svg_surface_create (filename, width_in_points,
				        height_in_points);

Py: surface = cairo.PDFSurface (f, width_in_points, height_in_points)
    surface = cairo.PSSurface  (f, width_in_points, height_in_points)
    surface = cairo.SVGSurface (f, width_in_points, height_in_points)
    where 'f' is a filename, a file object, or a file-like object

Methods supporting default argument values:
surface.mark_dirty (x=0, y=0, width=-1, height=-1)