C API Reference¶

This manual documents the API used by C and C++ programmers who want to write extension modules that use pycairo.

To access the Pycairo C API under Python 2¶

Edit the client module file to add the following lines:

/* All function, type and macro definitions needed to use the Pycairo/C API
 * are included in your code by the following line
 */
#include "Pycairo.h"

/* define a variable for the C API */
static Pycairo_CAPI_t *Pycairo_CAPI;

/* import pycairo - add to the init<module> function */
Pycairo_IMPORT;

To access the Pycairo C API under Python 3¶

Example showing how to import the pycairo API:

#include "py3cairo.h"

PyMODINIT_FUNC
PyInit_client(void)
{
  PyObject *m;

  m = PyModule_Create(&clientmodule);
  if (m == NULL)
      return NULL;
  if (import_cairo() < 0)
      return NULL;
  /* additional initialization can happen here */
  return m;
}

Pkg-Config Setup¶

pycairo installs “pycairo.pc” or “py3cairo.pc” in case of a Python 3 install:

> pkg-config --libs --cflags pycairo
> pkg-config --libs --cflags py3cairo
-I/usr/include/cairo -I/usr/include/glib-2.0
-I/usr/lib/x86_64-linux-gnu/glib-2.0/include -I/usr/include/pixman-1
-I/usr/include/freetype2 -I/usr/include/libpng16 -I/usr/include/pycairo
-lcairo

Misc Functions¶

int Pycairo_Check_Status(cairo_status_t status)¶

Parameters:	status (cairo_status_t) –
Returns:	-1 in case of an error, otherwise 0. Sets an exception in case of an error.

Takes a status value and converts it to an exception if it represents an error status.

Cairo Context¶

PyObject PycairoContext¶

cairo_t* PycairoContext.ctx¶: The wrapped cairo_t

PyTypeObject *PycairoContext_Type¶

cairo_t * PycairoContext_GET(PycairoContext *obj)¶

Parameters:	obj (PycairoContext) –
Returns:	`cairo_t` [transfer none]

Get the cairo_t object out of the PycairoContext.

PyObject * PycairoContext_FromContext(cairo_t *ctx, PyTypeObject *type, PyObject *base)¶

Parameters:

ctx (cairo_t) – a cairo_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoContext creation fails, or if the cairo_t has an error status. [transfer full]
type (PyTypeObject) – a pointer to the type to instantiate. It can be &PycairoContext_Type, or a PycairoContext_Type subtype. (cairo.Context or a cairo.Context subclass) [transfer none]
base (PyObject) – the base object used to create the context, or NULL. it is referenced to keep it alive while the cairo_t is being used [transfer none]

Returns:

New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoContext from a cairo_t

Cairo Font Face¶

PyObject PycairoFontFace¶

cairo_font_face_t* PycairoFontFace.font_face¶

The wrapped cairo_font_face_t

PyTypeObject *PycairoFontFace_Type¶

PyObject * PycairoFontFace_FromFontFace(cairo_font_face_t *font_face)¶

Parameters:	font_face (cairo_font_face_t) – a cairo_font_face_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoFontFace creation fails [transfer full]
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoFontFace from a cairo_font_face_t

PycairoFontFace PycairoToyFontFace¶

PyTypeObject *PycairoToyFontFace_Type¶

Cairo Font Options¶

PyObject PycairoFontOptions¶

cairo_font_options_t* PycairoFontOptions.font_options¶

PyTypeObject *PycairoFontOptions_Type¶

PyObject * PycairoFontOptions_FromFontOptions(cairo_font_options_t *font_options)¶

Parameters:	font_options (cairo_font_options_t) – a cairo_font_options_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoFontOptions creation fails [transfer full]
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoFontOptions from a cairo_font_options_t

Cairo Matrix¶

PyObject PycairoMatrix¶

cairo_matrix_t PycairoMatrix.matrix¶

PyTypeObject *PycairoMatrix_Type¶

PyObject * PycairoMatrix_FromMatrix(const cairo_matrix_t *matrix)¶

Parameters:	matrix (cairo_matrix_t) – a cairo_matrix_t to ‘wrap’ into a Python object. the cairo_matrix_t values are copied. [transfer none]
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoMatrix from a cairo_matrix_t

Cairo Path¶

PyObject PycairoPath¶

cairo_path_t* PycairoPath.path¶

PyTypeObject *PycairoPath_Type¶

PyObject * PycairoPath_FromPath(cairo_path_t *path)¶

Parameters:	path (cairo_path_t) – a cairo_path_t to ‘wrap’ into a Python object. path is unreferenced if the PycairoPath creation fails, or if path is in an error status. [transfer full]
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoPath from a cairo_path_t

Cairo Pattern¶

PyObject PycairoPattern¶

cairo_pattern_t* PycairoPattern.pattern¶

PyTypeObject *PycairoPattern_Type¶

