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