interface/wx/animate.h

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