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 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
  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 explicitely 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     @library{wxadv}
 185     @category{gdi}
 186
 187     @stdobjects
 188     ::wxNullAnimation
 189
 190     @see wxAnimationCtrl, @sample{animate}
 191 */
 192 class wxAnimation : public wxGDIObject
 193 {
 194 public:
 195     /**
 196         Copy ctor.
 197     */
 198     wxAnimation(const wxAnimation& anim);
 199
 200     /**
 201         Loads an animation from a file.
 202
 203         @param name
 204             The name of the file to load.
 205         @param type
 206             See LoadFile for more info.
 207     */
 208     wxAnimation(const wxString& name,
 209                 wxAnimationType type = wxANIMATION_TYPE_ANY);
 210
 211     /**
 212         Destructor.
 213         See @ref overview_refcount_destruct for more info.
 214     */
 215     virtual ~wxAnimation();
 216
 217     /**
 218         Returns the delay for the i-th frame in milliseconds.
 219         If @c -1 is returned the frame is to be displayed forever.
 220     */
 221     virtual int GetDelay(unsigned int i) const;
 222
 223     /**
 224         Returns the i-th frame as a wxImage.
 225     */
 226     virtual wxImage GetFrame(unsigned int i) const;
 227
 228     /**
 229         Returns the number of frames for this animation.
 230     */
 231     virtual unsigned int GetFrameCount() const;
 232
 233     /**
 234         Returns the size of the animation.
 235     */
 236     virtual wxSize GetSize() const;
 237
 238     /**
 239         Returns @true if animation data is present.
 240     */
 241     virtual bool IsOk() const;
 242
 243     /**
 244         Loads an animation from the given stream.
 245
 246         @param stream
 247             The stream to use to load the animation.
 248         @param type
 249             One of the following values:
 250              @li wxANIMATION_TYPE_GIF: loads an animated GIF file;
 251              @li wxANIMATION_TYPE_ANI: load an ANI file;
 252              @li wxANIMATION_TYPE_ANY: tries to autodetect the filetype.
 253
 254         @return @true if the operation succeeded, @false otherwise.
 255     */
 256     virtual bool Load(wxInputStream& stream,
 257                       wxAnimationType type = wxANIMATION_TYPE_ANY);
 258
 259     /**
 260         Loads an animation from a file.
 261
 262         @param name
 263             A filename.
 264         @param type
 265             One of the wxAnimationType values; wxANIMATION_TYPE_ANY
 266             means that the function should try to autodetect the filetype.
 267
 268         @return @true if the operation succeeded, @false otherwise.
 269     */
 270     virtual bool LoadFile(const wxString& name,
 271                           wxAnimationType type = wxANIMATION_TYPE_ANY);
 272
 273     /**
 274         Assignment operator, using @ref overview_refcount "reference counting".
 275     */
 276     wxAnimation& operator =(const wxAnimation& brush);
 277 };
 278
 279
 280 // ============================================================================
 281 // Global functions/macros
 282 // ============================================================================
 283
 284 /**
 285     An empty animation object.
 286 */
 287 wxAnimation wxNullAnimation;
 288