interface/animate.h

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