Synopsis

#include <adg-1/adg.h>

struct              AdgPath;
struct              AdgPathClass;
AdgPath *           adg_path_new                        (void);
const CpmlPair *    adg_path_get_current_point          (AdgPath *path);
gboolean            adg_path_has_current_point          (AdgPath *path);
const CpmlPrimitive * adg_path_last_primitive           (AdgPath *path);
const CpmlPrimitive * adg_path_over_primitive           (AdgPath *path);
void                adg_path_append                     (AdgPath *path,
                                                         CpmlPrimitiveType type,
                                                         ...);
void                adg_path_append_valist              (AdgPath *path,
                                                         CpmlPrimitiveType type,
                                                         va_list var_args);
void                adg_path_append_array               (AdgPath *path,
                                                         CpmlPrimitiveType type,
                                                         const CpmlPair **pairs);
void                adg_path_append_primitive           (AdgPath *path,
                                                         const CpmlPrimitive *primitive);
void                adg_path_append_segment             (AdgPath *path,
                                                         const CpmlSegment *segment);
void                adg_path_append_cpml_path           (AdgPath *path,
                                                         const cairo_path_t *cairo_path);
void                adg_path_move_to                    (AdgPath *path,
                                                         const CpmlPair *pair);
void                adg_path_move_to_explicit           (AdgPath *path,
                                                         gdouble x,
                                                         gdouble y);
void                adg_path_line_to                    (AdgPath *path,
                                                         const CpmlPair *pair);
void                adg_path_line_to_explicit           (AdgPath *path,
                                                         gdouble x,
                                                         gdouble y);
void                adg_path_arc_to                     (AdgPath *path,
                                                         const CpmlPair *throught,
                                                         const CpmlPair *pair);
void                adg_path_arc_to_explicit            (AdgPath *path,
                                                         gdouble x1,
                                                         gdouble y1,
                                                         gdouble x2,
                                                         gdouble y2);
void                adg_path_curve_to                   (AdgPath *path,
                                                         const CpmlPair *control1,
                                                         const CpmlPair *control2,
                                                         const CpmlPair *pair);
void                adg_path_curve_to_explicit          (AdgPath *path,
                                                         gdouble x1,
                                                         gdouble y1,
                                                         gdouble x2,
                                                         gdouble y2,
                                                         gdouble x3,
                                                         gdouble y3);
void                adg_path_close                      (AdgPath *path);
void                adg_path_arc                        (AdgPath *path,
                                                         const CpmlPair *center,
                                                         gdouble r,
                                                         gdouble start,
                                                         gdouble end);
void                adg_path_arc_explicit               (AdgPath *path,
                                                         gdouble xc,
                                                         gdouble yc,
                                                         gdouble r,
                                                         gdouble start,
                                                         gdouble end);
void                adg_path_chamfer                    (AdgPath *path,
                                                         gdouble delta1,
                                                         gdouble delta2);
void                adg_path_fillet                     (AdgPath *path,
                                                         gdouble radius);
void                adg_path_reflect                    (AdgPath *path,
                                                         const CpmlVector *vector);
void                adg_path_reflect_explicit           (AdgPath *path,
                                                         gdouble x,
                                                         gdouble y);

Object Hierarchy

  GObject
   +----AdgModel
         +----AdgTrail
               +----AdgPath

Description

The AdgPath model represents a virtual cairo_path_t: this class implements methods to create the path and provides additional operations specific to technical drawings.

AdgPath overrides the get_cairo_path() method of the parent AdgTrail class, avoiding the need of an AdgTrailCallback. The path is constructed programmaticaly: keep in mind any method that modifies the path will invalidate the cairo_path_t returned by adg_trail_get_cairo_path().

Although some of the provided methods are clearly based on the original cairo path manipulation API, their behavior could be sligthly different. This is intentional, because the ADG provides additional path manipulation algorithms, sometime quite complex, and a more restrictive filter on the path quality is required. Also, the ADG is designed to be used by technicians while cairo targets a broader range of developers.

As an example, following the rule of the less surprise, some cairo functions guess the current point when it is not defined, while the AdgPath methods trigger a warning without other effect. Furthermore, after cairo_path_close_path() a CPML_MOVE primitive to the starting point of the segment is automatically added by cairo; in ADG, after an adg_path_close() the current point is unset.

