Synopsis

#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);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----AdgEntity
               +----AdgDim
               +----AdgContainer
               +----AdgMarker
               +----AdgStroke
               +----AdgLogo
               +----AdgProjection
               +----AdgTable
               +----AdgText
               +----AdgToyText

Properties

  "global-map"               CairoMatrix*          : Read / Write
  "local-map"                CairoMatrix*          : Read / Write
  "local-mix"                AdgMix                : Read / Write
  "parent"                   AdgEntity*            : Read / Write

Signals

  "arrange"                                        : Run Last
  "destroy"                                        : Run First
  "global-changed"                                 : Run First
  "invalidate"                                     : Run Last
  "local-changed"                                  : Run First
  "parent-set"                                     : Run First
  "render"                                         : Run Last

Description

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.

Details

struct AdgEntity

struct AdgEntity;

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

Since 1.0


struct AdgEntityClass

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.

destroy ()

when a destroy request has been explicitely requested

parent_set ()

called whenever the parent of an entity has changed

global_changed ()

the global matrix has been invalidated

local_changed ()

the local matrix has been invalidated

invalidate ()

invalidating callback, used to clear the internal cache

arrange ()

prepare the layout and fill the extents struct

render ()

rendering callback, it must be implemented by every entity

Since 1.0


adg_switch_extents ()

void                adg_switch_extents                  (gboolean state);

Strokes (if state is TRUE) a rectangle around every entity to show their extents. Useful for debugging purposes.

state :

new extents state

Since 1.0


adg_entity_destroy ()

void                adg_entity_destroy                  (AdgEntity *entity);

Emits the "destroy" signal on entity and on all of its children, if any.

entity :

an AdgEntity

Since 1.0


adg_entity_get_canvas ()

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.

entity :

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


adg_entity_set_parent ()

void                adg_entity_set_parent               (AdgEntity *entity,
                                                         AdgEntity *parent);

Note

This function is only useful in entity implementations.

Sets a new parent on entity.

entity :

an AdgEntity

parent :

the parent entity

Since 1.0


adg_entity_get_parent ()

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.

entity :

an AdgEntity

Returns :

the parent entity or NULL on errors or if entity is a toplevel. [transfer none]

Since 1.0


adg_entity_set_global_map ()

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.

entity :

an AdgEntity object

map :

the new map

Since 1.0


adg_entity_transform_global_map ()

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);

entity :

an AdgEntity object

transformation :

the transformation to apply

mode :

how transformation should be applied

Since 1.0


adg_entity_get_global_map ()

const cairo_matrix_t * adg_entity_get_global_map        (AdgEntity *entity);

Gets the transformation to be used to compute the global matrix of entity.

entity :

an AdgEntity object

Returns :

the requested map or NULL on errors

Since 1.0


adg_entity_get_global_matrix ()

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.

entity :

an AdgEntity object

Returns :

the global matrix or NULL on errors

Since 1.0


adg_entity_set_local_map ()

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.

entity :

an AdgEntity object

map :

the new map

Since 1.0


adg_entity_transform_local_map ()

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);

entity :

an AdgEntity object

transformation :

the transformation to apply

mode :

how transformation should be applied

Since 1.0


adg_entity_get_local_map ()

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.

entity :

an AdgEntity object

Returns :

the requested map or NULL on errors

Since 1.0


adg_entity_get_local_matrix ()

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.

entity :

an AdgEntity object

Returns :

the local matrix or NULL on errors

Since 1.0


adg_entity_set_local_mix ()

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.

entity :

an AdgEntity object

local_mix :

new mix method

Since 1.0


adg_entity_get_local_mix ()

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.

entity :

an AdgEntity object

Returns :

the local mix method of entity or ADG_MIX_UNDEFINED on errors

Since 1.0


adg_entity_set_extents ()

void                adg_entity_set_extents              (AdgEntity *entity,
                                                         const CpmlExtents *extents);

Note

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.

entity :

an AdgEntity

extents :

the new extents

Since 1.0


adg_entity_get_extents ()

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.

entity :

an AdgEntity

Returns :

the bounding box of entity or NULL on errors

Since 1.0


adg_entity_set_style ()

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.

entity :

an AdgEntity

dress :

a dress style

style :

the new style to use

Since 1.0


adg_entity_get_style ()

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.

entity :

an AdgEntity

dress :

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


adg_entity_style ()

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:

  1. check if the style is directly overriden by this entity, as returned by adg_entity_get_style();
  2. check if entity has a parent, in which case returns the adg_entity_style() of the parent;
  3. returns the main style with adg_dress_get_fallback().

The returned object is owned by entity and should not be freed or modified.

entity :

an AdgEntity

dress :

the dress of the style to get

Returns :

the requested style or NULL for transparent dresses or errors. [transfer none]

Since 1.0


adg_entity_apply_dress ()

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.

entity :

an AdgEntity

dress :

the dress style to apply

cr :

a cairo_t drawing context

Since 1.0


adg_entity_global_changed ()

void                adg_entity_global_changed           (AdgEntity *entity);

Emits the "global-changed" signal on entity and on all of its children, if any.

entity :

an AdgEntity

Since 1.0


adg_entity_local_changed ()

void                adg_entity_local_changed            (AdgEntity *entity);

Emits the "local-changed" signal on entity and on all of its children, if any.

entity :

an AdgEntity

Since 1.0


adg_entity_invalidate ()

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.

entity :

an AdgEntity

Since 1.0


adg_entity_arrange ()

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().

entity :

an AdgEntity

Since 1.0


adg_entity_render ()

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.

entity :

an AdgEntity

cr :

a cairo_t drawing context

Since 1.0


adg_entity_point ()

AdgPoint *          adg_entity_point                    (AdgEntity *entity,
                                                         AdgPoint *point,
                                                         const AdgPoint *new_point);

Note

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.

entity :

an AdgEntity

point :

the AdgPoint to define

new_point :

the new AdgPoint value

Returns :

the new properly defined point. [transfer full]

Since 1.0

Property Details

The "global-map" property

  "global-map"               CairoMatrix*          : Read / Write

The transformation to be combined with the parent ones to get the global matrix.


The "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.


The "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


The "parent" property

  "parent"                   AdgEntity*            : Read / Write

The parent entity of this entity or NULL if this is a top-level entity.

Signal Details

The "arrange" signal

void                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.

entity :

an AdgEntity

user_data :

user data set when the signal handler was connected.

Since 1.0


The "destroy" signal

void                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.

entity :

an AdgEntity

user_data :

user data set when the signal handler was connected.

Since 1.0


The "global-changed" signal

void                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.

entity :

an AdgEntity

user_data :

user data set when the signal handler was connected.

Since 1.0


The "invalidate" signal

void                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.

entity :

an AdgEntity

user_data :

user data set when the signal handler was connected.

Since 1.0


The "local-changed" signal

void                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.

entity :

an AdgEntity

user_data :

user data set when the signal handler was connected.

Since 1.0


The "parent-set" signal

void                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.

entity :

an AdgEntity

old_parent :

the old parent

user_data :

user data set when the signal handler was connected.

Since 1.0


The "render" signal

void                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.

entity :

an AdgEntity

cr :

a cairo_t drawing context

user_data :

user data set when the signal handler was connected.

Since 1.0