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