summaryrefslogtreecommitdiff
path: root/lib/dia.dox
blob: c14497fcc475f7e4e3575a3847da957a08e4d583 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
/*!
 * \mainpage Dia Developer Documentation

This documentation describes some of the internal structure of the
Dia application for software developers interested in extending it.

Dia is a highly extensible application. There are plug-in mechanisms to add
diagram objects by 
 - C plug-ins (\ref Objects)
 - and by XML files (\ref Shapes).

Import and export facilities of Dia can be extended by plug-ins by
implementing \ref Renderers "Renderers"
 - written in C/C++ (\ref Plugins) 
 - and Python (\ref PyDia).

Additionally there is the possibility to extend Dia with arbitrary
functionality by registering actions in the menu. Again by
 - writing plug-ins in C/C++ (e.g. \ref LayoutPlugin)
 - or with Python (e.g. \ref arrange.py)

 */

/*!
\defgroup Objects Objects and their Building Blocks
\brief An \ref _DiaObject "Object" describes the appearance and behavior of diagram parts

There are a bunch of services to help implementing Dia objects.

 - arrows: \ref ObjectArrows
 - connectionpoint and handle: \ref ObjectConnects
 - bounding box calculation: \ref ObjectBBox
 - autorouting: \ref Autorouting
 - text editing: to render in canvas text and allow it's editing
 - font: \ref ObjectFonts
 - object change: \ref _ObjectChange
 - StdProps: \ref StdProps
 - load/save:

 */
 
/*!
\defgroup StdProps Standard Property System
\ingroup ObjectParts
\brief Automatic User Interface creation and serialization of object properties

The Property System for Dia Object allows to:
 - describe type, range and user interface representation, see PropDescription.
 - build dynamic user interfaces for all object properties
 - transform data fields of DiaObject implementation into list of generic Property
   to allow editing including undo/redo support without writing object specific code

 */
 
/*!
\defgroup ObjectParts Building Blocks
\ingroup Objects Building blocks to help implementing _DiaObject and interfacing _DiaRenderer
\brief Typical \ref _DiaObject "Objects" are assembled from existing building blocks like _DiaImage
*/

/*!
\defgroup ObjectConnects Object Connections
\ingroup Objects
\brief Connections between objects are realized with \ref _Handle "Handle" and \ref _ConnectionPoint "Connection Point"

There are two specialized objects involved in building a connection. One is a Handle, the other one 
is a ConnectionPoint. In an existing connection between two DiaObject the Handle belongs to the 
first ("connected to") and the ConnectionPoint belongs to second ("connected by").

The "Standard - Line" DiaObject is special because it is one of only few objects which can be 
"connected to" (has Handles) and also "connected by" (has a ConnectionPoint). 
Note: there is an important difference between the active and the passive form.

It is important to understand the difference Dia's source is making between handle->connected_to 
and "connected by" (connectionpoint->connected). The former is a 0 or 1 relation, the latter is 0..n.
*/

/*!
\defgroup Shapes Custom Shape Definition
\ingroup Objects
\brief Custom objects can not only be defined by writing C code, but also with a SVG dialect

\verbinclude custom-shapes

*/

/*!
\defgroup DiagramStructure Diagrams keeping it all together
\brief A \ref _DiagramData "Diagram" consists of at least one \ref _Layer "Layer" containing zero or more \ref _DiaObject "Object"

 */

/*!
\defgroup DiagramXmlIo Operations on the XML DOM
\brief Low level access to the document object model
\ingroup DiagramStructure
\details
\verbinclude diagram.dtd
 */

/*!
\defgroup Renderers Rendering Objects
\brief The visual representation of \ref _DiaObject "objects" is done by \ref _DiaRenderer "renderers"

\ingroup Plugins

Dia Objects are drawing themselves to a renderer, be it for display, print or
file export to various formats.  The Dia library includes some base classes 
to help implementing rendering.

 - _DiaRenderer : implementing the interface to all renderers and some emulations
   of high level functions 
 - _DiaSvgRenderer : to create SVG format for SVG export and Shape creation
 - _DiaGdkRenderer : the _DiaGdkRenderer is the first display renderer
 - _DiaCairoRenderer : multi-format renderer based on http://cairographics.org
 - _DiaPathRenderer : allows to convert objects into their path representation
 - _DiaTransformRenderer : for affine transformation on the renderer API level
 - _DiaImportRenderer : helps to write file importer for formats which are "rendering",
   the result is a list of \ref StandardObjects

 */

/*!
\defgroup Plugins Import, Export and other extensions
\brief Extending Dia with optional dependencies 
 */

/*!
\defgroup ExportFilters Export Filters
\ingroup Plugins
\brief Export filters are usually implementing the \ref _DiaRenderer "renderer" interface

 */
 
/*!
\defgroup ImportFilters Import Filters
\ingroup Plugins
\brief Import filters translate an external representation to Dia \ref _DiaObject "objects"

 */
 
/*!
\defgroup PyDia Scripting Dia
\brief Extending Dia with Python (http://www.python.org)

\ingroup Plugins

The documentation of PyDia is self-contained with PyDia. You can use some
example PyDia plug-ins to generate it from your local Dia installation
(if build with Python support)

\image html PyDiaObjects.svg "PyDia Object Model" width=10cm

 */