README

   1 Dia is a program for drawing structured diagrams.
   2
   3 Dia is a GNU program, and is Free Software.  See the COPYING file for
   4 the licence.
   5
   6 Documentation is a bit sparse at the moment.  Some info can be
   7 found in the doc/ directory.
   8
   9 --
  10
  11 I haven't had time to write anything here yet.
  12 Read INSTALL for some brief installation instructions.
  13
  14 Homepage for dia is at:
  15  http://www.gnome.org/projects/dia
  16
  17 Some comments about the source:
  18 -------------------------------
  19
  20  Everything on the screen 'inherits' from the structure Object
  21 in lib/object.h. (ps. this is a nice place to start reading the code.).
  22 Inherits in C means (as in gtk) that it begins with a copy of that structure.
  23 Some base classes exists in lib/, like element.h (for doing 'box-like'
  24 objects), connection.h (for doing 'line-like' objects), orth_conn.h (for doing
  25 connections with orthogonal lines, like the uml-stuff) and render_object.h
  26 (for doing picture-like objects). These base classes are then subclassed in
  27 the different object in the object-libraries like objects/standard object/UML
  28 and object/network.
  29
  30  The objects work by filling out two structures that the main program (app/*)
  31 uses to handle the objects. The ObjectType structure which consists of some
  32 info and a pointer to the type-operations (create+load+save). There's one
  33 ObjectType per object type currently loaded. Then the Object structure, there
  34 exists a copy of this for each object of the kind on screen (and in
  35 copy-buffers). This contains some info like: type, bounding_box, position,
  36 handles (the rectangles you move with the mouse) and connections. It also
  37 contains a pointer to the object-operations. These are called from the main
  38 program when if wants the object to do something. All ops take an Object as
  39 the first argument. This is usually casted to the subtype in the function
  40 headed (gives all those pita warnings) so that you directly can use the info
  41 stored in the subclasses. Most ops are quite self-describing, and the code can
  42 be copy-pasted from an object like the one you're doing. Rendering to
  43 screen/postscript is done through a 'Renderer' abstraction that can be found
  44 in lib/render.h.
  45
  46 XML based objects:
  47 ------------------
  48 You can (from version 0.80) create new objects using a SVG like XML languange.
  49 The file doc/custom-shapes has more information about this.
  50
  51 Note on handles and connection points:
  52 --------------------------------------
  53
  54 An object has handles to resize it. A handle can be moved either because
  55 the user dragged it with the mouse, or the handle is attached to another
  56 object, which moved itself. The handles are diplayed as little squares
  57 (red: normal, green: attached to an object, blue: can't be moved).
  58
  59 When the handle of an object is connected to another object, it's always
  60 on special points called connection points, displayed as crosses.
  61
  62 Implementation:
  63 - each object has an array of pointer to ConnectionPoint.
  64 - each object has an array of pointer to Handle.
  65 - each Handle has a pointer to 1 ConnectionPoint (NULL if the handle if
  66 the Handle is not connected).
  67 - each ConnectionPoint has a list of all objects connected to it.
  68
  69 The Object type does not manage the allocation/deallocation of handles and
  70 connection points. When saving a diagram the pointer from the handle to
  71 the connectionpoint is saved as the index of the connectionpoint. So make
  72 sure the order of the connectionpoints is the same when loading the saved
  73 object.
  74