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