Update the interface files for the animation classes

interface/wx/animate.h

@@ -174,6 +174,50 @@ public:
         the window's background colour as specified by the last SetInactiveBitmap() call.
     */
     virtual void Stop();
+
+
+    /**
+       Specify whether the animation's background colour is to be shown (the default),
+       or whether the window background should show through
+    
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+    */
+    void SetUseWindowBackgroundColour(bool useWinBackground = true);
+
+    /**
+       Returns @c true if the window's background colour is being used.
+
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+    */
+    bool IsUsingWindowBackgroundColour() const;
+
+    /**
+       This overload of Play() lets you specify if the animation must loop or not
+       
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+    */
+    bool Play(bool looped);
+
+    /**
+       Draw the current frame of the animation into given DC.
+       This is fast as current frame is always cached.
+
+      @note This method is only available when using the generic version of
+      @c wxAnimation and @c wxAnimationCtrl.
+    */
+    void DrawCurrentFrame(wxDC& dc);
+
+    
+    /**
+       Returns a wxBitmap with the current frame drawn in it.
+
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+    */
+    wxBitmap& GetBackingStore();
 };
 
 
@@ -291,9 +335,60 @@ public:
                           wxAnimationType type = wxANIMATION_TYPE_ANY);
 
     /**
-        Assignment operator, using @ref overview_refcount "reference counting".
+       Retuns the position of the given frame.
-    */
+
-    wxAnimation& operator =(const wxAnimation& brush);
+       Some kinds animation formats may provide partial frames that should be
+       overlayed on the previous frame at a postion other than (0,0).
+
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+     */
+    wxPoint GetFramePosition(unsigned int frame) const;
+
+    /**
+       Returns the size of the given animation frame.
+
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+     */
+    wxSize GetFrameSize(unsigned int frame) const;
+
+    /**
+       Returns the type of disposal that should be done for the given
+       animation frame.
+
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+     */
+    wxAnimationDisposal GetDisposalMethod(unsigned int frame) const;
+
+    /**
+       Returns the colour that should be treated as transparent. Returns @c
+       wxNullColour if the current decoder does not indicate a transparent
+       colour is to be used.
+
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+     */
+    wxColour GetTransparentColour(unsigned int frame) const;
+
+    /**
+       Returns the colour that should be on the animation's background, if any.
+       Returns @c wxNullColour otherwise.
+
+       @note This method is only available when using the generic version of
+       @c wxAnimation and @c wxAnimationCtrl.
+     */
+    wxColour GetBackgroundColour() const;
+
+
+    static inline wxAnimationDecoderList& GetHandlers();
+    static void AddHandler(wxAnimationDecoder *handler);
+    static void InsertHandler(wxAnimationDecoder *handler);
+    static const wxAnimationDecoder *FindHandler( wxAnimationType animType );
+
+    static void CleanUpHandlers();
+    static void InitStandardHandlers();
 };
 
 

interface/wx/animdecode.h