Details

struct AdgPath

struct AdgPath;

All fields are private and should not be used directly. Use its public methods instead.

Since 1.0


struct AdgPathClass

struct AdgPathClass {
};

adg_path_new ()

AdgPath *           adg_path_new                        (void);

Creates a new path model. The path should be constructed programmatically by using the methods provided by AdgPath.

Returns :

the newly created path model

Since 1.0


adg_path_get_current_point ()

const CpmlPair *    adg_path_get_current_point          (AdgPath *path);

Gets the current point of path, which is conceptually the final point reached by the path so far.

If there is no defined current point, NULL is returned. It is possible to check this in advance with adg_path_has_current_point().

Most AdgPath methods alter the current point and most of them expect a current point to be defined otherwise will fail triggering a warning. Check the description of every method for specific details.

path :

an AdgPath

Returns :

the current point or NULL on no current point set or errors. [transfer none]

Since 1.0


adg_path_has_current_point ()

gboolean            adg_path_has_current_point          (AdgPath *path);

Returns whether a current point is defined on path. See adg_path_get_current_point() for details on the current point.

path :

an AdgPath

Returns :

whether a current point is defined

Since 1.0


adg_path_last_primitive ()

const CpmlPrimitive * adg_path_last_primitive           (AdgPath *path);

Gets the last primitive appended to path. The returned struct is owned by path and should not be freed or modified.

path :

an AdgPath

Returns :

a pointer to the last appended primitive or NULL on errors. [transfer none]

Since 1.0


adg_path_over_primitive ()

const CpmlPrimitive * adg_path_over_primitive           (AdgPath *path);

Gets the primitive before the last one appended to path. The "over" term comes from forth, where the OVER operator works on the stack in the same way as adg_path_over_primitive() works on path. The returned struct is owned by path and should not be freed or modified.

path :

an AdgPath

Returns :

a pointer to the primitive before the last appended one or NULL on errors. [transfer none]

Since 1.0


adg_path_append ()

void                adg_path_append                     (AdgPath *path,
                                                         CpmlPrimitiveType type,
                                                         ...);

Generic method to append a primitive to path. The number of CpmlPair pointers to pass as Varargs depends on type: CPML_CLOSE does not require any pair, CPML_MOVE and CPML_LINE require one pair, CPML_ARC two pairs, CPML_CURVE three pairs and so on.

All the needed pairs must be not NULL pointers, otherwise the function will fail. The pairs in excess, if any, will be ignored.

path :

an AdgPath

type :

a cairo_data_type_t value

... :

point data, specified as CpmlPair pointers

Since 1.0


adg_path_append_valist ()

void                adg_path_append_valist              (AdgPath *path,
                                                         CpmlPrimitiveType type,
                                                         va_list var_args);

va_list version of adg_path_append().

path :

an AdgPath

type :

a cairo_data_type_t value

var_args :

point data, specified as CpmlPair pointers

Since 1.0


adg_path_append_array ()

void                adg_path_append_array               (AdgPath *path,
                                                         CpmlPrimitiveType type,
                                                         const CpmlPair **pairs);

A bindingable version of adg_path_append() that uses a NULL terminated array of pairs instead of variable argument list and friends.

Furthermore, because of the list is NULL terminated, an arbitrary number of pairs can be passed in pairs. This allows to embed in a primitive element more data pairs than requested, something impossible to do with adg_path_append() and adg_path_append_valist().

Rename to: adg_path_append

path :

an AdgPath

type :

a cairo_data_type_t value

pairs :

point data, specified as a NULL terminated array of CpmlPair pointers. [array zero-terminated=1][element-type Cpml.Pair][transfer none]

Since 1.0


adg_path_append_primitive ()

void                adg_path_append_primitive           (AdgPath *path,
                                                         const CpmlPrimitive *primitive);

Appends primitive to path. The primitive to add is considered the continuation of the current path so the org component of primitive is not used. Anyway the current point is checked against it: they must be equal or the function will fail without further processing.

path :

an AdgPath

primitive :

the CpmlPrimitive to append

Since 1.0


