[GNUnet-SVN] r22041 - in gnunet-gtk/src: include lib

[gnunet]

Author: grothoff
Date: 2012-06-16 16:36:15 +0200 (Sat, 16 Jun 2012)
New Revision: 22041

Modified:
   gnunet-gtk/src/include/gnunet_gtk.h
   gnunet-gtk/src/lib/animations.c
Log:
-document animation API

Modified: gnunet-gtk/src/include/gnunet_gtk.h
===================================================================
--- gnunet-gtk/src/include/gnunet_gtk.h 2012-06-16 14:09:45 UTC (rev 22040)
+++ gnunet-gtk/src/include/gnunet_gtk.h 2012-06-16 14:36:15 UTC (rev 22041)
@@ -254,6 +254,82 @@
 GNUNET_GTK_main_loop_quit (struct GNUNET_GTK_MainLoop *ml);
 
 
+/* ******************** animations ******************* */
 
+
+/**
+ * Handle for an animation.  Each animation file should only
+ * be loaded once and can then be used in multiple tree views.
+ */
+struct GNUNET_FS_AnimationContext;
+
+
+/**
+ * Handle to a tree view (and column) that contains animations.
+ * Whenever an animation is added to a tree view, this module
+ * must be told about the tree view and column for the animations
+ * to work.
+ */
+struct GNUNET_FS_AnimationTreeViewHandle;
+
+
+/**
+ * Create an animation context.  Usually animation contexts are
+ * created during the startup of the application and kept around
+ * until shutdown.
+ *
+ * @param filename name of the file with the animation to show
+ * @return context to use to get the animated pixbuf, NULL on error
+ */
+struct GNUNET_FS_AnimationContext *
+GNUNET_GTK_animation_context_create (const char *filename);
+
+
+/**
+ * Destroy an animation context.  Should only be called after the
+ * respective pixbufs are no longer needed.
+ *
+ * @param ac animation context to destroy.
+ */
+void
+GNUNET_GTK_animation_context_destroy (struct GNUNET_FS_AnimationContext *ac);
+
+
+/**
+ * Obtain the animated pixbuf from an animation context.  Note
+ * that the pixbuf will only properly work within GtkTreeViews
+ * where the column with the image has been registered using
+ * GNUNET_GTK_animation_tree_view_register.
+ *
+ * @param ac animation context to query
+ * @return pixbuf of the AC, NULL on error loading the pixbuf
+ */
+GdkPixbuf *
+GNUNET_GTK_animation_context_get_pixbuf (struct GNUNET_FS_AnimationContext 
*ac);
+
+
+/**
+ * Register a tree view column with the animation subsystem.  This
+ * column may contain animated pixbufs and thus needs to be periodically
+ * redrawn.
+ *
+ * @param tv tree view to register
+ * @param image_col column in the tree view with the animated pixbufs
+ * @return handle to unregister the tree view later
+ */
+struct GNUNET_FS_AnimationTreeViewHandle *
+GNUNET_GTK_animation_tree_view_register (GtkTreeView *tv,
+                                        GtkTreeViewColumn *image_col);
+
+
+/**
+ * Unregister a tree view, it no longer needs to be updated.
+ *
+ * @param atv tree view to unregister
+ */
+void
+GNUNET_GTK_animation_tree_view_unregister (struct 
GNUNET_FS_AnimationTreeViewHandle *atv);
+
+
 #endif
 /* end of gnunet_gtk.h */

Modified: gnunet-gtk/src/lib/animations.c
===================================================================
--- gnunet-gtk/src/lib/animations.c     2012-06-16 14:09:45 UTC (rev 22040)
+++ gnunet-gtk/src/lib/animations.c     2012-06-16 14:36:15 UTC (rev 22041)
@@ -26,48 +26,112 @@
  */
 #include "gnunet_gtk.h"
 
-
+/**
+ * How often do we update animations?  Should be small enough
+ * to fit with the animations used, but not so tiny that we just
+ * wake up the CPU for nothing all the time.
+ */
 #define TICKER_DELAY GNUNET_TIME_relative_multiply 
(GNUNET_TIME_UNIT_MILLISECONDS, 100)
 
 
+/**
+ * Handle for an animation.  Each animation file should only
+ * be loaded once and can then be used in multiple tree views.
+ */
 struct GNUNET_FS_AnimationContext
 {
+  /**
+   * This is a doublye-linked list.
+   */
   struct GNUNET_FS_AnimationContext *next;
-
+ 
+  /**
+   * This is a doublye-linked list.
+   */
   struct GNUNET_FS_AnimationContext *prev;
 
+  /**
+   * Handle to the animation.
+   */
   GdkPixbufAnimation *ani;
 
+  /**
+   * Iterator of the animation.
+   */
   GdkPixbufAnimationIter *iter;
 
+  /**
+   * Pixbuf with the current image from the animation.
+   */
   GdkPixbuf *pixbuf;
 
 };
 
 
