interface/wx/animate.h

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