aboutsummaryrefslogtreecommitdiffstats
path: root/e-util
diff options
context:
space:
mode:
authorMatthew Barnes <mbarnes@redhat.com>2010-03-22 02:33:38 +0800
committerMatthew Barnes <mbarnes@redhat.com>2010-03-22 03:49:30 +0800
commitecdb79111cdc6a38234655b668d81d1fed95ec30 (patch)
tree7c4c1d96a14f2e311d0b8df649d21ca780452882 /e-util
parent11cd3fda1a54523ffa450b90f7ac859198d49fbe (diff)
downloadgsoc2013-evolution-ecdb79111cdc6a38234655b668d81d1fed95ec30.tar.gz
gsoc2013-evolution-ecdb79111cdc6a38234655b668d81d1fed95ec30.tar.zst
gsoc2013-evolution-ecdb79111cdc6a38234655b668d81d1fed95ec30.zip
Document EExtensible and EExtension.
The mechanism here is simple but hard to explain without leaning heavily on object-oriented jargon. Consider this a rough draft. Illustrations would certainly help clarify.
Diffstat (limited to 'e-util')
-rw-r--r--e-util/e-extensible.c49
-rw-r--r--e-util/e-extension.c31
-rw-r--r--e-util/e-extension.h6
3 files changed, 86 insertions, 0 deletions
diff --git a/e-util/e-extensible.c b/e-util/e-extensible.c
index 9960d31d9f..a5e87c4280 100644
--- a/e-util/e-extensible.c
+++ b/e-util/e-extensible.c
@@ -16,6 +16,46 @@
*
*/
+/**
+ * SECTION: e-extensible
+ * @short_description: an interface for extending objects
+ * @include: e-util/e-extensible.h
+ *
+ * #EExtension objects can be tacked on to any #GObject instance that
+ * implements the #EExtensible interface. A #GObject type can be made
+ * extensible in two steps:
+ *
+ * 1. Add the #EExtensible interface when registering the #GType.
+ * There are no methods to implement.
+ *
+ * <informalexample>
+ * <programlisting>
+ * #include <e-util/e-extensible.h>
+ *
+ * G_DEFINE_TYPE_WITH_CODE (
+ * ECustomWidget, e_custom_widget, GTK_TYPE_WIDGET,
+ * G_IMPLEMENT_INTERFACE (E_TYPE_EXTENSIBLE, NULL))
+ * </programlisting>
+ * </informalexample>
+ *
+ * 2. Load extensions for the class at some point during #GObject
+ * initialization. Generally this should be done toward the end of
+ * the initialization code, so extensions get a fully initialized
+ * object to work with.
+ *
+ * <informalexample>
+ * <programlisting>
+ * static void
+ * e_custom_widget_init (ECustomWidget *widget)
+ * {
+ * Initialization code goes here...
+ *
+ * e_extensible_load_extensions (E_EXTENSIBLE (widget));
+ * }
+ * </programlisting>
+ * </informalexample>
+ **/
+
#include "e-extensible.h"
#include <e-util/e-util.h>
@@ -89,6 +129,15 @@ e_extensible_get_type (void)
return type;
}
+/**
+ * e_extensible_load_extensions:
+ * @extensible: an #EExtensible
+ *
+ * Creates an instance of all registered subtypes of #EExtension which
+ * target the class of @extensible. The lifetimes of these newly created
+ * #EExtension objects are bound to @extensible such that they are finalized
+ * when @extensible is finalized.
+ **/
void
e_extensible_load_extensions (EExtensible *extensible)
{
diff --git a/e-util/e-extension.c b/e-util/e-extension.c
index 05687b64ba..59eab840c9 100644
--- a/e-util/e-extension.c
+++ b/e-util/e-extension.c
@@ -16,6 +16,29 @@
*
*/
+/**
+ * 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) \
@@ -151,6 +174,14 @@ 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)
{
diff --git a/e-util/e-extension.h b/e-util/e-extension.h
index 905ef412f3..e9eee64a62 100644
--- a/e-util/e-extension.h
+++ b/e-util/e-extension.h
@@ -47,6 +47,12 @@ typedef struct _EExtension EExtension;
typedef struct _EExtensionClass EExtensionClass;
typedef struct _EExtensionPrivate EExtensionPrivate;
+/**
+ * EExtension:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
struct _EExtension {
GObject parent;
EExtensionPrivate *priv;