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,
  66                     const wxPoint& pos = wxDefaultPosition,
  67                     const wxSize& size = wxDefaultSize,
  68                     long style = wxAC_DEFAULT_STYLE,
  69                     const wxString& name = "animationctrl");
  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         @returns @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,
  98                 const wxPoint& pos = wxDefaultPosition,
  99                 const wxSize& size = wxDefaultSize,
 100                 long style = wxAC_DEFAULT_STYLE,
 101                 const wxString& name = "animationctrl");
 102
 103     /**
 104         Returns the animation associated with this control.
 105     */
 106     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     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     bool LoadFile(const wxString& file,
 124                   wxAnimationType animType = wxANIMATION_TYPE_ANY);
 125
 126     /**
 127         Starts playing the animation.
 128
 129         The animation is always played in loop mode (unless the last frame of the
 130         animation has an infinite delay time) and always start from the first frame
 131         even if you @ref Stop "stopped" it while some other frame was displayed.
 132     */
 133     bool Play();
 134
 135     /**
 136         Sets the animation to play in this control.
 137
 138         If the previous animation is being played, it's @ref Stop() stopped.
 139         Until Play() isn't called, a static image, the first frame of the given
 140         animation or the background colour will be shown
 141         (see SetInactiveBitmap() for more info).
 142     */
 143     void SetAnimation(const wxAnimation& anim);
 144
 145     /**
 146         Sets the bitmap to show on the control when it's not playing an animation.
 147
 148         If you set as inactive bitmap ::wxNullBitmap (which is the default), then the
 149         first frame of the animation is instead shown when the control is inactive;
 150         in this case, if there's no valid animation associated with the control
 151         (see SetAnimation()), then the background colour of the window is shown.
 152
 153         If the control is not playing the animation, the given bitmap will be
 154         immediately shown, otherwise it will be shown as soon as Stop() is called.
 155
 156         Note that the inactive bitmap, if smaller than the control's size, will be
 157         centered in the control; if bigger, it will be stretched to fit it.
 158     */
 159     void SetInactiveBitmap(const wxBitmap& bmp);
 160
 161     /**
 162         Stops playing the animation.
 163         The control will show the first frame of the animation, a custom static image or
 164         the window's background colour as specified by the last SetInactiveBitmap() call.
 165     */
 166     void Stop();
 167 };
 168
 169
 170
 171 /**
 172     @class wxAnimation
 173     @wxheader{animate.h}
 174
 175     This class encapsulates the concept of a platform-dependent animation.
 176     An animation is a sequence of frames of the same size.
 177     Sound is not supported by wxAnimation.
 178
 179     @library{wxadv}
 180     @category{gdi}
 181
 182     @stdobjects
 183     ::wxNullAnimation
 184
 185     @see wxAnimationCtrl
 186 */
 187 class wxAnimation : public wxGDIObject
 188 {
 189 public:
 190     wxAnimation();
 191     wxAnimation(const wxAnimation& anim);
 192
 193     /**
 194         Loads an animation from a file.
 195
 196         @param name
 197             The name of the file to load.
 198         @param type
 199             See LoadFile for more info.
 200     */
 201     wxAnimation(const wxString& name,
 202                 wxAnimationType type = wxANIMATION_TYPE_ANY);
 203
 204     /**
 205         Destructor.
 206         See @ref overview_refcount_destruct for more info.
 207     */
 208     ~wxAnimation();
 209
 210     /**
 211         Returns the delay for the i-th frame in milliseconds.
 212         If @c -1 is returned the frame is to be displayed forever.
 213     */
 214     int GetDelay(unsigned int i) const;
 215
 216     /**
 217         Returns the i-th frame as a wxImage.
 218     */
 219     wxImage GetFrame(unsigned int i) const;
 220
 221     /**
 222         Returns the number of frames for this animation.
 223     */
 224     unsigned int GetFrameCount() const;
 225
 226     /**
 227         Returns the size of the animation.
 228     */
 229     wxSize GetSize() const;
 230
 231     /**
 232         Returns @true if animation data is present.
 233     */
 234     bool IsOk() const;
 235
 236     /**
 237         Loads an animation from the given stream.
 238
 239         @param stream
 240             The stream to use to load the animation.
 241         @param type
 242             One of the following values:
 243              @li wxANIMATION_TYPE_GIF: loads an animated GIF file;
 244              @li wxANIMATION_TYPE_ANI: load an ANI file;
 245              @li wxANIMATION_TYPE_ANY: tries to autodetect the filetype.
 246
 247         @returns @true if the operation succeeded, @false otherwise.
 248     */
 249     bool Load(wxInputStream& stream,
 250               wxAnimationType type = wxANIMATION_TYPE_ANY);
 251
 252     /**
 253         Loads an animation from a file.
 254
 255         @param name
 256             A filename.
 257         @param type
 258             One of the wxAnimationType values; wxANIMATION_TYPE_ANY
 259             means that the function should try to autodetect the filetype.
 260
 261         @returns @true if the operation succeeded, @false otherwise.
 262     */
 263     bool LoadFile(const wxString& name,
 264                   wxAnimationType type = wxANIMATION_TYPE_ANY);
 265
 266     /**
 267         Assignment operator, using @ref overview_refcount "reference counting".
 268     */
 269     wxAnimation operator =(const wxAnimation& brush);
 270 };
 271
 272
 273 // ============================================================================
 274 // Global functions/macros
 275 // ============================================================================
 276
 277 /**
 278     An empty animation object.
 279 */
 280 wxAnimation wxNullAnimation;
 281