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 (filename, width_in_points, height_in_points) surface = cairo.PSSurface (filename, width_in_points, height_in_points) surface = cairo.SVGSurface (filename, width_in_points, height_in_points) Methods supporting default argument values: surface.mark_dirty (x=0, y=0, width=-1, height=-1)