AdgContainer

AdgContainer — Base class for entity that can contain other entities

Synopsis

struct              AdgContainer;
struct              AdgContainerClass;
void                adg_container_add                   (AdgContainer *container,
                                                         AdgEntity *entity);
GSList *            adg_container_children              (AdgContainer *container);
void                adg_container_foreach               (AdgContainer *container,
                                                         GCallback callback,
                                                         gpointer user_data);
AdgContainer *      adg_container_new                   (void);
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);
void                adg_container_remove                (AdgContainer *container,
                                                         AdgEntity *entity);

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/tutorial/view/3 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);
    void        (*add)                          (AdgContainer   *container,
                                                 AdgEntity      *entity);
    void        (*remove)                       (AdgContainer   *container,
                                                 AdgEntity      *entity);
};

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_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 empty list or on errors. [element-type AdgEntity][transfer container]

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: 

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

AdgContainer *      adg_container_new                   (void);

Creates a new container entity.

Returns :

the newly created container entity

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

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: 

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

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

Generated by GTK-Doc V1.18