interface/wx/animate.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        animate.h
   3 // Purpose:     interface of wxAnimation* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Supported animation types.
  11 */
  12 enum wxAnimationType
  13 {
  14     wxANIMATION_TYPE_INVALID,
  15
  16     /** represents an animated GIF file. */
  17     wxANIMATION_TYPE_GIF,
  18
  19     /** represents an ANI file. */
  20     wxANIMATION_TYPE_ANI,
  21
  22     /** autodetect the filetype. */
  23     wxANIMATION_TYPE_ANY
  24 };
  25
  26 /**
  27     @class wxAnimationCtrl
  28
  29     This is a static control which displays an animation.
  30     wxAnimationCtrl API is as simple as possible and won't give you full control
  31     on the animation; if you need it then use wxMediaCtrl.
  32
  33     This control is useful to display a (small) animation while doing a long task
  34     (e.g. a "throbber").
  35
  36     It is only available if @c wxUSE_ANIMATIONCTRL is set to 1 (the default).
  37
  38     @beginStyleTable
  39     @style{wxAC_DEFAULT_STYLE}
  40            The default style: wxBORDER_NONE.
  41     @style{wxAC_NO_AUTORESIZE}
  42            By default, the control will adjust its size to exactly fit to the
  43            size of the animation when SetAnimation is called. If this style
  44            flag is given, the control will not change its size
  45     @endStyleTable
  46
  47     @library{wxadv}
  48     @category{ctrl}
  49
  50     @nativeimpl{wxgtk,wxmsw}
  51
  52     @appearance{animationctrl.png}
  53
  54     @see wxAnimation, @sample{animate}
  55 */
  56 class wxAnimationCtrl : public wxControl
  57 {
  58 public:
  59     /**
  60         Initializes the object and calls Create() with
  61         all the parameters.
  62     */
  63     wxAnimationCtrl(wxWindow* parent, wxWindowID id,
  64                     const wxAnimation& anim = wxNullAnimation,
  65                     const wxPoint& pos = wxDefaultPosition,
  66                     const wxSize& size = wxDefaultSize,
  67                     long style = wxAC_DEFAULT_STYLE,
  68                     const wxString& name = wxAnimationCtrlNameStr);
  69
  70     /**
  71         Creates the control with the given @a anim animation.
  72
  73         After control creation you must explicitly call Play() to start to play
  74         the animation. Until that function won't be called, the first frame
  75         of the animation is displayed.
  76
  77         @param parent
  78             Parent window, must be non-@NULL.
  79         @param id
  80             The identifier for the control.
  81         @param anim
  82             The initial animation shown in the control.
  83         @param pos
  84             Initial position.
  85         @param size
  86             Initial size.
  87         @param style
  88             The window style, see wxAC_* flags.
  89         @param name
  90             Control name.
  91
  92         @return @true if the control was successfully created or @false if
  93                 creation failed.
  94     */
  95     bool Create(wxWindow* parent, wxWindowID id,
  96                 const wxAnimation& anim = wxNullAnimation,
  97                 const wxPoint& pos = wxDefaultPosition,
  98                 const wxSize& size = wxDefaultSize,
  99                 long style = wxAC_DEFAULT_STYLE,
 100                 const wxString& name = wxAnimationCtrlNameStr);
 101
 102     /**
 103         Returns the animation associated with this control.
 104     */
 105     virtual wxAnimation GetAnimation() const;
 106
 107     /**
 108         Returns the inactive bitmap shown in this control when the;
 109         see SetInactiveBitmap() for more info.
 110     */
 111     wxBitmap GetInactiveBitmap() const;
 112
 113     /**
 114         Returns @true if the animation is being played.
 115     */
 116     virtual bool IsPlaying() const;
 117
 118     /**
 119         Loads the animation from the given file and calls SetAnimation().
 120         See wxAnimation::LoadFile for more info.
 121     */
 122     virtual bool LoadFile(const wxString& file,
 123                           wxAnimationType animType = wxANIMATION_TYPE_ANY);
 124
 125     /**
 126         Loads the animation from the given stream and calls SetAnimation().
 127         See wxAnimation::Load() for more info.
 128     */
 129     virtual bool Load(wxInputStream& file,
 130                       wxAnimationType animType = wxANIMATION_TYPE_ANY);
 131
 132     /**
 133         Starts playing the animation.
 134
 135         The animation is always played in loop mode (unless the last frame of the
 136         animation has an infinite delay time) and always start from the first frame
 137         even if you @ref Stop "stopped" it while some other frame was displayed.
 138     */
 139     virtual bool Play();
 140
 141     /**
 142         Sets the animation to play in this control.
 143
 144         If the previous animation is being played, it's @ref Stop() stopped.
 145         Until Play() isn't called, a static image, the first frame of the given
 146         animation or the background colour will be shown
 147         (see SetInactiveBitmap() for more info).
 148     */
 149     virtual void SetAnimation(const wxAnimation& anim);
 150
 151     /**
 152         Sets the bitmap to show on the control when it's not playing an animation.
 153
 154         If you set as inactive bitmap ::wxNullBitmap (which is the default), then the
 155         first frame of the animation is instead shown when the control is inactive;
 156         in this case, if there's no valid animation associated with the control
 157         (see SetAnimation()), then the background colour of the window is shown.
 158
 159         If the control is not playing the animation, the given bitmap will be
 160         immediately shown, otherwise it will be shown as soon as Stop() is called.
 161
 162         Note that the inactive bitmap, if smaller than the control's size, will be
 163         centered in the control; if bigger, it will be stretched to fit it.
 164     */
 165     virtual void SetInactiveBitmap(const wxBitmap& bmp);
 166
 167     /**
 168         Stops playing the animation.
 169         The control will show the first frame of the animation, a custom static image or
 170         the window's background colour as specified by the last SetInactiveBitmap() call.
 171     */
 172     virtual void Stop();
 173 };
 174
 175
 176
 177 /**
 178     @class wxAnimation
 179
 180     This class encapsulates the concept of a platform-dependent animation.
 181     An animation is a sequence of frames of the same size.
 182     Sound is not supported by wxAnimation.
 183
 184     Note that on wxGTK wxAnimation is capable of loading the formats supported
 185     by the internally-used @c gdk-pixbuf library (typically this means only
 186     @c wxANIMATION_TYPE_GIF).
 187     On other platforms wxAnimation is always capable of loading both GIF and ANI
 188     formats (i.e. both @c wxANIMATION_TYPE_GIF and @c wxANIMATION_TYPE_ANI).
 189
 190     @library{wxadv}
 191     @category{gdi}
 192
 193     @stdobjects
 194     ::wxNullAnimation
 195
 196     @see wxAnimationCtrl, @sample{animate}
 197 */
 198 class wxAnimation : public wxGDIObject
 199 {
 200 public:
 201     /**
 202         Copy ctor.
 203     */
 204     wxAnimation(const wxAnimation& anim);
 205
 206     /**
 207         Loads an animation from a file.
 208
 209         @param name
 210             The name of the file to load.
 211         @param type
 212             See LoadFile() for more info.
 213     */
 214     wxAnimation(const wxString& name,
 215                 wxAnimationType type = wxANIMATION_TYPE_ANY);
 216
 217     /**
 218         Destructor.
 219         See @ref overview_refcount_destruct for more info.
 220     */
 221     virtual ~wxAnimation();
 222
 223     /**
 224         Returns the delay for the i-th frame in milliseconds.
 225         If @c -1 is returned the frame is to be displayed forever.
 226     */
 227     virtual int GetDelay(unsigned int i) const;
 228
 229     /**
 230         Returns the i-th frame as a wxImage.
 231
 232         This method is not implemented in the native wxGTK implementation of
 233         this class and always returns an invalid image there.
 234     */
 235     virtual wxImage GetFrame(unsigned int i) const;
 236
 237     /**
 238         Returns the number of frames for this animation.
 239
 240         This method is not implemented in the native wxGTK implementation of
 241         this class and always returns 0 there.
 242     */
 243     virtual unsigned int GetFrameCount() const;
 244
 245     /**
 246         Returns the size of the animation.
 247     */
 248     virtual wxSize GetSize() const;
 249
 250     /**
 251         Returns @true if animation data is present.
 252     */
 253     virtual bool IsOk() const;
 254
 255     /**
 256         Loads an animation from the given stream.
 257
 258         @param stream
 259             The stream to use to load the animation.
 260             Under wxGTK may be any kind of stream; under other platforms
 261             this must be a seekable stream.
 262         @param type
 263             One of the ::wxAnimationType enumeration values.
 264
 265         @return @true if the operation succeeded, @false otherwise.
 266     */
 267     virtual bool Load(wxInputStream& stream,
 268                       wxAnimationType type = wxANIMATION_TYPE_ANY);
 269
 270     /**
 271         Loads an animation from a file.
 272
 273         @param name
 274             A filename.
 275         @param type
 276             One of the ::wxAnimationType values; wxANIMATION_TYPE_ANY
 277             means that the function should try to autodetect the filetype.
 278
 279         @return @true if the operation succeeded, @false otherwise.
 280     */
 281     virtual bool LoadFile(const wxString& name,
 282                           wxAnimationType type = wxANIMATION_TYPE_ANY);
 283
 284     /**
 285         Assignment operator, using @ref overview_refcount "reference counting".
 286     */
 287     wxAnimation& operator =(const wxAnimation& brush);
 288 };
 289
 290
 291 // ============================================================================
 292 // Global functions/macros
 293 // ============================================================================
 294
 295 /**
 296     An empty animation object.
 297 */
 298 wxAnimation wxNullAnimation;
 299