@@ -0,0 +1,172 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        wx/animdecod.h
+// Purpose:     wxAnimationDecoder
+// Author:      Francesco Montorsi
+// Copyright:   (c) 2006 Francesco Montorsi
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+enum wxAnimationDisposal
+{
+    /// No disposal specified. The decoder is not required to take any action.
+    wxANIM_UNSPECIFIED = -1,
+
+    /// Do not dispose. The graphic is to be left in place.
+    wxANIM_DONOTREMOVE = 0,
+
+    /// Restore to background color. The area used by the graphic must be
+    /// restored to the background color.
+    wxANIM_TOBACKGROUND = 1,
+
+    /// Restore to previous. The decoder is required to restore the area
+    /// overwritten by the graphic with what was there prior to rendering the graphic.
+    wxANIM_TOPREVIOUS = 2
+};
+
+
+enum wxAnimationType
+{
+    wxANIMATION_TYPE_INVALID,
+    wxANIMATION_TYPE_GIF,
+    wxANIMATION_TYPE_ANI,
+
+    wxANIMATION_TYPE_ANY
+};
+
+
+/**
+   @class wxAnimationDecoder
+
+   wxAnimationDecoder is used by @c wxAnimation for loading frames and other
+   information for the animation from the animation image file.
+
+ */
+class wxAnimationDecoder : public wxObjectRefData
+{
+public:
+    wxAnimationDecoder();
+
+    /**
+       Load the animation image frames from the given stream.
+    */
+    virtual bool Load( wxInputStream& stream ) = 0;
+
+    /**
+       Returns @true if this decoder supports loading from the given stream.
+    */
+    bool CanRead( wxInputStream& stream ) const;
+
+    /**
+       Create a copy of this decoder.
+    */
+    virtual wxAnimationDecoder *Clone() const = 0;
+
+    /**
+       Return the animation type this decoder implements.
+    */
+    virtual wxAnimationType GetType() const = 0;
+
+    /**
+       Convert given frame to @c wxImage.
+    */
+    virtual bool ConvertToImage(unsigned int frame, wxImage *image) const = 0;
+
+
+    /*
+      Get the size of the given animation frame.
+
+      It's possible that not all frames are of the same size; e.g. GIF allows
+      to specify that between two frames only a smaller portion of the entire
+      animation has changed.
+    */
+    virtual wxSize GetFrameSize(unsigned int frame) const = 0;
+
+    /*
+      Returns the position of the frame, in case it's not as big as the animation size,
+      or @c wxPoint(0,0) otherwise.
+    */
+    virtual wxPoint GetFramePosition(unsigned int frame) const = 0;
+
+    /**
+      What should be done after displaying this frame.
+    */
+    virtual wxAnimationDisposal GetDisposalMethod(unsigned int frame) const = 0;
+
+    /**
+       Return the number of milliseconds this frame should be displayed.
+       If -1 is returned then the frame must be displayed forever.
+    */
+    virtual long GetDelay(unsigned int frame) const = 0;
+
+    /**
+       The transparent colour for this frame, if any, or @c wxNullColour.
+    */
+    virtual wxColour GetTransparentColour(unsigned int frame) const = 0;
+
+    wxSize GetAnimationSize() const;
+    wxColour GetBackgroundColour() const;
+    unsigned int GetFrameCount() const;
+
+protected:
+    /**
+       Checks the signature of the data in the given stream and returns true if it
+       appears to be a valid animation format recognized by the animation decoder;
+       this function should modify the stream current position without taking care
+       of restoring it since @c CanRead() will do it.
+    */
+    virtual bool DoCanRead(wxInputStream& stream) const = 0;
+};
+
+
+
+/**
+   @class wxGIFDecoder
+
+   An animation decoder supporting animated GIF files.
+*/
+class  wxGIFDecoder : public wxAnimationDecoder
+{
+public:
+    wxGIFDecoder();
+    ~wxGIFDecoder();
+
+    virtual bool Load( wxInputStream& stream );
+    virtual wxAnimationDecoder *Clone() const;
+    virtual wxAnimationType GetType() const;
+    virtual bool ConvertToImage(unsigned int frame, wxImage *image) const;
+    virtual wxSize GetFrameSize(unsigned int frame) const;
+    virtual wxPoint GetFramePosition(unsigned int frame) const;
+    virtual wxAnimationDisposal GetDisposalMethod(unsigned int frame) const;
+    virtual long GetDelay(unsigned int frame) const;
+    virtual wxColour GetTransparentColour(unsigned int frame) const;
+
+protected:
+    virtual bool DoCanRead(wxInputStream& stream) const;    
+};
+
+
+
+/**
+   @class wxANIDecoder
+
+   An animation decoder supporting animated cursor (.ani) files.
+*/
+class  wxANIDecoder : public wxAnimationDecoder
+{
+public:
+    wxANIDecoder();
+    ~wxANIDecoder();
+
+    virtual bool Load( wxInputStream& stream );
+    virtual wxAnimationDecoder *Clone() const;
+    virtual wxAnimationType GetType() const;
+    virtual bool ConvertToImage(unsigned int frame, wxImage *image) const;
+    virtual wxSize GetFrameSize(unsigned int frame) const;
+    virtual wxPoint GetFramePosition(unsigned int frame) const;
+    virtual wxAnimationDisposal GetDisposalMethod(unsigned int frame) const;
+    virtual long GetDelay(unsigned int frame) const;
+    virtual wxColour GetTransparentColour(unsigned int frame) const;
+
+protected:
+    virtual bool DoCanRead(wxInputStream& stream) const;    
+};