+/**
+ * Handle to a tree view (and column) that contains animations.
+ * Whenever an animation is added to a tree view, this module
+ * must be told about the tree view and column for the animations
+ * to work.
+ */
 struct GNUNET_FS_AnimationTreeViewHandle
 {
+  /**
+   * This is a doublye-linked list.
+   */
   struct GNUNET_FS_AnimationTreeViewHandle *next;
 
+  /**
+   * This is a doublye-linked list.
+   */
   struct GNUNET_FS_AnimationTreeViewHandle *prev;
 
+  /**
+   * Tree view to watch.
+   */
   GtkTreeView *tv;
 
+  /**
+   * Column that might contain animations.
+   */
   GtkTreeViewColumn *image_col;
 };
 
 
+/**
+ * Head of linked list of animations.
+ */
 static struct GNUNET_FS_AnimationContext *animation_head;
 
+/**
+ * Tail of linked list of animations.
+ */
 static struct GNUNET_FS_AnimationContext *animation_tail;
 
+/**
+ * Head of linked list of tree views with animations.
+ */
 static struct GNUNET_FS_AnimationTreeViewHandle *atv_head;
 
+/**
+ * Tail of linked list of tree views with animations.
+ */
 static struct GNUNET_FS_AnimationTreeViewHandle *atv_tail;
 
+/**
+ * Task run to update animations.
+ */
 static GNUNET_SCHEDULER_TaskIdentifier ticker_task;
 
 
+/**
+ * Create an animation context.  Usually animation contexts are
+ * created during the startup of the application and kept around
+ * until shutdown.
+ *
+ * @param filename name of the file with the animation to show
+ * @return context to use to get the animated pixbuf, NULL on error
+ */
 struct GNUNET_FS_AnimationContext *
 GNUNET_GTK_animation_context_create (const char *filename)
 {
@@ -76,6 +140,11 @@
 
   ac = GNUNET_malloc (sizeof (struct GNUNET_FS_AnimationContext));
   ac->ani = gdk_pixbuf_animation_new_from_file (filename, &err);
+  if (NULL == ac->ani)
+    {
+      GNUNET_free (ac);
+      return NULL;
+    }
   ac->iter = gdk_pixbuf_animation_get_iter (ac->ani, NULL);
   ac->pixbuf = gdk_pixbuf_copy (gdk_pixbuf_animation_iter_get_pixbuf 
(ac->iter));
   GNUNET_CONTAINER_DLL_insert (animation_head,
@@ -85,11 +154,19 @@
 }
 
 
+/**
+ * Destroy an animation context.  Should only be called after the
+ * respective pixbufs are no longer needed.
+ *
+ * @param ac animation context to destroy.
+ */
 void
 GNUNET_GTK_animation_context_destroy (struct GNUNET_FS_AnimationContext *ac)
 {
+  if (NULL == ac)
+    return;
   g_object_unref (ac->pixbuf);
-  g_object_unref (ac->iter);
+  g_object_unref (ac->iter); 
   g_object_unref (ac->ani);
   GNUNET_CONTAINER_DLL_remove (animation_head,
                               animation_tail,
@@ -98,9 +175,20 @@
 }
 
 
+/**
+ * Obtain the animated pixbuf from an animation context.  Note
+ * that the pixbuf will only properly work within GtkTreeViews
+ * where the column with the image has been registered using
+ * GNUNET_GTK_animation_tree_view_register.
+ *
+ * @param ac animation context to query
+ * @return pixbuf of the AC, NULL on error loading the pixbuf
+ */
 GdkPixbuf *
 GNUNET_GTK_animation_context_get_pixbuf (struct GNUNET_FS_AnimationContext *ac)
 {
+  if (NULL == ac)
+    return NULL;
   return ac->pixbuf;
 }
 
@@ -128,6 +216,12 @@
 }
 
 
+/**
+ * Redraw the visible portion of the tree view column (the animations
+ * there might have changed).
+ *
+ * @param atv handle to the tree view to redraw
+ */
 static void
 redraw_tree_view (struct GNUNET_FS_AnimationTreeViewHandle *atv)
 {  
@@ -186,6 +280,15 @@
 }
 
 
+/**
+ * Register a tree view column with the animation subsystem.  This
+ * column may contain animated pixbufs and thus needs to be periodically
+ * redrawn.
+ *
+ * @param tv tree view to register
+ * @param image_col column in the tree view with the animated pixbufs
+ * @return handle to unregister the tree view later
+ */
 struct GNUNET_FS_AnimationTreeViewHandle *
 GNUNET_GTK_animation_tree_view_register (GtkTreeView *tv,
                                         GtkTreeViewColumn *image_col)
@@ -206,6 +309,11 @@
 }
 
 
+/**
+ * Unregister a tree view, it no longer needs to be updated.
+ *
+ * @param atv tree view to unregister
+ */
 void
 GNUNET_GTK_animation_tree_view_unregister (struct 
GNUNET_FS_AnimationTreeViewHandle *atv)
 {