interface/animate.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        animate.h
   3 // Purpose:     documentation for wxAnimationCtrl class
   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     @seealso
  36     wxAnimation
  37 */
  38 class wxAnimationCtrl : public wxControl
  39 {
  40 public:
  41     /**
  42         Initializes the object and calls Create() with
  43         all the parameters.
  44     */
  45     wxAnimationCtrl(wxWindow* parent, wxWindowID id,
  46                     const wxAnimation& anim,
  47                     const wxPoint& pos = wxDefaultPosition,
  48                     const wxSize& size = wxDefaultSize,
  49                     long style = wxAC_DEFAULT_STYLE,
  50                     const wxString& name = "animationctrl");
  51
  52     /**
  53         After control creation you must explicitely call Play()
  54         to start to play the animation. Until that function won't be called, the first
  55         frame
  56         of the animation is displayed.
  57
  58         @param parent
  59             Parent window, must be non-@NULL.
  60         @param id
  61             The identifier for the control.
  62         @param anim
  63             The initial animation shown in the control.
  64         @param pos
  65             Initial position.
  66         @param size
  67             Initial size.
  68         @param style
  69             The window style, see wxAC_* flags.
  70         @param name
  71             Control name.
  72
  73         @returns @true if the control was successfully created or @false if
  74                  creation failed.
  75     */
  76     bool Create(wxWindow* parent, wxWindowID id,
  77                 const wxAnimation& anim,
  78                 const wxPoint& pos = wxDefaultPosition,
  79                 const wxSize& size = wxDefaultSize,
  80                 long style = wxAC_DEFAULT_STYLE,
  81                 const wxString& name = "animationctrl");
  82
  83     /**
  84         Returns the animation associated with this control.
  85     */
  86     wxAnimation GetAnimation();
  87
  88     /**
  89         Returns the inactive bitmap shown in this control when the;
  90         see SetInactiveBitmap() for more info.
  91     */
  92     wxBitmap GetInactiveBitmap();
  93
  94     /**
  95         Returns @true if the animation is being played.
  96     */
  97     bool IsPlaying();
  98
  99     /**
 100         Loads the animation from the given file and calls SetAnimation().
 101         See wxAnimation::LoadFile for more info.
 102     */
 103     bool LoadFile(const wxString& file,
 104                   wxAnimationType animType = wxANIMATION_TYPE_ANY);
 105
 106     /**
 107         Starts playing the animation.
 108         The animation is always played in loop mode (unless the last frame of the
 109         animation
 110         has an infinite delay time) and always start from the first frame
 111         (even if you @ref stop() stopped it while some other frame was
 112         displayed).
 113     */
 114     bool Play();
 115
 116     /**
 117         Sets the animation to play in this control.
 118         If the previous animation is being played, it's @ref stop() Stopped.
 119         Until Play() isn't called, a static image, the first
 120         frame of the given animation or the background colour will be shown
 121         (see SetInactiveBitmap() for more info).
 122     */
 123     void SetAnimation(const wxAnimation& anim);
 124
 125     /**
 126         Sets the bitmap to show on the control when it's not playing an animation.
 127         If you set as inactive bitmap @c wxNullBitmap (which is the default), then the
 128         first frame of the animation is instead shown when the control is inactive; in
 129         this case,
 130         if there's no valid animation associated with the control (see
 131         wxAnimationCtrl::SetAnimation),
 132         then the background colour of the window is shown.
 133         If the control is not playing the animation, the given bitmap will be
 134         immediately
 135         shown, otherwise it will be shown as soon as Stop()
 136         is called.
 137         Note that the inactive bitmap, if smaller than the control's size, will be
 138         centered in
 139         the control; if bigger, it will be stretched to fit it.
 140     */
 141     void SetInactiveBitmap(const wxBitmap& bmp);
 142
 143     /**
 144         Stops playing the animation.
 145         The control will show the first frame of the animation, a custom static image or
 146         the window's background colour as specified by the
 147         last SetInactiveBitmap() call.
 148     */
 149     void Stop();
 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:
 166     wxNullAnimation
 167
 168     @seealso
 169     wxAnimationCtrl
 170 */
 171 class wxAnimation : public wxGDIObject
 172 {
 173 public:
 174     //@{
 175     /**
 176         Loads an animation from a file.
 177
 178         @param name
 179             The name of the file to load.
 180         @param type
 181             See LoadFile for more info.
 182     */
 183     wxAnimation();
 184     wxAnimation(const wxAnimation& anim);
 185     wxAnimation(const wxString& name,
 186                 wxAnimationType type = wxANIMATION_TYPE_ANY);
 187     //@}
 188
 189     /**
 190         Destructor.
 191         See @ref overview_refcountdestruct "reference-counted object destruction" for
 192         more info.
 193     */
 194     ~wxAnimation();
 195
 196     /**
 197         Returns the delay for the i-th frame in milliseconds.
 198         If @c -1 is returned the frame is to be displayed forever.
 199     */
 200     int GetDelay(unsigned int i);
 201
 202     /**
 203         Returns the i-th frame as a wxImage.
 204     */
 205     wxImage GetFrame(unsigned int i);
 206
 207     /**
 208         Returns the number of frames for this animation.
 209     */
 210     unsigned int GetFrameCount();
 211
 212     /**
 213         Returns the size of the animation.
 214     */
 215     wxSize GetSize();
 216
 217     /**
 218         Returns @true if animation data is present.
 219     */
 220     bool IsOk();
 221
 222     /**
 223         Loads an animation from the given stream.
 224
 225         @param stream
 226             The stream to use to load the animation.
 227         @param type
 228             One of the following values:
 229
 230
 231
 232
 233
 234
 235
 236             wxANIMATION_TYPE_GIF
 237
 238
 239
 240
 241             Load an animated GIF file.
 242
 243
 244
 245
 246
 247             wxANIMATION_TYPE_ANI
 248
 249
 250
 251
 252             Load an ANI file.
 253
 254
 255
 256
 257
 258             wxANIMATION_TYPE_ANY
 259
 260
 261
 262
 263             Try to autodetect the filetype.
 264
 265         @returns @true if the operation succeeded, @false otherwise.
 266     */
 267     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 following values:
 277
 278
 279
 280
 281
 282
 283
 284             wxANIMATION_TYPE_GIF
 285
 286
 287
 288
 289             Load an animated GIF file.
 290
 291
 292
 293
 294
 295             wxANIMATION_TYPE_ANI
 296
 297
 298
 299
 300             Load an ANI file.
 301
 302
 303
 304
 305
 306             wxANIMATION_TYPE_ANY
 307
 308
 309
 310
 311             Try to autodetect the filetype.
 312
 313         @returns @true if the operation succeeded, @false otherwise.
 314     */
 315     bool LoadFile(const wxString& name,
 316                   wxAnimationType type = wxANIMATION_TYPE_ANY);
 317
 318     /**
 319         Assignment operator, using @ref overview_trefcount "reference counting".
 320     */
 321     wxAnimation operator =(const wxAnimation& brush);
 322 };