contrib/include/wx/animate/animate.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        animate.h
   3 // Purpose:     Animation classes
   4 // Author:      Julian Smart and Guillermo Rodriguez Garcia
   5 // Modified by:
   6 // Created:     13/8/99
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Julian Smart and Guillermo Rodriguez Garcia
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_ANIMATEH__
  13 #define _WX_ANIMATEH__
  14
  15 #if defined(__GNUG__) && !defined(__APPLE__)
  16     #pragma interface "animate.h"
  17 #endif
  18
  19 #include <wx/defs.h>
  20 #include <wx/string.h>
  21 #include <wx/gdicmn.h>
  22 #include <wx/list.h>
  23 #include <wx/timer.h>
  24
  25 //#define ANIMDLLEXPORT WXDLLEXPORT
  26 #define ANIMDLLEXPORT
  27
  28 class ANIMDLLEXPORT wxAnimationBase;
  29 class ANIMDLLEXPORT wxAnimationPlayer;
  30 class WXDLLEXPORT wxImage;
  31
  32 enum wxAnimationDisposal
  33 {
  34     wxANIM_UNSPECIFIED = -1,
  35     wxANIM_DONOTREMOVE = 0,
  36     wxANIM_TOBACKGROUND = 1,
  37     wxANIM_TOPREVIOUS = 2
  38 } ;
  39
  40 class ANIMDLLEXPORT wxAnimationTimer: public wxTimer
  41 {
  42 public:
  43     wxAnimationTimer() { m_player = (wxAnimationPlayer*) NULL; }
  44
  45     virtual void Notify();
  46     void SetPlayer(wxAnimationPlayer* player) { m_player = player; }
  47
  48 protected:
  49     wxAnimationPlayer*  m_player;
  50 };
  51
  52 /* wxAnimationPlayer
  53  * Create an object of this class, and either pass an wxXXXAnimation object in the constructor,
  54  * or call SetAnimation. Then call Play().
  55  * The wxAnimation object is only destroyed in the destructor if destroyAnimation is TRUE
  56  * in the constructor.
  57  */
  58
  59 class ANIMDLLEXPORT wxAnimationPlayer : public wxObject
  60 {
  61     DECLARE_CLASS(wxAnimationPlayer)
  62
  63 public:
  64     wxAnimationPlayer(wxAnimationBase *animation = (wxAnimationBase *) NULL, bool destroyAnimation = FALSE);
  65     ~wxAnimationPlayer();
  66 //// Accessors
  67
  68     void SetAnimation(wxAnimationBase* animation, bool destroyAnimation = FALSE);
  69     wxAnimationBase* GetAnimation() const { return m_animation; }
  70
  71     void SetDestroyAnimation(bool destroyAnimation) { m_destroyAnimation = destroyAnimation; };
  72     bool GetDestroyAnimation() const { return m_destroyAnimation; }
  73
  74     void SetCurrentFrame(int currentFrame) { m_currentFrame = currentFrame; };
  75     int GetCurrentFrame() const { return m_currentFrame; }
  76
  77     void SetWindow(wxWindow* window) { m_window = window; };
  78     wxWindow* GetWindow() const { return m_window; }
  79
  80     void SetPosition(const wxPoint& pos) { m_position = pos; };
  81     wxPoint GetPosition() const { return m_position; }
  82
  83     void SetLooped(bool looped) { m_looped = looped; };
  84     bool GetLooped() const { return m_looped; }
  85
  86     bool HasAnimation() const { return (m_animation != (wxAnimationBase*) NULL); }
  87
  88     bool IsPlaying() const { return m_isPlaying; }
  89
  90     // Specify whether the GIF's background colour is to be shown,
  91     // or whether the window background should show through (the default)
  92     void UseBackgroundColour(bool useBackground) { m_useBackgroundColour = useBackground; }
  93     bool UsingBackgroundColour() const { return m_useBackgroundColour; }
  94
  95     // Set and use a user-specified background colour (valid for transparent
  96     // animations only)
  97     void SetCustomBackgroundColour(const wxColour& col, bool useCustomBackgroundColour = TRUE)
  98     { m_customBackgroundColour = col; m_useCustomBackgroundColour = useCustomBackgroundColour; }
  99
 100     bool UsingCustomBackgroundColour() const { return m_useCustomBackgroundColour; }
 101     const wxColour& GetCustomBackgroundColour() const { return m_customBackgroundColour; }
 102
 103     // Another refinement - suppose we're drawing the animation in a separate
 104     // control or window. We may wish to use the background of the parent
 105     // window as the background of our animation. This allows us to specify
 106     // whether to grab from the parent or from this window.
 107     void UseParentBackground(bool useParent) { m_useParentBackground = useParent; }
 108     bool UsingParentBackground() const { return m_useParentBackground; }
 109
 110 //// Operations
 111
 112     // Play
 113     virtual bool Play(wxWindow& window, const wxPoint& pos = wxPoint(0, 0), bool looped = TRUE);
 114
 115     // Build animation (list of wxImages). If not called before Play
 116     // is called, Play will call this automatically.
 117     virtual bool Build();
 118
 119     // Stop the animation
 120     virtual void Stop();
 121
 122     // Draw the current view of the animation into this DC.
 123     // Call this from your OnPaint, for example.
 124     virtual void Draw(wxDC& dc);
 125
 126 //// Accessing the current animation
 127
 128     virtual int GetFrameCount() const;
 129     virtual wxImage* GetFrame(int i) const; // Creates a new wxImage
 130     virtual wxAnimationDisposal GetDisposalMethod(int i) const;
 131     virtual wxRect GetFrameRect(int i) const; // Position and size of frame
 132     virtual int GetDelay(int i) const; // Delay for this frame
 133
 134     virtual wxSize GetLogicalScreenSize() const;
 135     virtual bool GetBackgroundColour(wxColour& col) const ;
 136     virtual bool GetTransparentColour(wxColour& col) const ;
 137
 138 //// Implementation
 139
 140     // Play the frame
 141     virtual bool PlayFrame(int frame, wxWindow& window, const wxPoint& pos);
 142     virtual bool PlayFrame();
 143     virtual void DrawFrame(int frame, wxDC& dc, const wxPoint& pos);
 144     virtual void DrawBackground(wxDC& dc, const wxPoint& pos, const wxColour& colour);
 145
 146     // Clear the wxImage cache
 147     virtual void ClearCache();
 148
 149     // Save the pertinent area of the window so we can restore
 150     // it if drawing transparently
 151     void SaveBackground(const wxRect& rect);
 152
 153     wxBitmap& GetBackingStore() { return m_backingStore; }
 154
 155 //// Data members
 156 protected:
 157     wxAnimationBase*    m_animation;
 158     bool                m_destroyAnimation; // Destroy m_animation on deletion of this object
 159     wxList              m_frames;           // List of cached wxBitmap frames.
 160     int                 m_currentFrame;     // Current frame
 161     wxWindow*           m_window;           // Window to draw into
 162     wxPoint             m_position;         // Position to draw at
 163     bool                m_looped;           // Looped, or not
 164     wxAnimationTimer    m_timer;            // The timer
 165     bool                m_isPlaying;        // Is the animation playing?
 166     wxBitmap            m_savedBackground;  // Saved background of window portion
 167     wxBitmap            m_backingStore;     // The player draws into this
 168     bool                m_useBackgroundColour; // Use colour or background
 169     wxColour            m_customBackgroundColour; // Override animation background
 170     bool                m_useCustomBackgroundColour;
 171     bool                m_useParentBackground; // Grab background from parent?
 172 };
 173
 174 /* wxAnimationBase
 175  * Base class for animations.
 176  * A wxXXXAnimation only stores the animation, providing accessors to wxAnimationPlayer.
 177  * Currently an animation is read-only, but we could extend the API for adding frames
 178  * programmatically, and perhaps have a wxMemoryAnimation class that stores its frames
 179  * in memory, and is able to save all files with suitable filenames. You could then use
 180  * e.g. Ulead GIF Animator to load the image files into a GIF animation.
 181  */
 182
 183 class ANIMDLLEXPORT wxAnimationBase : public wxObject
 184 {
 185     DECLARE_ABSTRACT_CLASS(wxAnimationBase)
 186
 187 public:
 188     wxAnimationBase() {};
 189     ~wxAnimationBase() {};
 190
 191 //// Accessors. Should be overridden by each derived class.
 192
 193     virtual int GetFrameCount() const = 0;
 194     virtual wxImage* GetFrame(int i) const = 0; // Creates a new wxImage
 195     virtual wxAnimationDisposal GetDisposalMethod(int i) const = 0;
 196     virtual wxRect GetFrameRect(int i) const = 0; // Position and size of frame
 197     virtual int GetDelay(int i) const = 0; // Delay for this frame
 198
 199     virtual wxSize GetLogicalScreenSize() const = 0;
 200     virtual bool GetBackgroundColour(wxColour& col) const = 0;
 201     virtual bool GetTransparentColour(wxColour& col) const = 0;
 202
 203     // Is the animation OK?
 204     virtual bool IsValid() const = 0;
 205
 206 //// Operations
 207
 208     virtual bool LoadFile(const wxString& filename) { return FALSE; }
 209 };
 210
 211 /* wxGIFAnimation
 212  * This will be moved to a separate file in due course.
 213  */
 214
 215 class ANIMDLLEXPORT wxGIFDecoder;
 216
 217 class ANIMDLLEXPORT wxGIFAnimation : public wxAnimationBase
 218 {
 219     DECLARE_CLASS(wxGIFAnimation)
 220
 221 public:
 222     wxGIFAnimation() ;
 223     ~wxGIFAnimation() ;
 224
 225 //// Accessors
 226
 227     virtual int GetFrameCount() const;
 228     virtual wxImage* GetFrame(int i) const;
 229     virtual wxAnimationDisposal GetDisposalMethod(int i) const;
 230     virtual wxRect GetFrameRect(int i) const; // Position and size of frame
 231     virtual int GetDelay(int i) const; // Delay for this frame
 232
 233     virtual wxSize GetLogicalScreenSize() const ;
 234     virtual bool GetBackgroundColour(wxColour& col) const ;
 235     virtual bool GetTransparentColour(wxColour& col) const ;
 236
 237     virtual bool IsValid() const;
 238
 239 //// Operations
 240
 241     virtual bool LoadFile(const wxString& filename);
 242
 243 protected:
 244
 245     wxGIFDecoder*   m_decoder;
 246 };
 247
 248 /*
 249  * wxAnimationCtrlBase
 250  * Abstract base class for format-specific animation controls.
 251  * This class implements most of the functionality; all a derived
 252  * class has to do is create the appropriate animation class on demand.
 253  */
 254
 255 // Resize to animation size if this is set
 256 #define wxAN_FIT_ANIMATION       0x0010
 257
 258 class ANIMDLLEXPORT wxAnimationCtrlBase: public wxControl
 259 {
 260 public:
 261     wxAnimationCtrlBase() { }
 262     wxAnimationCtrlBase(wxWindow *parent, wxWindowID id,
 263             const wxString& filename = wxEmptyString,
 264             const wxPoint& pos = wxDefaultPosition,
 265             const wxSize& size = wxDefaultSize, long style = wxAN_FIT_ANIMATION|wxNO_BORDER,
 266             const wxString& name = wxT("animationControl"))
 267     {
 268         Create(parent, id, filename, pos, size, style, name);
 269     }
 270     ~wxAnimationCtrlBase();
 271
 272     bool Create(wxWindow *parent, wxWindowID id,
 273             const wxString& filename = wxEmptyString,
 274             const wxPoint& pos = wxDefaultPosition,
 275             const wxSize& size = wxDefaultSize, long style = wxAN_FIT_ANIMATION|wxNO_BORDER,
 276             const wxString& name = wxT("animationControl"));
 277
 278     //// Operations
 279     virtual bool LoadFile(const wxString& filename = wxEmptyString);
 280     virtual bool Play(bool looped = TRUE) ;
 281     virtual void Stop() { m_animationPlayer.Stop(); }
 282     virtual void FitToAnimation();
 283
 284     //// Accessors
 285     virtual bool IsPlaying() const { return m_animationPlayer.IsPlaying(); }
 286     virtual wxAnimationPlayer& GetPlayer() { return m_animationPlayer; }
 287     virtual wxAnimationBase* GetAnimation() { return m_animation; }
 288
 289     const wxString& GetFilename() const { return m_filename; }
 290     void SetFilename(const wxString& filename) { m_filename = filename; }
 291
 292     //// Event handlers
 293     void OnPaint(wxPaintEvent& event);
 294
 295 protected:
 296     virtual wxSize DoGetBestSize() const;
 297
 298     // Override this in derived classes
 299     virtual wxAnimationBase* DoCreateAnimation(const wxString& filename) = 0;
 300
 301     wxAnimationPlayer   m_animationPlayer;
 302     wxAnimationBase*    m_animation;
 303     wxString            m_filename;
 304
 305 private:
 306     DECLARE_ABSTRACT_CLASS(wxAnimationCtrlBase)
 307     DECLARE_EVENT_TABLE()
 308 };
 309
 310 /*
 311  * wxGIFAnimationCtrl
 312  * Provides a GIF animation class when required.
 313  */
 314
 315 class ANIMDLLEXPORT wxGIFAnimationCtrl: public wxAnimationCtrlBase
 316 {
 317 public:
 318     wxGIFAnimationCtrl() { }
 319     wxGIFAnimationCtrl(wxWindow *parent, wxWindowID id,
 320             const wxString& filename = wxEmptyString,
 321             const wxPoint& pos = wxDefaultPosition,
 322             const wxSize& size = wxDefaultSize, long style = wxAN_FIT_ANIMATION|wxNO_BORDER,
 323             const wxString& name = wxT("animationControl"))
 324     {
 325         Create(parent, id, filename, pos, size, style, name);
 326     }
 327
 328 protected:
 329     virtual wxAnimationBase* DoCreateAnimation(const wxString& filename) ;
 330 private:
 331     DECLARE_DYNAMIC_CLASS(wxGIFAnimationCtrl)
 332 };
 333
 334 #endif // _WX_ANIMATEH__
 335