![]() |
![]() |
![]() |
adg-1 reference manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#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
);
GObject +----GInitiallyUnowned +----AdgEntity +----AdgContainer +----AdgAlignment +----AdgCanvas
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.
struct AdgContainer;
All fields are private and should not be used directly. Use its public methods instead.
Since 1.0
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.
virtual method that gets the list of entities (that is AdgEntity and derived instances) owned by the container. | |
signal that adds a new entity to the container. | |
signal that removes a specific entity from the container. |
Since 1.0
AdgContainer * adg_container_new (void
);
Creates a new container entity.
Returns : |
the newly created container entity |
Since 1.0
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.
|
an AdgContainer |
Returns : |
a newly allocated GSList of AdgEntity or NULL on no children or errors. [element-type AdgEntity][transfer container]
|
Since 1.0
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()
.
|
an AdgContainer |
|
an AdgEntity |
Since 1.0
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); |
|
an AdgContainer |
|
an AdgEntity |
Since 1.0
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); |
|
an AdgContainer |
|
a callback. [scope call] |
|
callback user data |
Since 1.0
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.
|
an AdgContainer |
|
the signal id |
|
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
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.
|
an AdgContainer |
|
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
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.
|
an AdgContainer |
|
the signal id |
|
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
"add"
signalvoid 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.
|
an AdgContainer |
|
the AdgEntity to add |
|
user data set when the signal handler was connected. |
Since 1.0
"remove"
signalvoid user_function (AdgContainer *container,
AdgEntity *entity,
gpointer user_data) : Run First
Removes entity
from container
.
|
an AdgContainer |
|
the AdgEntity to remove |
|
user data set when the signal handler was connected. |
Since 1.0