[cairo-commit] pycairo/doc FAQ,NONE,1.1 NOTES,NONE,1.1

[Steve Chaplin]

Committed by: stevech1097

Update of /cvs/cairo/pycairo/doc
In directory kemper:/tmp/cvs-serv26713/doc

Added Files:
	FAQ NOTES 
Log Message:
'SC'

--- NEW FILE: FAQ ---
Pycairo FAQ - Frequently Asked Questions
----------------------------------------

Q Can I subclass pycairo classes?
A
Cairo, the C library, is not an object oriented library, so a Python binding
can never be a truly object oriented interface to cairo.  One way to write the
Python bindings for cairo would be as a single long list of module functions -
this would be the most accurate representation of the underlying C
library. Pycairo (and most other cairo language bindings?) instead chose to
implement the bindings using Context, Surface, Pattern, etc classes.  An
advantage is that the classes organise cairo into groups of similar functions.
A disadvantage is that creates an illusion that cairo is object oriented
library, and people are then tempted to create subclasses to override cairo
methods. When in fact there are no methods to override, just cairo functions
which can't be overridden.

The cairo documentation Appendix A "Creating a language binding for cairo"
section "Memory Management" describes why deriving from a Surface creates
problems and is best avoided.

cairo.Context can be subclassed.
All other pycairo subclasses cannot be subclassed.

--- NEW FILE: 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.

* 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

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)