From ecdb79111cdc6a38234655b668d81d1fed95ec30 Mon Sep 17 00:00:00 2001 From: Matthew Barnes Date: Sun, 21 Mar 2010 14:33:38 -0400 Subject: 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. --- doc/reference/shell/eshell-docs.sgml | 2 ++ doc/reference/shell/eshell-sections.txt | 34 +++++++++++++++++++++ doc/reference/shell/eshell.types | 2 ++ doc/reference/shell/tmpl/e-extensible.sgml | 33 ++++++++++++++++++++ doc/reference/shell/tmpl/e-extension.sgml | 39 ++++++++++++++++++++++++ e-util/e-extensible.c | 49 ++++++++++++++++++++++++++++++ e-util/e-extension.c | 31 +++++++++++++++++++ e-util/e-extension.h | 6 ++++ 8 files changed, 196 insertions(+) create mode 100644 doc/reference/shell/tmpl/e-extensible.sgml create mode 100644 doc/reference/shell/tmpl/e-extension.sgml diff --git a/doc/reference/shell/eshell-docs.sgml b/doc/reference/shell/eshell-docs.sgml index 99948f5007..96fae1a057 100644 --- a/doc/reference/shell/eshell-docs.sgml +++ b/doc/reference/shell/eshell-docs.sgml @@ -34,6 +34,8 @@ + + diff --git a/doc/reference/shell/eshell-sections.txt b/doc/reference/shell/eshell-sections.txt index be5171cb3d..776d08d13f 100644 --- a/doc/reference/shell/eshell-sections.txt +++ b/doc/reference/shell/eshell-sections.txt @@ -440,6 +440,40 @@ e_dialog_combo_box_set e_dialog_combo_box_get +
+e-extensible +Extensible +EExtensible +e_extensible_load_extensions + +E_EXTENSIBLE +E_IS_EXTENSIBLE +E_TYPE_EXTENSIBLE +E_EXTENSIBLE_INTERFACE +E_IS_EXTENSIBLE_INTERFACE +E_EXTENSIBLE_GET_INTERFACE +EExtensibleInterface +e_extensible_get_type +
+ +
+e-extension +Extensions +EExtension +e_extension_get_extensible + +E_EXTENSION +E_IS_EXTENSION +E_TYPE_EXTENSION +E_EXTENSION_CLASS +E_IS_EXTENSION_CLASS +E_EXTENSION_GET_CLASS +EExtensionClass +e_extension_get_type + +EExtensionPrivate +
+
e-html-utils Text to HTML Conversion diff --git a/doc/reference/shell/eshell.types b/doc/reference/shell/eshell.types index ae84ef0905..b5c41aecf6 100644 --- a/doc/reference/shell/eshell.types +++ b/doc/reference/shell/eshell.types @@ -1,4 +1,6 @@ e_bit_array_get_type +e_extensible_get_type +e_extension_get_type e_logger_get_type e_module_get_type e_signature_get_type diff --git a/doc/reference/shell/tmpl/e-extensible.sgml b/doc/reference/shell/tmpl/e-extensible.sgml new file mode 100644 index 0000000000..de8e8e140c --- /dev/null +++ b/doc/reference/shell/tmpl/e-extensible.sgml @@ -0,0 +1,33 @@ + +Extensible + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@extensible: + + diff --git a/doc/reference/shell/tmpl/e-extension.sgml b/doc/reference/shell/tmpl/e-extension.sgml new file mode 100644 index 0000000000..e1acb9d8e2 --- /dev/null +++ b/doc/reference/shell/tmpl/e-extension.sgml @@ -0,0 +1,39 @@ + +Extensions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@extension: +@Returns: + + 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. + * + * + * + * #include + * + * G_DEFINE_TYPE_WITH_CODE ( + * ECustomWidget, e_custom_widget, GTK_TYPE_WIDGET, + * G_IMPLEMENT_INTERFACE (E_TYPE_EXTENSIBLE, NULL)) + * + * + * + * 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. + * + * + * + * static void + * e_custom_widget_init (ECustomWidget *widget) + * { + * Initialization code goes here... + * + * e_extensible_load_extensions (E_EXTENSIBLE (widget)); + * } + * + * + **/ + #include "e-extensible.h" #include @@ -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; -- cgit v1.2.3