wxPython/contrib/animate/animate.i

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