[Xfce4-commits] <exo:master> Move all the documentation in the code.
Nick Schermer
nick at xfce.org
Tue Sep 1 12:30:02 CEST 2009
Updating branch refs/heads/master
to f4b112e3cde701624944f90a430404cf20a0999c (commit)
from 5f5e8f266f8dabef305a2a30c52534ed77fdbeda (commit)
commit f4b112e3cde701624944f90a430404cf20a0999c
Author: Nick Schermer <nick at xfce.org>
Date: Tue Sep 1 12:25:44 2009 +0200
Move all the documentation in the code.
exo-hal/exo-hal.c | 34 +++++++
exo/exo-binding.c | 150 +++++++++++++++++++++----------
exo/exo-binding.h | 21 ++++-
exo/exo-cell-renderer-ellipsized-text.c | 28 +++++-
exo/exo-cell-renderer-ellipsized-text.h | 6 ++
exo/exo-cell-renderer-icon.c | 25 +++++-
exo/exo-cell-renderer-icon.h | 6 ++
exo/exo-config.c | 52 ++++++++++-
exo/exo-config.h.in | 32 +++++++
exo/exo-execute.c | 27 +++++-
exo/exo-gdk-pixbuf-extensions.c | 52 +++++++----
exo/exo-gobject-extensions.c | 14 +++-
exo/exo-gtk-extensions.c | 18 ++++
exo/exo-gtk-extensions.h | 4 +-
exo/exo-icon-bar.c | 71 +++++++++++++--
exo/exo-icon-bar.h | 12 +++
exo/exo-icon-chooser-dialog.c | 24 ++++-
exo/exo-icon-chooser-model.c | 6 +-
exo/exo-icon-view.c | 95 +++++++++++---------
exo/exo-icon-view.h | 2 +-
exo/exo-job.c | 64 ++++++++++----
exo/exo-job.h | 6 ++
exo/exo-mount-point.c | 17 +++-
exo/exo-mount-point.h | 16 +++-
exo/exo-simple-job.c | 18 ++++-
exo/exo-simple-job.h | 2 +-
exo/exo-string.c | 31 ++++---
exo/exo-string.h | 26 +++++-
exo/exo-thumbnail-preview.c | 2 +-
exo/exo-thumbnail.c | 4 +-
exo/exo-toolbars-editor-dialog.c | 15 +++-
exo/exo-toolbars-editor-dialog.h | 6 ++
exo/exo-toolbars-editor.c | 26 +++++-
exo/exo-toolbars-editor.h | 6 ++
exo/exo-toolbars-model.c | 64 ++++++++-----
exo/exo-toolbars-model.h | 21 +++++
exo/exo-toolbars-private.c | 7 +-
exo/exo-toolbars-view.c | 37 ++++++--
exo/exo-toolbars-view.h | 6 ++
exo/exo-tree-view.c | 22 ++++-
exo/exo-tree-view.h | 6 ++
exo/exo-utils.c | 23 ++++-
exo/exo-utils.h | 25 +++++
exo/exo-wrap-table.c | 27 ++++--
exo/exo-wrap-table.h | 6 ++
exo/exo-xsession-client.c | 100 +++++++++++++++++++--
exo/exo-xsession-client.h | 6 ++
47 files changed, 1014 insertions(+), 254 deletions(-)
diff --git a/exo-hal/exo-hal.c b/exo-hal/exo-hal.c
index b764d94..c7dbbdb 100644
--- a/exo-hal/exo-hal.c
+++ b/exo-hal/exo-hal.c
@@ -42,6 +42,40 @@
#include <exo-hal/exo-hal.h>
+/**
+ * SECTION: exo-hal
+ * @title: HAL Support Functions
+ * @short_description: Miscellaneous Utility Functions for HAL integration
+ * @include: exo-hal/exo-hal.h
+ * @see_also: <ulink type="http" url="http://gitweb.freedesktop.org/?p=hal.git;a=blob_plain;f=doc/spec/hal-spec.html">
+ * HAL Specification</ulink>
+ *
+ * This is an additional library that ships with the
+ * <application>exo</application> package and offers support functions
+ * for HAL integration, that are used by <command>exo-mount</command>
+ * and <command>Thunar</command> to figure out display names and icons
+ * to visually present HAL devices to the user. The library may also be
+ * used by other components to offer smooth integration between various
+ * parts of the desktop, making sure that the same names and icons are
+ * used for devices everywhere.
+ *
+ * Since HAL is currently an optional dependency for Xfce, you should
+ * first check whether HAL support is really available by calling the
+ * <link linkend="exo-hal-init"><function>exo_hal_init()</function></link>
+ * function, which returns <literal>TRUE</literal> if HAL support is
+ * available and the other functions will be able to do their work, or
+ * <literal>FALSE</literal> if the functions will return hardcoded default
+ * values instead. The <link linkend="exo-hal-init">
+ * <function>exo_hal_init()</function></link> also takes care of setting
+ * up the internationalization support, so make sure you call it first.
+ *
+ * The HAL support module is not part of the main <filename>exo</filename>
+ * library, so you if you want to use any of these functions you will
+ * need to explicitly link to the <filename>exo-hal</filename> library.
+ * This is done with the <command>pkg-config</command> utility, using
+ * <filename>exo-hal-1</filename> as the package name.
+ **/
+
#ifdef HAVE_HAL
diff --git a/exo/exo-binding.c b/exo/exo-binding.c
index 5a68320..ad8a1b4 100644
--- a/exo/exo-binding.c
+++ b/exo/exo-binding.c
@@ -1,4 +1,3 @@
-/* $Id$ */
/*-
* Copyright (c) 2004-2006 os-cillation e.K.
* Copyright (c) 2004 Victor Porton (http://ex-code.com/~porton/)
@@ -30,6 +29,55 @@
#include <exo/exo-private.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-binding
+ * @title: Binding Properties Functions
+ * @short_description: Functions used to bind two object properties together
+ * @include: exo/exo.h
+ * @see_also: <ulink url="http://library.gnome.org/devel/gobject/stable/">
+ * GObject Reference Manual</ulink>,
+ * <link linkend="exo-Extensions-to-GObject">Extensions to GObject</link>
+ *
+ * Binding properties is synchronizing values of several properties,
+ * so that when one of the bound properties changes, the other
+ * bound properties are automatically changed to the new value as
+ * well. These functions eliminate the need to write property
+ * change notification callbacks manually. It also increases the
+ * reliability of your project as you don't need to repeat similar
+ * code (and errors) manually.
+ *
+ * Both uni-directional and mutual
+ * bindings are supported and you can specify functions to perform
+ * explicit transformation of values if required. Multiple properties
+ * can be bound together in a complex way and infinite loops are
+ * eliminated automatically.
+ *
+ * For example, lets say, your program has a #GtkEntry widget that allows
+ * the user to enter some text for the program, but this entry widget should
+ * only be sensitive if a #GtkCheckButton is active.
+ *
+ * <example>
+ * <title>Connecting a <structname>GtkCheckButton</structname> and a
+ * <structname>GtkEntry</structname></title>
+ * <programlisting>
+ * {
+ * GtkWidget *button;
+ * GtkWidget *entry;
+ *
+ * button = gtk_check_button_new_with_label ("Activate me");
+ * entry = gtk_entry_new ();
+ *
+ * exo_binding_new (G_OBJECT (button), "active",
+ * G_OBJECT (entry), "sensitive");
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * As you can see, all you need to do is to call one function to connect
+ * the sensitivity of the entry widget with the state of the check
+ * button. No need to write signal handlers for this purpose any more.
+ **/
+
typedef struct
{
GObject *dst_object;
@@ -41,6 +89,12 @@ typedef struct
}
ExoBindingLink;
+/**
+ * ExoBinding:
+ *
+ * Opaque structure representing a one-way binding between two properties.
+ * It is automatically removed if one of the bound objects is finalized.
+ **/
struct _ExoBinding
{
GObject *src_object;
@@ -48,6 +102,12 @@ struct _ExoBinding
ExoBindingLink link;
};
+/**
+ * ExoMutualBinding:
+ *
+ * Opaque structure representing a mutual binding between two properties.
+ * It is automatically freed if one of the bound objects is finalized.
+ **/
struct _ExoMutualBinding
{
GDestroyNotify destroy;
@@ -231,10 +291,10 @@ exo_binding_link_init (ExoBindingLink *link,
/**
* exo_binding_new:
- * @src_object : The source #GObject.
- * @src_property : The name of the property to bind from.
- * @dst_object : The destination #GObject.
- * @dst_property : The name of the property to bind to.
+ * @src_object: The source #GObject.
+ * @src_property: The name of the property to bind from.
+ * @dst_object: The destination #GObject.
+ * @dst_property: The name of the property to bind to.
*
* One-way binds @src_property in @src_object to @dst_property
* in @dst_object.
@@ -242,8 +302,8 @@ exo_binding_link_init (ExoBindingLink *link,
* Before binding the value of @dst_property is set to the
* value of @src_property.
*
- * Return value: The descriptor of the binding. It is automatically
- * removed if one of the objects is finalized.
+ * Returns: The descriptor of the binding. It is automatically
+ * removed if one of the objects is finalized.
**/
ExoBinding*
exo_binding_new (GObject *src_object,
@@ -260,14 +320,13 @@ exo_binding_new (GObject *src_object,
/**
* exo_binding_new_full:
- * @src_object : The source #GObject.
- * @src_property : The name of the property to bind from.
- * @dst_object : The destination #GObject.
- * @dst_property : The name of the property to bind to.
- * @transform : Transformation function or %NULL.
- * @destroy_notify : Callback function that is called on
- * disconnection with @user_data or %NULL.
- * @user_data : User data associated with the binding.
+ * @src_object: The source #GObject.
+ * @src_property: The name of the property to bind from.
+ * @dst_object: The destination #GObject.
+ * @dst_property: The name of the property to bind to.
+ * @transform: Transformation function or %NULL.
+ * @destroy_notify: Callback function that is called on disconnection with @user_data or %NULL.
+ * @user_data: User data associated with the binding.
*
* One-way binds @src_property in @src_object to @dst_property
* in @dst_object.
@@ -275,8 +334,8 @@ exo_binding_new (GObject *src_object,
* Before binding the value of @dst_property is set to the
* value of @src_property.
*
- * Return value: The descriptor of the binding. It is automatically
- * removed if one of the objects is finalized.
+ * Returns: The descriptor of the binding. It is automatically
+ * removed if one of the objects is finalized.
**/
ExoBinding*
exo_binding_new_full (GObject *src_object,
@@ -329,15 +388,15 @@ exo_binding_new_full (GObject *src_object,
/**
* exo_binding_new_with_negation:
- * @src_object : The source #GObject.
- * @src_property : The name of the property to bind from.
- * @dst_object : The destination #GObject.
- * @dst_property : The name of the property to bind to.
+ * @src_object: The source #GObject.
+ * @src_property: The name of the property to bind from.
+ * @dst_object: The destination #GObject.
+ * @dst_property: The name of the property to bind to.
*
* Convenience function for binding with boolean negation of value.
*
- * Return value: The descriptor of the binding. It is automatically
- * removed if one of the objects is finalized.
+ * Returns: The descriptor of the binding. It is automatically
+ * removed if one of the objects is finalized.
**/
ExoBinding*
exo_binding_new_with_negation (GObject *src_object,
@@ -374,18 +433,18 @@ exo_binding_unbind (ExoBinding *binding)
/**
* exo_mutual_binding_new:
- * @object1 : The first #GObject.
- * @property1 : The first property to bind.
- * @object2 : The second #GObject.
- * @property2 : The second property to bind.
+ * @object1: The first #GObject.
+ * @property1: The first property to bind.
+ * @object2: The second #GObject.
+ * @property2: The second property to bind.
*
* Mutually binds values of two properties.
*
* Before binding the value of @property2 is set to the value
* of @property1.
*
- * Return value: The descriptor of the binding. It is automatically
- * removed if one of the objects is finalized.
+ * Returns: The descriptor of the binding. It is automatically
+ * removed if one of the objects is finalized.
**/
ExoMutualBinding*
exo_mutual_binding_new (GObject *object1,
@@ -402,15 +461,14 @@ exo_mutual_binding_new (GObject *object1,
/**
* exo_mutual_binding_new_full:
- * @object1 : The first #GObject.
- * @property1 : The first property to bind.
- * @object2 : The second #GObject.
- * @property2 : The second property to bind.
- * @transform : Transformation function or %NULL.
- * @reverse_transform : The inverse transformation function or %NULL.
- * @destroy_notify : Callback function called on disconnection with
- * @user_data as argument or %NULL.
- * @user_data : User data associated with the binding.
+ * @object1: The first #GObject.
+ * @property1: The first property to bind.
+ * @object2: The second #GObject.
+ * @property2: The second property to bind.
+ * @transform: Transformation function or %NULL.
+ * @reverse_transform: The inverse transformation function or %NULL.
+ * @destroy_notify: Callback function called on disconnection with @user_data as argument or %NULL.
+ * @user_data: User data associated with the binding.
*
* Mutually binds values of two properties.
*
@@ -421,8 +479,8 @@ exo_mutual_binding_new (GObject *object1,
* %NULL or non-%NULL. If they are non-%NULL, they should be reverse
* in each other.
*
- * Return value: The descriptor of the binding. It is automatically
- * removed if one of the objects is finalized.
+ * Returns: The descriptor of the binding. It is automatically
+ * removed if one of the objects is finalized.
**/
ExoMutualBinding*
exo_mutual_binding_new_full (GObject *object1,
@@ -493,15 +551,15 @@ exo_mutual_binding_new_full (GObject *object1,
/**
* exo_mutual_binding_new_with_negation:
- * @object1 : The first #GObject.
- * @property1 : The first property to bind.
- * @object2 : The second #GObject.
- * @property2 : The second property to bind.
+ * @object1: The first #GObject.
+ * @property1: The first property to bind.
+ * @object2: The second #GObject.
+ * @property2: The second property to bind.
*
* Convenience function for binding with boolean negation of value.
*
- * Return value: The descriptor of the binding. It is automatically removed
- * if one of the objects if finalized.
+ * Returns: The descriptor of the binding. It is automatically removed
+ * if one of the objects if finalized.
**/
ExoMutualBinding*
exo_mutual_binding_new_with_negation (GObject *object1,
diff --git a/exo/exo-binding.h b/exo/exo-binding.h
index 467e8ee..0403bba 100644
--- a/exo/exo-binding.h
+++ b/exo/exo-binding.h
@@ -1,4 +1,3 @@
-/* $Id$ */
/*-
* Copyright (c) 2004 os-cillation e.K.
* Copyright (c) 2004 Victor Porton (http://ex-code.com/~porton/)
@@ -32,11 +31,23 @@
G_BEGIN_DECLS
-typedef struct _ExoBinding ExoBinding;
-typedef struct _ExoMutualBinding ExoMutualBinding;
-
-
+typedef struct _ExoBinding ExoBinding;
+typedef struct _ExoMutualBinding ExoMutualBinding;
+/**
+ * ExoBindingTransform:
+ * @src_value : Value to transform.
+ * @dst_value : Value to store the result of the transformation into.
+ * @user_data : User data supplied at binding creation.
+ *
+ * Function type used for binding transformation functions.
+ *
+ * Accomplished transformation from @src_value to @dst_value.
+ * @src_value and @dst_value are already initialized before
+ * this function gets called.
+ *
+ * Returns: %FALSE if transformation failed, else %TRUE.
+ **/
typedef gboolean (*ExoBindingTransform) (const GValue *src_value,
GValue *dst_value,
gpointer user_data);
diff --git a/exo/exo-cell-renderer-ellipsized-text.c b/exo/exo-cell-renderer-ellipsized-text.c
index 5dee42f..cb9bae6 100644
--- a/exo/exo-cell-renderer-ellipsized-text.c
+++ b/exo/exo-cell-renderer-ellipsized-text.c
@@ -28,11 +28,29 @@
#include <exo/exo-private.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-cell-renderer-ellipsized-text
+ * @title: ExoCellRendererEllipsizedText
+ * @short_description: Renders text in a cell
+ * @include: exo/exo.h
+ * @see_also: <ulink url="http://library.gnome.org/devel/gtk/stable/GtkCellRendererText.html"
+ * type="http">GtkCellRendererText</ulink>,
+ * <link linkend="ExoIconView">ExoIconView</link>
+ *
+ * The #ExoCellRendererEllipsizedText renders a given text in its cell,
+ * using the font, color and style information provided by its properties
+ * (which are actually inherited from #GtkCellRendererText).
+ *
+ * Despite the rather confusing name of this class, it is mainly useful
+ * to render text in an #ExoIconView (or a #GtkIconView), which require
+ * the renderers to actually draw the state indicators. State indicators
+ * will be drawn only if the
+ * <link linkend="ExoCellRendererEllipsizedText--follow-state">follow-state</link>
+ * property is %TRUE.
+ **/
-
-#define EXO_CELL_RENDERER_ELLIPSIZED_TEXT_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_CELL_RENDERER_ELLIPSIZED_TEXT, ExoCellRendererEllipsizedTextPrivate))
-
-
+#define EXO_CELL_RENDERER_ELLIPSIZED_TEXT_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_CELL_RENDERER_ELLIPSIZED_TEXT, ExoCellRendererEllipsizedTextPrivate))
/* Property identifiers */
enum
@@ -344,7 +362,7 @@ exo_cell_renderer_ellipsized_text_render (GtkCellRenderer *renderer,
* which can be set globally via g_object_set(). Also, with #GtkCellLayout and #GtkTreeViewColumn, you
* can bind a property to a value in a #GtkTreeModel.
*
- * Return value: the newly allocated #ExoCellRendererEllipsizedText.
+ * Returns: the newly allocated #ExoCellRendererEllipsizedText.
**/
GtkCellRenderer*
exo_cell_renderer_ellipsized_text_new (void)
diff --git a/exo/exo-cell-renderer-ellipsized-text.h b/exo/exo-cell-renderer-ellipsized-text.h
index eeb797a..8a83a99 100644
--- a/exo/exo-cell-renderer-ellipsized-text.h
+++ b/exo/exo-cell-renderer-ellipsized-text.h
@@ -50,6 +50,12 @@ struct _ExoCellRendererEllipsizedTextClass
GtkCellRendererTextClass __parent__;
};
+/**
+ * ExoCellRendererEllipsizedText:
+ *
+ * The #ExoIconCellRendererEllipsizedText
+ * struct contains only private fields and should not be directly accessed.
+ **/
struct _ExoCellRendererEllipsizedText
{
/*< private >*/
diff --git a/exo/exo-cell-renderer-icon.c b/exo/exo-cell-renderer-icon.c
index 9a77955..d2a624f 100644
--- a/exo/exo-cell-renderer-icon.c
+++ b/exo/exo-cell-renderer-icon.c
@@ -31,9 +31,28 @@
#include <exo/exo-thumbnail.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-cell-renderer-icon
+ * @title: ExoCellRendererIcon
+ * @short_description: Renders an icon in a cell
+ * @include: exo/exo.h
+ * @see_also: <link linkend="ExoIconView">ExoIconView</link>
+ *
+ * An #ExoCellRendererIcon can be used to render an icon in a cell. It
+ * allows to render either a named icon, which is looked up using the
+ * #GtkIconTheme, or an image file loaded from the file system. The icon
+ * name or absolute path to the image file is set via the
+ * <link linkend="ExoCellRendererIcon--icon">icon</link> property.
+ *
+ * To support the <link linkend="ExoIconView">ExoIconView</link> (and <link
+ * linkend="GtkIconView">GtkIconView</link>), #ExoCellRendererIcon supports
+ * rendering icons based on the state of the view if the
+ * <link linkend="ExoCellRendererIcon--follow-state">follow-state</link>
+ * property is set.
+ **/
-
-#define EXO_CELL_RENDERER_ICON_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_CELL_RENDERER_ICON, ExoCellRendererIconPrivate))
+#define EXO_CELL_RENDERER_ICON_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_CELL_RENDERER_ICON, ExoCellRendererIconPrivate))
@@ -539,7 +558,7 @@ exo_cell_renderer_icon_render (GtkCellRenderer *renderer,
* cell renderer to an icon name in the model, thus rendering a different icon in each row
* of the #GtkTreeView.
*
- * Return value: the newly allocated #ExoCellRendererIcon.
+ * Returns: the newly allocated #ExoCellRendererIcon.
*
* Since: 0.3.1.9
**/
diff --git a/exo/exo-cell-renderer-icon.h b/exo/exo-cell-renderer-icon.h
index b5c03c2..f0236d8 100644
--- a/exo/exo-cell-renderer-icon.h
+++ b/exo/exo-cell-renderer-icon.h
@@ -56,6 +56,12 @@ struct _ExoCellRendererIconClass
void (*reserved6) (void);
};
+/**
+ * ExoCellRendererIcon:
+ *
+ * The #ExoIconChooserDialog struct contains only private fields and
+ * should not be directly accessed.
+ **/
struct _ExoCellRendererIcon
{
/*< private >*/
diff --git a/exo/exo-config.c b/exo/exo-config.c
index 81d36d3..169f346 100644
--- a/exo/exo-config.c
+++ b/exo/exo-config.c
@@ -27,10 +27,52 @@
#include <exo/exo-config.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-config
+ * @title: Version Information
+ * @short_description: Variables and macros to check the exo version
+ * @include: exo/exo.h
+ *
+ * Exo provides version information, primarily useful in configure for
+ * builds that have a configure script. Applications may use it to
+ * check if a certain feature is available in the version of libexo
+ * they are being built against or being linked with.
+ **/
-
+/**
+ * exo_major_version:
+ *
+ * The major version number of the exo library (e.g. in exo 1.2.3 this is 1).
+ *
+ * This variable is in the library, and therefore represents the exo
+ * library you have linked against. Contrast with the #EXO_MAJOR_VERSION
+ * macro, which represents the major version of the libexo headers you
+ * have included.
+ **/
const guint exo_major_version = EXO_MAJOR_VERSION;
+
+/**
+ * exo_minor_version:
+ *
+ * The minor version number of the exo library (e.g. in exo 1.2.3 this is 2).
+ *
+ * This variable is in the library, and therefore represents the exo
+ * library you have linked against. Contrast with the #EXO_MINOR_VERSION
+ * macro, which represents the minor version of the libexo headers you
+ * have included.
+ **/
const guint exo_minor_version = EXO_MINOR_VERSION;
+
+/**
+ * exo_micro_version:
+ *
+ * The micro version number of the exo library (e.g. in exo 1.2.3 this is 3).
+ *
+ * This variable is in the library, and therefore represents the exo
+ * library you have linked against. Contrast with the #EXO_MICRO_VERSION
+ * macro, which represents the micro version of the libexo headers you
+ * have included.
+ **/
const guint exo_micro_version = EXO_MICRO_VERSION;
@@ -61,10 +103,10 @@ const guint exo_micro_version = EXO_MICRO_VERSION;
* </programlisting>
* </example>
*
- * Return value: %NULL if the library is compatible with the given version,
- * or a string describing the version mismatch. The returned
- * string is owned by the library and must not be freed or
- * modified by the caller.
+ * Returns: %NULL if the library is compatible with the given version,
+ * or a string describing the version mismatch. The returned
+ * string is owned by the library and must not be freed or
+ * modified by the caller.
*
* Since: 0.3.1
**/
diff --git a/exo/exo-config.h.in b/exo/exo-config.h.in
index 78c882e..d13a2f3 100644
--- a/exo/exo-config.h.in
+++ b/exo/exo-config.h.in
@@ -31,10 +31,42 @@
G_BEGIN_DECLS
+/**
+ * EXO_MAJOR_VERSION:
+ *
+ * Like #exo_major_version, but from the headers used at application
+ * compile time, rather than from the library linked against at
+ * application run time.
+ **/
#define EXO_MAJOR_VERSION @LIBEXO_VERSION_MAJOR@
+
+/**
+ * EXO_MINOR_VERSION:
+ *
+ * Like #exo_minor_version, but from the headers used at application
+ * compile time, rather than from the library linked against at
+ * application run time.
+ **/
#define EXO_MINOR_VERSION @LIBEXO_VERSION_MINOR@
+
+/**
+ * EXO_MICRO_VERSION:
+ *
+ * Like #exo_micro_version, but from the headers used at application
+ * compile time, rather than from the library linked against at
+ * application run time.
+ **/
#define EXO_MICRO_VERSION @LIBEXO_VERSION_MICRO@
+/**
+ * EXO_CHECK_VERSION:
+ * @major: major version (e.g. 1 for version 1.2.3)
+ * @minor: minor version (e.g. 2 for version 1.2.3)
+ * @micro: micro version (e.g. 3 for version 1.2.3)
+ *
+ * Returns: %TRUE if the version of the exo header files is equal or
+ * better than the passed-in version.
+ **/
#define EXO_CHECK_VERSION(major,minor,micro) \
(EXO_MAJOR_VERSION > (major) \
|| (EXO_MAJOR_VERSION == (major) \
diff --git a/exo/exo-execute.c b/exo/exo-execute.c
index 7965982..22c94ff 100644
--- a/exo/exo-execute.c
+++ b/exo/exo-execute.c
@@ -25,6 +25,25 @@
#include <exo/exo-execute.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-execute
+ * @title: Executing Applications
+ * @short_description: Execute preferred applications
+ * @include: exo/exo.h
+ * @see_also: gtk_show_uri()
+ *
+ * This module provides functions to execute certain kinds of applications,
+ * for which users can select their preferred ones. For example, whenever
+ * you need to run a command in a terminal emulator from within your
+ * application you should use exo_execute_terminal_shell() or
+ * exo_execute_terminal_shell_on_screen() to make sure you run the user's
+ * preferred terminal emulator.
+ * On the other hand if you need to display an URL (i.e. you want to point
+ * the user to the website of your application), you should use gtk_show_uri()
+ * instead, as it will try to automatically determine the appropriate
+ * viewer for a given URI.
+ **/
+
/**
@@ -47,7 +66,7 @@
* that if the execution fails at a later stage, the library will popup
* an error dialog to inform the user that the execution failed.
*
- * Return value: %TRUE on success, else %FALSE.
+ * Returns: %TRUE on success, else %FALSE.
*
* Since: 0.3.1.3
**/
@@ -93,7 +112,7 @@ exo_execute_preferred_application (const gchar *category,
* that if the execution fails at a later stage, the library will popup
* an error dialog to inform the user that the execution failed.
*
- * Return value: %TRUE on success, else %FALSE.
+ * Returns: %TRUE on success, else %FALSE.
*
* Since: 0.3.1.3
**/
@@ -147,7 +166,7 @@ exo_execute_preferred_application_on_screen (const gchar *category,
* fails at a later stage, the library will popup an error dialog to
* inform the user that the execution failed.
*
- * Return value: %TRUE on success, else %FALSE.
+ * Returns: %TRUE on success, else %FALSE.
*
* Since: 0.3.1.3
**/
@@ -189,7 +208,7 @@ exo_execute_terminal_shell (const gchar *command_line,
* fails at a later stage, the library will popup an error dialog to
* inform the user that the execution failed.
*
- * Return value: %TRUE on success, else %FALSE.
+ * Returns: %TRUE on success, else %FALSE.
*
* Since: 0.3.1.3
**/
diff --git a/exo/exo-gdk-pixbuf-extensions.c b/exo/exo-gdk-pixbuf-extensions.c
index 414652c..f44a108 100644
--- a/exo/exo-gdk-pixbuf-extensions.c
+++ b/exo/exo-gdk-pixbuf-extensions.c
@@ -74,6 +74,16 @@
#define _O_BINARY 0
#endif
+/**
+ * SECTION: exo-gdk-pixbuf-extensions
+ * @title: Extensions to gdk-pixbuf
+ * @short_description: Miscelleanous extensions to the gdk-pixbuf library
+ * @include: exo/exo.h
+ *
+ * This facility includes several functions to extend the basic functionality
+ * provided by the gdk-pixbuf library.
+ **/
+
/**
@@ -87,7 +97,7 @@
* The caller is responsible to free the returned object
* using g_object_unref() when no longer needed.
*
- * Return value: the colorized #GdkPixbuf.
+ * Returns: the colorized #GdkPixbuf.
*
* Since: 0.3.1.3
**/
@@ -257,7 +267,7 @@ draw_frame_column (const GdkPixbuf *frame_image,
*
* The caller is responsible to free the returned #GdkPixbuf using g_object_unref().
*
- * Return value: the framed version of @src.
+ * Returns: the framed version of @src.
*
* Since: 0.3.1.9
**/
@@ -334,7 +344,7 @@ exo_gdk_pixbuf_frame (const GdkPixbuf *src,
* The caller is responsible to free the returned object
* using g_object_unref() when no longer needed.
*
- * Return value: a translucent version of @src.
+ * Returns: a translucent version of @src.
*
* Since: 0.3.1.3
**/
@@ -437,7 +447,7 @@ lighten_channel (guchar cur_value)
* The caller is responsible to free the returned
* pixbuf using #g_object_unref().
*
- * Return value: the lightened version of @src.
+ * Returns: the lightened version of @src.
*
* Since: 0.3.1.3
**/
@@ -563,7 +573,7 @@ exo_gdk_pixbuf_spotlight (const GdkPixbuf *src)
* The caller is responsible to free the returned #GdkPixbuf
* using g_object_unref() when no longer needed.
*
- * Return value: the resulting #GdkPixbuf.
+ * Returns: the resulting #GdkPixbuf.
*
* Since: 0.3.1.1
**/
@@ -615,7 +625,7 @@ exo_gdk_pixbuf_scale_down (GdkPixbuf *source,
* Scales @source to @dest_size while preserving the aspect ratio of
* @source.
*
- * Return value: A newly created #GdkPixbuf.
+ * Returns: A newly created #GdkPixbuf.
**/
GdkPixbuf*
exo_gdk_pixbuf_scale_ratio (GdkPixbuf *source,
@@ -713,23 +723,31 @@ size_prepared (GdkPixbufLoader *loader,
/**
* exo_gdk_pixbuf_new_from_file_at_max_size:
- * @filename : name of the file to load, in the GLib file name encoding.
+ * @filename : name of the file to load, in the GLib file
+ * name encoding.
* @max_width : the maximum width of the loaded image.
* @max_height : the maximum height of the loaded image.
- * @preserve_aspect_ratio : %TRUE to preserve the image's aspect ratio while scaling to fit into @max_width and @max_height.
+ * @preserve_aspect_ratio : %TRUE to preserve the image's aspect ratio
+ * while scaling to fit into @max_width and @max_height.
* @error : return location for errors or %NULL.
*
- * Creates a new #GdkPixbuf by loading an image from the file at @filename. The file format is detected automatically. If %NULL
- * is returned, then @error will be set. Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. If the image
- * dimensions exceed @max_width or @max_height, the image will be scaled down to fit into the dimensions, optionally preserving
- * the image's aspect ratio. The image may still be larger, depending on the loader.
+ * Creates a new #GdkPixbuf by loading an image from the file at
+ * @filename. The file format is detected automatically. If %NULL is
+ * returned, then @error will be set. Possible errors are in the
+ * #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. If the image dimensions
+ * exceed @max_width or @max_height, the image will be scaled down to
+ * fit into the dimensions, optionally preservingthe image's aspect
+ * ratio. The image may still be larger, depending on the loader.
*
- * The advantage of using this function over gdk_pixbuf_new_from_file_at_scale() is that images will never be scaled up, which
- * would otherwise result in ugly images.
+ * The advantage of using this function over
+ * gdk_pixbuf_new_from_file_at_scale() is that images will never be
+ * scaled up, whichwould otherwise result in ugly images.
*
- * Return value: a newly created #GdkPixbuf with a reference count or 1, or %NULL if any of several error conditions occurred:
- * the file could not be opened, there was no loader for the file's format, there was not enough memory to allocate
- * the buffer for the image, or the image file contained invalid data.
+ * Returns: a newly created #GdkPixbuf with a reference count or 1, or
+ * %NULL if any of several error conditions occurred: the file
+ * could not be opened, there was no loader for the file's format,
+ * there was not enough memory to allocate the buffer for the
+ * image, or the image file contained invalid data.
*
* Since: 0.3.1.9
**/
diff --git a/exo/exo-gobject-extensions.c b/exo/exo-gobject-extensions.c
index 533ff7b..ce4a6a9 100644
--- a/exo/exo-gobject-extensions.c
+++ b/exo/exo-gobject-extensions.c
@@ -27,6 +27,18 @@
#include <exo/exo-gobject-extensions.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-gobject-extensions
+ * @title: Extensions to GObject
+ * @short_description: Miscelleanous extensions to the gdk-pixbuf library
+ * @include: exo/exo.h
+ * @see_also: <ulink url="http://library.gnome.org/devel/gobject/stable/">
+ * GObject Reference Manual</ulink>
+ *
+ * This facility includes several functions to extend the basic
+ * functionality provided by the GObject library.
+ **/
+
/**
@@ -40,7 +52,7 @@
* This function is mostly useful for binding boolean properties
* with inversing.
*
- * Return value: %TRUE on successful transformation.
+ * Returns: %TRUE on successful transformation.
**/
gboolean
exo_g_value_transform_negate (const GValue *src_value,
diff --git a/exo/exo-gtk-extensions.c b/exo/exo-gtk-extensions.c
index baf7e6b..84792ea 100644
--- a/exo/exo-gtk-extensions.c
+++ b/exo/exo-gtk-extensions.c
@@ -33,6 +33,21 @@
#include <exo/exo-thumbnail-preview.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-gtk-extensions
+ * @title: Extensions to Gtk+
+ * @short_description: Miscelleanous extensions to the Gtk+ library
+ * @include: exo/exo.h
+ *
+ * Various additional functions to the core API provided by the Gtk+ library.
+ *
+ * For example, exo_gtk_file_chooser_add_thumbnail_preview() is a
+ * convenience method to add a thumbnail based preview widget to a
+ * #GtkFileChooser, which will display a preview of the selected file if
+ * either a thumbnail is available or a thumbnail could be generated using
+ * the GdkPixbuf library.
+ **/
+
static gboolean
@@ -156,8 +171,11 @@ exo_gtk_file_chooser_add_thumbnail_preview (GtkFileChooser *chooser)
* <informalexample><programlisting>
* static void show_about_dialog (void)
* {
+ * #if !GTK_CHECK_VERSION (2, 18, 0)
* gtk_about_dialog_set_email_hook (exo_gtk_url_about_dialog_hook, NULL, NULL);
* gtk_about_dialog_set_url_hook (exo_gtk_url_about_dialog_hook, NULL, NULL);
+ * #endif
+ *
* gtk_show_about_dialog (.....);
* }
* </programlisting></informalexample>
diff --git a/exo/exo-gtk-extensions.h b/exo/exo-gtk-extensions.h
index 4a2e6f2..8073706 100644
--- a/exo/exo-gtk-extensions.h
+++ b/exo/exo-gtk-extensions.h
@@ -35,9 +35,9 @@ void exo_gtk_object_destroy_later (GtkObject *object);
void exo_gtk_file_chooser_add_thumbnail_preview (GtkFileChooser *chooser);
-void exo_gtk_url_about_dialog_hook (GtkAboutDialog *about,
+void exo_gtk_url_about_dialog_hook (GtkAboutDialog *about_dialog,
const gchar *link,
- gpointer data);
+ gpointer user_data);
G_END_DECLS
diff --git a/exo/exo-icon-bar.c b/exo/exo-icon-bar.c
index 4c1ab6e..95f1a40 100644
--- a/exo/exo-icon-bar.c
+++ b/exo/exo-icon-bar.c
@@ -31,6 +31,56 @@
#include <exo/exo-string.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-icon-bar
+ * @title: ExoIconBar
+ * @short_description: A widget for displaying icon bars
+ * @include: exo/exo.h
+ * @see_also: <ulink url="http://library.gnome.org/devel/gtk/stable/GtkTreeModel.html">
+ * GtkTreeModel</ulink>,
+ * <ulink url="http://library.gnome.org/devel/gtk/stable/TreeWidget.html">
+ * Tree and List Widget Overview</ulink>
+ *
+ * A widget that displays any object that implements the #GtkTreeModel interface
+ * in an icon bar.
+ *
+ * <example>
+ * <title>
+ * Creating a new <structname>ExoIconBar</structname> with a <structname>GtkListStore</structname>
+ * </title>
+ * <programlisting>
+ * enum
+ * {
+ * PIXBUF_COLUMN,
+ * STRING_COLUMN,
+ * N_COLUMNS,
+ * };
+ *
+ * {
+ * GtkListStore *store;
+ * GtkWidget *bar;
+ *
+ * // make a new list store
+ * store = gtk_list_store_new (N_COLUMNS, GDK_TYPE_PIXBUF, G_TYPE_STRING);
+ *
+ * // fill the store with data
+ * fill_store (store);
+ *
+ * // create the icon bar
+ * bar = exo_icon_bar_new_with_model (GTK_TREE_MODEL (store));
+ * exo_icon_bar_set_pixbuf_column (EXO_ICON_BAR (bar), PIXBUF_COLUMN);
+ * exo_icon_bar_set_text_column (EXO_ICON_BAR (bar), TEXT_COLUMN);
+ * gtk_widget_show (bar);
+ *
+ * // the icon bar keeps a reference on the store now
+ * g_object_unref (G_OBJECT (store));
+ *
+ * // add the bar to your GUI now...
+ * }
+ * </programlisting>
+ * </example>
+ **/
+
#define MINIMUM_ICON_ITEM_WIDTH 32
@@ -1410,7 +1460,9 @@ exo_icon_bar_rows_reordered (GtkTreeModel *model,
/**
* exo_icon_bar_new:
*
- * Return value: a newly allocated #ExoIconBar.
+ * Creates a new #ExoIconBar without model.
+ *
+ * Returns: a newly allocated #ExoIconBar.
**/
GtkWidget*
exo_icon_bar_new (void)
@@ -1427,8 +1479,7 @@ exo_icon_bar_new (void)
* Creates a new #ExoIconBar and associates it with
* @model.
*
- * Return value: a newly allocated #ExoIconBar, which
- * is associated with @model.
+ * Returns: a newly allocated #ExoIconBar, which is associated with @model.
**/
GtkWidget*
exo_icon_bar_new_with_model (GtkTreeModel *model)
@@ -1449,7 +1500,7 @@ exo_icon_bar_new_with_model (GtkTreeModel *model)
* Returns the model the #ExoIconBar is based on. Returns %NULL if
* the model is unset.
*
- * Return value: A #GtkTreeModel, or %NULL if none is currently being used.
+ * Returns: A #GtkTreeModel, or %NULL if none is currently being used.
**/
GtkTreeModel*
exo_icon_bar_get_model (ExoIconBar *icon_bar)
@@ -1560,7 +1611,7 @@ exo_icon_bar_set_model (ExoIconBar *icon_bar,
*
* Returns the column with pixbufs for @icon_bar.
*
- * Return value: the pixbuf column, or -1 if it's unset.
+ * Returns: the pixbuf column, or -1 if it's unset.
**/
gint
exo_icon_bar_get_pixbuf_column (ExoIconBar *icon_bar)
@@ -1618,7 +1669,7 @@ exo_icon_bar_set_pixbuf_column (ExoIconBar *icon_bar,
*
* Returns the column with text for @icon_bar.
*
- * Return value: the text column, or -1 if it's unset.
+ * Returns: the text column, or -1 if it's unset.
**/
gint
exo_icon_bar_get_text_column (ExoIconBar *icon_bar)
@@ -1678,7 +1729,7 @@ exo_icon_bar_set_text_column (ExoIconBar *icon_bar,
* Retrieves the current orientation of the toolbar. See
* exo_icon_bar_set_orientation().
*
- * Return value: The orientation of @icon_bar.
+ * Returns: The orientation of @icon_bar.
**/
GtkOrientation
exo_icon_bar_get_orientation (ExoIconBar *icon_bar)
@@ -1720,8 +1771,8 @@ exo_icon_bar_set_orientation (ExoIconBar *icon_bar,
* Returns the index of the currently active item, or -1 if there's no
* active item.
*
- * Return value: An integer which is the index of the currently active item,
- * or -1 if there's no active item.
+ * Returns: An integer which is the index of the currently active item,
+ * or -1 if there's no active item.
**/
gint
exo_icon_bar_get_active (ExoIconBar *icon_bar)
@@ -1773,7 +1824,7 @@ exo_icon_bar_set_active (ExoIconBar *icon_bar,
*
* Sets @iter to point to the current active item, if it exists.
*
- * Return value: %TRUE if @iter was set.
+ * Returns: %TRUE if @iter was set.
**/
gboolean
exo_icon_bar_get_active_iter (ExoIconBar *icon_bar,
diff --git a/exo/exo-icon-bar.h b/exo/exo-icon-bar.h
index 8f16500..8fa4526 100644
--- a/exo/exo-icon-bar.h
+++ b/exo/exo-icon-bar.h
@@ -42,6 +42,11 @@ typedef struct _ExoIconBarPrivate ExoIconBarPrivate;
typedef struct _ExoIconBarClass ExoIconBarClass;
typedef struct _ExoIconBar ExoIconBar;
+/**
+ * ExoIconBarClass:
+ * @set_scroll_adjustments : Used internally to make the ExoIconBar scrollable.
+ * @selection_changed : This signal is emitted whenever the currently selected icon changes.
+ **/
struct _ExoIconBarClass
{
GtkContainerClass __parent__;
@@ -52,12 +57,19 @@ struct _ExoIconBarClass
GtkAdjustment *vadjustment);
void (*selection_changed) (ExoIconBar *icon_bar);
+ /*< private >*/
void (*reserved1) (void);
void (*reserved2) (void);
void (*reserved3) (void);
void (*reserved4) (void);
};
+/**
+ * ExoIconBar:
+ *
+ * The #ExoIconBar struct contains only private fields and should not
+ * be directly accessed.
+ **/
struct _ExoIconBar
{
GtkContainer __parent__;
diff --git a/exo/exo-icon-chooser-dialog.c b/exo/exo-icon-chooser-dialog.c
index 11a17c1..4136de2 100644
--- a/exo/exo-icon-chooser-dialog.c
+++ b/exo/exo-icon-chooser-dialog.c
@@ -44,9 +44,23 @@
#include <exo/exo-private.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-icon-chooser-dialog
+ * @title: ExoIconChooserDialog
+ * @short_description: Dialog to select icons
+ * @include: exo/exo.h
+ * @see_also: <ulink type="http" href="http://library.gnome.org/devel/gtk/stable/GtkIconTheme.html">
+ * GtkIconTheme</ulink>
+ *
+ * The #ExoIconChooserDialog class provides an easy to use dialog to ask
+ * the user to select either a named icon from the selected icon theme,
+ * or an image file from the local file system.
+ **/
+
-#define EXO_ICON_CHOOSER_DIALOG_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_ICON_CHOOSER_DIALOG, ExoIconChooserDialogPrivate))
+#define EXO_ICON_CHOOSER_DIALOG_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_ICON_CHOOSER_DIALOG, ExoIconChooserDialogPrivate))
@@ -462,7 +476,7 @@ exo_icon_chooser_dialog_selection_changed (ExoIconChooserDialog *icon_chooser_di
*
* Creates a new #ExoIconChooserDialog. This function is analogous to gtk_dialog_new_with_buttons().
*
- * Return value: a new #ExoIconChooserDialog.
+ * Returns: a new #ExoIconChooserDialog.
*
* Since: 0.3.1.9
**/
@@ -511,7 +525,7 @@ exo_icon_chooser_dialog_new (const gchar *title,
*
* The caller is responsible to free the returned string using g_free() when no longer needed.
*
- * Return value: the currently selected icon for @icon_chooser_dialog or %NULL if no icon is selected.
+ * Returns: the currently selected icon for @icon_chooser_dialog or %NULL if no icon is selected.
*
* Since: 0.3.1.9
**/
@@ -568,8 +582,8 @@ exo_icon_chooser_dialog_get_icon (ExoIconChooserDialog *icon_chooser_dialog)
* Preselects the specified @icon in the @icon_chooser_dialog, and returns %TRUE if the
* @icon was successfully selected.
*
- * Return value: %TRUE if the @icon was successfully preselected in the @icon_chooser_dialog,
- * %FALSE otherwise.
+ * Returns: %TRUE if the @icon was successfully preselected in the @icon_chooser_dialog,
+ * %FALSE otherwise.
*
* Since: 0.3.1.9
**/
diff --git a/exo/exo-icon-chooser-model.c b/exo/exo-icon-chooser-model.c
index c3b603b..008eae6 100644
--- a/exo/exo-icon-chooser-model.c
+++ b/exo/exo-icon-chooser-model.c
@@ -535,7 +535,7 @@ exo_icon_chooser_model_item_free (ExoIconChooserModelItem *item)
* caller is responsible to free the returned object using g_object_unref()
* when no longer needed.
*
- * Return value: an #ExoIconChooserModel for the @widget.
+ * Returns: an #ExoIconChooserModel for the @widget.
*
* Since: 0.3.1.9
**/
@@ -563,7 +563,7 @@ _exo_icon_chooser_model_get_for_widget (GtkWidget *widget)
* caller is responsible to free the returned object using g_object_unref()
* when no longer needed.
*
- * Return value: an #ExoIconChooserModel for the @icon_theme.
+ * Returns: an #ExoIconChooserModel for the @icon_theme.
*
* Since: 0.3.1.9
**/
@@ -607,7 +607,7 @@ _exo_icon_chooser_model_get_for_icon_theme (GtkIconTheme *icon_theme)
* Looks up the #GtkTreeIter for the @icon_name in the @model and returns %TRUE if the
* @icon_name was found, %FALSE otherwise.
*
- * Return value: %TRUE if the iterator for @icon_name was found, %FALSE otherwise.
+ * Returns: %TRUE if the iterator for @icon_name was found, %FALSE otherwise.
*
* Since: 0.3.1.9
**/
diff --git a/exo/exo-icon-view.c b/exo/exo-icon-view.c
index 4ea75be..7a64a65 100644
--- a/exo/exo-icon-view.c
+++ b/exo/exo-icon-view.c
@@ -49,6 +49,20 @@
#include <exo/exo-string.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-icon-view
+ * @title: ExoIconView
+ * @short_description: A widget which displays a list of icons in a grid
+ * @include: exo/exo.h
+ *
+ * #ExoIconView provides an alternative view on a list model.
+ * It displays the model as a grid of icons with labels. Like
+ * #GtkTreeView, it allows to select one or multiple items
+ * (depending on the selection mode, see exo_icon_view_set_selection_mode()).
+ * In addition to selection with the arrow keys, #ExoIconView supports
+ * rubberband selection, which is controlled by dragging the pointer.
+ **/
+
/* the search dialog timeout (in ms) */
@@ -928,7 +942,7 @@ exo_icon_view_class_init (ExoIconViewClass *klass)
/**
* ExoIconView::item-activated:
* @icon_view : a #ExoIconView.
- * @path :
+ * @path : the #GtkTreePath of the activated item.
**/
icon_view_signals[ITEM_ACTIVATED] =
g_signal_new (I_("item-activated"),
@@ -956,8 +970,8 @@ exo_icon_view_class_init (ExoIconViewClass *klass)
/**
* ExoIconView::set-scroll-adjustments:
* @icon_view : a #ExoIconView.
- * @hadjustment :
- * @vadjustment :
+ * @hadjustment : the new horizontal #GtkAdjustment.
+ * @vadjustment : the new vertical #GtkAdjustment.
**/
gtkwidget_class->set_scroll_adjustments_signal =
g_signal_new (I_("set-scroll-adjustments"),
@@ -1025,7 +1039,7 @@ exo_icon_view_class_init (ExoIconViewClass *klass)
* ExoIconView::activate-cursor-item:
* @icon_view : a #ExoIconView.
*
- * Return value:
+ * Returns:
**/
icon_view_signals[ACTIVATE_CURSOR_ITEM] =
g_signal_new (I_("activate-cursor-item"),
@@ -1040,7 +1054,7 @@ exo_icon_view_class_init (ExoIconViewClass *klass)
* ExoIconView::start-interactive-search:
* @iconb_view : a #ExoIconView.
*
- * Return value:
+ * Returns:
**/
icon_view_signals[START_INTERACTIVE_SEARCH] =
g_signal_new (I_("start-interactive-search"),
@@ -1057,7 +1071,7 @@ exo_icon_view_class_init (ExoIconViewClass *klass)
* @step :
* @count :
*
- * Return value:
+ * Returns:
**/
icon_view_signals[MOVE_CURSOR] =
g_signal_new (I_("move-cursor"),
@@ -4824,7 +4838,7 @@ exo_icon_view_cell_layout_reorder (GtkCellLayout *layout,
*
* Creates a new #ExoIconView widget
*
- * Return value: A newly created #ExoIconView widget
+ * Returns: A newly created #ExoIconView widget
**/
GtkWidget*
exo_icon_view_new (void)
@@ -4840,7 +4854,7 @@ exo_icon_view_new (void)
*
* Creates a new #ExoIconView widget with the model @model.
*
- * Return value: A newly created #ExoIconView widget.
+ * Returns: A newly created #ExoIconView widget.
**/
GtkWidget*
exo_icon_view_new_with_model (GtkTreeModel *model)
@@ -4856,11 +4870,11 @@ exo_icon_view_new_with_model (GtkTreeModel *model)
/**
* exo_icon_view_widget_to_icon_coords:
- * @icon_view : a #ExoIconView.
- * @wx : widget x coordinate.
- * @wy : widget y coordinate.
- * @ix : return location for icon x coordinate or %NULL.
- * @iy : return location for icon y coordinate or %NULL.
+ * @icon_view: a #ExoIconView.
+ * @wx: widget x coordinate.
+ * @wy: widget y coordinate.
+ * @ix: return location for icon x coordinate or %NULL.
+ * @iy: return location for icon y coordinate or %NULL.
*
* Converts widget coordinates to coordinates for the icon window
* (the full scrollable area of the icon view).
@@ -4920,8 +4934,8 @@ exo_icon_view_icon_to_widget_coords (const ExoIconView *icon_view,
* See exo_icon_view_get_item_at_pos(), if you are also interested in
* the cell at the specified position.
*
- * Return value: The #GtkTreePath corresponding to the icon or %NULL
- * if no icon exists at that position.
+ * Returns: The #GtkTreePath corresponding to the icon or %NULL
+ * if no icon exists at that position.
**/
GtkTreePath*
exo_icon_view_get_path_at_pos (const ExoIconView *icon_view,
@@ -4957,7 +4971,7 @@ exo_icon_view_get_path_at_pos (const ExoIconView *icon_view,
* obtains the cell at the specified position. The returned path should
* be freed with gtk_tree_path_free().
*
- * Return value: %TRUE if an item exists at the specified position
+ * Returns: %TRUE if an item exists at the specified position
*
* Since: 0.3.1
**/
@@ -4997,7 +5011,7 @@ exo_icon_view_get_item_at_pos (const ExoIconView *icon_view,
*
* Both paths should be freed with gtk_tree_path_free() after use.
*
- * Return value: %TRUE, if valid paths were placed in @start_path and @end_path
+ * Returns: %TRUE, if valid paths were placed in @start_path and @end_path
*
* Since: 0.3.1
**/
@@ -5080,7 +5094,7 @@ exo_icon_view_selected_foreach (ExoIconView *icon_view,
*
* Gets the selection mode of the @icon_view.
*
- * Return value: the current selection mode
+ * Returns: the current selection mode
**/
GtkSelectionMode
exo_icon_view_get_selection_mode (const ExoIconView *icon_view)
@@ -5124,7 +5138,7 @@ exo_icon_view_set_selection_mode (ExoIconView *icon_view,
* Returns the #ExoIconViewLayoutMode used to layout the
* items in the @icon_view.
*
- * Return value: the layout mode of @icon_view.
+ * Returns: the layout mode of @icon_view.
*
* Since: 0.3.1.5
**/
@@ -5179,7 +5193,7 @@ exo_icon_view_set_layout_mode (ExoIconView *icon_view,
* Returns the model the #ExoIconView is based on. Returns %NULL if the
* model is unset.
*
- * Return value: A #GtkTreeModel, or %NULL if none is currently being used.
+ * Returns: A #GtkTreeModel, or %NULL if none is currently being used.
**/
GtkTreeModel*
exo_icon_view_get_model (const ExoIconView *icon_view)
@@ -5518,7 +5532,7 @@ exo_icon_view_unselect_path (ExoIconView *icon_view,
* g_list_free (list);
* </programlisting></informalexample>
*
- * Return value: A #GList containing a #GtkTreePath for each selected row.
+ * Returns: A #GList containing a #GtkTreePath for each selected row.
**/
GList*
exo_icon_view_get_selected_items (const ExoIconView *icon_view)
@@ -5604,7 +5618,7 @@ exo_icon_view_unselect_all (ExoIconView *icon_view)
* Returns %TRUE if the icon pointed to by @path is currently
* selected. If @icon does not point to a valid location, %FALSE is returned.
*
- * Return value: %TRUE if @path is selected.
+ * Returns: %TRUE if @path is selected.
**/
gboolean
exo_icon_view_path_is_selected (const ExoIconView *icon_view,
@@ -5654,7 +5668,7 @@ exo_icon_view_item_activated (ExoIconView *icon_view,
*
* The returned #GtkTreePath must be freed with gtk_tree_path_free().
*
- * Return value: %TRUE if the cursor is set.
+ * Returns: %TRUE if the cursor is set.
*
* Since: 0.3.1
**/
@@ -5850,7 +5864,7 @@ exo_icon_view_scroll_to_path (ExoIconView *icon_view,
* Returns the value of the ::orientation property which determines
* whether the labels are drawn beside the icons instead of below.
*
- * Return value: the relative position of texts and icons
+ * Returns: the relative position of texts and icons
*
* Since: 0.3.1
**/
@@ -5901,7 +5915,7 @@ exo_icon_view_set_orientation (ExoIconView *icon_view,
*
* Returns the value of the ::columns property.
*
- * Return value: the number of columns, or -1
+ * Returns: the number of columns, or -1
*/
gint
exo_icon_view_get_columns (const ExoIconView *icon_view)
@@ -5949,7 +5963,7 @@ exo_icon_view_set_columns (ExoIconView *icon_view,
*
* Returns the value of the ::item-width property.
*
- * Return value: the width of a single item, or -1
+ * Returns: the width of a single item, or -1
*
* Since: 0.3.1
*/
@@ -6000,7 +6014,7 @@ exo_icon_view_set_item_width (ExoIconView *icon_view,
*
* Returns the value of the ::spacing property.
*
- * Return value: the space between cells
+ * Returns: the space between cells
*
* Since: 0.3.1
*/
@@ -6049,7 +6063,7 @@ exo_icon_view_set_spacing (ExoIconView *icon_view,
*
* Returns the value of the ::row-spacing property.
*
- * Return value: the space between rows
+ * Returns: the space between rows
*
* Since: 0.3.1
*/
@@ -6097,7 +6111,7 @@ exo_icon_view_set_row_spacing (ExoIconView *icon_view,
*
* Returns the value of the ::column-spacing property.
*
- * Return value: the space between columns
+ * Returns: the space between columns
*
* Since: 0.3.1
**/
@@ -6145,7 +6159,7 @@ exo_icon_view_set_column_spacing (ExoIconView *icon_view,
*
* Returns the value of the ::margin property.
*
- * Return value: the space at the borders
+ * Returns: the space at the borders
*
* Since: 0.3.1
**/
@@ -7218,7 +7232,7 @@ exo_icon_view_get_drag_dest_item (ExoIconView *icon_view,
* #exo_icon_view_widget_to_icon_coords() if you need to translate
* widget coordinates first.
*
- * Return value: whether there is an item at the given position.
+ * Returns: whether there is an item at the given position.
*
* Since: 0.3.1
**/
@@ -7278,7 +7292,7 @@ exo_icon_view_get_dest_item_at_pos (ExoIconView *icon_view,
* Creates a #GdkPixmap representation of the item at @path.
* This image is used for a drag icon.
*
- * Return value: a newly-allocated pixmap of the drag icon.
+ * Returns: a newly-allocated pixmap of the drag icon.
*
* Since: 0.3.1
**/
@@ -7344,7 +7358,7 @@ exo_icon_view_create_drag_icon (ExoIconView *icon_view,
* Retrieves whether the user can reorder the list via drag-and-drop.
* See exo_icon_view_set_reorderable().
*
- * Return value: %TRUE if the list can be reordered.
+ * Returns: %TRUE if the list can be reordered.
*
* Since: 0.3.1
**/
@@ -7421,7 +7435,7 @@ exo_icon_view_set_reorderable (ExoIconView *icon_view,
* Returns %TRUE if @icon_view is currently in single click mode,
* else %FALSE will be returned.
*
- * Return value: whether @icon_view is currently in single click mode.
+ * Returns: whether @icon_view is currently in single click mode.
*
* Since: 0.3.1.3
**/
@@ -7472,8 +7486,8 @@ exo_icon_view_set_single_click (ExoIconView *icon_view,
* in single click mode. A value of %0 means that the behavior
* is disabled and the user must alter the selection manually.
*
- * Return value: the single click autoselect timeout or %0 if
- * the behavior is disabled.
+ * Returns: the single click autoselect timeout or %0 if
+ * the behavior is disabled.
*
* Since: 0.3.1.5
**/
@@ -7625,8 +7639,7 @@ exo_icon_view_single_click_timeout_destroy (gpointer user_data)
* Returns whether or not the @icon_view allows to start
* interactive searching by typing in text.
*
- * Return value: whether or not to let the user search
- * interactively.
+ * Returns: whether or not to let the user search interactively.
*
* Since: 0.3.1.3
**/
@@ -7675,7 +7688,7 @@ exo_icon_view_set_enable_search (ExoIconView *icon_view,
*
* Returns the column searched on by the interactive search code.
*
- * Return value: the column the interactive search code searches in.
+ * Returns: the column the interactive search code searches in.
*
* Since: 0.3.1.3
**/
@@ -7725,7 +7738,7 @@ exo_icon_view_set_search_column (ExoIconView *icon_view,
*
* Returns the compare function currently in use.
*
- * Return value: the currently used compare function for the search code.
+ * Returns: the currently used compare function for the search code.
*
* Since: 0.3.1.3
**/
@@ -7780,7 +7793,7 @@ exo_icon_view_set_search_equal_func (ExoIconView *icon_view,
*
* Returns the search dialog positioning function currently in use.
*
- * Return value: the currently used function for positioning the search dialog.
+ * Returns: the currently used function for positioning the search dialog.
*
* Since: 0.3.1.3
**/
diff --git a/exo/exo-icon-view.h b/exo/exo-icon-view.h
index 44affda..44f26b6 100644
--- a/exo/exo-icon-view.h
+++ b/exo/exo-icon-view.h
@@ -68,7 +68,7 @@ typedef void (*ExoIconViewForeachFunc) (ExoIconView *icon_view,
* entered by the user. Note the return value is reversed from what you would normally
* expect, though it has some similarity to strcmp() returning 0 for equal strings.
*
- * Return value: %FALSE if the row matches, %TRUE otherwise.
+ * Returns: %FALSE if the row matches, %TRUE otherwise.
**/
typedef gboolean (*ExoIconViewSearchEqualFunc) (GtkTreeModel *model,
gint column,
diff --git a/exo/exo-job.c b/exo/exo-job.c
index 5d27dde..b90fa08 100644
--- a/exo/exo-job.c
+++ b/exo/exo-job.c
@@ -33,9 +33,32 @@
#include <exo/exo-string.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-job
+ * @title: ExoJob
+ * @short_description: Base class for threaded/asynchronous jobs
+ * @include: exo/exo.h
+ * @see_also: <link linkend="ExoSimpleJob">ExoSimpleJob</link>
+ *
+ * <link linkend="ExoJob">ExoJob</link> is an abstract base class
+ * intended to wrap threaded/asynchronous operations (called jobs here).
+ * It was written because the ways of dealing with threads provided by
+ * GLib were too low-level and not exactly object-oriented.
+ *
+ * It can be used to wrap any kind of long-running or possibly-blocking
+ * operation, like file operations or communication with web services.
+ * The benefit of using <link linkend="ExoJob">ExoJob</link> is that you
+ * get an object associated with an operation. After creating the job
+ * you can connect to signals like <link linkend="ExoJob::error">"error"
+ * </link> or <link linkend="ExoJob::percent">"percent"</link>. This
+ * design integrates very well in the usual object-oriented design of
+ * applications based on GLib.
+ **/
-#define EXO_JOB_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_JOB, ExoJobPrivate))
+
+#define EXO_JOB_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_JOB, ExoJobPrivate))
@@ -210,7 +233,7 @@ exo_job_finalize (GObject *object)
* Finishes the execution of an operation by propagating errors
* from the @result into @error.
*
- * Return value: %TRUE if there was no error during the operation,
+ * Returns: %TRUE if there was no error during the operation,
* %FALSE otherwise.
**/
static gboolean
@@ -272,8 +295,7 @@ exo_job_async_ready (GObject *object,
* operation associated with the job. It basically calls the
* ExoJobClass#execute function.
*
- * Return value: %FALSE, to stop the thread at the end of the
- * operation.
+ * Returns: %FALSE, to stop the thread at the end of the operation.
**/
static gboolean
exo_job_scheduler_job_func (GIOSchedulerJob *scheduler_job,
@@ -314,7 +336,7 @@ exo_job_scheduler_job_func (GIOSchedulerJob *scheduler_job,
* Called from the main loop of the application to emit the signal
* specified by the @user_data.
*
- * Return value: %FALSE, to keep the function from being called
+ * Returns: %FALSE, to keep the function from being called
* multiple times in a row.
**/
static gboolean
@@ -420,7 +442,7 @@ exo_job_finished (ExoJob *job)
* returned #ExoJob in order to be notified on errors, progress updates
* and the end of the operation.
*
- * Return value: the @job itself.
+ * Returns: the @job itself.
**/
ExoJob *
exo_job_launch (ExoJob *job)
@@ -475,7 +497,7 @@ exo_job_cancel (ExoJob *job)
* Checks whether @job was previously cancelled
* by a call to exo_job_cancel().
*
- * Return value: %TRUE if @job is cancelled.
+ * Returns: %TRUE if @job is cancelled.
**/
gboolean
exo_job_is_cancelled (const ExoJob *job)
@@ -492,8 +514,8 @@ exo_job_is_cancelled (const ExoJob *job)
*
* Returns the #GCancellable that can be used to cancel the @job.
*
- * Return value: the #GCancellable associated with the @job. It
- * is owned by the @job and must not be released.
+ * Returns: the #GCancellable associated with the @job. It
+ * is owned by the @job and must not be released.
**/
GCancellable *
exo_job_get_cancellable (const ExoJob *job)
@@ -517,8 +539,7 @@ exo_job_get_cancellable (const ExoJob *job)
* g_cancellable_set_error_if_cancelled (cancellable, error);
* </programlisting></informalexample>
*
- * Return value: %TRUE if the job was cancelled and @error is now set,
- * %FALSE otherwise.
+ * Returns: %TRUE if the job was cancelled and @error is now set, %FALSE otherwise.
**/
gboolean
exo_job_set_error_if_cancelled (ExoJob *job,
@@ -535,7 +556,7 @@ exo_job_set_error_if_cancelled (ExoJob *job,
* @job : an #ExoJob.
* @signal_id : the signal id.
* @signal_detail : the signal detail.
- * ... : a list of parameters to be passed to the signal,
+ * @Varargs : 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.
@@ -562,9 +583,9 @@ exo_job_emit (ExoJob *job,
/**
* exo_job_info_message:
- * @job : an #ExoJob.
- * @format : a format string.
- * ... : parameters for the format string.
+ * @job : an #ExoJob.
+ * @format : a format string.
+ * @Varargs : parameters for the format string.
*
* Generates and emits an "info-message" signal and sends it to the
* application's main loop.
@@ -611,7 +632,18 @@ exo_job_percent (ExoJob *job,
-
+/**
+ * exo_job_send_to_mainloop:
+ * @job : an #ExoJob.
+ * @func : a #GSourceFunc callback that will be called in the main thread.
+ * @user_data : data to pass to @func.
+ * @destroy_notify : a #GDestroyNotify for @user_data, or %NULL.
+ *
+ * This functions schedules the @job to be run in the main loop (main thread),
+ * waiting for the result (and thus blocking the I/O job).
+ *
+ * Returns: The return value of @func.
+ **/
gboolean
exo_job_send_to_mainloop (ExoJob *job,
GSourceFunc func,
diff --git a/exo/exo-job.h b/exo/exo-job.h
index a692c4b..b2d8452 100644
--- a/exo/exo-job.h
+++ b/exo/exo-job.h
@@ -58,6 +58,12 @@ struct _ExoJobClass
gdouble percent);
};
+/**
+ * ExoJob:
+ *
+ * The #ExoJob struct contains only private fields and should not be
+ * directly accessed.
+ **/
struct _ExoJob
{
GObject __parent__;
diff --git a/exo/exo-mount-point.c b/exo/exo-mount-point.c
index 92ff40f..67c886f 100644
--- a/exo/exo-mount-point.c
+++ b/exo/exo-mount-point.c
@@ -72,6 +72,19 @@
#include <exo/exo-string.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-mount-point
+ * @title: Mount Points
+ * @short_description: Functions to query active and configured mount points
+ * @include: exo/exo.h
+ *
+ * This module provides functions to query active and configured mount
+ * points from the system. This is commonly required in file and volume
+ * management, and hence it was added to the library. For example,
+ * <command>exo-mount</command>, <command>Thunar</command> and
+ * <command>thunar-volman</command> make use of this.
+ **/
+
/* define _PATH_FSTAB if undefined */
@@ -458,7 +471,7 @@ exo_mount_point_get_type (void)
* point using exo_mount_point_free() when no longer
* needed.
*
- * Return value: a copy of the specified @mount_point.
+ * Returns: a copy of the specified @mount_point.
*
* Since: 0.3.1.13
**/
@@ -534,7 +547,7 @@ exo_mount_point_free (ExoMountPoint *mount_point)
* </programlisting></informalexample>
* when no longer needed.
*
- * Return value: the list of matching #ExoMountPoint<!---->s.
+ * Returns: the list of matching #ExoMountPoint<!---->s.
*
* Since: 0.3.1.13
**/
diff --git a/exo/exo-mount-point.h b/exo/exo-mount-point.h
index 658bf4d..539f087 100644
--- a/exo/exo-mount-point.h
+++ b/exo/exo-mount-point.h
@@ -44,6 +44,18 @@ typedef enum /*< flags >*/
#define EXO_TYPE_MOUNT_POINT (exo_mount_point_get_type ())
+/**
+ * ExoMountPoint:
+ * @flags : see #ExoMountPointFlags.
+ * @device : the device file path.
+ * @folder : the folder where the device is mounted (or may be mounted).
+ * @fstype : the type of the file system used for the device.
+ *
+ * Structure to represent a mount point, which can be either an active
+ * mount point, queried from the kernel's internal mount table, or a
+ * configured mount point queried from the file system table (usually
+ * <filename>/etc/fstab</filename> or <filename>/etc/vfstab</filename>).
+ **/
typedef struct _ExoMountPoint ExoMountPoint;
struct _ExoMountPoint
{
@@ -101,7 +113,7 @@ GSList *exo_mount_point_list_matched (ExoMountPointMatchMask mask,
* </programlisting></informalexample>
* when no longer needed.
*
- * Return value: the list of currently active mount points.
+ * Returns: the list of currently active mount points.
*
* Since: 0.3.1.13
**/
@@ -122,7 +134,7 @@ GSList *exo_mount_point_list_matched (ExoMountPointMatchMask mask,
* </programlisting></informalexample>
* when no longer needed.
*
- * Return value: the list of configured mount points.
+ * Returns: the list of configured mount points.
*
* Since: 0.3.1.13
**/
diff --git a/exo/exo-simple-job.c b/exo/exo-simple-job.c
index 26ee5b5..94c0b20 100644
--- a/exo/exo-simple-job.c
+++ b/exo/exo-simple-job.c
@@ -40,6 +40,16 @@
#include <exo/exo-simple-job.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-simple-job
+ * @title: ExoSimpleJob
+ * @short_description: FIXME
+ * @include: exo/exo.h
+ * @see_also:
+ *
+ * FIXME
+ **/
+
static void exo_simple_job_finalize (GObject *object);
@@ -53,6 +63,12 @@ struct _ExoSimpleJobClass
ExoJobClass __parent__;
};
+/**
+ * ExoSimpleJob:
+ *
+ * The #ExoSimpleJob struct contains only private fields and should not be
+ * directly accessed.
+ **/
struct _ExoSimpleJob
{
ExoJob __parent__;
@@ -158,7 +174,7 @@ exo_simple_job_execute (ExoJob *job,
* The caller is responsible to release the returned object using
* g_object_unref() when no longer needed.
*
- * Return value: the launched #ExoJob.
+ * Returns: the launched #ExoJob.
**/
ExoJob*
exo_simple_job_launch (ExoSimpleJobFunc func,
diff --git a/exo/exo-simple-job.h b/exo/exo-simple-job.h
index e824b24..d20747d 100644
--- a/exo/exo-simple-job.h
+++ b/exo/exo-simple-job.h
@@ -39,7 +39,7 @@ G_BEGIN_DECLS
* Used by the #ExoSimpleJob to process the @job. See exo_simple_job_launch()
* for further details.
*
- * Return value: %TRUE on success, %FALSE in case of an error.
+ * Returns: %TRUE on success, %FALSE in case of an error.
**/
typedef gboolean (*ExoSimpleJobFunc) (ExoJob *job,
GValueArray *param_values,
diff --git a/exo/exo-string.c b/exo/exo-string.c
index b381fdb..920f26c 100644
--- a/exo/exo-string.c
+++ b/exo/exo-string.c
@@ -37,6 +37,16 @@
#include <exo/exo-string.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-string
+ * @title: String Utility Functions
+ * @short_description: Various string-related functions
+ * @include: exo/exo.h
+ *
+ * This section describes a number of utility functions for
+ * manipulating strings.
+ **/
+
/**
@@ -46,9 +56,8 @@
* Returns a copy of @text with all mnemonic underscores
* stripped off.
*
- * Return value: A copy of @text without underscores. The
- * returned string must be freed when no
- * longer required.
+ * Returns: A copy of @text without underscores. The returned string
+ * must be freed when no longer required.
**/
gchar*
exo_str_elide_underscores (const gchar *text)
@@ -90,7 +99,7 @@ exo_str_elide_underscores (const gchar *text)
*
* You should always prefer this function over strcmp().
*
- * Return value: %TRUE if @a equals @b, else %FALSE.
+ * Returns: %TRUE if @a equals @b, else %FALSE.
**/
gboolean
exo_str_is_equal (const gchar *a,
@@ -124,10 +133,9 @@ exo_str_is_equal (const gchar *a,
* same size. If @replacement is %NULL, the pattern will be
* removed from the string.
*
- * Return value: a newly allocated copy of @str where all
- * occurances of @pattern are replaced with
- * @replacement. Or %NULL if @str and/or @pattern
- * is %NULL.
+ * Returns: a newly allocated copy of @str where all occurances of
+ * @pattern are replaced with @replacement. Or %NULL if
+ * @str and/or @pattern is %NULL.
*
* Since: 0.3.1.1
**/
@@ -197,7 +205,7 @@ exo_str_replace (const gchar *str,
* warning, so it's easy to notice use of the extensions without
* testing with multiple versions of the library.
*
- * Return value: a newly allocated string containing the formatted date/time.
+ * Returns: a newly allocated string containing the formatted date/time.
*
* Since: 0.3.3
**/
@@ -366,9 +374,8 @@ exo_strdup_strftime (const gchar *format,
* of @strv. If called on a %NULL value or @num is 0, exo_strndupv()
* simply returns %NULL.
*
- * Return value: A new NULL-terminated array of strings or %NULL.
- * Should be freed using g_strfreev() when no
- * longer needed.
+ * Returns: A new NULL-terminated array of strings or %NULL.
+ * Should be freed using g_strfreev() when no longer needed.
**/
gchar**
exo_strndupv (gchar **strv,
diff --git a/exo/exo-string.h b/exo/exo-string.h
index 1a9390e..eebd8fa 100644
--- a/exo/exo-string.h
+++ b/exo/exo-string.h
@@ -46,10 +46,34 @@ gchar *exo_strdup_strftime (const gchar *format,
gchar **exo_strndupv (gchar **strv,
guint num) G_GNUC_MALLOC G_GNUC_WARN_UNUSED_RESULT;
-#define I_(string) (g_intern_static_string ((string)))
+/**
+ * exo_str_is_empty:
+ * @string : a string
+ *
+ * Macro to check if a string is %NULL or empty. You should prefer
+ * this function over strlen (str) == 0.
+ *
+ * Returns: %TRUE if the string is not %NULL and its length > 1,
+ * %FALSE otherwise.
+ *
+ * Since : 0.5.0
+ **/
#define exo_str_is_empty(string) ((string) == NULL || *(string) == '\0')
+/**
+ * I_:
+ * @string : A static string.
+ *
+ * Shortcut for g_intern_static_string() to return a
+ * canonical representation for @string.
+ *
+ * Returns: a canonical representation for the string.
+ *
+ * Since : 0.3.1.1
+ **/
+#define I_(string) (g_intern_static_string ((string)))
+
G_END_DECLS
#endif /* !__EXO_STRING_H__ */
diff --git a/exo/exo-thumbnail-preview.c b/exo/exo-thumbnail-preview.c
index 603d8cb..565b2d8 100644
--- a/exo/exo-thumbnail-preview.c
+++ b/exo/exo-thumbnail-preview.c
@@ -165,7 +165,7 @@ exo_thumbnail_preview_style_set (GtkWidget *ebox,
*
* Allocates a new #ExoThumbnailPreview instance.
*
- * Return value: the newly allocated #ExoThumbnailPreview.
+ * Returns: the newly allocated #ExoThumbnailPreview.
**/
GtkWidget*
_exo_thumbnail_preview_new (void)
diff --git a/exo/exo-thumbnail.c b/exo/exo-thumbnail.c
index 7ca6e2c..7aba2f9 100644
--- a/exo/exo-thumbnail.c
+++ b/exo/exo-thumbnail.c
@@ -184,7 +184,7 @@ exo_thumbnail_save (GdkPixbuf *thumbnail,
*
* The caller is responsible to free the returned pixbuf using g_object_unref() when no longer needed.
*
- * Return value: the #GdkPixbuf for the thumbnail of @filename or %NULL in case of an error.
+ * Returns: the #GdkPixbuf for the thumbnail of @filename or %NULL in case of an error.
**/
GdkPixbuf*
_exo_thumbnail_get_for_file (const gchar *filename,
@@ -262,7 +262,7 @@ _exo_thumbnail_get_for_file (const gchar *filename,
* Similar to _exo_thumbnail_get_for_file(), but does not try to generate
* a thumbnail if no valid thumbnail is found.
*
- * Return value: the thumbnail for the @uri or %NULL.
+ * Returns: the thumbnail for the @uri or %NULL.
**/
GdkPixbuf*
_exo_thumbnail_get_for_uri (const gchar *uri,
diff --git a/exo/exo-toolbars-editor-dialog.c b/exo/exo-toolbars-editor-dialog.c
index cc548c8..dbb11bf 100644
--- a/exo/exo-toolbars-editor-dialog.c
+++ b/exo/exo-toolbars-editor-dialog.c
@@ -40,9 +40,20 @@
#include <exo/exo-toolbars-editor-dialog.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-toolbars-editor-dialog
+ * @title: ExoToolbarsEditorDialog
+ * @short_description: Dialog to edit toolbars
+ * @include: exo/exo.h
+ * @see_also: #ExoToolbarsEditor
+ *
+ * Provides an easy-to-use wrapper for the #ExoToolbarsEditor widget.
+ **/
+
-#define EXO_TOOLBARS_EDITOR_DIALOG_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_TOOLBARS_EDITOR_DIALOG, ExoToolbarsEditorDialogPrivate))
+#define EXO_TOOLBARS_EDITOR_DIALOG_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_TOOLBARS_EDITOR_DIALOG, ExoToolbarsEditorDialogPrivate))
@@ -143,7 +154,7 @@ exo_toolbars_editor_dialog_add_toolbar (ExoToolbarsEditorDialog *dialog)
* Creates a new #ExoToolbarsEditorDialog that is associated with
* @ui_manager and @model.
*
- * Return value: A new #ExoToolbarsEditorDialog.
+ * Returns: A new #ExoToolbarsEditorDialog.
**/
GtkWidget*
exo_toolbars_editor_dialog_new_with_model (GtkUIManager *ui_manager,
diff --git a/exo/exo-toolbars-editor-dialog.h b/exo/exo-toolbars-editor-dialog.h
index 5c9f7cd..f65eb62 100644
--- a/exo/exo-toolbars-editor-dialog.h
+++ b/exo/exo-toolbars-editor-dialog.h
@@ -53,6 +53,12 @@ struct _ExoToolbarsEditorDialogClass
void (*reserved4) (void);
};
+/**
+ * ExoToolbarsEditorDialog:
+ *
+ * The #ExoToolbarsEditorDialog struct contains only private fields and
+ * should not be directly accessed.
+ **/
struct _ExoToolbarsEditorDialog
{
GtkDialog __parent__;
diff --git a/exo/exo-toolbars-editor.c b/exo/exo-toolbars-editor.c
index cb517f6..0beecf7 100644
--- a/exo/exo-toolbars-editor.c
+++ b/exo/exo-toolbars-editor.c
@@ -41,9 +41,25 @@
#include <exo/exo-toolbars-private.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-toolbars-editor
+ * @title: ExoToolbarsEditor
+ * @short_description: Widget to edit toolbars
+ * @include: exo/exo.h
+ * @see_also: #ExoToolbarsEditorDialog
+ *
+ * #ExoToolbarsEditor is a widget that allows the user to edit toolbars
+ * used within your application by simply dragging and dropping toolbar
+ * items between the editor widget and the toolbar widgets.
+ *
+ * Most applications should simply use the #ExoToolbarsEditorDialog
+ * class, which includes an #ExoToolbarsEditor as main widget.
+ **/
+
-#define EXO_TOOLBARS_EDITOR_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_TOOLBARS_EDITOR, ExoToolbarsEditorPrivate))
+#define EXO_TOOLBARS_EDITOR_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_TOOLBARS_EDITOR, ExoToolbarsEditorPrivate))
@@ -545,7 +561,7 @@ exo_toolbars_editor_update (ExoToolbarsEditor *editor)
* You should probably use exo_toolbars_editor_new_with_model()
* instead.
*
- * Return value: A new #ExoToolbarsEditor.
+ * Returns: A new #ExoToolbarsEditor.
**/
GtkWidget*
exo_toolbars_editor_new (GtkUIManager *ui_manager)
@@ -570,7 +586,7 @@ exo_toolbars_editor_new (GtkUIManager *ui_manager)
* #ExoToolbarsModel here or the function will
* fail.
*
- * Return value: A new #ExoToolbarsEditor.
+ * Returns: A new #ExoToolbarsEditor.
**/
GtkWidget*
exo_toolbars_editor_new_with_model (GtkUIManager *ui_manager,
@@ -595,7 +611,7 @@ exo_toolbars_editor_new_with_model (GtkUIManager *ui_manager,
* with @editor or %NULL if no #ExoToolbarsModel is
* currently associated with @editor.
*
- * Return value: An #ExoToolbarsModel or %NULL.
+ * Returns: An #ExoToolbarsModel or %NULL.
**/
ExoToolbarsModel*
exo_toolbars_editor_get_model (ExoToolbarsEditor *editor)
@@ -668,7 +684,7 @@ exo_toolbars_editor_set_model (ExoToolbarsEditor *editor,
* @editor or %NULL if no user interface
* manager is associated with @editor currently.
*
- * Return value: A #GtkUIManager or %NULL.
+ * Returns: A #GtkUIManager or %NULL.
**/
GtkUIManager*
exo_toolbars_editor_get_ui_manager (ExoToolbarsEditor *editor)
diff --git a/exo/exo-toolbars-editor.h b/exo/exo-toolbars-editor.h
index d817bc3..2a15cb2 100644
--- a/exo/exo-toolbars-editor.h
+++ b/exo/exo-toolbars-editor.h
@@ -53,6 +53,12 @@ struct _ExoToolbarsEditorClass
void (*reserved4) (void);
};
+/**
+ * ExoToolbarsEditor:
+ *
+ * The #ExoToolbarsEditor struct contains only private fields and
+ * should not be directly accessed.
+ **/
struct _ExoToolbarsEditor
{
GtkVBox __parent__;
diff --git a/exo/exo-toolbars-model.c b/exo/exo-toolbars-model.c
index f5c412f..c231131 100644
--- a/exo/exo-toolbars-model.c
+++ b/exo/exo-toolbars-model.c
@@ -39,9 +39,21 @@
#include <exo/exo-toolbars-private.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-toolbars-model
+ * @title: ExoToolbarsModel
+ * @short_description: The toolbars backend used by #ExoToolbarsView
+ * @include: exo/exo.h
+ * @see_also: #ExoToolbarsView, #ExoToolbarsEditor, #ExoToolbarsEditorDialog
+ *
+ * The #ExoToolbarsModel class includes the basic functionality to
+ * manage editable toolbars.
+ **/
+
-#define EXO_TOOLBARS_MODEL_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_TOOLBARS_MODEL, ExoToolbarsModelPrivate))
+#define EXO_TOOLBARS_MODEL_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_TOOLBARS_MODEL, ExoToolbarsModelPrivate))
@@ -646,7 +658,7 @@ unknown_element:
* you created an #ExoToolbarsModel to set the list of actions,
* that should be available from the toolbars.
*
- * Return value: A newly created #ExoToolbarsModel.
+ * Returns: A newly created #ExoToolbarsModel.
**/
ExoToolbarsModel*
exo_toolbars_model_new (void)
@@ -703,7 +715,7 @@ exo_toolbars_model_set_actions (ExoToolbarsModel *model,
*
* Returns the list of valid actions for @model.
*
- * Return value: The list of valid actions for @model.
+ * Returns: The list of valid actions for @model.
**/
gchar**
exo_toolbars_model_get_actions (ExoToolbarsModel *model)
@@ -723,8 +735,8 @@ exo_toolbars_model_get_actions (ExoToolbarsModel *model)
* Parses a file containing a toolbars UI definition and merges it with
* the current contents of @model.
*
- * Return value: %TRUE if the data was successfully loaded from the file
- * specified by @filename, else %FALSE.
+ * Returns: %TRUE if the data was successfully loaded from the file
+ * specified by @filename, else %FALSE.
**/
gboolean
exo_toolbars_model_load_from_file (ExoToolbarsModel *model,
@@ -782,8 +794,7 @@ exo_toolbars_model_load_from_file (ExoToolbarsModel *model,
* Stores the UI definition of the contents of @model to the file
* specified by @filename.
*
- * Return value: %TRUE if saving was successfully, else %FALSE is
- * returned.
+ * Returns: %TRUE if saving was successfully, else %FALSE is returned.
**/
gboolean
exo_toolbars_model_save_to_file (ExoToolbarsModel *model,
@@ -875,8 +886,7 @@ exo_toolbars_model_save_to_file (ExoToolbarsModel *model,
* %EXO_TOOLBARS_MODEL_OVERRIDE_STYLE is set for the
* toolbar.
*
- * Return value: The #GtkToolbarStyle associated with
- * @toolbar_position.
+ * Returns: The #GtkToolbarStyle associated with @toolbar_position.
**/
GtkToolbarStyle
exo_toolbars_model_get_style (ExoToolbarsModel *model,
@@ -967,8 +977,7 @@ exo_toolbars_model_unset_style (ExoToolbarsModel *model,
* Returns the #ExoToolbarsModelFlags associated with the
* toolbar at @toolbar_position.
*
- * Return value: The #ExoToolbarsModelFlags associated
- * with @toolbar_position.
+ * Returns: The #ExoToolbarsModelFlags associated with @toolbar_position.
**/
ExoToolbarsModelFlags
exo_toolbars_model_get_flags (ExoToolbarsModel *model,
@@ -1018,9 +1027,11 @@ exo_toolbars_model_set_flags (ExoToolbarsModel *model,
/**
* exo_toolbars_model_get_item_type:
* @model : An #ExoToolbarsModel.
- * @dnd_type :
+ * @dnd_type : FIXME.
*
- * Return value :
+ * FIXME.
+ *
+ * Returns: FIXME.
**/
gchar*
exo_toolbars_model_get_item_type (ExoToolbarsModel *model,
@@ -1037,10 +1048,12 @@ exo_toolbars_model_get_item_type (ExoToolbarsModel *model,
/**
* exo_toolbars_model_get_item_id:
* @model : An #ExoToolbarsModel.
- * @type :
- * @name :
+ * @type : FIXME.
+ * @name : FIXME.
+ *
+ * FIXME.
*
- * Return value :
+ * Returns: FIXME.
**/
gchar*
exo_toolbars_model_get_item_id (ExoToolbarsModel *model,
@@ -1058,10 +1071,12 @@ exo_toolbars_model_get_item_id (ExoToolbarsModel *model,
/**
* exo_toolbars_model_get_item_data:
* @model : An #ExoToolbarsModel.
- * @type :
- * @id :
+ * @type : FIXME.
+ * @id : FIXME.
+ *
+ * FIXME.
*
- * Return value :
+ * Returns: FIXME.
**/
gchar*
exo_toolbars_model_get_item_data (ExoToolbarsModel *model,
@@ -1088,7 +1103,7 @@ exo_toolbars_model_get_item_data (ExoToolbarsModel *model,
* where @id has to be a valid action name for @model, that was previously
* set with exo_toolbars_model_set_actions().
*
- * Return value: %TRUE if the item was added successfully, else %FALSE.
+ * Returns: %TRUE if the item was added successfully, else %FALSE.
**/
gboolean
exo_toolbars_model_add_item (ExoToolbarsModel *model,
@@ -1149,7 +1164,7 @@ exo_toolbars_model_add_separator (ExoToolbarsModel *model,
* inserted at the specified position. Emits the ::toolbar-added
* signal.
*
- * Return value: The real position of the new toolbar in @model.
+ * Returns: The real position of the new toolbar in @model.
**/
gint
exo_toolbars_model_add_toolbar (ExoToolbarsModel *model,
@@ -1304,7 +1319,7 @@ exo_toolbars_model_remove_toolbar (ExoToolbarsModel *model,
*
* Returns the number of items in the specified toolbar.
*
- * Return value: The number of items in the specified toolbar.
+ * Returns: The number of items in the specified toolbar.
**/
gint
exo_toolbars_model_n_items (ExoToolbarsModel *model,
@@ -1372,7 +1387,7 @@ exo_toolbars_model_item_nth (ExoToolbarsModel *model,
* Returns the number of toolbars currently
* managed by @model.
*
- * Return value: The number of toolbars in @model.
+ * Returns: The number of toolbars in @model.
**/
gint
exo_toolbars_model_n_toolbars (ExoToolbarsModel *model)
@@ -1391,8 +1406,7 @@ exo_toolbars_model_n_toolbars (ExoToolbarsModel *model)
* Returns the name of the toolbar at @toolbar_position in
* @model.
*
- * Return value: The name of the toolbar at @toolbar_position
- * in @model.
+ * Returns: The name of the toolbar at @toolbar_position in @model.
**/
const gchar*
exo_toolbars_model_toolbar_nth (ExoToolbarsModel *model,
diff --git a/exo/exo-toolbars-model.h b/exo/exo-toolbars-model.h
index 5329257..60ec596 100644
--- a/exo/exo-toolbars-model.h
+++ b/exo/exo-toolbars-model.h
@@ -43,6 +43,15 @@ typedef struct _ExoToolbarsModelPrivate ExoToolbarsModelPrivate;
typedef struct _ExoToolbarsModelClass ExoToolbarsModelClass;
typedef struct _ExoToolbarsModel ExoToolbarsModel;
+/**
+ * ExoToolbarsModelFlags:
+ * @EXO_TOOLBARS_MODEL_NOT_REMOVABLE : Not possible to remove items from the model.
+ * @EXO_TOOLBARS_MODEL_ACCEPT_ITEMS_ONLY : Only accept new item, dragging items around
+ * is disabled.
+ * @EXO_TOOLBARS_MODEL_OVERRIDE_STYLE : If set, the #ExoToolbarsModel
+ * accepts a custom #GtkToolbarStyle. See
+ * exo_toolbars_model_set_style().
+ */
typedef enum
{
EXO_TOOLBARS_MODEL_NOT_REMOVABLE = 1 << 0,
@@ -50,6 +59,12 @@ typedef enum
EXO_TOOLBARS_MODEL_OVERRIDE_STYLE = 1 << 2,
} ExoToolbarsModelFlags;
+
+/**
+ * EXO_TOOLBARS_ITEM_TYPE:
+ *
+ * The string used for drag-and-drop in the toolbars editor/model.
+ **/
#define EXO_TOOLBARS_ITEM_TYPE "application/x-exo-toolbars-item"
struct _ExoToolbarsModelClass
@@ -96,6 +111,12 @@ struct _ExoToolbarsModelClass
void (*reserved8) (void);
};
+/**
+ * ExoToolbarsModel:
+ *
+ * The #ExoToolbarsModel struct contains only private fields and should
+ * not be directly accessed.
+ **/
struct _ExoToolbarsModel
{
GObject __parent__;
diff --git a/exo/exo-toolbars-private.c b/exo/exo-toolbars-private.c
index fdac25d..aa81128 100644
--- a/exo/exo-toolbars-private.c
+++ b/exo/exo-toolbars-private.c
@@ -146,7 +146,7 @@ style_set (GtkWidget *image)
* Creates a new #GdkPixbuf with the picture
* of a vertical separator.
*
- * Return value : A #GdkPixbuf.
+ * Returns: A #GdkPixbuf.
**/
GdkPixbuf*
_exo_toolbars_new_separator_pixbuf (void)
@@ -169,7 +169,7 @@ _exo_toolbars_new_separator_pixbuf (void)
* Creates a #GtkImage with the picture of a
* vertical separator in it.
*
- * Return value : A #GtkImage.
+ * Returns: A #GtkImage.
**/
GtkWidget*
_exo_toolbars_new_separator_image (void)
@@ -191,8 +191,7 @@ _exo_toolbars_new_separator_image (void)
* @ui_manager : A #GtkUIManager.
* @name : The name of an action in @ui_manager.
*
- * Return value : The last #GtkAction named @name in @ui_manager
- * or %NULL.
+ * Returns: The last #GtkAction named @name in @ui_manager or %NULL.
**/
GtkAction*
_exo_toolbars_find_action (GtkUIManager *ui_manager,
diff --git a/exo/exo-toolbars-view.c b/exo/exo-toolbars-view.c
index ee542ae..7a43e8e 100644
--- a/exo/exo-toolbars-view.c
+++ b/exo/exo-toolbars-view.c
@@ -40,13 +40,22 @@
#include <exo/exo-toolbars-view.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-toolbars-view
+ * @title: ExoToolbarsView
+ * @short_description: Widget for displaying toolbars
+ * @include: exo/exo.h
+ * @see_also: #ExoToolbarsEditor, #ExoToolbarsEditorDialog, #ExoToolbarsModel
+ *
+ * A widget that displays toolbars as described in a #ExoToolbarsModel object.
+ **/
-#define MIN_TOOLBAR_HEIGHT 20
-
+#define MIN_TOOLBAR_HEIGHT 20
-#define EXO_TOOLBARS_VIEW_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_TOOLBARS_VIEW, ExoToolbarsViewPrivate))
+#define EXO_TOOLBARS_VIEW_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_TOOLBARS_VIEW, ExoToolbarsViewPrivate))
@@ -1167,7 +1176,7 @@ exo_toolbars_view_deconstruct (ExoToolbarsView *view)
*
* Creates a new #ExoToolbarsView.
*
- * Return value: A newly created #ExoToolbarsView.
+ * Returns: A newly created #ExoToolbarsView.
**/
GtkWidget*
exo_toolbars_view_new (GtkUIManager *ui_manager)
@@ -1189,7 +1198,7 @@ exo_toolbars_view_new (GtkUIManager *ui_manager)
* Creates a new #ExoToolbarsView and associates it with
* @model.
*
- * Return value: A newly created #ExoToolbarsView.
+ * Returns: A newly created #ExoToolbarsView.
**/
GtkWidget*
exo_toolbars_view_new_with_model (GtkUIManager *ui_manager,
@@ -1210,7 +1219,9 @@ exo_toolbars_view_new_with_model (GtkUIManager *ui_manager,
* exo_toolbars_view_get_editing:
* @view : An #ExoToolbarsView.
*
- * Return value: %TRUE if @view is currently being edited, else %FALSE.
+ * Gets wether @view is currently being edited.
+ *
+ * Returns: %TRUE if @view is currently being edited, else %FALSE.
**/
gboolean
exo_toolbars_view_get_editing (ExoToolbarsView *view)
@@ -1290,7 +1301,7 @@ exo_toolbars_view_set_editing (ExoToolbarsView *view,
* Returns the #ExoToolbarsModel currently associated with
* @view or %NULL if @view has no model.
*
- * Return value: The #ExoToolbarsModel associated with @view.
+ * Returns: The #ExoToolbarsModel associated with @view.
**/
ExoToolbarsModel*
exo_toolbars_view_get_model (ExoToolbarsView *view)
@@ -1305,6 +1316,9 @@ exo_toolbars_view_get_model (ExoToolbarsView *view)
* exo_toolbars_view_set_model:
* @view : An #ExoToolbarsView.
* @model : An #ExoToolbarsModel or %NULL.
+ *
+ * Set the #ExoToolbarsModel currently associated with
+ * @view or %NULL to disconnect from the active model.
**/
void
exo_toolbars_view_set_model (ExoToolbarsView *view,
@@ -1368,8 +1382,10 @@ exo_toolbars_view_set_model (ExoToolbarsView *view,
* exo_toolbars_view_get_ui_manager:
* @view : An #ExoToolbarsView.
*
- * Return value: The #GtkUIManager associated with @view or
- * %NULL.
+ * Returns the #GtkUIManager currently associated with @view or %NULL is
+ * no ui-manager has been set.
+ *
+ * Returns: The #GtkUIManager associated with @view or %NULL.
**/
GtkUIManager*
exo_toolbars_view_get_ui_manager (ExoToolbarsView *view)
@@ -1384,6 +1400,9 @@ exo_toolbars_view_get_ui_manager (ExoToolbarsView *view)
* exo_toolbars_view_set_ui_manager:
* @view : An #ExoToolbarsView.
* @ui_manager : A #GtkUIManager or %NULL.
+ *
+ * Set the #GtkUIManager currently associated with @view or %NULL
+ * to disconnect from the current ui-manager.
**/
void
exo_toolbars_view_set_ui_manager (ExoToolbarsView *view,
diff --git a/exo/exo-toolbars-view.h b/exo/exo-toolbars-view.h
index 0e678ce..1494945 100644
--- a/exo/exo-toolbars-view.h
+++ b/exo/exo-toolbars-view.h
@@ -58,6 +58,12 @@ struct _ExoToolbarsViewClass
void (*reserved4) (void);
};
+/**
+ * ExoToolbarsView:
+ *
+ * The #ExoToolbarsView struct contains only private fields and should
+ * not be directly accessed.
+ **/
struct _ExoToolbarsView
{
GtkVBox __parent__;
diff --git a/exo/exo-tree-view.c b/exo/exo-tree-view.c
index 45b3520..2d2f6c7 100644
--- a/exo/exo-tree-view.c
+++ b/exo/exo-tree-view.c
@@ -29,9 +29,23 @@
#include <exo/exo-utils.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-tree-view
+ * @title: ExoTreeView
+ * @short_description: An improved version of #GtkTreeView
+ * @include: exo/exo.h
+ *
+ * The #ExoTreeView class derives from #GtkTreeView and extends it with
+ * the ability to activate rows using single button clicks instead of
+ * the default double button clicks. It also works around a few shortcomings
+ * of #GtkTreeView, i.e. #ExoTreeView allows the user to drag around multiple
+ * selected rows.
+ **/
+
-#define EXO_TREE_VIEW_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_TREE_VIEW, ExoTreeViewPrivate))
+#define EXO_TREE_VIEW_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_TREE_VIEW, ExoTreeViewPrivate))
@@ -738,7 +752,7 @@ exo_tree_view_single_click_timeout_destroy (gpointer user_data)
*
* Allocates a new #ExoTreeView instance.
*
- * Return value: the newly allocated #ExoTreeView.
+ * Returns: the newly allocated #ExoTreeView.
*
* Since: 0.3.1.3
**/
@@ -756,7 +770,7 @@ exo_tree_view_new (void)
*
* Returns %TRUE if @tree_view is in single-click mode, else %FALSE.
*
- * Return value: whether @tree_view is in single-click mode.
+ * Returns: whether @tree_view is in single-click mode.
*
* Since: 0.3.1.3
**/
@@ -803,7 +817,7 @@ exo_tree_view_set_single_click (ExoTreeView *tree_view,
* in single click mode. A value of %0 means that the behavior
* is disabled and the user must alter the selection manually.
*
- * Return value: the single click autoselect timeout or %0 if
+ * Returns: the single click autoselect timeout or %0 if
* the behavior is disabled.
*
* Since: 0.3.1.5
diff --git a/exo/exo-tree-view.h b/exo/exo-tree-view.h
index 96057a0..87984b5 100644
--- a/exo/exo-tree-view.h
+++ b/exo/exo-tree-view.h
@@ -56,6 +56,12 @@ struct _ExoTreeViewClass
void (*reserved8) (void);
};
+/**
+ * ExoTreeView:
+ *
+ * The #ExoIconView struct contains only private fields and should
+ * not be directly accessed.
+ **/
struct _ExoTreeView
{
/*< private >*/
diff --git a/exo/exo-utils.c b/exo/exo-utils.c
index aea0040..312a7ef 100644
--- a/exo/exo-utils.c
+++ b/exo/exo-utils.c
@@ -28,6 +28,19 @@
#include <exo/exo-utils.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-utils
+ * @title: Miscellaneous Utility Functions
+ * @short_description: Various utility functions
+ * @include: exo/exo.h
+ * @see_also: <ulink type="http" url="http://library.gnome.org/devel/glib/stable/glib-Atomic-Operations.html">
+ * GLib Atomic Operations</ulink>
+ *
+ * This module contains various utility functions that extend the basic
+ * utility functions provided by the <ulink type="http"
+ * url="http://library.gnome.org/devel/glib/stable/">GLib</ulink> library.
+ **/
+
/**
@@ -57,7 +70,7 @@ exo_noop (void)
* returns %1, but don't want to perform any other
* actions.
*
- * Return value: the integer value %1.
+ * Returns: the integer value %1.
*
* Since: 0.3.1
**/
@@ -78,7 +91,7 @@ exo_noop_one (void)
* returns %0, but don't want to perform any other
* actions.
*
- * Return value: the integer value %0.
+ * Returns: the integer value %0.
*
* Since: 0.3.1
**/
@@ -99,7 +112,7 @@ exo_noop_zero (void)
* returns %NULL, but don't want to perform any
* other actions.
*
- * Return value: a %NULL pointer.
+ * Returns: a %NULL pointer.
*
* Since: 0.3.1
**/
@@ -120,7 +133,7 @@ exo_noop_null (void)
* returns %TRUE, but don't want to perform any
* other actions.
*
- * Return value: the boolean value %TRUE.
+ * Returns: the boolean value %TRUE.
*
* Since: 0.3.1
**/
@@ -141,7 +154,7 @@ exo_noop_true (void)
* returns %FALSE, but don't want to perform any
* other actions.
*
- * Return value: the boolean value %FALSE.
+ * Returns: the boolean value %FALSE.
*
* Since: 0.3.1
**/
diff --git a/exo/exo-utils.h b/exo/exo-utils.h
index f38dd2a..c5625c1 100644
--- a/exo/exo-utils.h
+++ b/exo/exo-utils.h
@@ -42,6 +42,17 @@ gboolean exo_noop_false (void) G_GNUC_PURE;
G_INLINE_FUNC void exo_atomic_inc (gint *value);
G_INLINE_FUNC gboolean exo_atomic_dec (gint *value);
+/**
+ * exo_atomic_inc:
+ * @value : a pointer to the integer value to increment.
+ *
+ * Increments the integer at @value by one in an
+ * atomic fashion. The advantage over using
+ * g_atomic_int_inc() is that calls to this
+ * function can be inlined.
+ *
+ * Since : 0.3.1
+ **/
G_INLINE_FUNC void
exo_atomic_inc (gint *value)
{
@@ -54,6 +65,20 @@ exo_atomic_inc (gint *value)
#endif
}
+/**
+ * exo_atomic_dec:
+ * @value : a pointer to the integer value to decrement.
+ *
+ * Decrements the integer at @value by one in an atomic
+ * fashion and returns %TRUE if the @value dropped to
+ * zero by this operation, else %FALSE. The advantage
+ * over using g_atomic_int_dec() is that calls to this
+ * function can be inlined.
+ *
+ * Returns: %TRUE if @value dropped to zero, else %FALSE.
+ *
+ * Since : 0.3.1
+ **/
G_INLINE_FUNC gboolean
exo_atomic_dec (gint *value)
{
diff --git a/exo/exo-wrap-table.c b/exo/exo-wrap-table.c
index 6d988dc..a9c4390 100644
--- a/exo/exo-wrap-table.c
+++ b/exo/exo-wrap-table.c
@@ -29,9 +29,23 @@
#include <exo/exo-wrap-table.h>
#include <exo/exo-alias.h>
+/**
+ * SECTION: exo-wrap-table
+ * @title: ExoWrapTable
+ * @short_description: A container widget with automatic child layouting
+ * @include: exo/exo.h
+ *
+ * The #ExoWrapTable class layouts its children automatically
+ * according to the available width allocated to the container
+ * class.
+ *
+ * Since: 0.3.1
+ **/
+
-#define EXO_WRAP_TABLE_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_WRAP_TABLE, ExoWrapTablePrivate))
+#define EXO_WRAP_TABLE_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_WRAP_TABLE, ExoWrapTablePrivate))
@@ -552,7 +566,7 @@ exo_wrap_table_get_num_fitting (gint available,
*
* Allocates a new #ExoWrapTable.
*
- * Return value: the newly allocated #ExoWrapTable.
+ * Returns: the newly allocated #ExoWrapTable.
*
* Since: 0.3.1
**/
@@ -573,8 +587,7 @@ exo_wrap_table_new (gboolean homogeneous)
* Returns the amount of space between consecutive
* columns in @table.
*
- * Return value: the amount of space between
- * consecutive columns.
+ * Returns: the amount of space between consecutive columns.
*
* Since: 0.3.1
**/
@@ -620,8 +633,7 @@ exo_wrap_table_set_col_spacing (ExoWrapTable *table,
* Returns the amount of space between consecutive
* rows in @table.
*
- * Return value: the amount of space between
- * consecutive rows in @table.
+ * Returns: the amount of space between consecutive rows in @table.
*
* Since: 0.3.1
**/
@@ -667,8 +679,7 @@ exo_wrap_table_set_row_spacing (ExoWrapTable *table,
* Returns whether the table cells are all constrained
* to the same width and height.
*
- * Return value: %TRUE if the cells are all constrained
- * to the same size.
+ * Returns: %TRUE if the cells are all constrained to the same size.
*
* Since: 0.3.1
**/
diff --git a/exo/exo-wrap-table.h b/exo/exo-wrap-table.h
index e2801a3..5e7172b 100644
--- a/exo/exo-wrap-table.h
+++ b/exo/exo-wrap-table.h
@@ -53,6 +53,12 @@ struct _ExoWrapTableClass
void (*reserved4) (void);
};
+/**
+ * ExoWrapTable:
+ *
+ * The #ExoWrapTable struct contains only private fields
+* and should not be directly accessed.
+ **/
struct _ExoWrapTable
{
/*< private >*/
diff --git a/exo/exo-xsession-client.c b/exo/exo-xsession-client.c
index 198db49..38ef9a3 100644
--- a/exo/exo-xsession-client.c
+++ b/exo/exo-xsession-client.c
@@ -41,9 +41,98 @@
#include <gdk/gdkx.h>
#endif
+/**
+ * SECTION: exo-xsession-client
+ * @title: ExoXsessionClient
+ * @short_description: Lightweight session management support
+ * @include: exo/exo.h
+ *
+ * This module provides application developers with lightweight
+ * session management functions, based on the X11R5 session management
+ * protocol. The X11R5 session management protocol is very limited in
+ * its functionality and flexibility compared to the newer X11R6
+ * session management protocol (XSMP), but - on the other hand - offers several
+ * advantages for applications that do not need the complicated features
+ * of the XSMP. Most importantly, the setup is much easier and
+ * faster than with XSMP, because no special actions must be taken.
+ *
+ * So, in case your application is simple in its session management
+ * requirements, e.g. it only needs to tell the session manager
+ * its restart command, you may want to use the #ExoXsessionClient
+ * instead of a full featured XSMP client.
+ *
+ * Lets say, for example, you are developing a text editor, which
+ * should provide basic session management support, limited to
+ * proper restarting all editor windows that where left open
+ * when you logged off the X session. In case the user was editing
+ * a file when logging off, the same file should be opened in the
+ * window on next startup.
+ *
+ * <example>
+ * <title>Texteditor with <structname>ExoXsessionClient</structname></title>
+ * <programlisting>
+ * static gchar *open_file_name = NULL;
+ *
+ * static void
+ * save_yourself (ExoXsessionClient *client)
+ * {
+ * gchar *argv[2];
+ *
+ * if (open_file_name != NULL)
+ * {
+ * argv[0] = "myeditor";
+ * argv[1] = open_file_name;
+ *
+ * exo_xsession_client_set_restart_command (client, argv, 2);
+ * }
+ * else
+ * {
+ * argv[0] = "myeditor";
+ *
+ * exo_xsession_client_set_restart_command (client, argv, 1);
+ * }
+ * }
+ *
+ * // ...
+ *
+ * int
+ * main (int argc, char **argv)
+ * {
+ * ExoXsessionClient *client;
+ * GdkDisplay *display;
+ * GdkWindow *leader;
+ * GtkWidget *window;
+ *
+ * gtk_init (&argc, &argv);
+ *
+ * if (argc > 1)
+ * open_file_name = argv[1];
+ *
+ * // create the main window
+ * window = create_window ();
+ *
+ * // setup the session client
+ * display = gtk_widget_get_display (window);
+ * leader = gdk_display_get_default_group (display);
+ * client = exo_xsession_client_new_with_group (leader);
+ * g_signal_connect (G_OBJECT (client), "save-yourself",
+ * G_CALLBACK (save_yourself), NULL);
+ *
+ * // ...
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * This example demonstrates the basic handling of #ExoXsessionClient. It is
+ * oversimplified, but we hope you get the point. The rule of thumb is, use
+ * #ExoXsessionClient if you can store all session data in the restart command,
+ * else use a full-featured XSMP client.
+ **/
+
-#define EXO_XSESSION_CLIENT_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), EXO_TYPE_XSESSION_CLIENT, ExoXsessionClientPrivate))
+#define EXO_XSESSION_CLIENT_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ EXO_TYPE_XSESSION_CLIENT, ExoXsessionClientPrivate))
@@ -264,7 +353,7 @@ exo_xsession_client_filter (GdkXEvent *xevent,
* Creates a new #ExoXsessionClient and associates it
* with the group, which is lead by @leader.
*
- * Return value: A newly allocated #ExoXsessionClient.
+ * Returns: A newly allocated #ExoXsessionClient.
**/
ExoXsessionClient*
exo_xsession_client_new_with_group (GdkWindow *leader)
@@ -286,9 +375,8 @@ exo_xsession_client_new_with_group (GdkWindow *leader)
* the @client is associated or %NULL if @client is not
* associated with any group.
*
- * Return value: The client leader window of the group
- * with which @client is associated or
- * %NULL.
+ * Returns: The client leader window of the group with which @client is
+ * associated or %NULL.
**/
GdkWindow*
exo_xsession_client_get_group (ExoXsessionClient *client)
@@ -402,7 +490,7 @@ exo_xsession_client_set_group (ExoXsessionClient *client,
* See exo_xsession_client_set_restart_command() for further
* explanation.
*
- * Return value: %TRUE on success, else %FALSE.
+ * Returns: %TRUE on success, else %FALSE.
**/
gboolean
exo_xsession_client_get_restart_command (ExoXsessionClient *client,
diff --git a/exo/exo-xsession-client.h b/exo/exo-xsession-client.h
index 582891d..5a90135 100644
--- a/exo/exo-xsession-client.h
+++ b/exo/exo-xsession-client.h
@@ -53,6 +53,12 @@ struct _ExoXsessionClientClass
void (*reserved2) (void);
};
+/**
+ * ExoXsessionClient:
+ *
+ * The ExoXsessionClient struct contains only private fields and should
+ * not be directly accessed.
+ **/
struct _ExoXsessionClient
{
GObject __parent__;
More information about the Xfce4-commits
mailing list