PycairoPattern PycairoSolidPattern¶

PyTypeObject *PycairoSolidPattern_Type¶

PycairoPattern PycairoSurfacePattern¶

PyTypeObject *PycairoSurfacePattern_Type¶

PycairoPattern PycairoGradient¶

PyTypeObject *PycairoGradient_Type¶

PycairoGradient PycairoLinearGradient¶

PyTypeObject *PycairoLinearGradient_Type¶

PycairoGradient PycairoRadialGradient¶

PyTypeObject *PycairoRadialGradient_Type¶

PyObject * PycairoPattern_FromPattern(cairo_pattern_t *pattern, PyObject *base)¶

Parameters:	pattern (cairo_pattern_t) – a cairo_pattern_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoPattern creation fails, or if the pattern has an error status. [transfer full] base (PyObject) – the base object used to create the pattern, or NULL. It is referenced to keep it alive while the cairo_pattern_t is being used. [transfer none]
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoSolidPattern, PycairoSurfacePattern, PycairoLinearGradient, or PycairoRadialGradient from a cairo_pattern_t.

Cairo Region¶

PyObject PycairoRegion¶

cairo_region_t* PycairoRegion.region¶

PyTypeObject *PycairoRegion_Type¶

PyObject * PycairoRegion_FromRegion(cairo_region_t *region)¶

Parameters:	region (cairo_region_t) – a cairo_region_t to ‘wrap’ into a Python object. region is unreferenced if the PycairoRegion creation fails, or if region is in an error status.
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoRegion from a cairo_region_t

Cairo RectangleInt¶

PyObject PycairoRectangleInt¶

cairo_rectangle_int_t* PycairoRectangleInt.rectangle_int¶

PyTypeObject *PycairoRectangleInt_Type¶

PyObject * PycairoRectangleInt_FromRectangleInt(const cairo_rectangle_int_t *rectangle_int)¶

Parameters:	rectangle_int (cairo_rectangle_int_t) – a cairo_rectangle_int_t to ‘wrap’ into a Python object. rectangle_int is unreferenced if the PycairoRectangleInt creation fails. [transfer none]
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoRectangleInt from a cairo_rectangle_int_t

Scaled Font¶

PyObject PycairoScaledFont¶

cairo_scaled_font_t* PycairoScaledFont.scaled_font¶

PyTypeObject *PycairoScaledFont_Type¶

PyObject * PycairoScaledFont_FromScaledFont(cairo_scaled_font_t *scaled_font)¶

Parameters:	scaled_font (cairo_scaled_font_t) – a cairo_scaled_font_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoScaledFont creation fails [transfer full]
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoScaledFont from a cairo_scaled_font_t

Cairo Surface¶

PyObject PycairoSurface¶

cairo_surface_t* PycairoSurface.surface¶

PyTypeObject *PycairoSurface_Type¶

PycairoSurface PycairoImageSurface¶

PyTypeObject *PycairoImageSurface_Type¶

PycairoSurface PycairoPDFSurface¶

PyTypeObject *PycairoPDFSurface_Type¶

PycairoSurface PycairoPSSurface¶

PyTypeObject *PycairoPSSurface_Type¶

PycairoSurface PycairoRecordingSurface¶

PyTypeObject *PycairoRecordingSurface_Type¶

PycairoSurface PycairoSVGSurface¶

PyTypeObject *PycairoSVGSurface_Type¶

PycairoSurface PycairoWin32Surface¶

PyTypeObject *PycairoWin32Surface_Type¶

PycairoSurface PycairoXCBSurface¶

PyTypeObject *PycairoXCBSurface_Type¶

PycairoSurface PycairoXlibSurface¶

PyTypeObject *PycairoXlibSurface_Type¶

PyObject * PycairoSurface_FromSurface(cairo_surface_t *surface, PyObject *base)¶

Parameters:	surface (cairo_surface_t) – a cairo_surface_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoSurface creation fails, or if the cairo_surface_t has an error status. [transfer full] base (PyObject) – the base object used to create the surface, or NULL. It is referenced to keep it alive while the cairo_surface_t is being used. [transfer none]
Returns:	New reference or NULL on failure and sets an exception [transfer full]

Create a new PycairoImageSurface, PycairoPDFSurface, PycairoPSSurface, PycairoRecordingSurface, PycairoSVGSurface, PycairoWin32Surface, PycairoWin32PrintingSurface, PycairoXCBSurface, or PycairoXlibSurface from a cairo_surface_t.

Cairo Types¶

These are only listed here so they can be referenced in the documentation.

See https://www.cairographics.org/manual/ for details.

cairo_t¶
cairo_status_t¶
cairo_surface_t¶
cairo_scaled_font_t¶
cairo_rectangle_int_t¶
cairo_region_t¶
cairo_pattern_t¶
cairo_matrix_t¶
cairo_font_options_t¶
cairo_path_t¶
cairo_font_face_t¶