AdgTrail

AdgTrailCallback ()

CpmlPath *          (*AdgTrailCallback)                 (AdgTrail *trail,
                                                         gpointer user_data);

This is the callback used to generate the CpmlPath and it is called directly by adg_trail_cpml_path(). The caller owns the returned path, that is the finalization of the returned CpmlPath should be made by the caller when appropriate.

AdgTrail

typedef struct _AdgTrail AdgTrail;

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

adg_trail_new ()

AdgTrail *          adg_trail_new                       (AdgTrailCallback callback,
                                                         gpointer user_data);

Creates a new trail model. The CpmlPath must be constructed by the callback function: AdgTrail will not cache anything, so you should implement any caching mechanism in the callback, if needed.

adg_trail_get_cairo_path ()

const cairo_path_t * adg_trail_get_cairo_path           (AdgTrail *trail);

Gets a pointer to the cairo path of trail. The return path is owned by trail and must be considered read-only.

This function gets the CpmlPath of trail by calling adg_trail_cpml_path() and converts its CPML_ARC primitives, not recognized by cairo, into approximated Bézier curves primitives (CPML_CURVE). The conversion is cached, so any further request is O(1). This cache is cleared only by the adg_model_clear() method.

adg_trail_cpml_path ()

CpmlPath *          adg_trail_cpml_path                 (AdgTrail *trail);

Gets the CPML path structure defined by trail. The returned value is managed by the AdgTrail implementation, that is this function directly calls the AdgTrailClass::get_cpml_path() virtual method that any trail instance must have.

Whenever used internally by the ADG project, the returned path is (by convention) owned by trail and so it should not be freed. Anyway, callers are allowed to modify it as long as its size is retained and its data contains a valid path: this is needed to let the AdgMarker infrastructure work properly (the markers should be able to modify the trail where they are applied).

Any further call to this method will probably make the pointer previously returned useless because the CpmlPath could be relocated and the old CpmlPath will likely contain rubbish.

adg_trail_put_segment ()

gboolean            adg_trail_put_segment               (AdgTrail *trail,
                                                         guint n_segment,
                                                         AdgSegment *segment);

Convenient function to get a segment from trail. The segment is got from the CPML path: check out adg_trail_cpml_path() for further information.

When the segment is not found, either because n_segment is out of range or because there is still no path bound to trail, this function will return FALSE leaving segment untouched. If the segment is found and segment is not NULL, the resulting segment is copied in segment.

adg_trail_get_extents ()

const CpmlExtents * adg_trail_get_extents               (AdgTrail *trail);

Gets the extents of trail. The returned pointer is owned by trail and should not be freed nor modified.

adg_trail_dump ()

void                adg_trail_dump                      (AdgTrail *trail);

Dumps the data content of trail to stdout in a human readable format.