adg_path_append_segment ()

void                adg_path_append_segment             (AdgPath *path,
                                                         const CpmlSegment *segment);

Appends segment to path.

path :

an AdgPath

segment :

the CpmlSegment to append

Since 1.0


adg_path_append_cpml_path ()

void                adg_path_append_cpml_path           (AdgPath *path,
                                                         const cairo_path_t *cairo_path);

adg_path_move_to ()

void                adg_path_move_to                    (AdgPath *path,
                                                         const CpmlPair *pair);

Begins a new segment. After this call the current point will be pair.

path :

an AdgPath

pair :

the destination coordinates

Since 1.0


adg_path_move_to_explicit ()

void                adg_path_move_to_explicit           (AdgPath *path,
                                                         gdouble x,
                                                         gdouble y);

Convenient function to call adg_path_move_to() using explicit coordinates instead of CpmlPair.

path :

an AdgPath

x :

the new x coordinate

y :

the new y coordinate

Since 1.0


adg_path_line_to ()

void                adg_path_line_to                    (AdgPath *path,
                                                         const CpmlPair *pair);

Adds a line to path from the current point to pair. After this call the current point will be pair.

If path has no current point before this call, this function will trigger a warning without other effect.

path :

an AdgPath

pair :

the destination coordinates

Since 1.0


adg_path_line_to_explicit ()

void                adg_path_line_to_explicit           (AdgPath *path,
                                                         gdouble x,
                                                         gdouble y);

Convenient function to call adg_path_line_to() using explicit coordinates instead of CpmlPair.

path :

an AdgPath

x :

the new x coordinate

y :

the new y coordinate

Since 1.0


adg_path_arc_to ()

void                adg_path_arc_to                     (AdgPath *path,
                                                         const CpmlPair *throught,
                                                         const CpmlPair *pair);

Adds an arc to the path from the current point to pair, passing throught throught. After this call the current point will be pair.

If path has no current point before this call, this function will trigger a warning without other effect.

path :

an AdgPath

throught :

an arbitrary point on the arc

pair :

the destination coordinates

Since 1.0


adg_path_arc_to_explicit ()

void                adg_path_arc_to_explicit            (AdgPath *path,
                                                         gdouble x1,
                                                         gdouble y1,
                                                         gdouble x2,
                                                         gdouble y2);

Convenient function to call adg_path_arc_to() using explicit coordinates instead of CpmlPair.

path :

an AdgPath

x1 :

the x coordinate of an intermediate point

y1 :

the y coordinate of an intermediate point

x2 :

the x coordinate of the end of the arc

y2 :

the y coordinate of the end of the arc

Since 1.0


adg_path_curve_to ()

void                adg_path_curve_to                   (AdgPath *path,
                                                         const CpmlPair *control1,
                                                         const CpmlPair *control2,
                                                         const CpmlPair *pair);

Adds a cubic Bézier curve to the path from the current point to position pair, using control1 and control2 as control points. After this call the current point will be pair.

If path has no current point before this call, this function will trigger a warning without other effect.

path :

an AdgPath

control1 :

the first control point of the curve

control2 :

the second control point of the curve

pair :

the destination coordinates

Since 1.0


adg_path_curve_to_explicit ()

void                adg_path_curve_to_explicit          (AdgPath *path,
                                                         gdouble x1,
                                                         gdouble y1,
                                                         gdouble x2,
                                                         gdouble y2,
                                                         gdouble x3,
                                                         gdouble y3);

Convenient function to call adg_path_curve_to() using explicit coordinates instead of CpmlPair.

path :

an AdgPath

x1 :

the x coordinate of the first control point

y1 :

the y coordinate of the first control point

x2 :

the x coordinate of the second control point

y2 :

the y coordinate of the second control point

x3 :

the x coordinate of the end of the curve

y3 :

the y coordinate of the end of the curve

Since 1.0


adg_path_close ()

void                adg_path_close                      (AdgPath *path);

Adds a line segment to the path from the current point to the beginning of the current segment, (the most recent point passed to an adg_path_move_to()), and closes this segment. After this call the current point will be unset.

