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