gtkmm r993 - in trunk: . gdk/src

[murrayc svn gnome org]

Author: murrayc
Date: Tue Apr 29 20:36:29 2008
New Revision: 993
URL: http://svn.gnome.org/viewvc/gtkmm?rev=993&view=rev

Log:
2008-04-29  Murray Cumming  <murrayc murrayc com>

* gdk/src/pixbufanimationiter.[hg|cc]: Added  get_pixbuf(), get_delay_time(), 
advance(), on_currently_loading_frame().
* gdk/src/gdk_docs_override.xml: Customized the documentation for these 
methods, to avoid C-specific advice, and to add @newin2p14.
Bug #528037 (Balazs Tirpak) 


Modified:
   trunk/ChangeLog
   trunk/gdk/src/gdk_docs_override.xml
   trunk/gdk/src/pixbufanimation.ccg
   trunk/gdk/src/pixbufanimationiter.ccg
   trunk/gdk/src/pixbufanimationiter.hg
   trunk/gdk/src/window.hg

Modified: trunk/gdk/src/gdk_docs_override.xml
==============================================================================
--- trunk/gdk/src/gdk_docs_override.xml	(original)
+++ trunk/gdk/src/gdk_docs_override.xml	Tue Apr 29 20:36:29 2008
@@ -501,6 +501,107 @@
 </parameters>
 </function>
 
+<function name="gdk_pixbuf_animation_iter_get_delay_time">
+<description>
+Gets the number of milliseconds the current pixbuf should be displayed,
+or -1 if the current pixbuf should be displayed forever. Glib::signal_timeout.connect()
+conveniently takes a timeout in milliseconds, so you can use a timeout
+to schedule the next update.
+
+ newin2p14
+</description>
+<parameters>
+<parameter name="iter">
+<parameter_description> an animation iterator
+</parameter_description>
+</parameter>
+</parameters>
+<return> delay time in milliseconds (thousandths of a second)
+</return>
+</function>
+
+<function name="gdk_pixbuf_animation_iter_get_pixbuf">
+<description>
+Gets the current pixbuf which should be displayed; the pixbuf will
+be the same size as the animation itself
+(Gdk::Pixbuf::get_width(), Gdk::Pixbuf:get_height()). 
+This pixbuf should be displayed for get_delay_time() milliseconds. 
+The returned pixbuf will become invalid when the iterator advances
+to the next frame, which may happen anytime you call
+gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it, with 
+Gdk::Pixbuf::copy() as it may get recycled as you advance the iterator.
+
+ newin2p14
+</description>
+<parameters>
+<parameter name="iter">
+<parameter_description> an animation iterator
+</parameter_description>
+</parameter>
+</parameters>
+<return> the pixbuf to be displayed
+</return>
+</function>
+
+<function name="gdk_pixbuf_animation_iter_on_currently_loading_frame">
+<description>
+Used to determine how to respond to the area_updated signal on
+Gdk::PixbufLoader when loading an animation. The area_updated signal is emitted
+for an area of the frame currently streaming in to the loader. So if
+you&apos;re on the currently loading frame, you need to redraw the screen for
+the updated area.
+
+ newin2p14
+</description>
+<parameters>
+<parameter name="iter">
+<parameter_description> a #GdkPixbufAnimationIter
+</parameter_description>
+</parameter>
+</parameters>
+<return> %TRUE if the frame we&apos;re on is partially loaded, or the last frame
+</return>
+</function>
+
+<function name="gdk_pixbuf_animation_iter_advance">
+<description>
+Possibly advances an animation to a new frame. Chooses the frame based
+on the start time passed to Gdk::PixbufAnimation::get_iter().
+
+ current_time would normally come from g_get_current_time(), and
+must be greater than or equal to the time passed to
+Gdk::PixbufAnimation::get_iter(), and must increase or remain
+unchanged each time get_pixbuf() is
+called. That is, you can&apos;t go backward in time; animations only
+play forward.
+
+If using the method overload that takes no current_time parameter then the 
+current time will be used. So you only need to explicitly pass
+ current_time if you&apos;re doing something odd like playing the animation
+at double speed.
+
+If this function returns %FALSE, there&apos;s no need to update the animation
+display, assuming the display had been rendered prior to advancing;
+if %TRUE, you need to call get_pixbuf() and update the
+display with the new pixbuf.
+
+ newin2p14
+</description>
+<parameters>
+<parameter name="iter">
+<parameter_description> a #GdkPixbufAnimationIter
+</parameter_description>
+</parameter>
+<parameter name="current_time">
+<parameter_description> current time
+</parameter_description>
+</parameter>
+</parameters>
+<return> %TRUE if the image may need updating
+
+</return>
+</function>
+
 <function name="gdk_window_set_cursor">
 <description>
 Sets the mouse pointer for a #GdkWindow. 

