interface/animate.h

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