[dia] [dox] more documentation and improved grouping
- From: Hans Breuer <hans src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [dia] [dox] more documentation and improved grouping
- Date: Wed, 3 Oct 2012 20:01:40 +0000 (UTC)
commit 907980be99b781bf9a5f25da1490deb369814a1e
Author: Hans Breuer <hans breuer org>
Date: Sat Sep 22 16:20:29 2012 +0200
[dox] more documentation and improved grouping
- make collaboration and inheritance graphs useful
(remove 'ops' - object vtables - from documentation to avoid
collaboration graph information overflow)
- dox for Autorouting, DiagramData, Layer, XmlIo, ...
- create enum PropFlags for better documentation
lib/Doxyfile | 20 ++++--
lib/arrows.h | 2 +-
lib/autoroute.c | 108 ++++++++++++++++++++------
lib/boundingbox.h | 42 ++++++++--
lib/color.h | 9 ++-
lib/connpoint_line.h | 1 -
lib/create.h | 53 ++++++++++---
lib/dia.dox | 115 +++++++++++++---------------
lib/dia_xml.c | 210 ++++++++++++++++++++++++++++++++++++--------------
lib/dia_xml.h | 5 +-
lib/diagramdata.c | 137 ++++++++++++++++++++++++++-------
lib/diagramdata.h | 18 ++---
lib/font.c | 2 +-
lib/font.h | 16 ++--
lib/layer.c | 104 +++++++++++++++++--------
lib/objchange.h | 4 +-
lib/object.h | 21 +++---
lib/properties.h | 99 ++++++++++++++++--------
18 files changed, 669 insertions(+), 297 deletions(-)
---
diff --git a/lib/Doxyfile b/lib/Doxyfile
index 32ee866..93dbec4 100644
--- a/lib/Doxyfile
+++ b/lib/Doxyfile
@@ -5,10 +5,12 @@ PROJECT_LOGO = ../data/icons/scalable/apps/dia.svg
TAB_SIZE = 8
OPTIMIZE_OUTPUT_FOR_C = YES
# w/o this we could use \extends DiaObject instead of \extends _DiaObject
-TYPEDEF_HIDES_STRUCT = YES
+# also the names in the diagram would be nicer, but the collaboration graph
+# wont work anymore
+TYPEDEF_HIDES_STRUCT = NO
WARN_IF_UNDOCUMENTED = NO
WARN_LOGFILE = doxygen.log
-INPUT = ../lib ../objects/standard \
+INPUT = ../lib ../objects/standard ../objects/custom \
../plug-ins/python ../plug-ins/svg ../plug-ins/shape \
../plug-ins/layout
#STRIP_FROM_PATH = ../
@@ -21,15 +23,21 @@ GENERATE_LATEX = NO
HAVE_DOT = YES
#UML_LOOK = YES
-EXAMPLE_PATH = ../doc/custom-shapes
-IMAGE_PATH = ../samples/Self/PyDiaObjects.svg
+EXAMPLE_PATH = ../doc/custom-shapes ../doc/diagram.dtd ..
+IMAGE_PATH = ../samples/Self
CLASS_DIAGRAMS = YES
-# Fixme: would like to have this but it only shows inheritance information in Dia
-COLLABORATION_GRAPH = NO
+# to have this also needs also undoc relations to be turned on for non-class
+COLLABORATION_GRAPH = YES
+HIDE_UNDOC_RELATIONS = YES
+# class graph is just redundant than
+CLASS_GRAPH = YES
+MAX_DOT_GRAPH_DEPTH = 3
# Needed to e.g. get documentation for standard/arc.c
EXTRACT_LOCAL_CLASSES = YES
+# A lot of the documentation would be missing otherwise
+EXTRACT_STATIC = YES
HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES
HIDE_UNDOC_RELATIONS = NO
diff --git a/lib/arrows.h b/lib/arrows.h
index e54be4b..7429f00 100644
--- a/lib/arrows.h
+++ b/lib/arrows.h
@@ -28,7 +28,7 @@
/* NOTE: Add new arrow types at the end, or the enums
will change order leading to file incompatibilities. */
/*!
- * \defgroup ObjectArrows All objects derived from _Connection can end in Arrow
+ * \defgroup ObjectArrows Arrows for Connection
* \ingroup ObjectParts
*/
diff --git a/lib/autoroute.c b/lib/autoroute.c
index 3048655..b2e5c58 100644
--- a/lib/autoroute.c
+++ b/lib/autoroute.c
@@ -19,6 +19,13 @@
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
+/*!
+ * \file autoroute.c - simple autorouting for orthogonal lines
+ */
+/*!
+ * \defgroup Autorouting Built-in Autorouting
+ * \ingroup ObjectServices
+ */
#include "config.h"
#include "object.h"
@@ -53,7 +60,10 @@ static Point *autolayout_unnormalize_points(guint dir,
Point *points,
guint num_points);
-/** Calculate a 'pleasing' route between two connection points.
+/*!
+ * \brief Apply a good route (or none) to the given _OrthConn
+ *
+ * Calculate a 'pleasing' route between two connection points.
* If a good route is found, updates the given OrthConn with the values
* and returns TRUE.
* Otherwise, the OrthConn is untouched, and the function returns FALSE.
@@ -63,7 +73,11 @@ static Point *autolayout_unnormalize_points(guint dir,
* or null if it is not connected there at the moment.
* @param endconn The connectionpoint at the end (target) of the orthconn,
* or null if it is not connected there at the moment.
- * @returns TRUE if the orthconn could be laid out reasonably, FALSE otherwise.
+ * @return TRUE if the orthconn could be laid out reasonably, FALSE otherwise.
+ *
+ * \ingroup Autorouting
+ *
+ * \callgraph
*/
gboolean
autoroute_layout_orthconn(OrthConn *conn,
@@ -164,10 +178,13 @@ autoroute_layout_orthconn(OrthConn *conn,
}
}
-/** Returns the basic badness of a length. The best length is MIN_DIST,
+/*!
+ * Returns the basic badness of a length. The best length is MIN_DIST,
* anything shorter quickly becomes messy, longer segments are linearly worse.
* @param len The length of an orthconn segment.
- * @returns How bad this segment would be to have in the autorouting.
+ * @return How bad this segment would be to have in the autorouting.
+ *
+ * \ingroup Autorouting
*/
static real
length_badness(real len)
@@ -180,12 +197,17 @@ length_badness(real len)
}
}
-/** Returns the accumulated badness of a layout. At the moment, this is
+/*!
+ * \brief Calculate badness of a point array
+ *
+ * Returns the accumulated badness of a layout. At the moment, this is
* calculated as the sum of the badnesses of the segments plus a badness for
* each bend in the line.
* @param ps An array of points.
* @param num_points How many points in the array.
- * @returns How bad the points would look as an orthconn layout.
+ * @return How bad the points would look as an orthconn layout.
+ *
+ * \ingroup Autorouting
*/
static real
calculate_badness(Point *ps, guint num_points)
@@ -202,12 +224,17 @@ calculate_badness(Point *ps, guint num_points)
return badness;
}
-/** Adjust one end of an orthconn for gaps, if autogap is on for the connpoint.
+/*!
+ * \brief Gap adjustement for points and a connection point
+ *
+ * Adjust one end of an orthconn for gaps, if autogap is on for the connpoint.
* @param pos Point of the end of the line.
* @param dir Which of the four cardinal directions the line goes from pos.
* @param cp The connectionpoint the line is connected to.
- * @returns Where the line should end to be on the correct edge of the
+ * @return Where the line should end to be on the correct edge of the
* object, if cp has autogap on.
+ *
+ * \brief Calculate badness depending on length
*/
static Point
autolayout_adjust_for_gap(Point *pos, int dir, ConnectionPoint *cp)
@@ -243,13 +270,15 @@ autolayout_adjust_for_gap(Point *pos, int dir, ConnectionPoint *cp)
return calculate_object_edge(pos, &dir_other, object);
}
-/**
- * Adjust the original position to move away from a potential arrow
+/*!
+ * \brief Adjust the original position to move away from a potential arrow
*
* We could do some similar by making MIN_DIST depend on the arrow size,
- * but this one is much more easy, not touchun the autolayout algorithm at
+ * but this one is much more easy, not touchun the autolayout algorithm at
* all. Needs to be called twice - second time with negative adjust - to
* move the point back to where it was.
+ *
+ * \brief Calculate badness depending on length
*/
static void
autolayout_adjust_for_arrow(Point *pos, int dir, real adjust)
@@ -270,14 +299,19 @@ autolayout_adjust_for_arrow(Point *pos, int dir, real adjust)
}
}
-/** Lay out autorouting where start and end lines are parallel pointing the
+/*!
+ * \brief Parallel layout
+ *
+ * Lay out autorouting where start and end lines are parallel pointing the
* same direction. This can either a simple up-right-down layout, or if the
* to point is too close to origo, it will go up-right-down-left-down.
* @param to Where to lay out to, coming from origo.
* @param num_points Return value of how many points in the points array.
* @param points The points in the layout. Free the array after use. The
* passed in is ignored and overwritten, so should be NULL.
- * @returns The badness of this layout.
+ * @return The badness of this layout.
+ *
+ * \brief Calculate badness depending on length
*/
static real
autoroute_layout_parallel(Point *to, guint *num_points, Point **points)
@@ -336,7 +370,10 @@ autoroute_layout_parallel(Point *to, guint *num_points, Point **points)
return calculate_badness(ps, *num_points);
}
-/** Do layout for the case where the directions are orthogonal to each other.
+/*!
+ * \brief Orthogonal layout
+ *
+ * Do layout for the case where the directions are orthogonal to each other.
* If both x and y of to are far enough from origo, this will be a simple
* bend, otherwise it will be a question-mark style line.
* @param to Where to lay out to, coming from origo.
@@ -344,7 +381,9 @@ autoroute_layout_parallel(Point *to, guint *num_points, Point **points)
* @param num_points Return value of how many points in the points array.
* @param points The points in the layout. Free the array after use. The
* passed in is ignored and overwritten, so should be NULL.
- * @returns The badness of this layout.
+ * @return The badness of this layout.
+ *
+ * \ingroup Autorouting
*/
static real
autoroute_layout_orthogonal(Point *to, int enddir,
@@ -408,14 +447,19 @@ autoroute_layout_orthogonal(Point *to, int enddir,
return calculate_badness(ps, *num_points);
}
-/** Do layout for the case where the end directions are opposite.
+/*!
+ * \brief Opposite layout
+ *
+ * Do layout for the case where the end directions are opposite.
* This can be either a straight line, a zig-zag, a rotated s-shape or
* a spiral.
* @param to Where to lay out to, coming from origo.
* @param num_points Return value of how many points in the points array.
* @param points The points in the layout. Free the array after use. The
* passed in is ignored and overwritten, so should be NULL.
- * @returns The badness of this layout.
+ * @return The badness of this layout.
+ *
+ * \ingroup Autorouting
*/
static real
autoroute_layout_opposite(Point *to, guint *num_points, Point **points)
@@ -477,8 +521,10 @@ autoroute_layout_opposite(Point *to, guint *num_points, Point **points)
return calculate_badness(ps, *num_points);
}
-/** Rotate a point clockwise.
+/*!
+ * \brief Rotate a point clockwise.
* @param p The point to rotate.
+ * \ingroup Autorouting
*/
static void
point_rotate_cw(Point *p)
@@ -488,8 +534,10 @@ point_rotate_cw(Point *p)
p->y = tmp;
}
-/** Rotate a point counterclockwise.
+/*!
+ * \brief Rotate a point counterclockwise.
* @param p The point to rotate.
+ * \ingroup Autorouting
*/
static void
point_rotate_ccw(Point *p)
@@ -499,8 +547,10 @@ point_rotate_ccw(Point *p)
p->y = -tmp;
}
-/** Rotate a point 180 degrees.
+/*!
+ * \brief Rotate a point 180 degrees.
* @param p The point to rotate.
+ * \ingroup Autorouting
*/
static void
point_rotate_180(Point *p)
@@ -509,14 +559,19 @@ point_rotate_180(Point *p)
p->y = -p->y;
}
-/** Normalizes the directions and points to make startdir be north and
+/*!
+ * \brief Autolayout normalization
+ *
+ * Normalizes the directions and points to make startdir be north and
* the starting point be 0,0.
* @param startdir The original startdir.
* @param enddir The original enddir.
* @param start The original start point.
* @param end The original end point.
* @param newend Return address for the normalized end point.
- * @returns The normalized end direction.
+ * @return The normalized end direction.
+ *
+ * \ingroup Autorouting
*/
static guint
autolayout_normalize_points(guint startdir, guint enddir,
@@ -543,7 +598,10 @@ autolayout_normalize_points(guint startdir, guint enddir,
return enddir;
}
-/** Reverses the normalizing process of autolayout_normalize_points by
+/*!
+ * \brief Reverse normalization
+ *
+ * Reverses the normalizing process of autolayout_normalize_points by
* moving and rotating the points to start at `start' with the start direction
* `startdir', instead of from origo going north.
* Returns the new array of points, freeing the old one if necessary.
@@ -552,7 +610,9 @@ autolayout_normalize_points(guint startdir, guint enddir,
* @param points A set of points laid out from origo northbound. This array
* will be freed by calling this function.
* @param num_points The number of points in the `points' array.
- * @returns A newly allocated array of points starting at `start'.
+ * @return A newly allocated array of points starting at `start'.
+ *
+ * \ingroup Autorouting
*/
static Point *
autolayout_unnormalize_points(guint startdir,
diff --git a/lib/boundingbox.h b/lib/boundingbox.h
index eff37a0..6127fe1 100644
--- a/lib/boundingbox.h
+++ b/lib/boundingbox.h
@@ -18,9 +18,11 @@
*/
/*!
- * \file boundingbox.h Boundingbox calculation (helpers)
- * \defgroup bbox Bounding box calculation
- * \ingroup Objects
+ * \file boundingbox.h Boundingbox calculation (helpers)
+ */
+/*!
+ * \defgroup ObjectBBox Bounding box calculation
+ * \ingroup ObjectServices
*/
#ifndef BOUNDINGBOX_H
@@ -31,7 +33,7 @@
/*!
* \brief Polygon/Polyline bounding box extras
- * \ingroup bbox
+ * \ingroup ObjectBBox
*/
struct _PolyBBExtras {
real start_long, start_trans;
@@ -41,7 +43,7 @@ struct _PolyBBExtras {
/*!
* \brief Line bounding box extras
- * \ingroup bbox
+ * \ingroup ObjectBBox
*/
struct _LineBBExtras {
real start_long, start_trans;
@@ -50,7 +52,7 @@ struct _LineBBExtras {
/*!
* \brief Element bounding box extras
- * \ingroup bbox
+ * \ingroup ObjectBBox
*/
struct _ElementBBExtras {
real border_trans;
@@ -61,23 +63,45 @@ void bicubicbezier2D_bbox(const Point *p0,const Point *p1,
const PolyBBExtras *extra,
Rectangle *rect);
+/*!
+ * \brief Bounding box calculation for a straight line
+ * The calcualtion includes line width and arrwos with the right extra
+ * \ingroup ObjectBBox
+ */
void line_bbox(const Point *p1, const Point *p2,
const LineBBExtras *extra,
Rectangle *rect);
+/*!
+ * \brief Bounding box calculation for a rectangle
+ * The calcualtion includes line width with the right extra
+ * \ingroup ObjectBBox
+ */
void rectangle_bbox(const Rectangle *rin,
const ElementBBExtras *extra,
Rectangle *rout);
-void circle_bbox(const Point *centre, real radius,
- Rectangle *rect);
-
+/*!
+ * \brief Bounding box calculation for an ellipse
+ * The calcualtion includes line width with the right extra
+ * \ingroup ObjectBBox
+ */
void ellipse_bbox(const Point *centre, real width, real height,
const ElementBBExtras *extra,
Rectangle *rect);
+/*!
+ * \brief Bounding box calculation for a polyline
+ * The calcualtion includes line width and arrwos with the right extra
+ * \ingroup ObjectBBox
+ */
void polyline_bbox(const Point *pts, int numpoints,
const PolyBBExtras *extra, gboolean closed,
Rectangle *rect);
+/*!
+ * \brief Bounding box calculation for a bezier
+ * The calcualtion includes line width and arrwos with the right extra
+ * \ingroup ObjectBBox
+ */
void polybezier_bbox(const BezPoint *pts, int numpoints,
const PolyBBExtras *extra, gboolean closed,
Rectangle *rect);
diff --git a/lib/color.h b/lib/color.h
index d76fcc7..5e92f9b 100644
--- a/lib/color.h
+++ b/lib/color.h
@@ -18,9 +18,11 @@
/*!
* \file color.h Diagram and object tinting
+ */
+/*!
+ * \defgroup ObjectColors Colors for DiaObject
* \ingroup ObjectParts
*/
-
#ifndef COLOR_H
#define COLOR_H
@@ -28,7 +30,10 @@
#include <gdk/gdk.h>
#include "diavar.h"
-/*! \brief Dia's internal color representation */
+/*!
+ * \brief Dia's internal color representation
+ * \ingroup ObjectColors
+ */
struct _Color {
float red; /*!< 0..1 */
float green; /*!< 0..1 */
diff --git a/lib/connpoint_line.h b/lib/connpoint_line.h
index 977fe4e..129bb03 100644
--- a/lib/connpoint_line.h
+++ b/lib/connpoint_line.h
@@ -23,7 +23,6 @@
/*!
\file connpoint_line.h - services for extra connection points
- \ingroup ObjectParts
*/
#ifndef __CONNPOINT_LINE_H
diff --git a/lib/create.h b/lib/create.h
index 10ea5fb..3d59aa5 100644
--- a/lib/create.h
+++ b/lib/create.h
@@ -31,25 +31,33 @@
#include "diatypes.h"
-/** \brief Can be used as extra parameter at create. Usually discouraged, you can set via StdProp API */
+/*!
+ * \brief Can be used as extra parameter at create. Usually discouraged, you can set via StdProp API
+ * \ingroup ObjectCreate
+ */
struct _MultipointCreateData {
int num_points; /**< count */
Point *points; /**< data */
};
-/** \brief Can be used as extra parameter at create. Usually discouraged, you can set via StdProp API */
+/*!
+ * \brief Can be used as extra parameter at create. Usually discouraged, you can set via StdProp API
+ * \ingroup ObjectCreate
+ */
struct _BezierCreateData {
int num_points; /**< count */
BezPoint *points; /**< data */
};
-/*! Create a text object for the diagram.
+/*!
+ * \brief Create a text object for the diagram.
* @param xpos X position (in cm from the origo) of the object.
* @param ypos Y position (in cm from the origo) of the object.
* \ingroup ObjectCreate
*/
DiaObject *create_standard_text(real xpos, real ypos);
-/*! Create an ellipse object for the diagram
+/*!
+ * \brief Create an ellipse object for the diagram
* @param xpos top-left corner
* @param ypos top-lef corner
* @param width the horizontal diameter
@@ -57,20 +65,41 @@ DiaObject *create_standard_text(real xpos, real ypos);
* \ingroup ObjectCreate
*/
DiaObject *create_standard_ellipse(real xpos, real ypos, real width, real height);
-/*! Create a rectangular box */
+/*!
+ * \brief Create a rectangular box
+ * \ingroup ObjectCreate
+ */
DiaObject *create_standard_box(real xpos, real ypos, real width, real height);
-/*! Create a _Polyline with arrows */
+/*!
+ * \brief Create a _Polyline with arrows
+ * \ingroup ObjectCreate
+ */
DiaObject *create_standard_polyline(int num_points, Point *points,
Arrow *end_arrow, Arrow *start_arrow);
-/*! Create an _OrthConn with arrows */
+/*!
+ * \brief Create a \ref _Zigzagline with arrows
+ * \ingroup ObjectCreate
+ */
DiaObject *create_standard_zigzagline(int num_points, const Point *points,
const Arrow *end_arrow, const Arrow *start_arrow);
+/*!
+ * \brief Create a \ref _Polygon
+ * \ingroup ObjectCreate
+ */
DiaObject *create_standard_polygon(int num_points, Point *points);
-/*! Create a _Bezierline with arrows */
+/*!
+ * \brief Create a \ref _Bezierline with arrows
+ * \ingroup ObjectCreate
+ */
DiaObject *create_standard_bezierline(int num_points, BezPoint *points,
Arrow *end_arrow, Arrow *start_arrow);
+/*!
+ * \brief Create a \ref _Beziergon
+ * \ingroup ObjectCreate
+ */
DiaObject *create_standard_beziergon(int num_points, BezPoint *points);
-/*! Create an _Arc with arrows
+/*!
+ * \brief Create an \ref _Arc with arrows
* @param x1 arc start position
* @param y1 arc start position
* @param x2 arc end position
@@ -83,11 +112,13 @@ DiaObject *create_standard_beziergon(int num_points, BezPoint *points);
DiaObject *create_standard_arc(real x1, real y1, real x2, real y2,
real curve_distance,
Arrow *end_arrow, Arrow *start_arrow);
-/*! Create an image object from file with the given size and position
+/*!
+ * \brief Create an \ref _Image object from file with the given size and position
* \ingroup ObjectCreate
*/
DiaObject *create_standard_image(real xpos, real ypos, real width, real height, char *file);
-/*! Create a _Group of objects given by list.
+/*!
+ * \brief Create a _Group of objects given by list.
* The objects in list must not be added to the diagra at the same time.
* \ingroup ObjectCreate
*/
diff --git a/lib/dia.dox b/lib/dia.dox
index dd8c86f..420220f 100644
--- a/lib/dia.dox
+++ b/lib/dia.dox
@@ -21,46 +21,16 @@ functionality by registering actions in the menu. Again by
*/
/*!
-\defgroup Plugins Import, Export and other extensions
-
- */
-
-/*!
-\defgroup ExportFilters Export Filters for various Formats
-\ingroup Plugins
-
-
- */
-
-/*!
-\defgroup ImportFilters Import Filters for various Formats
-\ingroup Plugins
-
-
- */
-
-/*!
-\defgroup PyDia Extending Dia with Python
-\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 installtion
-(if build with Python support)
-
-\image html PyDiaObjects.svg "PyDia Object Model" width=10cm
-
- */
-
-/*!
\defgroup Objects Objects and their Building Blocks
There are a bunch of services to help implementing Dia objects.
- arrows: \ref ObjectArrows
- connectionpoint and handle: \ref ObjectConnects
- - bounding box calculation: \ref bbox
+ - bounding box calculation: \ref ObjectBBox
+ - autorouting: \ref Autorouting
- text editing: to render in canvas text and allow it's editing
- - font: \ref FontServices
+ - font: \ref ObjectFonts
- object change: \ref _ObjectChange
- StdProps: \ref StdProps
- load/save:
@@ -69,7 +39,7 @@ There are a bunch of services to help implementing Dia objects.
/*!
\defgroup StdProps Property System for Dia Object
-\ingroup Objects
+\ingroup ObjectServices
The Propery System for Dia Object allows to
- describe type, range and user interface representation, see PropDescription.
@@ -86,34 +56,6 @@ The Propery System for Dia Object allows to
*/
/*!
-\defgroup Objects Objects and their Building Blocks
-
-There are a bunch of services to help implementing Dia objects.
-
- - arrows: \ref ObjectArrows
- - connectionpoint and handle: \ref ObjectConnects
- - bounding box calculation: \ref bbox
- - text editing: to render in canvas text and allow it's editing
- - font: \ref FontServices
- - object change: \ref _ObjectChange
- - StdProps: \ref StdProps
- - load/save:
-
- */
-
-/*!
-\defgroup StdProps Property System for Dia Object
-\ingroup Objects
-
-The Propery 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
@@ -168,6 +110,23 @@ and "connected by" (connectionpoint->connected). The former is a 0 or 1 relation
*/
/*!
+\defgroup ObjectServices Object Implementation
+\ingroup Objects
+ */
+
+/*!
+\defgroup DiagramStructure Diagrams keeping it all together
+\brief A \ref _DiagramData "Diagram" consists of at least one \ref _Layer containing zero or more _DiaObject
+
+ */
+
+/*!
+\defgroup DiagramXmlIo Operations on the XML DOM
+\ingroup DiagramStructure
+\verbinclude diagram.dtd
+ */
+
+/*!
\defgroup Renderers Rendering Objects
\ingroup Plugins
@@ -181,3 +140,35 @@ to help implementing rendering.
- _DiaGdkRenderer : the _DiaGdkRenderer is the first display renderer
*/
+
+/*!
+\defgroup Plugins Import, Export and other extensions
+
+ */
+
+/*!
+\defgroup ExportFilters Export Filters for various Formats
+\ingroup Plugins
+
+
+ */
+
+/*!
+\defgroup ImportFilters Import Filters for various Formats
+\ingroup Plugins
+
+
+ */
+
+/*!
+\defgroup PyDia Extending Dia with Python
+\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 installtion
+(if build with Python support)
+
+\image html PyDiaObjects.svg "PyDia Object Model" width=10cm
+
+ */
+
diff --git a/lib/dia_xml.c b/lib/dia_xml.c
index ac200a7..b04cd20 100644
--- a/lib/dia_xml.c
+++ b/lib/dia_xml.c
@@ -82,7 +82,19 @@ static inline int isinf_d (double x) { return isnan (x - x); }
static inline int isinf_ld (long double x) { return isnan (x - x); }
#endif
-/** If all files produced by dia were good XML files, we wouldn't have to do
+/*!
+ * \defgroup DiagramXmlOut Converting data to XML
+ * \ingroup DiagramXmlIo
+ */
+/*!
+ * \defgroup DiagramXmlIn Retrieving data from XML
+ * \ingroup DiagramXmlIo
+ */
+
+/*!
+ * \brief Fallback implementation for not well-formed diagram files
+ *
+ * If all files produced by dia were good XML files, we wouldn't have to do
* this little gymnastic. Alas, during the libxml1 days, we were outputting
* files with no encoding specification (which means UTF-8 if we're in an
* asciish encoding) and strings encoded in local charset (so, we wrote
@@ -101,6 +113,7 @@ static inline int isinf_ld (long double x) { return isnan (x - x); }
* @bug The many gzclose-g_free-return sequences should be refactored into
* an "exception handle" (goto+label). At least for people who think goto is
* better than this. I dont. --hb
+ * \ingroup DiagramXmlIo
*/
static const gchar *
xml_file_check_encoding(const gchar *filename, const gchar *default_enc, DiaContext *ctx)
@@ -234,11 +247,13 @@ xml_file_check_encoding(const gchar *filename, const gchar *default_enc, DiaCont
return res; /* caller frees the name and unlinks the file. */
}
-/** Parse a given file into XML, handling old broken files correctly.
+/*!
+ * \brief Parse a given file into XML, handling old broken files correctly.
* @param filename The name of the file to read.
* @returns An XML document parsed from the file.
* @see xmlParseFile() in the XML2 library for details on the return value.
* @param ctx The context in which this function is called
+ * \ingroup DiagramXmlIo
*/
static xmlDocPtr
xmlDiaParseFile(const char *filename, DiaContext *ctx)
@@ -266,9 +281,11 @@ xmlDiaParseFile(const char *filename, DiaContext *ctx)
}
}
-/** Parse an xml file from a filename given in Dia's/GLib's filename encoding
+/*!
+ * \brief Parse an xml file from a filename given in Dia's/GLib's filename encoding
* @param filename A file to parse. On win32 the filename encoding is utf-8 since GLib 2.6
* @return An XML document.
+ * \ingroup DiagramXmlIo
*/
xmlDocPtr
xmlDoParseFile(const char *filename)
@@ -283,11 +300,15 @@ xmlDoParseFile(const char *filename)
return doc;
}
-/** Parse an xml file from a filename given in Dia's/GLib's filename encoding
+/*!
+ * \brief Parse an xml file from a filename given in Dia's/GLib's filename encoding
+ *
* @param filename A file to parse. On win32 the filename encoding is utf-8 since GLib 2.6
* @param ctx If something goes wrong during parsing ctx will include according messages
* @param try_harder If set an additional attempt is done with guessed encoding
* @return An XML document.
+ *
+ * \ingroup DiagramXmlIo
*/
xmlDocPtr
diaXmlParseFile(const char *filename, DiaContext *ctx, gboolean try_harder)
@@ -306,12 +327,16 @@ diaXmlParseFile(const char *filename, DiaContext *ctx, gboolean try_harder)
return doc;
}
-/** Find a named attribute node in an XML object node.
- * Note that Dia has a concept of attribute node that is not the same
- * as an XML attribute.
+/*!
+ * \brief Find a named attribute node in an XML object node.
+ *
+ * Note that Dia has a concept of attribute node that is not the same
+ * as an XML attribute.
+ *
* @param obj_node The node to look in.
* @param attrname The name of the attribute node to find.
* @return The node matching the given name, or NULL if none found.
+ * \ingroup DiagramXmlIn
*/
AttributeNode
object_find_attribute(ObjectNode obj_node,
@@ -343,10 +368,12 @@ object_find_attribute(ObjectNode obj_node,
return NULL;
}
-/** Find an attribute in a composite XML node.
+/*!
+ * \brief Find an attribute in a composite XML node.
* @param composite_node The composite node to search.
* @param attrname The name of the attribute node to find.
* @return The desired node, or NULL if none exists in `composite_node'.
+ * \ingroup DiagramXmlIn
*/
AttributeNode
composite_find_attribute(DataNode composite_node,
@@ -378,9 +405,11 @@ composite_find_attribute(DataNode composite_node,
return NULL;
}
-/** The number of non-blank data nodes in an attribute node.
+/*!
+ * \brief Count the number of non-blank data nodes in an attribute node.
* @param attribute The attribute node to read from.
- * @returns The number of non-blank data nodes in the node.
+ * @return The number of non-blank data nodes in the node.
+ * \ingroup DiagramXmlIn
*/
int
attribute_num_data(AttributeNode attribute)
@@ -400,9 +429,11 @@ attribute_num_data(AttributeNode attribute)
return nr;
}
-/** Get the first data node in an attribute node.
+/*!
+ * \brief Get the first data node in an attribute node.
* @param attribute The attribute node to look through.
* @return The first non-black data node in the attribute node.
+ * \ingroup DiagramXmlIn
*/
DataNode
attribute_first_data(AttributeNode attribute)
@@ -412,9 +443,11 @@ attribute_first_data(AttributeNode attribute)
return (DataNode) data;
}
-/** Get the next data node (sibling).
+/*!
+ * \brief Get the next data node (sibling).
* @param data A data node to start from (e.g. just processed)
- * @returns The next sibling data node.
+ * @return The next sibling data node.
+ * \ingroup DiagramXmlIn
*/
DataNode
data_next(DataNode data)
@@ -427,13 +460,14 @@ data_next(DataNode data)
return (DataNode) data;
}
-/** Get the type of a data node.
+/*!
+ * \brief Get the type of a data node.
* @param data The data node.
* @param ctx The context in which this function is called
- * @return The type that the data node defines, or 0 on error. In case of
- * error, an error message is displayed.
+ * @return The type that the data node defines, or 0 on error.
* @note This function does a number of strcmp calls, which may not be the
* fastest way to check if a node is of the expected type.
+ * \ingroup DiagramXmlIn
*/
DataType
data_type(DataNode data, DiaContext *ctx)
@@ -473,11 +507,13 @@ data_type(DataNode data, DiaContext *ctx)
return 0;
}
-/** Return the value of an integer-type data node.
+/*!
+ * \brief Return the value of an integer-type data node.
* @param data The data node to read from.
- * @returns The integer value found in the node. If the node is not an
- * integer node, an error message is displayed and 0 is returned.
* @param ctx The context in which this function is called
+ * @return The integer value found in the node. If the node is not an
+ * integer node, an error message is displayed and 0 is returned.
+ * \ingroup DiagramXmlIn
*/
int
data_int(DataNode data, DiaContext *ctx)
@@ -497,11 +533,13 @@ data_int(DataNode data, DiaContext *ctx)
return res;
}
-/** Return the value of an enum-type data node.
+/*!
+ * \brief Return the value of an enum-type data node.
* @param data The data node to read from.
- * @returns The enum value found in the node. If the node is not an
- * enum node, an error message is displayed and 0 is returned.
* @param ctx The context in which this function is called
+ * @return The enum value found in the node. If the node is not an
+ * enum node, an error message is displayed and 0 is returned.
+ * \ingroup DiagramXmlIn
*/
int
data_enum(DataNode data, DiaContext *ctx)
@@ -521,11 +559,13 @@ data_enum(DataNode data, DiaContext *ctx)
return res;
}
-/** Return the value of a real-type data node.
+/*!
+ * \brief Return the value of a real-type data node.
* @param data The data node to read from.
- * @returns The real value found in the node. If the node is not a
- * real-type node, an error message is displayed and 0.0 is returned.
* @param ctx The context in which this function is called
+ * @return The real value found in the node. If the node is not a
+ * real-type node, an error message is displayed and 0.0 is returned.
+ * \ingroup DiagramXmlIn
*/
real
data_real(DataNode data, DiaContext *ctx)
@@ -545,11 +585,13 @@ data_real(DataNode data, DiaContext *ctx)
return res;
}
-/** Return the value of a boolean-type data node.
+/*!
+ * \brief Return the value of a boolean-type data node.
* @param data The data node to read from.
- * @returns The boolean value found in the node. If the node is not a
- * boolean node, an error message is displayed and FALSE is returned.
* @param ctx The context in which this function is called
+ * @return The boolean value found in the node. If the node is not a
+ * boolean node, an error message is displayed and FALSE is returned.
+ * \ingroup DiagramXmlIn
*/
int
data_boolean(DataNode data, DiaContext *ctx)
@@ -574,11 +616,13 @@ data_boolean(DataNode data, DiaContext *ctx)
return res;
}
-/** Return the integer value of a hex digit.
+/*!
+ * \brief Return the integer value of a hex digit.
* @param c A hex digit, one of 0-9, a-f or A-F.
- * @returns The value of the digit, i.e. 0-15. If a non-gex digit is given
- * an error is registered in ctx, and 0 is returned.
* @param ctx The context in which this function is called
+ * @return The value of the digit, i.e. 0-15. If a non-gex digit is given
+ * an error is registered in ctx, and 0 is returned.
+ * \ingroup DiagramXmlIn
*/
static int
hex_digit(char c, DiaContext *ctx)
@@ -593,13 +637,14 @@ hex_digit(char c, DiaContext *ctx)
return 0;
}
-/** Return the value of a color-type data node.
+/*!
+ * \brief Return the value of a color-type data node.
* @param data The XML node to read from
- * @param col A place to store the resulting RGB values. If the node does
+ * @param col A place to store the resulting RGBA values. If the node does
* not contain a valid color value, an error message is registered in ctx
* and `col' is unchanged.
- * @note Could be cool to use RGBA data here, even if we can't display it yet.
* @param ctx The context in which this function is called
+ * \ingroup DiagramXmlIn
*/
void
data_color(DataNode data, Color *col, DiaContext *ctx)
@@ -636,12 +681,14 @@ data_color(DataNode data, Color *col, DiaContext *ctx)
col->alpha = (float)(a/255.0);
}
-/** Return the value of a point-type data node.
+/*!
+ * \brief Return the value of a point-type data node.
* @param data The XML node to read from
* @param point A place to store the resulting x, y values. If the node does
* not contain a valid point value, an error message is registered in ctx
* and `point' is unchanged.
* @param ctx The context in which this function is called
+ * \ingroup DiagramXmlIn
*/
void
data_point(DataNode data, Point *point, DiaContext *ctx)
@@ -683,11 +730,13 @@ data_point(DataNode data, Point *point, DiaContext *ctx)
xmlFree(val);
}
-/** Return the value of a bezpoint-type data node.
+/*!
+ * \brief Return the value of a bezpoint-type data node.
* @param data The XML node to read from
* @param point A place to store the resulting values. If the node does
* not contain a valid bezpoint zero initialization is performed.
* @param ctx The context in which this function is called
+ * \ingroup DiagramXmlIn
*/
void
data_bezpoint(DataNode data, BezPoint *point, DiaContext *ctx)
@@ -752,12 +801,14 @@ data_bezpoint(DataNode data, BezPoint *point, DiaContext *ctx)
}
}
-/** Return the value of a rectangle-type data node.
+/*!
+ * Return the value of a rectangle-type data node.
* @param data The data node to read from.
* @param rect A place to store the resulting values. If the node does
* not contain a valid rectangle value, an error message is displayed to the
* user, and `rect' is unchanged.
* @param ctx The context in which this function is called
+ * \ingroup DiagramXmlIn
*/
void
data_rectangle(DataNode data, Rectangle *rect, DiaContext *ctx)
@@ -810,13 +861,15 @@ data_rectangle(DataNode data, Rectangle *rect, DiaContext *ctx)
xmlFree(val);
}
-/** Return the value of a string-type data node.
+/*!
+ * \brief Return the value of a string-type data node.
* @param data The data node to read from.
- * @returns The string value found in the node. If the node is not a
+ * @return The string value found in the node. If the node is not a
* string node, an error message is displayed and NULL is returned. The
* returned valuee should be freed after use.
* @note For historical reasons, strings in Dia XML are surrounded by ##.
* @param ctx The context in which this function is called
+ * \ingroup DiagramXmlIn
*/
gchar *
data_string(DataNode data, DiaContext *ctx)
@@ -887,7 +940,8 @@ data_string(DataNode data, DiaContext *ctx)
return NULL;
}
-/** Return the value of a filename-type data node.
+/*!
+ * \brief Return the value of a filename-type data node.
* @param data The data node to read from.
* @param ctx The context in which this function is called
* @return The filename value found in the node. If the node is not a
@@ -895,6 +949,7 @@ data_string(DataNode data, DiaContext *ctx)
* The resulting string is in the local filesystem's encoding rather than
* UTF-8, and should be freed after use.
* @bug data_string() can return NULL, what does g_filename_from_utf8 do then?
+ * \ingroup DiagramXmlIn
*/
char *
data_filename(DataNode data, DiaContext *ctx)
@@ -905,13 +960,16 @@ data_filename(DataNode data, DiaContext *ctx)
return filename;
}
-/** Return the value of a font-type data node. This handles both the current
- * format (family and style) and the old format (name).
+/*!
+ * \brief Return the value of a font-type data node.
+ *
+ * This handles both the current format (family and style) and the old format (name).
* @param data The data node to read from.
* @param ctx The context in which this function is called
* @return The font value found in the node. If the node is not a
- * font node, an error message is displayed and NULL is returned. The
+ * font node, an error message is registered and NULL is returned. The
* resulting value should be freed after use.
+ * \ingroup DiagramXmlIn
*/
DiaFont *
data_font(DataNode data, DiaContext *ctx)
@@ -945,10 +1003,12 @@ data_font(DataNode data, DiaContext *ctx)
/* ***** Saving XML **** */
-/** Create a new attribute node.
+/*!
+ * \brief Create a new attribute node.
* @param obj_node The object node to create the attribute node under.
* @param attrname The name of the attribute node.
* @return A new attribute node.
+ * \ingroup DiagramXmlOut
*/
AttributeNode
new_attribute(ObjectNode obj_node,
@@ -961,10 +1021,12 @@ new_attribute(ObjectNode obj_node,
return attr;
}
-/** Add an attribute node to a composite node.
+/*!
+ * \brief Add an attribute node to a composite node.
* @param composite_node The composite node.
* @param attrname The name of the new attribute node.
* @return The attribute node added.
+ * \ingroup DiagramXmlOut
*/
AttributeNode
composite_add_attribute(DataNode composite_node,
@@ -977,9 +1039,11 @@ composite_add_attribute(DataNode composite_node,
return attr;
}
-/** Add integer data to an attribute node.
+/*!
+ * \brief Add integer data to an attribute node.
* @param attr The attribute node.
* @param data The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_int(AttributeNode attr, int data)
@@ -993,9 +1057,11 @@ data_add_int(AttributeNode attr, int data)
xmlSetProp(data_node, (const xmlChar *)"val", (xmlChar *)buffer);
}
-/** Add enum data to an attribute node.
+/*!
+ * \brief Add enum data to an attribute node.
* @param attr The attribute node.
* @param data The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_enum(AttributeNode attr, int data)
@@ -1009,9 +1075,11 @@ data_add_enum(AttributeNode attr, int data)
xmlSetProp(data_node, (const xmlChar *)"val", (xmlChar *)buffer);
}
-/** Add real-typed data to an attribute node.
+/*!
+ * \brief Add real-typed data to an attribute node.
* @param attr The attribute node.
* @param data The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_real(AttributeNode attr, real data)
@@ -1025,9 +1093,11 @@ data_add_real(AttributeNode attr, real data)
xmlSetProp(data_node, (const xmlChar *)"val", (xmlChar *)buffer);
}
-/** Add boolean data to an attribute node.
+/*!
+ * \brief Add boolean data to an attribute node.
* @param attr The attribute node.
* @param data The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_boolean(AttributeNode attr, int data)
@@ -1041,13 +1111,15 @@ data_add_boolean(AttributeNode attr, int data)
xmlSetProp(data_node, (const xmlChar *)"val", (const xmlChar *)"false");
}
-/** Convert a floating-point value to hexadecimal.
+/*!
+ * \brief Convert a floating-point value to hexadecimal.
* @param x The floating point value.
* @param str A string to place the result in.
* @note Currently only works for 0 <= x <= 255 and will silently cap the value
* to those limits. Also expects str to have at least two bytes allocated,
* and doesn't null-terminate it. This works well for converting a color
* value, but is pretty much useless for other values.
+ * \ingroup DiagramXmlOut
*/
static void
convert_to_hex(float x, char *str)
@@ -1065,9 +1137,11 @@ convert_to_hex(float x, char *str)
str[1] = hex_digit[val%16];
}
-/** Add color data to an attribute node.
+/*!
+ * \brief Add color data to an attribute node.
* @param attr The attribute node.
* @param col The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_color(AttributeNode attr, const Color *col)
@@ -1100,9 +1174,11 @@ _str_point (const Point *point)
return buffer;
}
-/** Add point data to an attribute node.
+/*!
+ * \brief Add point data to an attribute node.
* @param attr The attribute node.
* @param point The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_point(AttributeNode attr, const Point *point)
@@ -1115,6 +1191,10 @@ data_add_point(AttributeNode attr, const Point *point)
g_free(buffer);
}
+/*!
+ * \brief Saving _BezPoint in a single node
+ * \ingroup DiagramXmlOut
+ */
void
data_add_bezpoint(AttributeNode attr, const BezPoint *point)
{
@@ -1149,9 +1229,11 @@ data_add_bezpoint(AttributeNode attr, const BezPoint *point)
}
}
-/** Add rectangle data to an attribute node.
+/*!
+ * \brief Add rectangle data to an attribute node.
* @param attr The attribute node.
* @param rect The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_rectangle(AttributeNode attr, const Rectangle *rect)
@@ -1176,9 +1258,11 @@ data_add_rectangle(AttributeNode attr, const Rectangle *rect)
g_free(buffer);
}
-/** Add string data to an attribute node.
+/*!
+ * \brief Add string data to an attribute node.
* @param attr The attribute node.
* @param str The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_string(AttributeNode attr, const char *str)
@@ -1202,10 +1286,12 @@ data_add_string(AttributeNode attr, const char *str)
g_free(sharped_str);
}
-/** Add filename data to an attribute node.
+/*!
+ * \brief Add filename data to an attribute node.
* @param data The data node.
* @param str The filename value to set. This should be n the local filesystem
* encoding, not utf-8.
+ * \ingroup DiagramXmlOut
*/
void
data_add_filename(DataNode data, const char *str)
@@ -1217,9 +1303,11 @@ data_add_filename(DataNode data, const char *str)
g_free(utf8);
}
-/** Add font data to an attribute node.
+/*!
+ * \brief Add font data to an attribute node.
* @param attr The attribute node.
* @param font The value to set.
+ * \ingroup DiagramXmlOut
*/
void
data_add_font(AttributeNode attr, const DiaFont *font)
@@ -1236,10 +1324,12 @@ data_add_font(AttributeNode attr, const DiaFont *font)
xmlSetProp(data_node, (const xmlChar *)"name", (xmlChar *) dia_font_get_legacy_name(font));
}
-/** Add a new composite node to an attribute node.
+/*!
+ * \brief Add a new composite node to an attribute node.
* @param attr The attribute node to add to.
* @param type The type of the new node.
- * @returns The new child of `attr'.
+ * @return The new child of `attr'.
+ * \ingroup DiagramXmlOut
*/
DataNode
data_add_composite(AttributeNode attr, const char *type)
@@ -1260,11 +1350,13 @@ data_add_composite(AttributeNode attr, const char *type)
/* diarc option */
int pretty_formated_xml = TRUE;
-/** Save an XML document to a file.
+/*!
+ * \brief Save an XML document to a file.
* @param filename The file to save to.
* @param cur The XML document structure.
* @return The return value of xmlSaveFormatFileEnc.
* @todo Get the proper defn of the return value from libxml2.
+ * \ingroup DiagramXmlIo
*/
int
xmlDiaSaveFile(const char *filename,
diff --git a/lib/dia_xml.h b/lib/dia_xml.h
index d7a4b96..d9a95e4 100644
--- a/lib/dia_xml.h
+++ b/lib/dia_xml.h
@@ -26,7 +26,10 @@
#include "diacontext.h"
#include <libxml/tree.h>
-/*
+/*!
+ * \note Dia's diagram namespace
+ * \ingroup DiagramXmlIo
+ *
* Though the Dia homepage is now http://www.gnome.org/projects/dia
* Dia's xml namespace definition still needs to point to the
* original site. In fact the xml namespace definition has nothing to do
diff --git a/lib/diagramdata.c b/lib/diagramdata.c
index 34c2b5c..085e8ca 100644
--- a/lib/diagramdata.c
+++ b/lib/diagramdata.c
@@ -162,13 +162,15 @@ diagram_data_finalize(GObject *object)
}
-/**
- * Create a copy of the whole diagram data
+/*!
+ * \brief Create a copy of the whole diagram data
*
* This is kind of a deep copy, everything not immutable gets duplicated.
* Still this is supposed to be relatively fast, because the most expensive
* objects have immutuable properties, namely the pixbufs in DiaImage are
* only referenced.
+ *
+ * \memberof _DiagramData
*/
DiagramData *
diagram_data_clone (DiagramData *data)
@@ -206,8 +208,9 @@ diagram_data_clone (DiagramData *data)
return clone;
}
-/**
- * Create a new diagram data object only containing the selected objects
+/*!
+ * \brief Create a new diagram data object only containing the selected objects
+ * \memberof _DiagramData
*/
DiagramData *
diagram_data_clone_selected (DiagramData *data)
@@ -289,9 +292,11 @@ diagram_data_class_init(DiagramDataClass *klass)
klass->object_remove = _diagram_data_object_remove;
}
-/** Raise a layer up one in a diagram.
+/*!
+ * \brief Raise a layer up one in a diagram.
* @param data The diagram that the layer belongs to.
* @param layer The layer to raise.
+ * \memberof _DiagramData
*/
void
data_raise_layer(DiagramData *data, Layer *layer)
@@ -313,9 +318,11 @@ data_raise_layer(DiagramData *data, Layer *layer)
}
}
-/** Lower a layer by one in a diagram.
+/*!
+ * \brief Lower a layer by one in a diagram.
* @param data The diagram that the layer belongs to.
* @param layer The layer to lower.
+ * \memberof _DiagramData
*/
void
data_lower_layer(DiagramData *data, Layer *layer)
@@ -339,9 +346,11 @@ data_lower_layer(DiagramData *data, Layer *layer)
}
}
-/** Add a layer object to a diagram.
+/*!
+ * \brief Add a layer object to a diagram.
* @param data The diagram to add the layer to.
* @param layer The layer to add.
+ * \memberof _DiagramData
*/
void
data_add_layer(DiagramData *data, Layer *layer)
@@ -353,6 +362,16 @@ data_add_layer(DiagramData *data, Layer *layer)
data_update_extents(data);
}
+/*!
+ * \brief Add a layer at a defined postion in the stack
+ *
+ * If the given pos is out of range the layer is added at the top of the stack.
+ *
+ * @param data the diagram
+ * @param layer layer to add
+ * @param pos the position in the layer stack
+ * \memberof _DiagramData
+ */
void
data_add_layer_at(DiagramData *data, Layer *layer, int pos)
{
@@ -375,6 +394,15 @@ data_add_layer_at(DiagramData *data, Layer *layer, int pos)
data_update_extents(data);
}
+/*!
+ * \brief Get the index of a layer contained in the diagram
+ *
+ * @param data the diagram
+ * @param layer the layer
+ * @return the zero based index or -1 if not found
+ *
+ * \memberof _DiagramData
+ */
int
data_layer_get_index (const DiagramData *data, const Layer *layer)
{
@@ -388,6 +416,15 @@ data_layer_get_index (const DiagramData *data, const Layer *layer)
}
return -1;
}
+/*!
+ * \brief Get the layer at position index
+ *
+ * @param data the diagram
+ * @param index the layer position
+ * @return the _Layer or NULL if not found
+ *
+ * \memberof _DiagramData
+ */
Layer *
data_layer_get_nth (const DiagramData *data, guint index)
{
@@ -401,9 +438,12 @@ data_layer_count(const DiagramData *data)
return data->layers->len;
}
-/** Set which layer is the active layer in a diagram.
+/*!
+ * \brief Set which layer is the active layer in a diagram.
* @param data The diagram in which to set the active layer.
* @param layer The layer that should be active.
+ *
+ * \memberof _DiagramData
*/
void
data_set_active_layer(DiagramData *data, Layer *layer)
@@ -411,9 +451,11 @@ data_set_active_layer(DiagramData *data, Layer *layer)
data->active_layer = layer;
}
-/** Delete a layer from a diagram.
+/*!
+ * \brief Delete a layer from a diagram.
* @param data The diagram to delete the layer from.
* @param layer The layer to delete.
+ * \memberof _DiagramData
*/
void
data_delete_layer(DiagramData *data, Layer *layer)
@@ -480,10 +522,14 @@ data_object_get_highlight(DiagramData *data, DiaObject *obj)
return type;
}
-/** Select an object in a diagram. Note that this does not unselect other
- * objects currently selected in the diagram.
+/*!
+ * \brief Select an object in a diagram
+ *
+ * Note that this does not unselect other objects currently selected in the diagram.
* @param data The diagram to select in.
- * @param obj The object to select.
+ * @param obj The object to select
+ *
+ * \memberof _DiagramData
*/
void
data_select(DiagramData *data, DiaObject *obj)
@@ -495,10 +541,14 @@ data_select(DiagramData *data, DiaObject *obj)
g_signal_emit (data, diagram_data_signals[SELECTION_CHANGED], 0, data->selected_count_private);
}
-/** Deselect an object in a diagram. Note that other objects may still be
- * selected after this function is done.
+/*!
+ * \brief Deselect an object in a diagram
+ *
+ * Note that other objects may still be selected after this function is done.
* @param data The diagram to deselect in.
* @param obj The object to deselect.
+ *
+ * \memberof _DiagramData
*/
void
data_unselect(DiagramData *data, DiaObject *obj)
@@ -510,9 +560,11 @@ data_unselect(DiagramData *data, DiaObject *obj)
g_signal_emit (data, diagram_data_signals[SELECTION_CHANGED], 0, data->selected_count_private);
}
-/** Clears the list of selected objects.
+/*!
+ * \brief Clears the list of selected objects.
* Does *not* remove these objects from the object list, despite its name.
* @param data The diagram to unselect all objects in.
+ * \memberof _DiagramData
*/
void
data_remove_all_selected(DiagramData *data)
@@ -523,9 +575,11 @@ data_remove_all_selected(DiagramData *data)
g_signal_emit (data, diagram_data_signals[SELECTION_CHANGED], 0, data->selected_count_private);
}
-/** Return TRUE if the diagram has visible layers.
+/*!
+ * \brief Return TRUE if the diagram has visible layers.
* @param data The diagram to check.
* @return TRUE if at least one layer in the diagram is visible.
+ * \protected \memberof _DiagramData
*/
static gboolean
data_has_visible_layers(DiagramData *data)
@@ -538,8 +592,10 @@ data_has_visible_layers(DiagramData *data)
return FALSE;
}
-/** Set the diagram extents field to the union of the extents of the layers.
+/*!
+ * \brief Set the diagram extents field to the union of the extents of the layers.
* @param data The diagram to get the extents for.
+ * \protected \memberof _DiagramData
*/
static void
data_get_layers_extents_union(DiagramData *data)
@@ -567,8 +623,10 @@ data_get_layers_extents_union(DiagramData *data)
data->extents = new_extents;
}
-/** Change diagram scaling so that the extents are exactly visible.
+/*!
+ * \brief Change diagram scaling so that the extents are exactly visible.
* @param data The diagram to adjust.
+ * \protected \memberof _DiagramData
*/
static void
data_adapt_scaling_to_extents(DiagramData *data)
@@ -586,9 +644,11 @@ data_adapt_scaling_to_extents(DiagramData *data)
data->paper.height = (float)(pheight / data->paper.scaling);
}
-/** Adjust the extents field of a diagram.
+/*!
+ * \brief Adjust the extents field of a diagram.
* @param data The diagram to adjust.
* @return TRUE if the extents changed.
+ * \protected \memberof _DiagramData
*/
static gboolean
data_compute_extents(DiagramData *data)
@@ -668,12 +728,15 @@ data_get_sorted_selected(DiagramData *data)
return sorted_list;
}
-/** Remove the currently selected objects from the list of objects.
+/*!
+ * \brief Remove the currently selected objects from the list of objects.
+ *
* The selected objects are returned in a newly created GList.
* @param data The diagram to get and remove the selected objects from.
* @return A list of all selected objects in the current diagram. This list
* should be freed after use. Unlike data_get_sorted_selected, the
* objects in the list are not in the diagram anymore.
+ * \memberof _DiagramData
*/
GList *
data_get_sorted_selected_remove(DiagramData *data)
@@ -708,11 +771,13 @@ data_get_sorted_selected_remove(DiagramData *data)
}
-/** Emits a GObject signal on DiagramData
- * @param data The DiagramData that emits the signal.
- * @param layer The Layer that the fired signal carries.
- * @param obj The DiaObject that the fired signal carries.
- * @param signal_name The name of the signal.
+/*!
+ * \brief Emits a GObject signal on DiagramData
+ * @param data The DiagramData that emits the signal.
+ * @param layer The Layer that the fired signal carries.
+ * @param obj The DiaObject that the fired signal carries.
+ * @param signal_name The name of the signal.
+ * \memberof _DiagramData
*/
void
data_emit(DiagramData *data, Layer *layer, DiaObject* obj,
@@ -728,12 +793,14 @@ data_emit(DiagramData *data, Layer *layer, DiaObject* obj,
}
-/** Render a diagram.
+/*!
+ * \brief Render a diagram
* @param data The diagram to render.
* @param renderer The renderer to render on.
- * @param update The area that needs updating.
+ * @param update The area that needs updating or NULL
* @param obj_renderer If non-NULL, an alternative renderer of objects.
* @param gdata User data passed on to inner calls.
+ * \memberof _DiagramData
*/
void
data_render(DiagramData *data, DiaRenderer *renderer, Rectangle *update,
@@ -757,7 +824,13 @@ data_render(DiagramData *data, DiaRenderer *renderer, Rectangle *update,
(DIA_RENDERER_GET_CLASS(renderer)->end_render)(renderer);
}
-/** Call data_render() for every used page in the diagram */
+/*!
+ * \brief Calls data_render() for paginated formats
+ *
+ * Call data_render() for every used page in the diagram
+ *
+ * \memberof _DiagramData
+ */
void
data_render_paginated (DiagramData *data, DiaRenderer *renderer, gpointer user_data)
{
@@ -802,6 +875,13 @@ data_render_paginated (DiagramData *data, DiaRenderer *renderer, gpointer user_d
}
}
+/*!
+ * \brief Visit all objects within the diagram
+ * @param data the diagram
+ * @param func per object callback function
+ * @param user_data data passed to the callback function
+ * \memberof _DiagramData
+ */
void
data_foreach_object (DiagramData *data, GFunc func, gpointer user_data)
{
@@ -812,4 +892,3 @@ data_foreach_object (DiagramData *data, GFunc func, gpointer user_data)
g_list_foreach (layer->objects, func, user_data);
}
}
-
diff --git a/lib/diagramdata.h b/lib/diagramdata.h
index 3f59f2e..a512b18 100644
--- a/lib/diagramdata.h
+++ b/lib/diagramdata.h
@@ -58,6 +58,8 @@ GType diagram_data_get_type (void) G_GNUC_CONST;
*
* Dia's diagram object is the container of _Layer, the managment object of _DiaObject selections
* and text foci (_Focus) as well a highlithing state resulting from selections.
+ *
+ * \ingroup DiagramStructure
*/
struct _DiagramData {
GObject parent_instance; /*!< inheritance in C */
@@ -90,9 +92,7 @@ struct _DiagramData {
};
-/**
- * \brief DiagramData vtable
- */
+/* DiagramData vtable */
typedef struct _DiagramDataClass {
GObjectClass parent_class;
@@ -106,18 +106,19 @@ typedef struct _DiagramDataClass {
/*!
* \brief A diagram consists of layers holding objects
*
+ * \ingroup DiagramStructure
* \todo : make this a GObject as well
*/
struct _Layer {
- char *name; /*!< */
- Rectangle extents; /*!< The extents of the layer */
+ char *name; /*!< The name of the layer */
+ Rectangle extents; /*!< The extents of the layer */
GList *objects; /*!< List of objects in the layer,
- sorted by decreasing z-valued,
+ sorted by decreasing z-value,
objects can ONLY be connected to objects
in the same layer! */
- gboolean visible;
+ gboolean visible; /*!< The visibility of the layer */
gboolean connectable; /*!< Whether the layer can currently be connected to.
The selected layer is by default connectable */
@@ -211,9 +212,6 @@ void layer_replace_object_with_list(Layer *layer, DiaObject *obj,
void layer_set_object_list(Layer *layer, GList *list);
DiagramData *layer_get_parent_diagram(Layer *layer);
-/* Make sure all objects that are in the layer and not in the new
- list eventually gets destroyed. */
-
G_END_DECLS
#endif /* DIAGRAMDATA_H */
diff --git a/lib/font.c b/lib/font.c
index 25be02c..c2d21e6 100644
--- a/lib/font.c
+++ b/lib/font.c
@@ -50,7 +50,7 @@ static PangoContext* pango_context = NULL;
/*!
* \brief Opaque type to represent a font
- * \ingroup ObjectParts
+ * \ingroup ObjectFonts
*/
struct _DiaFont
{
diff --git a/lib/font.h b/lib/font.h
index 0253fcf..aaf6784 100644
--- a/lib/font.h
+++ b/lib/font.h
@@ -25,9 +25,11 @@
#include "dia-enums.h"
#include "geometry.h"
-/*!
+/*!
\file font.h -- services based on font definitions
- \defgroup FontServices Dia's font definiton based on Pango model
+ */
+/*!
+ \defgroup ObjectFonts Dia's font definiton
\ingroup ObjectParts
*/
@@ -107,7 +109,7 @@ struct _DiaFontClass {
};
/*! Set the PangoContext used to render text.
- * \ingroup FontServices
+ * \ingroup ObjectFonts
*/
void dia_font_init(PangoContext* pcontext);
/* Start using a new context (for AA rendering) */
@@ -119,7 +121,7 @@ PangoContext *dia_font_get_context(void);
/*!
* \brief Font creation for object implementation
- * \ingroup FontServices
+ * \ingroup ObjectFonts
* Get a font matching family,style,height. MUST be freed with dia_font_unref().
*/
DiaFont* dia_font_new(const char *family, DiaFontStyle style,
@@ -129,14 +131,14 @@ DiaFont* dia_font_new(const char *family, DiaFontStyle style,
* \brief Font creation for object implementation
* Get a font matching style. This is the preferred method to
* create default fonts within objects.
- * \ingroup FontServices
+ * \ingroup ObjectFonts
*/
DiaFont* dia_font_new_from_style(DiaFontStyle style, real height);
/*!
* \brief Font creation for object implementation
* Get a font from a legacy font name
- * \ingroup FontServices
+ * \ingroup ObjectFonts
*/
DiaFont* dia_font_new_from_legacy_name(const char *name);
@@ -144,7 +146,7 @@ DiaFont* dia_font_new_from_legacy_name(const char *name);
* \brief Font creation for object implementation
* Get a simple font name from a font.
* Name will be valid for the duration of the DiaFont* lifetime.
- * \ingroup FontServices
+ * \ingroup ObjectFonts
*/
const char* dia_font_get_legacy_name(const DiaFont* font);
diff --git a/lib/layer.c b/lib/layer.c
index 64cdcd7..48fb180 100644
--- a/lib/layer.c
+++ b/lib/layer.c
@@ -27,11 +27,12 @@
static const Rectangle invalid_extents = { -1.0,-1.0,-1.0,-1.0 };
-/** The default object renderer.
+/*! The default object renderer.
* @param obj An object to render.
* @param renderer The renderer to render on.
* @param active_layer The layer containing the object.
* @param data The diagram containing the layer.
+ * \ingroup DiagramStructure
*/
static void
normal_render(DiaObject *obj, DiaRenderer *renderer,
@@ -44,8 +45,10 @@ normal_render(DiaObject *obj, DiaRenderer *renderer,
int render_bounding_boxes = FALSE;
-/** Render all components of a single layer. This function also handles
- * rendering of bounding boxes for debugging purposes.
+/*!
+ * \brief Render all components of a single layer.
+ *
+ * This function also handles rendering of bounding boxes for debugging purposes.
* @param layer The layer to render.
* @param renderer The renderer to draw things with.
* @param update The rectangle that requires update. Only objects that
@@ -53,6 +56,7 @@ int render_bounding_boxes = FALSE;
* @param obj_renderer A function that will render an object.
* @param data The diagram that the layer belongs to.
* @param active_layer Which number layer in the diagram is currently active.
+ * \memberof _Layer
*/
void
layer_render(Layer *layer, DiaRenderer *renderer, Rectangle *update,
@@ -94,10 +98,12 @@ layer_render(Layer *layer, DiaRenderer *renderer, Rectangle *update,
}
}
-/** Create a new layer in this diagram.
+/*!
+ * \brief Create a new layer in this diagram.
* @param name Name of the new layer.
* @param parent The DiagramData that the layer will belong to,.
* @return A new Layer object.
+ * \memberof _Layer
*/
Layer *
new_layer(gchar *name, DiagramData *parent)
@@ -122,8 +128,10 @@ new_layer(gchar *name, DiagramData *parent)
return layer;
}
-/** Destroy a layer object.
+/*!
+ * \brief Destroy a layer object.
* @param layer The layer object to deallocate entirely.
+ * \memberof _Layer
*/
void
layer_destroy(Layer *layer)
@@ -133,25 +141,29 @@ layer_destroy(Layer *layer)
g_free(layer);
}
-/** Set the parent layer of an object.
+/*!
+ * \brief Set the parent layer of an object.
* @param element A DiaObject that should be part of a layer.
* @param user_data The layer it should be part of.
+ * \protected \memberof _Layer
*/
static void
set_parent_layer(gpointer element, gpointer user_data)
{
((DiaObject*)element)->parent_layer = (Layer*)user_data;
/* FIXME: even group members need a parent_layer and what about parent objects ???
- * Now I know again why I always try to avoid back-pointers )-; --hb.
- * If the group objects didn't actually leave the diagram, this wouldn't
- * be a problem. --LC */
+ * Now I know again why I always try to avoid back-pointers )-; --hb.
+ * If the group objects didn't actually leave the diagram, this wouldn't
+ * be a problem. --LC */
}
-/** Get the index of an object in a layer.
+/*!
+ * \brief Get the index of an object in a layer.
* @param layer The layer the object is (should be) in.
* @param obj The object to look for.
* @return The index of the object in the layers list of objects. This is also
* the vertical position of the object.
+ * \memberof _Layer
*/
int
layer_object_get_index(Layer *layer, DiaObject *obj)
@@ -159,10 +171,11 @@ layer_object_get_index(Layer *layer, DiaObject *obj)
return (int)g_list_index(layer->objects, (gpointer) obj);
}
-/**
- * Get the object a index or NULL
+/*!
+ * \brief Get the object a index or NULL
* @param layer The layer to query for the nth object
* @param index The zero-based indexed of the object
+ * \memberof _Layer
*/
DiaObject *
layer_object_get_nth (Layer *layer, guint index)
@@ -183,7 +196,8 @@ layer_get_name (Layer *layer)
{
return g_strdup (layer->name);
}
-/** Add an object to the top of a layer.
+/*!
+ * \brief Add an object to the top of a layer.
* @param layer The layer to add the object to.
* @param obj The object to add. This must not already be part of another layer.
* \memberof _Layer
@@ -198,7 +212,8 @@ layer_add_object(Layer *layer, DiaObject *obj)
data_emit (layer_get_parent_diagram(layer), layer, obj, "object_add");
}
-/** Add an object to a layer at a specific position.
+/*!
+ * \brief Add an object to a layer at a specific position.
* @param layer The layer to add the object to.
* @param obj The object to add. This must not be part of another layer.
* @param pos The top-to-bottom position this object should be inserted at.
@@ -214,7 +229,8 @@ layer_add_object_at(Layer *layer, DiaObject *obj, int pos)
data_emit (layer_get_parent_diagram(layer), layer, obj, "object_add");
}
-/** Add a list of objects to the end of a layer.
+/*!
+ * \brief Add a list of objects to the end of a layer.
* @param layer The layer to add objects to.
* @param obj_list The list of objects to add. These must not already
* be part of another layer.
@@ -238,7 +254,8 @@ layer_add_objects(Layer *layer, GList *obj_list)
}
}
-/** Add a list of objects to the top of a layer.
+/*!
+ * \brief Add a list of objects to the top of a layer.
* @param layer The layer to add objects to.
* @param obj_list The list of objects to add. These must not already
* be part of another layer.
@@ -264,7 +281,8 @@ layer_add_objects_first(Layer *layer, GList *obj_list)
}
-/** Remove an object from a layer.
+/*!
+ * \brief Remove an object from a layer.
* @param layer The layer to remove the object from.
* @param obj The object to remove.
* \memberof _Layer
@@ -280,7 +298,8 @@ layer_remove_object(Layer *layer, DiaObject *obj)
set_parent_layer(obj, NULL);
}
-/** Remove a list of objects from a layer.
+/*!
+ * Remove a list of objects from a layer.
* @param layer The layer to remove the objects from.
* @param obj_list The objects to remove.
* \memberof _Layer
@@ -298,7 +317,8 @@ layer_remove_objects(Layer *layer, GList *obj_list)
}
}
-/** Find the objects that intersect a given rectangle.
+/*!
+ * \brief Find the objects that intersect a given rectangle.
* @param layer The layer to search in.
* @param rect The rectangle to intersect with.
* @return List of objects whose bounding box intersect the rectangle. The
@@ -332,11 +352,13 @@ layer_find_objects_intersecting_rectangle(Layer *layer, Rectangle *rect)
return selected_list;
}
-/** Find objects entirely contained in a rectangle.
+/*!
+ * \brief Find objects entirely contained in a rectangle.
* @param layer The layer to search for objects in.
* @param rect The rectangle that the objects should be in.
* @return A list containing the objects that are entirely contained in the
* rectangle. The list should be freed by the caller.
+ * \memberof _Layer
*/
GList *
layer_find_objects_in_rectangle(Layer *layer, Rectangle *rect)
@@ -362,11 +384,13 @@ layer_find_objects_in_rectangle(Layer *layer, Rectangle *rect)
return selected_list;
}
-/** Find objects entirely containing a rectangle.
+/*!
+ * \brief Find objects entirely containing a rectangle.
* @param layer The layer to search for objects in.
* @param rect The rectangle that the objects should surround.
* @return A list containing the objects that entirely contain the
* rectangle. The list should be freed by the caller.
+ * \memberof _Layer
*/
GList *
layer_find_objects_containing_rectangle(Layer *layer, Rectangle *rect)
@@ -395,7 +419,9 @@ layer_find_objects_containing_rectangle(Layer *layer, Rectangle *rect)
}
-/** Find the object closest to the given point in the layer,
+/*!
+ * \brief Find the object closest to the given point in the layer
+ *
* no further away than maxdist, and not included in avoid.
* Stops it if finds an object that includes the point.
* @param layer The layer to search in.
@@ -404,6 +430,7 @@ layer_find_objects_containing_rectangle(Layer *layer, Rectangle *rect)
* @param avoid A list of objects that cannot be returned by this search.
* @return The closest object, or NULL if no allowed objects are closer than
* maxdist.
+ * \memberof _Layer
*/
DiaObject *
layer_find_closest_object_except(Layer *layer, Point *pos,
@@ -442,9 +469,10 @@ layer_find_closest_object_except(Layer *layer, Point *pos,
return closest;
}
-/** Find the object closest to the given point in the layer,
- * no further away than maxdist.
- * Stops it if finds an object that includes the point.
+/*!
+ * \brief Find the object closest to the given point in the layer,
+ *
+ * no further away than maxdist. Stops it if finds an object that includes the point.
* @param layer The layer to search in.
* @param pos The point to compare to.
* @param maxdist The maximum distance the object can be from the point.
@@ -457,12 +485,14 @@ layer_find_closest_object(Layer *layer, Point *pos, real maxdist)
}
-/** Find the connectionpoint closest to pos in a layer.
- * @param layer
- * @param closest
- * @param pos
- * @param notthis
- * @return
+/*!
+ * \brief Find the connectionpoint closest to pos in a layer.
+ * @param layer the layer to search in
+ * @param closest connection point found or NULL
+ * @param pos refernce position in diagram coordinates
+ * @param notthis object not to search on
+ * @return the distance of the connection point and pos
+ * \memberof _Layer
*/
real
layer_find_closest_connectionpoint(Layer *layer,
@@ -501,6 +531,10 @@ layer_find_closest_connectionpoint(Layer *layer,
return mindist;
}
+/*!
+ * \brief Recalculation of the bounding box containing all objects in the layer
+ * \memberof _Layer
+ */
int
layer_update_extents(Layer *layer)
{
@@ -533,6 +567,14 @@ layer_update_extents(Layer *layer)
return TRUE;
}
+/*!
+ * \brief Swaps a list of objects with a single object
+ *
+ * This function exchanges the given object with the list of objects.
+ * Ownership of remove_obj and insert_list objects is swapped, too.
+ *
+ * \memberof _Layer
+ */
void
layer_replace_object_with_list(Layer *layer, DiaObject *remove_obj,
GList *insert_list)
diff --git a/lib/objchange.h b/lib/objchange.h
index db368d3..9573247 100644
--- a/lib/objchange.h
+++ b/lib/objchange.h
@@ -18,8 +18,10 @@
/*!
* \file objchange.h -- Forming the basic of undo support to be implemented in objects
+ */
+/*!
* \defgroup ObjChange Objects support for undo/redo
- * \ingroup Objects
+ * \ingroup ObjectServices
*/
#ifndef OBJCHANGE_H
#define OBJCHANGE_H
diff --git a/lib/object.h b/lib/object.h
index 7f57df7..7782ea4 100644
--- a/lib/object.h
+++ b/lib/object.h
@@ -414,9 +414,7 @@ DiaObject *object_copy_using_properties(DiaObject *obj);
** The structures used to define an object
*****************************************/
-/*!
- \brief _DiaObject vtable
-
+/*
This structure gives access to the functions used to manipulate an object
See information above on the use of the functions
*/
@@ -464,7 +462,10 @@ struct _ObjectOps {
struct _DiaObject {
DiaObjectType *type; /*!< pointer to the registered type */
Point position; /*!< often but not necessarily the upper left corner of the object */
- /** The area that contains all parts of the 'real' object, i.e. the parts
+ /*!
+ * \brief Rectangle containing the whole object
+ *
+ * The area that contains all parts of the 'real' object, i.e. the parts
* that would be printed, exported to pixmaps etc. This is also used to
* determine the size of autofit scaling, so it should be as large as
* the objects without interactive bits and preferably no larger.
@@ -483,7 +484,7 @@ struct _DiaObject {
/*! Array of ConnectionPoint* - indexing fixed by meaning */
ConnectionPoint **connections;
- ObjectOps *ops; /*!< pointer to the vtable */
+ ObjectOps *ops; /* pointer to the vtable */
Layer *parent_layer; /*!< Back-pointer to the owning layer.
This may only be set by functions internal to
@@ -508,7 +509,7 @@ struct _DiaObject {
GHashTable *meta;
};
-/*!
+/*
* \brief Vtable for _DiaObjectType
*/
struct _ObjectTypeOps {
@@ -537,14 +538,14 @@ struct _DiaObjectType {
char *name; /*!< The type name should follow a pattern of '\<module\> - \<class\>' like "UML - Class" */
int version; /*!< DiaObjects must be backward compatible, i.e. support possibly older versions formats */
- char **pixmap; /* Also put a pixmap in the sheet_object.
+ char **pixmap; /*! Also put a pixmap in the sheet_object.
This one is used if not in sheet but in toolbar.
Stored in xpm format */
- ObjectTypeOps *ops; /*!< pointer to the vtable */
+ ObjectTypeOps *ops; /* pointer to the vtable */
- char *pixmap_file; /* fallback if pixmap is NULL */
- void *default_user_data; /* use this if no user data is specified in
+ char *pixmap_file; /*! fallback if pixmap is NULL */
+ void *default_user_data; /*! use this if no user data is specified in
the .sheet file */
};
diff --git a/lib/properties.h b/lib/properties.h
index 7aa0048..8fe6fdc 100644
--- a/lib/properties.h
+++ b/lib/properties.h
@@ -126,7 +126,7 @@ typedef void (*PropertyType_SetFromOffset)(Property *prop,
void *base, guint offset, guint offset2);
typedef int (*PropertyType_GetDataSize)(Property *prop);
-/*!
+/*
* \brief Virtual function table for Property objects
*
* \ingroup StdProps
@@ -239,21 +239,31 @@ struct _PropDescription {
* editing them as one in a multiple object selection.
*/
PropertyType type;
- /*! Combination of values from */
+ /*! Combination of values from \ref PropFlags */
guint flags;
const gchar *description;
const gchar *tooltip;
- /* Holds some extra data whose meaning is dependent on the property type.
+ /*!
+ * \brief Additional type specifc range information
+ *
+ * Holds some extra data whose meaning is dependent on the property type.
* For example, int or float may use bounds for a spin button, and enums
- * may use a list of string names for enumeration values. */
+ * may use a list of string names for enumeration values.
+ *
+ * See: \ref _PropEnumData, \ref _PropNumData
+ */
gpointer extra_data;
- /* if the property widget can send events when it's somehow interacted with,
- control will be passed to object_type-supplied event_handler, and
- event->dialog->obj_copy will be current with the dialog's values.
- When control comes back, event->dialog->obj_copy's properties will be
- brought back into the dialog. */
+ /*!
+ * \brief Optional event handler
+ *
+ * If the property widget can send events when it's somehow interacted with,
+ * control will be passed to object_type-supplied event_handler, and
+ * event->dialog->obj_copy will be current with the dialog's values.
+ * When control comes back, event->dialog->obj_copy's properties will be
+ * brought back into the dialog.
+ */
PropEventHandler event_handler;
GQuark quark; /* quark for property name -- helps speed up lookups. */
@@ -265,28 +275,53 @@ struct _PropDescription {
const PropertyOps *ops;
};
-/*! PropFlags */
-/*! @{ */
-#define PROP_FLAG_VISIBLE 0x0001 /*!< should be visible in an editor */
-#define PROP_FLAG_DONT_SAVE 0x0002 /*!< not to be saved at all */
-#define PROP_FLAG_DONT_MERGE 0x0004 /*!< in case group properties are edited */
-#define PROP_FLAG_NO_DEFAULTS 0x0008 /*!< don't edit this in defaults dialog */
-#define PROP_FLAG_LOAD_ONLY 0x0010 /*!< for loading old formats */
-#define PROP_FLAG_STANDARD 0x0020 /*!< one of the default toolbox props */
-#define PROP_FLAG_MULTIVALUE 0x0040 /*!< multiple values for prop in group */
-#define PROP_FLAG_WIDGET_ONLY 0x0080 /*!< only cosmetic property, no data */
-#define PROP_FLAG_OPTIONAL 0x0100 /*!< don't complain if it does not exist */
-#define PROP_FLAG_SELF_ONLY 0x0200 /*!< do not apply to object lists */
-/*! @} */
+/*!
+ * \brief Behavior definition for Property
+ *
+ * With PropFlags the behavior of properties are further defined. A combination
+ * of flags is given to PropDescription::flags during declaration of a new property.
+ *
+ * \ingroup StdProps
+ */
+typedef enum {
+ PROP_FLAG_VISIBLE = 0x0001, /*!< should be visible in an editor */
+ PROP_FLAG_DONT_SAVE = 0x0002, /*!< not to be saved at all */
+ PROP_FLAG_DONT_MERGE = 0x0004, /*!< in case group properties are edited */
+ PROP_FLAG_NO_DEFAULTS = 0x0008, /*!< don't edit this in defaults dialog */
+ PROP_FLAG_LOAD_ONLY = 0x0010, /*!< for loading old formats */
+ PROP_FLAG_STANDARD = 0x0020, /*!< one of the default toolbox props */
+ PROP_FLAG_MULTIVALUE = 0x0040, /*!< multiple values for prop in group */
+ PROP_FLAG_WIDGET_ONLY = 0x0080, /*!< only cosmetic property, no data */
+ PROP_FLAG_OPTIONAL = 0x0100, /*!< don't complain if it does not exist */
+ PROP_FLAG_SELF_ONLY = 0x0200 /*!< do not apply to object lists */
+} PropFlags;
typedef enum {PROP_UNION, PROP_INTERSECTION} PropMergeOption;
#define PROP_DESC_END { NULL, 0, 0, NULL, NULL, NULL, 0 }
/* extra data pointers for various property types */
+/*!
+ * \brief Provide limits and step size for RealProperty
+ *
+ * Setting PropDescription::extra_data to an instance of this type
+ * allows to give limits and step size to the specified numeric property.
+ *
+ * \ingroup StdProps
+ */
struct _PropNumData {
gfloat min, max, step;
};
+/*!
+ * \brief Provide names and values for EnumProperty
+ *
+ * An array of PropEnumData is necessary to initailize the range
+ * of the EnumProperty. It has to be NULL terminated by seting a
+ * NULL name to the last array value. Set PropDescription::extra_data
+ * to the type specific extension.
+ *
+ * \ingroup StdProps
+ */
struct _PropEnumData {
const gchar *name;
guint enumv;
@@ -353,26 +388,26 @@ struct _Property {
/* Operations on property descriptors and property descriptor lists. */
void prop_desc_list_calculate_quarks(PropDescription *plist);
-/* plist must have all quarks calculated in advance */
+/*! plist must have all quarks calculated in advance */
const PropDescription *prop_desc_list_find_prop(const PropDescription *plist,
const gchar *name);
-/* finds the real handler in case there are several levels of indirection */
+/*! finds the real handler in case there are several levels of indirection */
PropEventHandler prop_desc_find_real_handler(const PropDescription *pdesc);
-/* free a handler indirection list */
+/*! free a handler indirection list */
void prop_desc_free_handler_chain(PropDescription *pdesc);
-/* free a handler indirection list in a list of descriptors */
+/*! free a handler indirection list in a list of descriptors */
void prop_desc_list_free_handler_chain(PropDescription *pdesc);
-/* insert an event handler */
+/*! insert an event handler */
void prop_desc_insert_handler(PropDescription *pdesc,
PropEventHandler handler);
-/* operations on lists of property description lists */
+/*! operations on lists of property description lists */
PropDescription *prop_desc_lists_union(GList *plists);
PropDescription *prop_desc_lists_intersection(GList *plists);
/* ********************************************* */
-/* Functions for dealing with the Type Registry */
+/*! Functions for dealing with the Type Registry */
void prop_type_register(PropertyType type, const PropertyOps *ops);
const PropertyOps *prop_type_get_ops(PropertyType type);
@@ -382,11 +417,11 @@ const PropertyOps *prop_type_get_ops(PropertyType type);
void prop_list_free(GPtrArray *plist);
-/* copies the whole property structure, including the data. */
+/*! copies the whole property structure, including the data. */
GPtrArray *prop_list_copy(GPtrArray *plist);
-/* copies the whole property structure, excluding the data. */
+/*! copies the whole property structure, excluding the data. */
GPtrArray *prop_list_copy_empty(GPtrArray *plist);
-/* Appends copies of the properties in the second list to the first. */
+/*! Appends copies of the properties in the second list to the first. */
void prop_list_add_list (GPtrArray *props, const GPtrArray *ptoadd);
GPtrArray *prop_list_from_descs(const PropDescription *plist,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
