]> Version 0.14.0 ArjanMolenaar This is the DiaCanvas2 reference manual. It contains information about how to use the DiaCanvas2. This documentation is written for people who want to start programming with DiaCanvas2. In the canvas model is discussed. In the usage and rationale behind the DiaSolver class is explained. The solver is used to keep connections between objects true. The third chapter tells you about some standard objects. Visualization is explained in . A view will allow you to display the (abstract) contents of a DiaCanvas in a window. This will also tell you something about the default behavior of the canvas(-views). The last chapter discusses some functions for determining distances and intersections of points, lines and rectangles. DiaCanvas is a GNOME widget tailored to applications that draw a diagram, in the wider sense of the word. DiaCanvas has a Visio like appearance and supports the GNOME anti-alias canvas. DiaCanvas2 uses the model/view/controller paradigm to make it possible to create multiple views of one object and to separate visualization data from the (more simple) data model. DiaCanvas is the base class for the canvas model. A canvas contains a set of DiaCanvasItems. The DiaCanvasView class is the visual counterpart of DiaCanvas. The DiaCanvasViewItem is the visual counterpart of the DiaCanvasItem, the object that contains information about an object on the canvas. A programmer should not need to worry about the views of the canvas. All the programmer needs to do is inherit from DiaCanvasItem to create a object that has more specialized functionality. The view will request the DiaShape objects that describe the appearance. A shape is the most simple representation of a drawing primitive. For a line is would be a list of points, the line width, end point type and the color. DiaCanvasItems are stateless. A few functions are provided that can request the visibility status (normal, selected, focus, grabbed) from the active view. As of version 0.13, DiaCanvasItems do no longer handle events themselves. All events are hanlded by tools. A tool acts as a controler in the canvas: it receives user events and translates them to an action. Tools handle the movement of handles, the movement of items and the rubberband selection. Objects can be transformed in a generic way. This can be done by using an transformation matrix. If you have programmed with the GnomeCanvas this probably sounds familiar. For example if an object needs to be rotated, the matrix is assigned values to make the transformation possible. The object itself, however does not need to know that it is transformed, it creates its shapes the same way it would have done when the object was not rotated. The interface DiaCanvasGroupable has a special meaning. Groupable objects have the ability to contain child objects visible to the view. The views use this interface to access those child objects. Objects exposed via the DiaCanvasGroupable interface can recieve events and can therefore be selected individually. The DiaCanvasGroup class realizes this interface. Items can be assembled by using multiple composite items. Another interface, DiaCanvasEditable, can be used to make text editable on the canvas. The default tools will check if an item supports this interface whenever the item is double-clicked. The DiaCanvasItem may then return a text shape that will then be edited. An object usually has a bunch of handles. A handle (DiaHandle) is an object used to manipulate the DiaCanvasItem. For a line the handles can be used to move the different points on the line (every point is represented by a handle). A rectangle might have a handle on every corner, this makes it easy to resize the rectangle. DiaHandle objects are always drawn on top of the objects. This way you can guess where an object is, even if it is hidden by another object. Like all diagrams an item can be connected to another. In DiaCanvas2 those relations are held true by means of a linear constraint solver. If a line connects to a rectangle object (e.g. a box), an equation is created that will position the line's handle on the side of the rectangle. If the rectangle is moved, the line also moves (or at least the line's handle). Please read the chapter about the constraint solver for more information.

&DiaCanvas; &DiaCanvasGroupable; &DiaCanvasEditable; &DiaCanvasItem; &DiaCanvasGroup; &DiaShape; &DiaHandle; &DiaUndoManager; &DiaExport; Creating a diagram is no fun if the different objects on the canvas can not create relations with each other. The easiest way (at first) seems to hard code the behavior that is desirable when objects need to have a relation with each other. This is a quite limited approach, since it is hard to tailor the objects behavior to the expectations of the user. It is also hard to verify if the code works correctly under all circumstances, since the code is scattered among a lot of different classes. When using a constraint solver instead we can solve a bunch of problems at once: We are free to create any relation between any object on the canvas. All constraints on the canvas can easily be verified at once. Stability: no strange behavior can be expected as long as the constraints are constructed properly. It is easy to assign new values to a bunch of objects and then solve all constraints at once. This is desirable in an interactive environment where speed is a prerequisite. Every variable is assigned a strength. When solving constraints the weakest variable in an equation will be adjusted to make the equation true. DiaCanvas2 features a small constraint solver based on GObject. The big advantage is that you can send signals between the different parts of the constraint solver, this will keep the code clean. The solver consists of three classes: DiaVariable A DiaVariable hold a variable value. If the value changes the changed_internal signal is emitted. This signal is emitted every time the variable is assigned a new value. The DiaVariable also has a changed signal. This signal is emitted if its value is changed by the constraint solver. You usually want to connect to this signal. DiaConstraint A Constraint consists of an linear expression. For this purpose a helper class "DiaExpression" is created. An expression is an array of variable * constant pairs. This will result in an expression like: a*x + b*y +c = 0. A constraint will react on DiaVariable's changed_internal signal by emitting need_resolve. DiaSolver The solver is the most interesting class of all: this is where the actual work is done. You can add constraints to the solver. The solver will connect to the constraints need_resolve signal. If a constraint emits the need_resolve signal the constraint will be marked. If the resolve function is called the solver tries to satisfy all constraints. This is done by looking for the weakest variable in the constraint. If weakest variable is already edited the constraint is not resolved again.

