Synopsis

#include <adg-1/adg.h>

AdgPoint *          adg_point_new                       (void);
AdgPoint *          adg_point_dup                       (const AdgPoint *src);
void                adg_point_destroy                   (AdgPoint *point);
void                adg_point_copy                      (AdgPoint *point,
                                                         const AdgPoint *src);
void                adg_point_set_pair                  (AdgPoint *point,
                                                         const CpmlPair *pair);
void                adg_point_set_pair_explicit         (AdgPoint *point,
                                                         gdouble x,
                                                         gdouble y);
void                adg_point_set_pair_from_model       (AdgPoint *point,
                                                         AdgModel *model,
                                                         const gchar *name);
void                adg_point_invalidate                (AdgPoint *point);
void                adg_point_unset                     (AdgPoint *point);
gboolean            adg_point_update                    (AdgPoint *point);
CpmlPair *          adg_point_get_pair                  (AdgPoint *point);
AdgModel *          adg_point_get_model                 (const AdgPoint *point);
const gchar *       adg_point_get_name                  (const AdgPoint *point);
gboolean            adg_point_equal                     (const AdgPoint *point1,
                                                         const AdgPoint *point2);

Description

AdgPoint is an opaque structure that manages 2D coordinates, either set explicitely throught adg_point_set_pair() and adg_point_set_pair_explicit() or taken from a model with adg_point_set_pair_from_model(). It can be thought as an CpmlPair on steroid, because it adds named pair support to a simple pair, enabling coordinates depending on AdgModel.

Details

adg_point_new ()

AdgPoint *          adg_point_new                       (void);

Creates a new empty AdgPoint. The returned pointer should be freed with adg_point_destroy() when no longer needed.

Returns :

a newly created AdgPoint

Since 1.0


adg_point_dup ()

AdgPoint *          adg_point_dup                       (const AdgPoint *src);

Duplicates src. This operation also adds a new reference to the internal model if src is linked to a named pair.

The returned value should be freed with adg_point_destroy() when no longer needed.

src :

an AdgPoint

Returns :

the duplicated AdgPoint struct or NULL on errors

Since 1.0


adg_point_destroy ()

void                adg_point_destroy                   (AdgPoint *point);

Destroys the point instance, unreferencing the internal model if point is linked to a named pair.

point :

an AdgPoint

Since 1.0


adg_point_copy ()

void                adg_point_copy                      (AdgPoint *point,
                                                         const AdgPoint *src);

Copies src into point. If the old content of point was linked to the named pair of a model, the reference to that model is dropped. Similary, if src is a named pair, a new reference to the new model is added.

point :

an AdgPoint

src :

the source point to copy

Since 1.0


adg_point_set_pair ()

void                adg_point_set_pair                  (AdgPoint *point,
                                                         const CpmlPair *pair);

Sets an explicit pair in point by using the given pair. If point was linked to a named pair in a model, this link is dropped before setting the pair.

point :

an AdgPoint

pair :

the CpmlPair to use

Since 1.0


adg_point_set_pair_explicit ()

void                adg_point_set_pair_explicit         (AdgPoint *point,
                                                         gdouble x,
                                                         gdouble y);

Works in the same way of adg_point_set_pair() but accept direct numbers instead of an CpmlPair structure.

point :

an AdgPoint

x :

the x coordinate of the point

y :

the y coordinate of the point

Since 1.0


adg_point_set_pair_from_model ()

void                adg_point_set_pair_from_model       (AdgPoint *point,
                                                         AdgModel *model,
                                                         const gchar *name);

Links the name named pair of model to point, so any subsequent call to adg_point_get_pair() will return the named pair value. A new reference is added to model while the previous model (if any) is unreferenced.

point :

an AdgPoint

model :

the AdgModel

name :

the id of a named pair in model

Since 1.0


adg_point_invalidate ()

void                adg_point_invalidate                (AdgPoint *point);

Invalidates point, forcing a refresh of its internal CpmlPair if the point is linked to a named pair. If point is explicitely set, this function has no effect.

point :

an AdgPoint

Since 1.0


adg_point_unset ()

void                adg_point_unset                     (AdgPoint *point);

Unsets point by resetting the internal up_to_date flag and (eventually) unlinking it from the named pair it is bound to. After this call the content of point is undefined, so a subsequent call to adg_point_get_pair() will return NULL raising a warning.

point :

a pointer to an AdgPoint

Since 1.0


adg_point_update ()

gboolean            adg_point_update                    (AdgPoint *point);

Updates the internal CpmlPair of point. The internal implementation is protected against multiple calls so it can be called more times without harms.

point :

a pointer to an AdgPoint

Returns :

TRUE if point has been updated or FALSE on errors, i.e. when it is bound to a non-existent named pair.

Since 1.0


adg_point_get_pair ()

CpmlPair *          adg_point_get_pair                  (AdgPoint *point);

AdgPoint is an evolution of the pair concept but internally the relevant data is still stored in an CpmlPair struct. This function returns a copy of the internally owned pair.

Note

The CpmlPair is the first field of an AdgPoint struct so casting is allowed between them and, in fact, it is often more convenient than calling this function. Just remember to update the internal pair by using adg_point_update() before.

point :

an AdgPoint

Returns :

the pair of point or NULL if the named pair does not exist. [transfer full]

Since 1.0


adg_point_get_model ()

AdgModel *          adg_point_get_model                 (const AdgPoint *point);

Gets the source model of the named pair bound to point, or returns NULL if point is an explicit pair. The returned value is owned by point.

point :

an AdgPoint

Returns :

an AdgModel or NULL. [transfer none]

Since 1.0


adg_point_get_name ()

const gchar *       adg_point_get_name                  (const AdgPoint *point);

Gets the name of the named pair bound to point, or returns NULL if point is an explicit pair. The returned value is owned by point and should not be modified or freed.

point :

an AdgPoint

Returns :

the name of the named pair or NULL

Since 1.0


adg_point_equal ()

gboolean            adg_point_equal                     (const AdgPoint *point1,
                                                         const AdgPoint *point2);

Compares point1 and point2 and returns TRUE if the points are equals. The comparison is made by checking also the named pairs they are bound to. If you want to compare only their coordinates, use cpml_pair_equal() directly on the AdgPoint structs:

1
2
3
4
5
6
if (adg_point_update(point1) &&
    adg_point_update(point2) &&
    cpml_pair_equal((CpmlPair *) point1, (CpmlPair *) point2))
{
    ...
}

NULL points are handled gracefully.

point1 :

the first point to compare

point2 :

the second point to compare

Returns :

TRUE if point1 is equal to point2, FALSE otherwise

Since 1.0