Python bindings

DiaCanvas supports Python bindings. This is nice. A typical Python program looks like this:

#!/usr/bin/env python

import gtk
import diacanvas as dia

canvas = dia.Canvas()
box = canvas.root.create_item (dia.CanvasBox, line_width=0.3, \
                               color=dia.color(200, 100, 100, 128))
box.move (200, 200)

window = gtk.Window()
view = dia.CanvasView (canvas=canvas)
view.show()
window.add (view)
window.show()

gtk.main()
      

The Python DiaCanvas2 module is split up in one main module (diacanvas) and two submodules (shape and geometry). The diacanvas module contains the main canvas stuff, like Canvas, CanvasItem and CanvasView. The shape module is interesting if you want to create your own canvas items in Python, so is the geometry module.

In Python we do not have special types for points, rectangles and transformation matrixes, instead we use a simple tuple:

DiaPointTuple (x, y)
DiaRectangleTuple (left, top, right, bottom)
gdouble[6] (affine matrix)Tuple (a0, a1, a2, a3, a4, a5)

There are a few methods that have been renamed or otherwise modified to suite Python:

C functionPython method
dia_canvas_item_connect (item, handle): booleanDiaCanvasItem.connect_handle (self, handle): boolean
dia_canvas_item_disconnect (item, handle): booleanDiaCanvasItem.disconnect_handle (self, handle): boolean
DIA_SET_FLAGS (item, flags)DiaCanvasItem.set_flags (self, flags)
DIA_UNSET_FLAGS (item, flags)DiaCanvasItem.unset_flags (self, flags)
DIA_COLOR_A (r, g, b, a): intcolor (r, g, b, a): int
dia_shape_text_cursor_from_pos (shape, pos, *cursor): inshape.Text.cursor_from_pos (self, pos): (in, cursor)
dia_handle_get_pos_i (handle, *x, *y)Handle.get_pos_i (self): (x, y)
dia_handle_get_pos_w (handle, *x, *y)Handle.get_pos_w (self): (x, y)
dia_canvas_snap_to_grid (canvas, *x, *y)Canvas.snap_to_grid (self, x, y): (x, y)
dia_canvas_glue_handle (canvas, handle, dest_x, dest_y, *glue_x, *glue_y, *item): distCanvas.glue_handle (self, handle, dest_x, dest_y): (dist, (glue_x, glue_y), item)
dia_canvas_item_affine_w2i (item, affine)DiaCanvasItem.affine_w2i(self): affine
dia_canvas_item_affine_i2w (item, affine)DiaCanvasItem.affine_i2w(self): affine
dia_canvas_item_affine_point_w2i (item, *x, *y)DiaCanvasItem.affine_point_w2i (self, x, y): (x, y)
dia_canvas_item_affine_point_i2w (item, *x, *y)DiaCanvasItem.affine_point_i2w (self, x, y): (x, y)
dia_rectangle_add_point (rect, point)geometry.rectangle_add_point (rect, point): new_rect
dia_distance_line_point (line_start, line_end, point, line_width, style, *point_on_line): distancegeometry.distance_line_point (line_start, line_end, point, line_width, style): (distance, point_on_line)
dia_intersection_line_line (s1, e1, s2, e2, *intersect): booleangeometry.intersection_line_line (s1, e1, s2, e2): intersection point or None
dia_intersection_line_rectangle (line_start, line_end, rect, intersect[2]): n_intersectgeometry.intersection_line_rectangle (start, end, rect): (point1, point2)[a]
Notes:
a. If no intersections, None is set in place of point1 and/or point2.

Some new methods and functions (and one new class) is defined:

DiaCanvasItem.set (self, name=value, ...)Set multiple properties at once.
DiaCanvasItem.set_bounds (self, bounds)Set the bounds of the canvas item.
set_callbacks(class)Initialize the GObject class to forward calls to the python object.
set_groupable(class)Add the CanvasGroupable interface to the class. You should inherit your class from CanvasAbstractGroup also.
CanvasAbstractGroupA wrapper class for the CanvasGroupable interface. This way you can inherit from the interface too. You should call set_groupable() too if you want to use groupability in your canvas item.


Creating canvas items in Python

It is possible to create fully functional canvas items in Python. You have to define the callback methods in your python class and call set_callbacks() the first time you inherit from CanvasItem (or a predefined canvas item from the diacanvas module). Note that you have to call the parent's method from within your canvas item just like you do with normal python classes. All callback methods start with on_ followed by their name. See DiaCanvasItem for details.

The following callbacks can be defined: