This is an automated email from the git hooks/post-receive script.
nomad pushed a commit to branch master
in repository apps/xfdashboard.
commit 2d6f3f5c9aecf5bce44abe132c1b9b547dc1d7d1
Author: Stephan Haller <no...@froevel.de>
Date: Sun Aug 16 11:17:54 2015 +0200
Add gtk-doc documentation annotations to utils.{c,h}
---
xfdashboard/utils.c | 125 +++++++++++++++++++++++++++++++++++++++++++--------
xfdashboard/utils.h | 48 ++++++++++++++++----
2 files changed, 147 insertions(+), 26 deletions(-)
diff --git a/xfdashboard/utils.c b/xfdashboard/utils.c
index 44e993d..7faba84 100644
--- a/xfdashboard/utils.c
+++ b/xfdashboard/utils.c
@@ -36,6 +36,15 @@
#include "stage.h"
#include "window-tracker.h"
+/**
+ * SECTION:utils
+ * @title: Utilities
+ * @short_description: Common functions, helpers, macros and definitions
+ * @include: xfdashboard/utils.h
+ *
+ * Utility functions to ease some common tasks.
+ */
+
/* Gobject type for pointer arrays (GPtrArray) */
GType xfdashboard_pointer_array_get_type(void)
{
@@ -51,8 +60,24 @@ GType xfdashboard_pointer_array_get_type(void)
return(type__volatile);
}
-/* Show a notification */
-void xfdashboard_notify(ClutterActor *inSender, const gchar *inIconName, const
gchar *inFormatText, ...)
+/**
+ * xfdashboard_notify:
+ * @inSender: The sending #ClutterActor or %NULL
+ * @inIconName: The icon name to display in notification or %NULL
+ * @inFormat: A standard printf() format string for notification text
+ * @...: The parameters to insert into the format string
+ *
+ * Shows a notification with the formatted text as specified in @inFormat
+ * and the parameters at the monitor where the sending actor @inSender
+ * is placed on.
+ *
+ * If @inSender is NULL the primary monitor is used.
+ *
+ * If @inIconName is NULL no icon will be shown in notification.
+ */
+void xfdashboard_notify(ClutterActor *inSender,
+ const gchar *inIconName,
+ const gchar *inFormat,
...)
{
XfdashboardStage *stage;
ClutterStageManager *stageManager;
@@ -65,8 +90,8 @@ void xfdashboard_notify(ClutterActor *inSender, const gchar
*inIconName, const g
stage=NULL;
/* Build text to display */
- va_start(args, inFormatText);
- text=g_strdup_vprintf(inFormatText, args);
+ va_start(args, inFormat);
+ text=g_strdup_vprintf(inFormat, args);
va_end(args);
/* Get stage of sending actor if available */
@@ -106,8 +131,16 @@ void xfdashboard_notify(ClutterActor *inSender, const
gchar *inIconName, const g
g_free(text);
}
-/* Create a application context for launching application by GIO.
- * Object returned must be freed with g_object_unref().
+/**
+ * xfdashboard_create_app_context:
+ * @inWorkspace: The workspace where to place application windows on or %NULL
+ *
+ * Returns a #GAppLaunchContext suitable for launching applications on the
given display and workspace by GIO.
+ *
+ * If @inWorkspace is specified it sets workspace on which applications will
be launched when using this context when running under a window manager that
supports multiple workspaces.
+ * When the workspace is not specified it is up to the window manager to pick
one, typically it will be the current workspace.
+ *
+ * Return value: (transfer full): the newly created #GAppLaunchContext or
%NULL in case of an error. Use g_object_unref() to free return value.
*/
GAppLaunchContext*
xfdashboard_create_app_context(XfdashboardWindowTrackerWorkspace *inWorkspace)
{
@@ -276,6 +309,12 @@ static void
_xfdashboard_gvalue_transform_string_flags(const GValue *inSourceVal
g_type_class_unref(flagsClass);
}
+/**
+ * xfdashboard_register_gvalue_transformation_funcs:
+ *
+ * Registers additional transformation functions used in #GValue to convert
+ * values between types.
+ */
void xfdashboard_register_gvalue_transformation_funcs(void)
{
/* Register GValue transformation functions not provided by Glib */
@@ -299,7 +338,7 @@ gboolean xfdashboard_actor_contains_child_deep(ClutterActor
*inActor, ClutterAct
ClutterActor *child;
g_return_val_if_fail(CLUTTER_IS_ACTOR(inActor), FALSE);
- g_return_val_if_fail(CLUTTER_IS_ACTOR(inActor), FALSE);
+ g_return_val_if_fail(CLUTTER_IS_ACTOR(inChild), FALSE);
/* For each child of actor call ourselve recursive */
clutter_actor_iter_init(&iter, inActor);
@@ -321,7 +360,17 @@ gboolean
xfdashboard_actor_contains_child_deep(ClutterActor *inActor, ClutterAct
return(FALSE);
}
-/* Find child by name deeply beginning at given actor */
+/**
+ * xfdashboard_find_actor_by_name:
+ * @inActor: The root #ClutterActor where to begin searching
+ * @inName: A string containg the name of the #ClutterActor to lookup
+ *
+ * Iterates through all children of @inActor recursively and looks for
+ * the child having the name as specified at @inName.
+ *
+ * Return value: (transfer none): The #ClutterActor matching the name
+ * to lookup or %NULL if none was found.
+ */
ClutterActor* xfdashboard_find_actor_by_name(ClutterActor *inActor, const
gchar *inName)
{
ClutterActorIter iter;
@@ -346,9 +395,17 @@ ClutterActor* xfdashboard_find_actor_by_name(ClutterActor
*inActor, const gchar
return(NULL);
}
-/* Split a string into a NULL-terminated list of tokens using the delimiters
and remove
- * white-spaces at the beginning and end of each token. Empty tokens will not
be added.
- * Caller is responsible to free result with g_strfreev() if not NULL.
+/**
+ * xfdashboard_split_string:
+ * @inString: The string to split
+ * @inDelimiters: A string containg the delimiters
+ *
+ * Split the string @inString into a NULL-terminated list of tokens using
+ * the delimiters at @inDelimiters and removes white-spaces at the beginning
+ * and end of each token. Empty tokens will not be added to list.
+ *
+ * Return value: A newly-allocated %NULL-terminated array of strings or %NULL
+ * in case of an error. Use g_strfreev() to free it.
*/
gchar** xfdashboard_split_string(const gchar *inString, const gchar
*inDelimiters)
{
@@ -446,12 +503,20 @@ gchar** xfdashboard_split_string(const gchar *inString,
const gchar *inDelimiter
return(result);
}
-/* Check if ID matches requirements that it has to begin either with one or
- * multiple '_' (underscore) following by a character of ASCII character set
- * or it has to begin with a character of ASCII character set directly. Each
- * following character in string can either be a digit, a character of
- * ASCII character set or any of the following symbols: '_' (underscore) or
- * '-' (minus).
+/**
+ * xfdashboard_is_valid_id:
+ * @inString: The string containing the ID to check
+ *
+ * Checks if ID specified at @inString matches the requirements to be a
+ * valid ID.
+ *
+ * To be a valid ID it has to begin either with one or multiple '_'
(underscores)
+ * following by a character of ASCII character set or it has to begin with a
+ * character of ASCII character set directly. Each following character can
either
+ * be a digit, a character of ASCII character set or any of the following
symbols:
+ * '_' (underscore) or '-' (minus).
+ *
+ * Return value: %TRUE if @inString contains a valid ID, otherwise %FALSE
*/
gboolean xfdashboard_is_valid_id(const gchar *inString)
{
@@ -496,7 +561,18 @@ gboolean xfdashboard_is_valid_id(const gchar *inString)
return(TRUE);
}
-/* Get textual representation for an enumeration value */
+/**
+ * xfdashboard_get_enum_value_name:
+ * @inEnumClass: The #GType of enum class
+ * @inValue: The numeric value of enumeration at @inEnumClass
+ *
+ * Returns textual representation for numeric value @inValue of
+ * enumeration class @inEnumClass.
+ *
+ * Return value: A string containig the textual representation or
+ * %NULL if @inValue is not a value of enumeration
+ * @inEnumClass. Use g_free() to free returned string.
+ */
gchar* xfdashboard_get_enum_value_name(GType inEnumClass, gint inValue)
{
GEnumClass *enumClass;
@@ -554,6 +630,19 @@ static void _xfdashboard_dump_actor_internal(ClutterActor
*inActor, gint inLevel
}
}
+/**
+ * xfdashboard_dump_actor:
+ * @inActor: The #ClutterActor to dump
+ *
+ * Dumps a textual representation of actor specified in @inActor
+ * to console. The dump contains all children recursively displayed
+ * in a tree. Each entry contains the object class name, address,
+ * position and size of this actor and also the state like is-mapped,
+ * is-visible and a number of children it contains.
+ *
+ * This functions is for debugging purposes and should not be used
+ * normally.
+ */
void xfdashboard_dump_actor(ClutterActor *inActor)
{
_xfdashboard_dump_actor_internal(inActor, 0);
diff --git a/xfdashboard/utils.h b/xfdashboard/utils.h
index a4d1fb8..50cc92a 100644
--- a/xfdashboard/utils.h
+++ b/xfdashboard/utils.h
@@ -24,28 +24,60 @@
#ifndef __XFDASHBOARD_UTILS__
#define __XFDASHBOARD_UTILS__
-#define DEBUG_OBJECT_NAME(x) ((x)!=NULL ? G_OBJECT_TYPE_NAME((x)) : "<nil>")
-#define DEBUG_BOX(msg, box) g_message("%s: %s: x1=%.2f, y1=%.2f, x2=%.2f,
y2=%.2f [%.2fx%.2f]", __func__, msg, (box).x1, (box).y1, (box).x2, (box).y2,
(box).x2-(box).x1, (box).y2-(box).y1)
-#define DEBUG_NOTIFY(self, property, format, ...) g_message("%s: Property '%s'
of %p (%s) changed to "format, __func__, property, (self), (self) ?
G_OBJECT_TYPE_NAME((self)) : "<nil>", ## __VA_ARGS__)
-
#include <clutter/clutter.h>
#include <gio/gio.h>
-#include <garcon/garcon.h>
#include "window-tracker-workspace.h"
G_BEGIN_DECLS
+/* Debug macros */
+#define _DEBUG_OBJECT_NAME(x) \
+ ((x)!=NULL ? G_OBJECT_TYPE_NAME((x)) : "<nil>")
+
+#define _DEBUG_BOX(msg, box) \
+ g_message("%s: %s: x1=%.2f, y1=%.2f, x2=%.2f, y2=%.2f [%.2fx%.2f]", \
+ __func__, \
+ msg, \
+ (box).x1, (box).y1, (box).x2, (box).y2, \
+ (box).x2-(box).x1, (box).y2-(box).y1)
+
+#define _DEBUG_NOTIFY(self, property, format, ...) \
+ g_message("%s: Property '%s' of %p (%s) changed to "format, \
+ __func__, \
+ property, \
+ (self), (self) ? G_OBJECT_TYPE_NAME((self)) :
"<nil>", \
+ ## __VA_ARGS__)
+
/* Gobject type of pointer array (GPtrArray) */
#define XFDASHBOARD_TYPE_POINTER_ARRAY
(xfdashboard_pointer_array_get_type())
/* Public API */
-#define GTYPE_TO_POINTER(gtype) (GSIZE_TO_POINTER(gtype))
-#define GPOINTER_TO_GTYPE(item) ((GType)GPOINTER_TO_SIZE(item))
+
+/**
+ * GTYPE_TO_POINTER:
+ * @gtype: A #GType to stuff into the pointer
+ *
+ * Stuffs the #GType specified at @gtype into a pointer type.
+ */
+#define GTYPE_TO_POINTER(gtype) \
+ (GSIZE_TO_POINTER(gtype))
+
+/**
+ * GPOINTER_TO_GTYPE:
+ * @pointer: A pointer to extract a #GType from
+ *
+ * Extracts a #GType from a pointer. The #GType must have been stored in the
pointer with GTYPE_TO_POINTER().
+ */
+#define GPOINTER_TO_GTYPE(pointer) \
+ ((GType)GPOINTER_TO_SIZE(pointer))
GType xfdashboard_pointer_array_get_type(void);
-void xfdashboard_notify(ClutterActor *inSender, const gchar *inIconName, const
gchar *inFormatText, ...) G_GNUC_PRINTF(3, 4);
+void xfdashboard_notify(ClutterActor *inSender,
+ const gchar *inIconName,
+ const gchar *inFormat,
...)
+ G_GNUC_PRINTF(3, 4);
GAppLaunchContext*
xfdashboard_create_app_context(XfdashboardWindowTrackerWorkspace *inWorkspace);
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
_______________________________________________
Xfce4-commits mailing list
Xfce4-commits@xfce.org
https://mail.xfce.org/mailman/listinfo/xfce4-commits
