![]() |
![]() |
![]() |
adg-1 reference manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#include <adg-1/adg.h> struct AdgEntity; struct AdgEntityClass; void adg_switch_extents (gboolean state
); void adg_entity_destroy (AdgEntity *entity
); AdgCanvas * adg_entity_get_canvas (AdgEntity *entity
); void adg_entity_set_parent (AdgEntity *entity
,AdgEntity *parent
); AdgEntity * adg_entity_get_parent (AdgEntity *entity
); void adg_entity_set_global_map (AdgEntity *entity
,const cairo_matrix_t *map
); void adg_entity_transform_global_map (AdgEntity *entity
,const cairo_matrix_t *transformation
,AdgTransformMode mode
); const cairo_matrix_t * adg_entity_get_global_map (AdgEntity *entity
); const cairo_matrix_t * adg_entity_get_global_matrix (AdgEntity *entity
); void adg_entity_set_local_map (AdgEntity *entity
,const cairo_matrix_t *map
); void adg_entity_transform_local_map (AdgEntity *entity
,const cairo_matrix_t *transformation
,AdgTransformMode mode
); const cairo_matrix_t * adg_entity_get_local_map (AdgEntity *entity
); const cairo_matrix_t * adg_entity_get_local_matrix (AdgEntity *entity
); void adg_entity_set_local_mix (AdgEntity *entity
,AdgMix local_mix
); AdgMix adg_entity_get_local_mix (AdgEntity *entity
); void adg_entity_set_extents (AdgEntity *entity
,const CpmlExtents *extents
); const CpmlExtents * adg_entity_get_extents (AdgEntity *entity
); void adg_entity_set_style (AdgEntity *entity
,AdgDress dress
,AdgStyle *style
); AdgStyle * adg_entity_get_style (AdgEntity *entity
,AdgDress dress
); AdgStyle * adg_entity_style (AdgEntity *entity
,AdgDress dress
); void adg_entity_apply_dress (AdgEntity *entity
,AdgDress dress
,cairo_t *cr
); void adg_entity_global_changed (AdgEntity *entity
); void adg_entity_local_changed (AdgEntity *entity
); void adg_entity_invalidate (AdgEntity *entity
); void adg_entity_arrange (AdgEntity *entity
); void adg_entity_render (AdgEntity *entity
,cairo_t *cr
); AdgPoint * adg_entity_point (AdgEntity *entity
,AdgPoint *point
,const AdgPoint *new_point
);
GObject +----GInitiallyUnowned +----AdgEntity +----AdgDim +----AdgContainer +----AdgMarker +----AdgStroke +----AdgLogo +----AdgProjection +----AdgTable +----AdgText +----AdgToyText
"global-map" CairoMatrix* : Read / Write "local-map" CairoMatrix* : Read / Write "local-mix" AdgMix : Read / Write "parent" AdgEntity* : Read / Write
"arrange" :Run Last
"destroy" :Run First
"global-changed" :Run First
"invalidate" :Run Last
"local-changed" :Run First
"parent-set" :Run First
"render" :Run Last
This abstract class provides the base for all renderable objects.
To provide a proper AdgEntity derived type, you must at least
implement its arrange()
and render()
virtual methods. Also, if
you are using some sort of caching, ensure to clear it in the
invalidate()
method.
struct AdgEntity;
All fields are private and should not be used directly. Use its public methods instead.
Since 1.0
struct AdgEntityClass { /* Signals */ void (*destroy) (AdgEntity *entity); void (*parent_set) (AdgEntity *entity, AdgEntity *old_parent); void (*global_changed) (AdgEntity *entity); void (*local_changed) (AdgEntity *entity); void (*invalidate) (AdgEntity *entity); void (*arrange) (AdgEntity *entity); void (*render) (AdgEntity *entity, cairo_t *cr); };
Any entity (if not abstract) must implement at least the render
method.
The other signal handlers can be overriden to provide custom behaviors
and usually must chain up the original handler.
when a destroy request has been explicitely requested | |
called whenever the parent of an entity has changed | |
the global matrix has been invalidated | |
the local matrix has been invalidated | |
invalidating callback, used to clear the internal cache | |
prepare the layout and fill the extents struct | |
rendering callback, it must be implemented by every entity |
Since 1.0
void adg_switch_extents (gboolean state
);
Strokes (if state
is TRUE
) a rectangle around every entity to
show their extents. Useful for debugging purposes.
|
new extents state |
Since 1.0
void adg_entity_destroy (AdgEntity *entity
);
Emits the "destroy" signal on entity
and on all of
its children, if any.
|
an AdgEntity |
Since 1.0
AdgCanvas * adg_entity_get_canvas (AdgEntity *entity
);
Walks on the entity
hierarchy and gets the first parent of entity
,
that is the first AdgCanvas instance. The returned object is
owned by entity
and should not be freed or modified.
|
an AdgEntity |
Returns : |
the requested canvas or NULL on errors
or if there is no AdgCanvas in the
entity hierarchy. [transfer none]
|
Since 1.0
void adg_entity_set_parent (AdgEntity *entity
,AdgEntity *parent
);
This function is only useful in entity implementations.
Sets a new parent on entity
.
|
an AdgEntity |
|
the parent entity |
Since 1.0
AdgEntity * adg_entity_get_parent (AdgEntity *entity
);
Gets the parent of entity
. The returned object is owned
by entity
and should not be freed or modified.
|
an AdgEntity |
Returns : |
the parent entity or NULL on errors
or if entity is a toplevel. [transfer none]
|
Since 1.0
void adg_entity_set_global_map (AdgEntity *entity
,const cairo_matrix_t *map
);
Sets the new global transformation of entity
to map
:
the old map is discarded. If map
is NULL
, the global
map is left unchanged.
|
an AdgEntity object |
|
the new map |
Since 1.0
void adg_entity_transform_global_map (AdgEntity *entity
,const cairo_matrix_t *transformation
,AdgTransformMode mode
);
Convenient function to change the global map of entity
by
applying tranformation
using the mode
operator. This is
logically equivalent to the following:
1 2 3 4 |
cairo_matrix_t map; adg_matrix_copy(&map, adg_entity_get_global_map(entity)); adg_matrix_transform(&map, transformation, mode); adg_entity_set_global_map(entity, &map); |
|
an AdgEntity object |
|
the transformation to apply |
|
how transformation should be applied |
Since 1.0
const cairo_matrix_t * adg_entity_get_global_map (AdgEntity *entity
);
Gets the transformation to be used to compute the global matrix
of entity
.
|
an AdgEntity object |
Returns : |
the requested map or NULL on errors |
Since 1.0
const cairo_matrix_t * adg_entity_get_global_matrix (AdgEntity *entity
);
Gets the current global matrix of entity
. The returned value
is owned by entity
and should not be changed or freed.
The global matrix is computed in the arrange()
phase by
combining all the global maps of the entity
hierarchy using
the ADG_MIX_ANCESTORS
method.
|
an AdgEntity object |
Returns : |
the global matrix or NULL on errors |
Since 1.0
void adg_entity_set_local_map (AdgEntity *entity
,const cairo_matrix_t *map
);
Sets the new local transformation of entity
to map
:
the old map is discarded. If map
is NULL
, the local
map is left unchanged.
|
an AdgEntity object |
|
the new map |
Since 1.0
void adg_entity_transform_local_map (AdgEntity *entity
,const cairo_matrix_t *transformation
,AdgTransformMode mode
);
Convenient function to change the local map of entity
by
applying tranformation
using the mode
operator. This is
logically equivalent to the following:
1 2 3 4 |
cairo_matrix_t map; adg_matrix_copy(&map, adg_entity_get_local_map(entity)); adg_matrix_transform(&map, transformation, mode); adg_entity_set_local_map(entity, &map); |
|
an AdgEntity object |
|
the transformation to apply |
|
how transformation should be applied |
Since 1.0
const cairo_matrix_t * adg_entity_get_local_map (AdgEntity *entity
);
Gets the transformation to be used to compute the local matrix
of entity
and store it in map
.
|
an AdgEntity object |
Returns : |
the requested map or NULL on errors |
Since 1.0
const cairo_matrix_t * adg_entity_get_local_matrix (AdgEntity *entity
);
Gets the current local matrix of entity
. The returned value
is owned by entity
and should not be changed or freed.
The local matrix is computed in the arrange()
phase by
combining all the local maps of the entity
hierarchy using
the method specified by the "local-mix" property.
|
an AdgEntity object |
Returns : |
the local matrix or NULL on errors |
Since 1.0
void adg_entity_set_local_mix (AdgEntity *entity
,AdgMix local_mix
);
Sets a new local mix method on entity
. The
"local-mix" property defines how the local
matrix must be computed: check out the AdgMix
documentation to know what are the availables methods
and how they affect the local matrix computation.
Setting a different local mix method emits an
"local-changed" signal on entity
.
|
an AdgEntity object |
|
new mix method |
Since 1.0
AdgMix adg_entity_get_local_mix (AdgEntity *entity
);
Gets the local mix method of entity
. Check out the
adg_entity_set_local_mix()
documentation to know what the
local mix method is used for.
|
an AdgEntity object |
Returns : |
the local mix method of entity or ADG_MIX_UNDEFINED on errors |
Since 1.0
void adg_entity_set_extents (AdgEntity *entity
,const CpmlExtents *extents
);
This function is only useful in entity implementations.
Sets a new bounding box for entity
. extents
can be NULL
,
in which case the extents are unset.
|
an AdgEntity |
|
the new extents |
Since 1.0
const CpmlExtents * adg_entity_get_extents (AdgEntity *entity
);
Gets the bounding box of entity
. The returned struct is
owned by entity
and should not modified or freed.
This struct specifies the surface portion (in global space
of entity
) occupied by the entity without taking into
account rendering properties such as line thickness or caps.
The "arrange" signal should be emitted before
this call (either explicitely trought adg_entity_arrange()
or implicitely with adg_entity_render()
) in order to get
an up to date boundary box.
|
an AdgEntity |
Returns : |
the bounding box of entity or NULL on errors |
Since 1.0
void adg_entity_set_style (AdgEntity *entity
,AdgDress dress
,AdgStyle *style
);
Overrides the style of dress
for entity
and its children.
If style
is NULL
, any previous override is removed.
The new style must still be compatible with dress
: check out
the adg_dress_style_is_compatible()
documentation to know
what a compatible style means.
|
an AdgEntity |
|
a dress style |
|
the new style to use |
Since 1.0
AdgStyle * adg_entity_get_style (AdgEntity *entity
,AdgDress dress
);
Gets the overriden dress
style from entity
. This is a kind
of accessor function: for rendering purpose use adg_entity_style()
instead. The returned object is owned by entity
and should not be
freed or modified.
|
an AdgEntity |
|
the dress of the style to get |
Returns : |
the requested style or NULL
if the dress style is not overriden. [transfer none]
|
Since 1.0
AdgStyle * adg_entity_style (AdgEntity *entity
,AdgDress dress
);
Gets the style to be used for entity
. dress
specifies which
"family" of style to get.
The following sequence of checks is performed to get the proper style, stopping at the first succesfull result:
adg_entity_get_style()
;entity
has a parent, in which case returns the
adg_entity_style()
of the parent;adg_dress_get_fallback()
.
The returned object is owned by entity
and should not be
freed or modified.
|
an AdgEntity |
|
the dress of the style to get |
Returns : |
the requested style or NULL for
transparent dresses or errors. [transfer none]
|
Since 1.0
void adg_entity_apply_dress (AdgEntity *entity
,AdgDress dress
,cairo_t *cr
);
Convenient function to apply a dress
style (as returned by
adg_entity_style()
) to the cr
cairo context.
Since 1.0
void adg_entity_global_changed (AdgEntity *entity
);
Emits the "global-changed" signal on entity
and on all of
its children, if any.
|
an AdgEntity |
Since 1.0
void adg_entity_local_changed (AdgEntity *entity
);
Emits the "local-changed" signal on entity
and on all of
its children, if any.
|
an AdgEntity |
Since 1.0
void adg_entity_invalidate (AdgEntity *entity
);
Emits the "invalidate" signal on entity
and on all of
its children, if any, clearing the eventual cache stored by the
"arrange" signal and setting the entity state similary
to the just initialized entity.
|
an AdgEntity |
Since 1.0
void adg_entity_arrange (AdgEntity *entity
);
Emits the "arrange" signal on entity
and all its children,
if any. The arrange call is implicitely called by the
"render" signal but not by adg_entity_get_extents()
.
|
an AdgEntity |
Since 1.0
void adg_entity_render (AdgEntity *entity
,cairo_t *cr
);
Emits the "render" signal on entity
and on all of its
children, if any, causing the rendering to the cr
cairo context.
Since 1.0
AdgPoint * adg_entity_point (AdgEntity *entity
,AdgPoint *point
,const AdgPoint *new_point
);
This function is only useful in entity implementations.
A convenient method to set an AdgPoint owned by entity
.
old_point
is the old value while new_point
is the new value.
It can be used for changing a private AdgPoint struct, such as:
1 |
data->point = adg_entity_point(entity, data->point, new_point); |
This function takes care of the dependencies between entity
and
the eventual models bound to the old and new points.
old_point
can be NULL
, in which case a clone of new_point
will
be returned. Also new_point
can be NULL
, in which case old_point
is destroyed and NULL
will be returned.
|
an AdgEntity |
|
the AdgPoint to define |
|
the new AdgPoint value |
Returns : |
the new properly defined point. [transfer full] |
Since 1.0
"global-map"
property "global-map" CairoMatrix* : Read / Write
The transformation to be combined with the parent ones to get the global matrix.
"local-map"
property "local-map" CairoMatrix* : Read / Write
The local transformation that could be used to compute the local matrix in the way specified by the #AdgEntity:local-mix property.
"local-mix"
property"local-mix" AdgMix : Read / Write
Define how the local maps of the entity and its ancestors should be combined to get the local matrix.
Default value: ADG_MIX_ANCESTORS
"parent"
property"parent" AdgEntity* : Read / Write
The parent entity of this entity or NULL if this is a top-level entity.
"arrange"
signalvoid user_function (AdgEntity *entity,
gpointer user_data) : Run Last
Arranges the layout of entity
, updating the cache if necessary,
and computes the extents of entity
.
|
an AdgEntity |
|
user data set when the signal handler was connected. |
Since 1.0
"destroy"
signalvoid user_function (AdgEntity *entity,
gpointer user_data) : Run First
Emitted to explicitely destroy entity
. It unreferences
entity
so that will be destroyed, unless the caller owns
an additional references added with g_object_ref()
.
In the usual case, this is equivalent of calling
g_object_unref()
on entity
but, for composite entities or
containers, the destroy signal is propagated to the children.
|
an AdgEntity |
|
user data set when the signal handler was connected. |
Since 1.0
"global-changed"
signalvoid user_function (AdgEntity *entity,
gpointer user_data) : Run First
Emitted when the global map of entity
or any of its parent
has changed. The default handler will compute the new global
matrix, updating the internal cache.
|
an AdgEntity |
|
user data set when the signal handler was connected. |
Since 1.0
"invalidate"
signalvoid user_function (AdgEntity *entity,
gpointer user_data) : Run Last
Invalidates the whole entity
, that is resets all the cache
(if present) built during the "arrange" signal.
The resulting state is a clean entity, similar to what you
have just before the first rendering.
|
an AdgEntity |
|
user data set when the signal handler was connected. |
Since 1.0
"local-changed"
signalvoid user_function (AdgEntity *entity,
gpointer user_data) : Run First
Emitted when the local map of entity
or any of its parent
has changed. The default handler will compute the new local
matrix, updating the internal cache.
|
an AdgEntity |
|
user data set when the signal handler was connected. |
Since 1.0
"parent-set"
signalvoid user_function (AdgEntity *entity,
AdgEntity *old_parent,
gpointer user_data) : Run First
Emitted after the parent entity has changed. The new parent
can be inspected using adg_entity_get_parent()
.
It is allowed for both old and new parent to be NULL
.
|
an AdgEntity |
|
the old parent |
|
user data set when the signal handler was connected. |
Since 1.0
"render"
signalvoid user_function (AdgEntity *entity,
gpointer cr,
gpointer user_data) : Run Last
Causes the rendering of entity
on cr
. A render signal will
automatically emit "arrange" just before the real
rendering on the cairo context.
|
an AdgEntity |
|
a cairo_t drawing context |
|
user data set when the signal handler was connected. |
Since 1.0