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