Synopsis

#include <adg-1/adg.h>

void                (*AdgDependencyFunc)                (AdgModel *model,
                                                         AdgEntity *entity,
                                                         gpointer user_data);
void                (*AdgNamedPairFunc)                 (AdgModel *model,
                                                         const gchar *name,
                                                         CpmlPair *pair,
                                                         gpointer user_data);
struct              AdgModel;
struct              AdgModelClass;
void                adg_model_add_dependency            (AdgModel *model,
                                                         AdgEntity *entity);
void                adg_model_remove_dependency         (AdgModel *model,
                                                         AdgEntity *entity);
const GSList *      adg_model_get_dependencies          (AdgModel *model);
void                adg_model_foreach_dependency        (AdgModel *model,
                                                         AdgDependencyFunc callback,
                                                         gpointer user_data);
void                adg_model_set_named_pair            (AdgModel *model,
                                                         const gchar *name,
                                                         const CpmlPair *pair);
void                adg_model_set_named_pair_explicit   (AdgModel *model,
                                                         const gchar *name,
                                                         gdouble x,
                                                         gdouble y);
const CpmlPair *    adg_model_get_named_pair            (AdgModel *model,
                                                         const gchar *name);
void                adg_model_foreach_named_pair        (AdgModel *model,
                                                         AdgNamedPairFunc callback,
                                                         gpointer user_data);
void                adg_model_clear                     (AdgModel *model);
void                adg_model_reset                     (AdgModel *model);
void                adg_model_changed                   (AdgModel *model);

Object Hierarchy

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

Properties

  "dependency"               AdgEntity*            : Write

Signals

  "add-dependency"                                 : Run First
  "changed"                                        : No Recursion
  "clear"                                          : No Recursion
  "remove-dependency"                              : Run First
  "reset"                                          : No Recursion
  "set-named-pair"                                 : Run First

Description

A model is a conceptual representation of something. From an ADG user point of view, it is a collection of data and rules that defines how an object should be represented on a drawing.

Because AdgModel instances are only a conceptual idea, they are not renderable (that is, AdgModel is not derived from AdgEntity). Instead, it must be passed as subject to entities such as AdgStroke or AdgHatch.

The relationships between model and view are handled by dependencies: whenever an AdgModel changes (that is the "changed" signal is emitted), every dependency of the model (AdgEntity instances) is invalidated with adg_entity_invalidate().

To help the interaction between model and view another concept is introduced: named pairs. This provides a way to abstract real values (the coordinates stored in CpmlPair) by accessing them using a string. To easily the access of named pairs from the view, use AdgPoint instead of CpmlPair.

Details

AdgDependencyFunc ()

void                (*AdgDependencyFunc)                (AdgModel *model,
                                                         AdgEntity *entity,
                                                         gpointer user_data);

Callback used by adg_model_foreach_dependency().

model :

the AdgModel

entity :

the AdgEntity dependent on model

user_data :

a general purpose pointer

Since 1.0


AdgNamedPairFunc ()

void                (*AdgNamedPairFunc)                 (AdgModel *model,
                                                         const gchar *name,
                                                         CpmlPair *pair,
                                                         gpointer user_data);

Callback used by adg_model_foreach_named_pair().

model :

the AdgModel

name :

the name of the named pair

pair :

an CpmlPair

user_data :

a general purpose pointer

Since 1.0


struct AdgModel

struct AdgModel;

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

Since 1.0


struct AdgModelClass

struct AdgModelClass {
    /* Virtual table */
    const CpmlPair *    (*named_pair)           (AdgModel         *model,
                                                 const gchar      *name);

    /* Signals */
    void                (*set_named_pair)       (AdgModel         *model,
                                                 const gchar      *name,
                                                 const CpmlPair   *pair);
    void                (*clear)                (AdgModel         *model);
    void                (*reset)                (AdgModel         *model);
    void                (*add_dependency)       (AdgModel         *model,
                                                 AdgEntity        *entity);
    void                (*remove_dependency)    (AdgModel         *model,
                                                 AdgEntity        *entity);
    void                (*changed)              (AdgModel         *model);
};

