Synopsis

#include <adg-1/adg.h>

struct              AdgContainer;
struct              AdgContainerClass;
AdgContainer *      adg_container_new                   (void);
GSList *            adg_container_children              (AdgContainer *container);
void                adg_container_add                   (AdgContainer *container,
                                                         AdgEntity *entity);
void                adg_container_remove                (AdgContainer *container,
                                                         AdgEntity *entity);
void                adg_container_foreach               (AdgContainer *container,
                                                         GCallback callback,
                                                         gpointer user_data);
void                adg_container_propagate             (AdgContainer *container,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         ...);
void                adg_container_propagate_by_name     (AdgContainer *container,
                                                         const gchar *detailed_signal,
                                                         ...);
void                adg_container_propagate_valist      (AdgContainer *container,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         va_list var_args);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----AdgEntity
               +----AdgContainer
                     +----AdgAlignment
                     +----AdgCanvas

Properties

  "child"                    AdgEntity*            : Write

Signals

  "add"                                            : Run First
  "remove"                                         : Run First

Description

The AdgContainer is an entity that can contains more sub-entities. Moreover, it can apply a common transformation to local and/or global maps: see http://adg.entidi.com/home/details/ for further details.

Adding an entity to a container will make a circular dependency between the two objects. The container will also add a weak reference to the child entity to intercept when the entity is manually destroyed (usually by calling g_object_unref()) and remove the child reference from the internal children list.

Details

struct AdgContainer

struct AdgContainer;

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

Since 1.0


struct AdgContainerClass

struct AdgContainerClass {
    /* Virtual table */
    GSList *    (*children)                     (AdgContainer   *container);

    /* Signals */
    void        (*add)                          (AdgContainer   *container,
                                                 AdgEntity      *entity);
    void        (*remove)                       (AdgContainer   *container,
                                                 AdgEntity      *entity);
};

AdgContainer effectively stores a GSList of children into its private data and keeps a reference to every children it owns.

children ()

virtual method that gets the list of entities (that is AdgEntity and derived instances) owned by the container.

add ()

signal that adds a new entity to the container.

remove ()

signal that removes a specific entity from the container.

Since 1.0


adg_container_new ()

AdgContainer *      adg_container_new                   (void);

Creates a new container entity.

Returns :

the newly created container entity

Since 1.0


adg_container_children ()

GSList *            adg_container_children              (AdgContainer *container);

Gets the children list of container. This list must be manually freed with g_slist_free() when no longer user.

The returned list is ordered from the most recently added child to the oldest one.

container :

an AdgContainer

Returns :

a newly allocated GSList of AdgEntity or NULL on no children or errors. [element-type AdgEntity][transfer container]

Since 1.0


adg_container_add ()

void                adg_container_add                   (AdgContainer *container,
                                                         AdgEntity *entity);

Emits a "add" signal on container passing entity as argument. entity must be added to only one container at a time, you can't place the same entity inside two different containers.

Once entity has been added, the floating reference will be removed and container will own a reference to entity. This means the only proper way to destroy entity is to call adg_container_remove().

container :

an AdgContainer

entity :

an AdgEntity

Since 1.0


adg_container_remove ()

void                adg_container_remove                (AdgContainer *container,
                                                         AdgEntity *entity);

Emits a "remove" signal on container passing entity as argument. entity must be inside container.

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

If you want to use entity again, you need to add a reference to it, using g_object_ref(), before removing it from container. The following typical example shows you how to properly move entity from container1 to container2:

1
2
3
4
g_object_ref(entity);
adg_container_remove(container1, entity);
adg_container_add(container2, entity)
g_object_unref(entity);

container :

an AdgContainer

entity :

an AdgEntity

Since 1.0


adg_container_foreach ()

void                adg_container_foreach               (AdgContainer *container,
                                                         GCallback callback,
                                                         gpointer user_data);

Invokes callback on each child of container. The callback should be declared as:

1
void callback(AdgEntity *entity, gpointer user_data);

container :

an AdgContainer

callback :

a callback. [scope call]

user_data :

callback user data

Since 1.0


adg_container_propagate ()

void                adg_container_propagate             (AdgContainer *container,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         ...);

Emits the specified signal to all the children of container using g_signal_emit_valist() calls.

container :

an AdgContainer

signal_id :

the signal id

detail :

the detail

... :

parameters to be passed to the signal, followed by a pointer to the allocated memory where to store the return type: if the signal is G_TYPE_NONE (void return type), this trailing pointer should be omitted

Since 1.0


adg_container_propagate_by_name ()

void                adg_container_propagate_by_name     (AdgContainer *container,
                                                         const gchar *detailed_signal,
                                                         ...);

Emits the specified signal to all the children of container using g_signal_emit_valist() calls.

container :

an AdgContainer

detailed_signal :

a string of the form "signal-name::detail".

... :

parameters to be passed to the signal, followed by a pointer to the allocated memory where to store the return type: if the signal is G_TYPE_NONE (void return type), this trailing pointer should be omitted

Since 1.0


adg_container_propagate_valist ()

void                adg_container_propagate_valist      (AdgContainer *container,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         va_list var_args);

Emits the specified signal to all the children of container using g_signal_emit_valist() calls.

container :

an AdgContainer

signal_id :

the signal id

detail :

the detail

var_args :

parameters to be passed to the signal, followed by a pointer to the allocated memory where to store the return type: if the signal is G_TYPE_NONE (void return type), this trailing pointer should be omitted

Since 1.0

Property Details

The "child" property

  "child"                    AdgEntity*            : Write

Can be used to add a new child to the container.

Signal Details

The "add" signal

void                user_function                      (AdgContainer *container,
                                                        AdgEntity    *entity,
                                                        gpointer      user_data)      : Run First

Adds entity to container. entity must not be inside another container or the operation will fail.

container :

an AdgContainer

entity :

the AdgEntity to add

user_data :

user data set when the signal handler was connected.

Since 1.0


The "remove" signal

void                user_function                      (AdgContainer *container,
                                                        AdgEntity    *entity,
                                                        gpointer      user_data)      : Run First

Removes entity from container.

container :

an AdgContainer

entity :

the AdgEntity to remove

user_data :

user data set when the signal handler was connected.

Since 1.0