GContainerable

GContainerable — A generic interface for GChildable containers

Stability Level

Unstable, unless otherwise indicated

Synopsis


#include <gcontainer/gcontainer.h>

                    GContainerable;
                    GContainerableIface;

GSList*             g_containerable_get_children        (GContainerable *containerable);
void                g_containerable_add                 (GContainerable *containerable,
                                                         GChildable *childable);
void                g_containerable_remove              (GContainerable *containerable,
                                                         GChildable *childable);

void                g_containerable_foreach             (GContainerable *containerable,
                                                         GCallback callback,
                                                         gpointer user_data);
void                g_containerable_propagate           (GContainerable *containerable,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         ...);
void                g_containerable_propagate_by_name   (GContainerable *containerable,
                                                         const gchar *detailed_signal,
                                                         ...);
void                g_containerable_propagate_valist    (GContainerable *containerable,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         va_list var_args);

void                g_containerable_dispose             (GObject *object);

Object Hierarchy

  GInterface
   +----GContainerable

Prerequisites

GContainerable requires GObject.

Known Implementations

GContainerable is implemented by GContainer and GBin.

Properties

  "child"                    GObject*              : Write

Signals

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

Description

The GContainerable interface should be implemented by all containers of GChildable objects. It is an interface, so can be implemented by objects at any hierarchy level.

If you prefer to derive your container from a base class, take a look to the sample implementations of GContainerable (GContainer, GBin).

Details

GContainerable

typedef struct _GContainerable GContainerable;

Dummy type of the GContainerableIface interface.


GContainerableIface

typedef struct {
  GTypeInterface base_iface;


  /* Virtual Table */

  GSList *	(*get_children)			(GContainerable *containerable);
  gboolean	(*add)				(GContainerable	*containerable,
						 GChildable	*childable);
  gboolean	(*remove)			(GContainerable *containerable,
						 GChildable	*childable);
} GContainerableIface;

The virtual methods add, remove and get_children must be defined by all the types which implement this interface.

GTypeInterface base_iface; the base interface.
get_children () returns a newly allocated GSList containing the children list of the container.
add () signal handler for "add" signals.
remove () signal handler for "remove" signals.

g_containerable_get_children ()

GSList*             g_containerable_get_children        (GContainerable *containerable);

Gets the children list of containerable. This list must be manually freed when no longer user.

containerable : a GContainerable
Returns : a newly allocated GSList or NULL on error.

g_containerable_add ()

void                g_containerable_add                 (GContainerable *containerable,
                                                         GChildable *childable);

Emits a "add" signal on containerable passing childable as argument.

A GChildable implemented object may be added to only one container at a time; you can't place the same child inside two different containers.

containerable : a GContainerable
childable : a Gobject implementing GChildable

g_containerable_remove ()

void                g_containerable_remove              (GContainerable *containerable,
                                                         GChildable *childable);

Emits a "remove" signal on containerable passing childable as argument.

childable must be inside containerable. Note that containerable will own a reference to childable and that this may be the last reference held; so removing a child from its container can destroy that child. If you want to use childable again, you need to add a reference to it, using g_object_ref(), before remove it from containerable. If you don't want to use childable again, it's usually more efficient to simply destroy it directly using g_object_unref() since this will remove it from the container and help break any circular reference count cycles.

containerable : a GContainerable
childable : a Gobject implementing GChildable

g_containerable_foreach ()

void                g_containerable_foreach             (GContainerable *containerable,
                                                         GCallback callback,
                                                         gpointer user_data);

Invokes callback on each child of containerable.

containerable : a GContainerable
callback : a callback
user_data : callback user data

g_containerable_propagate ()

void                g_containerable_propagate           (GContainerable *containerable,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         ...);

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

containerable : a GContainerable
signal_id : the signal id
detail : the detail
... : parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is G_TYPE_NONE, the return value location can be omitted.

g_containerable_propagate_by_name ()

void                g_containerable_propagate_by_name   (GContainerable *containerable,
                                                         const gchar *detailed_signal,
                                                         ...);

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

containerable : a GContainerable
detailed_signal : a string of the form "signal-name::detail".
... : a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is G_TYPE_NONE, the return value location can be omitted.

g_containerable_propagate_valist ()

void                g_containerable_propagate_valist    (GContainerable *containerable,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         va_list var_args);

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

containerable : a GContainerable
signal_id : the signal id
detail : the detail
var_args : a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is G_TYPE_NONE, the return value location can be omitted.

g_containerable_dispose ()

void                g_containerable_dispose             (GObject *object);

Convenience function to be used in the class initialization of objects implementing the GContainerable interface. g_containerable_dispose() automatically chain up the dispose method of the parent class of the type in the object hierarchy which implements GContainerable.

object : a GObject implementing GContainerable

Property Details

The "child" property

  "child"                    GObject*              : Write

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

Signal Details

The "add" signal

void                user_function                      (GContainerable *containerable,
                                                        GObject        *childable,
                                                        gpointer        user_data)          : Run First

Adds childable to the children list of containerable.

containerable : a GContainerable
childable : a Gobject implementing GChildable
user_data : user data set when the signal handler was connected.

The "remove" signal

void                user_function                      (GContainerable *containerable,
                                                        GObject        *childable,
                                                        gpointer        user_data)          : Run First

Removes childable from the children list of containerable.

containerable : a GContainerable
childable : a Gobject implementing GChildable
user_data : user data set when the signal handler was connected.