[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r22041 - in gnunet-gtk/src: include lib
From: |
gnunet |
Subject: |
[GNUnet-SVN] r22041 - in gnunet-gtk/src: include lib |
Date: |
Sat, 16 Jun 2012 16:36:15 +0200 |
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)
{
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r22041 - in gnunet-gtk/src: include lib,
gnunet <=