evolution/e-util/e-extension.c

/*
 * e-extension.c
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) version 3.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with the program; if not, see <http://www.gnu.org/licenses/>
 *
 */

/**
 * SECTION: e-extension
 * @short_description: abstract base class for extensions
 * @include: e-util/e-extension.h
 *
 * #EExtension provides a way to extend the functionality of objects
 * that implement the #EExtensible interface.  #EExtension subclasses
 * can target a particular extensible object type.  New instances of
 * an extensible object type get paired with a new instance of each
 * #EExtension subclass that targets the extensible object type.
 *
 * The first steps of writing a new extension are as follows:
 *
 * 1. Subclass #EExtension.
 *
 * 2. In the class initialization function, specify the #GType being
 *    extended.  The #GType must implement the #EExtensible interface.
 *
 * 3. Register the extension's own #GType.  If the extension is to
 *    be loaded dynamically using #GTypeModule, the type should be
 *    registered in the library module's e_module_load() function.
 **/

#include "e-extension.h"

#define E_EXTENSION_GET_PRIVATE(obj) \
	(G_TYPE_INSTANCE_GET_PRIVATE \
	((obj), E_TYPE_EXTENSION, EExtensionPrivate))

struct _EExtensionPrivate {
	gpointer extensible;  /* weak pointer */
};

enum {
	PROP_0,
	PROP_EXTENSIBLE
};

G_DEFINE_ABSTRACT_TYPE (EExtension, e_extension, G_TYPE_OBJECT)

static void
extension_set_extensible (EExtension *extension,
                          EExtensible *extensible)
{
	EExtensionClass *class;
	GType extensible_type;

	g_return_if_fail (E_IS_EXTENSIBLE (extensible));
	g_return_if_fail (extension->priv->extensible == NULL);

	class = E_EXTENSION_GET_CLASS (extension);
	extensible_type = G_OBJECT_TYPE (extensible);

	/* Verify the EExtensible object is the type we want. */
	if (!g_type_is_a (extensible_type, class->extensible_type)) {
		g_warning ("%s is meant to extend %s but was given an %s",
			G_OBJECT_TYPE_NAME (extension),
			g_type_name (class->extensible_type),
			g_type_name (extensible_type));
		return;
	}

	extension->priv->extensible = extensible;

	g_object_add_weak_pointer (
		G_OBJECT (extensible), &extension->priv->extensible);
}

static void
extension_set_property (GObject *object,
                        guint property_id,
                        const GValue *value,
                        GParamSpec *pspec)
{
	switch (property_id) {
		case PROP_EXTENSIBLE:
			extension_set_extensible (
				E_EXTENSION (object),
				g_value_get_object (value));
			return;
	}

	G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
}

static void
extension_get_property (GObject *object,
                        guint property_id,
                        GValue *value,
                        GParamSpec *pspec)
{
	switch (property_id) {
		case PROP_EXTENSIBLE:
			g_value_set_object (
				value, e_extension_get_extensible (
				E_EXTENSION (object)));
			return;
	}

	G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
}

static void
extension_constructed (GObject *object)
{
	/* This allows subclasses to chain up safely since GObject
	 * does not implement this method, and we might want to do
	 * something here in the future. */
}

static void
extension_dispose (GObject *object)
{
	EExtensionPrivate *priv;

	priv = E_EXTENSION_GET_PRIVATE (object);

	if (priv->extensible != NULL) {
		g_object_remove_weak_pointer (
			G_OBJECT (priv->extensible), &priv->extensible);
		priv->extensible = NULL;
	}

	/* Chain up to parent's dispose() method. */
	G_OBJECT_CLASS (e_extension_parent_class)->dispose (object);
}

static void
e_extension_class_init (EExtensionClass *class)
{
	GObjectClass *object_class;

	g_type_class_add_private (class, sizeof (EExtensionPrivate));

	object_class = G_OBJECT_CLASS (class);
	object_class->set_property = extension_set_property;
	object_class->get_property = extension_get_property;
	object_class->constructed = extension_constructed;
	object_class->dispose = extension_dispose;

	g_object_class_install_property (
		object_class,
		PROP_EXTENSIBLE,
		g_param_spec_object (
			"extensible",
			"Extensible Object",
			"The object being extended",
			E_TYPE_EXTENSIBLE,
			G_PARAM_READWRITE |
			G_PARAM_CONSTRUCT_ONLY));
}

static void
e_extension_init (EExtension *extension)
{
	extension->priv = E_EXTENSION_GET_PRIVATE (extension);
}

/**
 * e_extension_get_extensible:
 * @extension: an #EExtension
 *
 * Returns the object that @extension extends.
 *
 * Returns: the object being extended
 **/
EExtensible *
e_extension_get_extensible (EExtension *extension)
{
	g_return_val_if_fail (E_IS_EXTENSION (extension), NULL);

	return E_EXTENSIBLE (extension->priv->extensible);
}