DiaCanvas2 Reference Manual: Version 0.9.0 | |||
---|---|---|---|
<<< Previous Page | Home |
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:
DiaPoint | Tuple (x, y) |
DiaRectangle | Tuple (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 function | Python method |
---|---|
dia_canvas_item_connect (item, handle): boolean | DiaCanvasItem.connect_handle (self, handle): boolean |
dia_canvas_item_disconnect (item, handle): boolean | DiaCanvasItem.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): int | color (r, g, b, a): int |
dia_shape_text_cursor_from_pos (shape, pos, *cursor): in | shape.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): dist | Canvas.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): distance | geometry.distance_line_point (line_start, line_end, point, line_width, style): (distance, point_on_line) |
dia_intersection_line_line (s1, e1, s2, e2, *intersect): boolean | geometry.intersection_line_line (s1, e1, s2, e2): intersection point or None |
dia_intersection_line_rectangle (line_start, line_end, rect, intersect[2]): n_intersect | geometry.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. |
CanvasAbstractGroup | A 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. |
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:
on_update (self, affine): None | Update the items state. You should try to do most of the update actions in this function, since it is called when the system is idle. |
on_get_shape_iter(self): object | Get an iterator for shapes defined in your canvas item. Return None if no shapes are defined. Use together with on_shape_next() and on_shape_value(). |
on_shape_next (self, iter): object | Return the next iterator. Return None if there is no next shape. |
on_shape_value (self, iter): shape | Return the shape that corresponds to the iterator |
on_point (self, x, y): distance | Return the distance from point (x, y) to the item. |
on_move (self, x, y): None | Do something if the item moves. You might want to do a CanvasItem.request_update() on any sub-items. |
on_handle_motion (self, handle, wx, wy, mask): None | Do something if a handle is moved. |
on_event (self, event): boolean | Handle an event send to this item. It should return 1 if the event is handles and 0 otherwise. |
on_glue (self, handle, wx, wy): (dist, (x, y)) | This method is called if a connectable handle of another canvas item is moved. It should return the distance to the item (dist) and the point where the handle may connect (x,y). (wx, wy) is the position where the handle is moved to in world coordinates. |
on_connect_handle (self, handle): boolean | A handle wants to connect to the item. Return 1 if the handle is connected, 0 otherwise. |
on_disconnect_handle (self, handle): boolean | Like on_connect_handle(), but now the handle wants to disconnect. |
For canvas items to support grouping you should inherit your canvas item from CanvasAbstractGroup. You should also set some groupability internals by calling set_groupable() on your canvas item class. Once you have done that you have to define the following methods:
on_groupable_add (self, item): boolean | Add an item to the canvas item. Should return 1 on success, 0 on failure. |
on_groupable_remove (self, item): boolean | Idem, for removing items from the group. |
on_groupable_get_iter(self): object | Return an iterator. Note that iterators are not referenced by the system, so you have to keep an explicit refererence to the returned object. |
on_groupable_next (self, iter): object | Return an iterator who points to the next item. |
on_groupable_value (self, iter): CanvasItem | Return the value that corresponds to the iterator. |
on_groupable_length (self): int | Return the amount of items held by the group. |
on_groupable_pos (self, item): int | Return the position of item in the group list, -1 on failure. |