The behavior of adg_path_close() is distinct from simply calling adg_line_to() with the coordinates of the segment starting point. When a closed segment is stroked, there are no caps on the ends. Instead, there is a line join connecting the final and initial primitive of the segment.

If path has no current point before this call, this function will trigger a warning without other effect.

path :

an AdgPath

Since 1.0


adg_path_arc ()

void                adg_path_arc                        (AdgPath *path,
                                                         const CpmlPair *center,
                                                         gdouble r,
                                                         gdouble start,
                                                         gdouble end);

A more usual way to add an arc to path. After this call, the current point will be the computed end point of the arc. The arc will be rendered in increasing angle, accordling to start and end. This means if start is less than end, the arc will be rendered in clockwise direction (accordling to the default cairo coordinate system) while if start is greather than end, the arc will be rendered in couterclockwise direction.

By explicitely setting the whole arc data, the start point could be different from the current point. In this case, if path has no current point before the call a CPML_MOVE to the start point of the arc will be automatically prepended to the arc. If path has a current point, a CPML_LINE to the start point of the arc will be used instead of the "move to" primitive.

path :

an AdgPath

center :

coordinates of the center of the arc

r :

the radius of the arc

start :

the start angle, in radians

end :

the end angle, in radians

Since 1.0


adg_path_arc_explicit ()

void                adg_path_arc_explicit               (AdgPath *path,
                                                         gdouble xc,
                                                         gdouble yc,
                                                         gdouble r,
                                                         gdouble start,
                                                         gdouble end);

Convenient function to call adg_path_arc() using explicit coordinates instead of CpmlPair.

path :

an AdgPath

xc :

x position of the center of the arc

yc :

y position of the center of the arc

r :

the radius of the arc

start :

the start angle, in radians

end :

the end angle, in radians

Since 1.0


adg_path_chamfer ()

void                adg_path_chamfer                    (AdgPath *path,
                                                         gdouble delta1,
                                                         gdouble delta2);

A binary action that generates a chamfer between two primitives. The first primitive involved is the current primitive, the second will be the next primitive appended to path after this call. The second primitive is required: if the chamfer operation is not properly terminated (by not providing the second primitive), any API accessing the path in reading mode will raise a warning.

An exception is a chamfer after a CPML_CLOSE primitive. In this case, the second primitive is not required: the current close path is used as first operand while the first primitive of the current segment is used as second operand.

The chamfer operation requires two lengths: delta1 specifies the "quantity" to trim on the first primitive while delta2 is the same applied on the second primitive. The term "quantity" means the length of the portion to cut out from the original primitive (that is the primitive as would be without the chamfer).

path :

an AdgPath

delta1 :

the distance from the intersection point of the current primitive

delta2 :

the distance from the intersection point of the next primitive

Since 1.0


adg_path_fillet ()

void                adg_path_fillet                     (AdgPath *path,
                                                         gdouble radius);

A binary action that joins to primitives with an arc. The first primitive involved is the current primitive, the second will be the next primitive appended to path after this call. The second primitive is required: if the fillet operation is not properly terminated (by not providing the second primitive), any API accessing the path in reading mode will raise a warning.

An exception is a fillet after a CPML_CLOSE primitive. In this case, the second primitive is not required: the current close path is used as first operand while the first primitive of the current segment is used as second operand.

path :

an AdgPath

radius :

the radius of the fillet

Since 1.0


adg_path_reflect ()

void                adg_path_reflect                    (AdgPath *path,
                                                         const CpmlVector *vector);

Reflects the first segment or path around the axis passing throught (0, 0) and with a vector slope. The internal segment is duplicated and the proper transformation (computed from vector) to mirror the segment is applied on all its points. The result is then reversed with cpml_segment_reverse() and appended to the original path with adg_path_append_segment().

For convenience, if vector is NULL the path is reversed around the x axis (y=0).

path :

an AdgPath

vector :

the slope of the axis. [allow-none]

Since 1.0


adg_path_reflect_explicit ()

void                adg_path_reflect_explicit           (AdgPath *path,
                                                         gdouble x,
                                                         gdouble y);

Convenient function to call adg_path_reflect() using explicit vector components instead of CpmlVector.

path :

an AdgPath

x :

the vector x component

y :

the vector y component

Since 1.0