The default named_pair implementation looks up the CpmlPair in an internal GHashTable that uses the pair name as key and the CpmlPair struct as value.

The default set_named_pair implementation can be used for either adding (if the CpmlPair is not NULL) or removing (if CpmlPair is NULL) an item from the named pairs hash table.

The default handler for clear signals does not do anything.

The default reset involves the clearing of the internal cache data (done by emitting the "clear" signal) and the destruction of the internal named pair hash table.

The default add_dependency and remove_dependency implementations add and remove items from an internal GSList of AdgEntity.

The default handler of the changed signal calls adg_entity_invalidate() on every dependency by using adg_model_foreach_dependency().

named_pair ()

virtual method that returns the CpmlPair bound to a given name.

set_named_pair ()

signal for defining or undefining a new named pair.

clear ()

signal for removing the internal cache data, if any.

reset ()

signal used to redefine a model from scratch.

add_dependency ()

signal for adding a new dependency.

remove_dependency ()

signal used to remove an old dependency.

changed ()

signal for emitting an "changed" signal.

Since 1.0


adg_model_add_dependency ()

void                adg_model_add_dependency            (AdgModel *model,
                                                         AdgEntity *entity);

Note

This function is only useful in entity implementations.

Emits a "add-dependency" signal on model passing entity as argument. This will add a reference to entity owned by model.

model :

an AdgModel

entity :

an AdgEntity

Since 1.0


adg_model_remove_dependency ()

void                adg_model_remove_dependency         (AdgModel *model,
                                                         AdgEntity *entity);

Note

This function is only useful in entity implementations.

Emits a "remove-dependency" signal on model passing entity as argument. entity must be inside model.

Note that model will own a reference to entity and it may be the last reference held: this means removing an entity from the model can destroy it.

model :

an AdgModel

entity :

an AdgEntity

Since 1.0


adg_model_get_dependencies ()

const GSList *      adg_model_get_dependencies          (AdgModel *model);

model :

an AdgModel . Gets the list of entities dependending on model. This list is owned by model and must not be modified or freed.

Returns :

a GSList of dependencies or NULL on error. [transfer none][element-type Adg.Entity]

Since 1.0


adg_model_foreach_dependency ()

void                adg_model_foreach_dependency        (AdgModel *model,
                                                         AdgDependencyFunc callback,
                                                         gpointer user_data);

Invokes callback on each entity linked to model.

model :

an AdgModel

callback :

the entity callback. [scope call]

user_data :

general purpose user data passed "as is" to callback

Since 1.0


adg_model_set_named_pair ()

void                adg_model_set_named_pair            (AdgModel *model,
                                                         const gchar *name,
                                                         const CpmlPair *pair);

Note

This function is only useful in model definitions, such as inside an AdgTrailCallback function or while constructing an AdgPath instance.

Emits a "set-named-pair" signal on model passing name and pair as arguments.

model :

an AdgModel

name :

the name to associate to the pair

pair :

the CpmlPair

Since 1.0


adg_model_set_named_pair_explicit ()

void                adg_model_set_named_pair_explicit   (AdgModel *model,
                                                         const gchar *name,
                                                         gdouble x,
                                                         gdouble y);

Note

This function is only useful in model definitions, such as inside an AdgTrailCallback function or while constructing an AdgPath instance.

Convenient wrapper on adg_model_set_named_pair() that accepts explicit coordinates.

model :

an AdgModel

name :

the name to associate to the pair

x :

the x coordinate of the point

y :

the y coordinate of the point

Since 1.0


adg_model_get_named_pair ()

const CpmlPair *    adg_model_get_named_pair            (AdgModel *model,
                                                         const gchar *name);