&DiaStrength; &DiaVariable; &DiaExpression; &DiaConstraint; &DiaSolver; &DiaCanvasLine; &DiaCanvasElement; &DiaCanvasBox; &DiaCanvasImage; &DiaCanvasText; Once you have created a DiaCanvas it is likely that you want to display it on the screen. This is done by creating a DiaCanvasView object. The DiaCanvasView is used to interact with the object. Once you create a DiaCanvasView, a DiaCanvasViewItem is created for every DiaCanvasItem in the DiaCanvas (notice the difference: with or without View). The DiaCanvasViewItem objects will render the information found while iterating the DiaShape objects. A view can be either LibArt based (with anti-aliasing) or X based. The X based implementation might work a little faster, but on a not-too-old computer you will hardly notice the difference. In order to increase usability, the render information used by the view items will be stored. Every view item will have it's own render data of a DiaShape. Once you have a nice DiaCanvasView on your screen it is likely that you want to interact with it. We can split the user interaction in four parts: Actions on the item itself. Actions on the handles of an item. Actions involving multiple items on the canvas. View related actions. Actions on the item are mainly button presses, motion events and button release events. The object should not worry about being selected or not, those kinds of state changes are taken care of by the view. The object should grab the focus if it wants to receive all user actions (this is usually the case when a mouse button is pressed). Actions on the handles are not handled by the item. A special object (DiaHandleLayer) takes care of the handles. There is one exception: when a handle is moved the handle owner (a DiaCanvasItem) is asked whether or not it is allowed to do a certain motion by calling the DiaCanvasItemClass::handle_motion() callback function. If a handle is pressed the owner object will get the focus. The DiaHandleLayer does not know about any special action that should take place when a certain key modifier is pressed. For example DiaCanvasElement like objects will rotate when a corner handle is moved and the CONTROL key is pressed and shear when a center handle is moved. This behavior is dictated by the DiaCanvasItem rather than the DiaHandleLayer. The only case where more than one object is involved is when multiple objects are selected and the objects are moved. It is the DiaCanvasItem that has the focus who initiates the move: by calling dia_canvas_item_move_interactive() all selected objects on the active view are moved. View related actions consist of selecting objects and deselecting objects. If the SHIFT button is held, no objects will be deselected. Pressing the CONTROL key while selecting objects will toggle the selection.

&DiaCanvasView; &DiaCanvasViewItem; &DiaTool; &DiaHandleLayer; &DiaShapeArt; &DiaShapeX; Function related to points and rectangles. &DiaGeometry; DiaCanvas supports Python bindings. This is nice. A typical Python program looks like this: #!/usr/bin/env python import pygtk pygtk.require('2.0') import gtk import diacanvas canvas = diacanvas.Canvas() box = diacanvas.CanvasBox() box.set(border_width=0.3, color=diacanvas.color(200, 100, 100, 128)) canvas.root.add(box) box.move(20, 20) window = gtk.Window() view = diacanvas.CanvasView(canvas=canvas) view.show() window.add(view) window.connect("destroy", gtk.mainquit) 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=255): 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)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. DiaCanvasItem.shape_iter (self) Get a Python iterator to the first shape to be rendered. 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 CanvasGroupable too. set_editable(class) Add the CanvasEditable interface to the class. You should inherit your class from CanvasEditable too. CanvasEditable A abstract base class for the DiaCanvasEditable interface. You should call set_editable() too if you want to use this interface. CanvasGroupable 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. CanvasGroupable.groupable_iter Return an iterator which can be used to traverse the groups children. 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_shape_iter(self): object Return an iterator object that points to the first shape to be rendered, e.g: iter([shape1, shape2]). You can also use generators for this purpose (using the yield statement). (Since 0.10.0) on_point (self, x, y): distance Return the distance from point (x, y) to the item. on_move (self, x, y, interactive): 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 CanvasGroupable. 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 True on success, False on failure. on_groupable_remove (self, item): boolean Idem, for removing items from the group. on_groupable_iter(self): iter Return an iterator object of the first item in the group. You can return something like iter([item1, item2]) or create a generator object (using the yield statement). (Since 0.10.0) 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. For text to be edited on a DiaCanvasView, a canvas item should support the CanvasEditable interface. Also call set_editable(class) to make the interface actually work. Once you have done that you have to define the following methods: on_editable_start_editing (self, shape) Start editing of the text represented by the shape, which must be a diacanvas.shape.Text. on_editable_editing_done (self, shape, new_text) Inform that the editing is finished. shape is a diacanvas.shape.Text and new_text is the text after it has been edited. on_editable_text_changed (self, shape, new_text) Notify the canvas item that the text has changed. shape is a diacanvas.shape.Text and new_text is the text as it is edited. Here is an example of a canvas item created in Python. The item is derived from DiaCanvasElement and has one line on top and one one on the bottom. It also has a child item which can be used to edit some text. &PythonDemoItem;