![]() |
![]() |
![]() |
adg-1 reference manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#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
);
"add-dependency" :Run First
"changed" :No Recursion
"clear" :No Recursion
"remove-dependency" :Run First
"reset" :No Recursion
"set-named-pair" :Run First
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.
void (*AdgDependencyFunc) (AdgModel *model
,AdgEntity *entity
,gpointer user_data
);
Callback used by adg_model_foreach_dependency()
.
|
the AdgModel |
|
the AdgEntity dependent on model
|
|
a general purpose pointer |
Since 1.0
void (*AdgNamedPairFunc) (AdgModel *model
,const gchar *name
,CpmlPair *pair
,gpointer user_data
);
Callback used by adg_model_foreach_named_pair()
.
|
the AdgModel |
|
the name of the named pair |
|
an CpmlPair |
|
a general purpose pointer |
Since 1.0
struct AdgModel;
All fields are private and should not be used directly. Use its public methods instead.
Since 1.0
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()
.
virtual method that returns the CpmlPair bound to a given name. | |
signal for defining or undefining a new named pair. | |
signal for removing the internal cache data, if any. | |
signal used to redefine a model from scratch. | |
signal for adding a new dependency. | |
signal used to remove an old dependency. | |
signal for emitting an "changed" signal. |
Since 1.0
void adg_model_add_dependency (AdgModel *model
,AdgEntity *entity
);
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
.
Since 1.0
void adg_model_remove_dependency (AdgModel *model
,AdgEntity *entity
);
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.
Since 1.0
const GSList * adg_model_get_dependencies (AdgModel *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
void adg_model_foreach_dependency (AdgModel *model
,AdgDependencyFunc callback
,gpointer user_data
);
Invokes callback
on each entity linked to model
.
|
an AdgModel |
|
the entity callback. [scope call] |
|
general purpose user data passed "as is" to callback
|
Since 1.0
void adg_model_set_named_pair (AdgModel *model
,const gchar *name
,const CpmlPair *pair
);
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.
Since 1.0
void adg_model_set_named_pair_explicit (AdgModel *model
,const gchar *name
,gdouble x
,gdouble y
);
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.
|
an AdgModel |
|
the name to associate to the pair |
|
the x coordinate of the point |
|
the y coordinate of the point |
Since 1.0
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.
|
an AdgModel |
|
the name of the pair to get |
Returns : |
the requested CpmlPair or NULL if not found |
Since 1.0
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.
|
an AdgModel |
|
the named pair callback. [scope call] |
|
general purpose user data passed "as is" to callback
|
Since 1.0
void adg_model_clear (AdgModel *model
);
This function is only useful new model implementations.
Emits the "clear" signal on model
.
|
an AdgModel |
Since 1.0
void adg_model_reset (AdgModel *model
);
Emits the "reset" signal on model
.
|
an AdgModel |
Since 1.0
"dependency"
property"dependency" AdgEntity* : Write
Can be used to add a new dependency from this model (this entity will be invalidated on model changed).
"add-dependency"
signalvoid 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
.
|
an AdgModel |
|
an AdgEntity that depends on model
|
|
user data set when the signal handler was connected. |
Since 1.0
"changed"
signalvoid user_function (AdgModel *model,
gpointer user_data) : No Recursion
Notificates that the model has changed. By default, all the dependent entities are invalidated.
|
an AdgModel |
|
user data set when the signal handler was connected. |
Since 1.0
"clear"
signalvoid user_function (AdgModel *model,
gpointer user_data) : No Recursion
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.
|
an AdgModel |
|
user data set when the signal handler was connected. |
Since 1.0
"remove-dependency"
signalvoid 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.
|
an AdgModel |
|
the AdgEntity that does not depend on model anymore |
|
user data set when the signal handler was connected. |
Since 1.0
"reset"
signalvoid 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); |
|
an AdgModel |
|
user data set when the signal handler was connected. |
Since 1.0
"set-named-pair"
signalvoid 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
.
|
an AdgModel |
|
an arbitrary name |
|
an CpmlPair |
|
user data set when the signal handler was connected. |
Since 1.0