Gets the name named pair associated to model. The returned pair is owned by model and must not be modified or freed.

model :

an AdgModel

name :

the name of the pair to get

Returns :

the requested CpmlPair or NULL if not found

Since 1.0


adg_model_foreach_named_pair ()

void                adg_model_foreach_named_pair        (AdgModel *model,
                                                         AdgNamedPairFunc callback,
                                                         gpointer user_data);

Invokes callback for each named pair set on model. This can be used, for example, to retrieve all the named pairs of a model or to duplicate a transformed version of every named pair.

model :

an AdgModel

callback :

the named pair callback. [scope call]

user_data :

general purpose user data passed "as is" to callback

Since 1.0


adg_model_clear ()

void                adg_model_clear                     (AdgModel *model);

Note

This function is only useful new model implementations.

Emits the "clear" signal on model.

model :

an AdgModel

Since 1.0


adg_model_reset ()

void                adg_model_reset                     (AdgModel *model);

Emits the "reset" signal on model.

model :

an AdgModel

Since 1.0


adg_model_changed ()

void                adg_model_changed                   (AdgModel *model);

Note

This function is only useful in entity implementations.

Emits the "changed" signal on model.

model :

an AdgModel

Since 1.0

Property Details

The "dependency" property

  "dependency"               AdgEntity*            : Write

Can be used to add a new dependency from this model (this entity will be invalidated on model changed).

Signal Details

The "add-dependency" signal

void                user_function                      (AdgModel  *model,
                                                        AdgEntity *entity,
                                                        gpointer   user_data)      : Run First

Adds entity to model. After that entity will depend on model, that is "changed" on model will invalidate entity.

model :

an AdgModel

entity :

an AdgEntity that depends on model

user_data :

user data set when the signal handler was connected.

Since 1.0


The "changed" signal

void                user_function                      (AdgModel *model,
                                                        gpointer  user_data)      : No Recursion

Notificates that the model has changed. By default, all the dependent entities are invalidated.

model :

an AdgModel

user_data :

user data set when the signal handler was connected.

Since 1.0


The "clear" signal

void                user_function                      (AdgModel *model,
                                                        gpointer  user_data)      : No Recursion

Note

This signal is only useful in model implementations.

Removes any information from model cached by the implementation code. Useful to force a recomputation of the cache when something in the model has changed.

model :

an AdgModel

user_data :

user data set when the signal handler was connected.

Since 1.0


The "remove-dependency" signal

void                user_function                      (AdgModel  *model,
                                                        AdgEntity *entity,
                                                        gpointer   user_data)      : Run First

Removes the entity from model, that is entity will not depend on model anymore.

model :

an AdgModel

entity :

the AdgEntity that does not depend on model anymore

user_data :

user data set when the signal handler was connected.

Since 1.0


The "reset" signal

void                user_function                      (AdgModel *model,
                                                        gpointer  user_data)      : No Recursion

Resets the state of model by destroying any named pair associated to it. This step also involves the emission of the "clear" signal.

This signal is intended to be used while redefining the model. A typical usage would be in these terms:

1
2
3
4
5
adg_model_reset(model);
// Definition of model. This also requires the redefinition of
// the named pairs because the old ones have been destroyed.
...
adg_model_changed(model);

model :

an AdgModel

user_data :

user data set when the signal handler was connected.

Since 1.0


The "set-named-pair" signal

void                user_function                      (AdgModel *model,
                                                        gchar    *name,
                                                        gpointer  pair,
                                                        gpointer  user_data)      : Run First

Adds, updates or deletes a named pair, accordling to the given parameters.

If pair is NULL, the name named pair is searched and deleted. If it is not found, a warning is raised.

Otherwise, the name named pair is searched: if it is found, its data are updated with pair. If it is not found, a new named pair is created using name and pair.

model :

an AdgModel

name :

an arbitrary name

pair :

an CpmlPair

user_data :

user data set when the signal handler was connected.

Since 1.0