Modified: trunk/gdk/src/pixbufanimation.ccg
==============================================================================
--- trunk/gdk/src/pixbufanimation.ccg	(original)
+++ trunk/gdk/src/pixbufanimation.ccg	Tue Apr 29 20:36:29 2008
@@ -29,6 +29,7 @@
 {
   GError* pError = 0;
   return Glib::wrap(gdk_pixbuf_animation_new_from_file(filename.c_str(), &pError));
+  //TODO: Handle the error (don't just leak it).
 }
 
 } //Gdk

Modified: trunk/gdk/src/pixbufanimationiter.ccg
==============================================================================
--- trunk/gdk/src/pixbufanimationiter.ccg	(original)
+++ trunk/gdk/src/pixbufanimationiter.ccg	Tue Apr 29 20:36:29 2008
@@ -20,4 +20,14 @@
  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
+namespace Gdk
+{
+
+bool PixbufAnimationIter::advance()
+{
+  return gdk_pixbuf_animation_iter_advance(gobj(), NULL);
+}
+
+} //namespace Gdk
+
 

Modified: trunk/gdk/src/pixbufanimationiter.hg
==============================================================================
--- trunk/gdk/src/pixbufanimationiter.hg	(original)
+++ trunk/gdk/src/pixbufanimationiter.hg	Tue Apr 29 20:36:29 2008
@@ -20,6 +20,7 @@
  */
 
 #include <glibmm/object.h>
+#include <gdkmm/pixbuf.h>
 #include <gdk-pixbuf/gdk-pixbuf.h>
 
 _DEFS(gdkmm,gdk)
@@ -29,12 +30,36 @@
 namespace Gdk
 {
 
+
+//TODO: Documentation:
 class PixbufAnimationIter : public Glib::Object
 {
   _CLASS_GOBJECT(PixbufAnimationIter, GdkPixbufAnimationIter, GDK_PIXBUF_ANIMATION_ITER, Glib::Object, GObject)
 protected:
 
+  _WRAP_METHOD(int get_delay_time() const, gdk_pixbuf_animation_iter_get_delay_time)
+
+  _WRAP_METHOD(Glib::RefPtr<Gdk::Pixbuf> get_pixbuf(), gdk_pixbuf_animation_iter_get_pixbuf, refreturn)
+  _WRAP_METHOD(Glib::RefPtr<const Gdk::Pixbuf> get_pixbuf() const, gdk_pixbuf_animation_iter_get_pixbuf, refreturn, constversion)
+
+  _WRAP_METHOD(bool on_currently_loading_frame() const, gdk_pixbuf_animation_iter_on_currently_loading_frame)
 
+#m4 _CONVERSION(`const Glib::TimeVal&', `const GTimeVal*', static_cast<$2>(&$3))
+  _WRAP_METHOD(bool advance(const Glib::TimeVal& current_time), gdk_pixbuf_animation_iter_advance)
+  
+  /** Possibly advances an animation to a new frame. Chooses the frame based
+   * on the start time passed to Gdk::PixbufAnimation::get_iter().
+   * 
+   * If this function returns false, there's no need to update the animation
+   * display, assuming the display had been rendered prior to advancing;
+   * if true, you need to call get_pixbuf() and update the
+   * display with the new pixbuf.
+   *
+   * @newin2p14
+   *
+   * @return true if the image may need updating.
+   */
+  bool advance();
 };
 
 } /* namespace Gdk */

Modified: trunk/gdk/src/window.hg
==============================================================================
--- trunk/gdk/src/window.hg	(original)
+++ trunk/gdk/src/window.hg	Tue Apr 29 20:36:29 2008
@@ -141,6 +141,7 @@
    * the display.
    *
    * @see set_back_pixmap().
+   * @newin2p14
    */
   void unset_back_pixmap();