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     @ingroup group_class_gdi
 174     @wxheader{animate.h}
 175
 176     This class encapsulates the concept of a platform-dependent animation.
 177     An animation is a sequence of frames of the same size.
 178     Sound is not supported by wxAnimation.
 179
 180     @library{wxadv}
 181     @category{gdi}
 182
 183     @stdobjects
 184     ::wxNullAnimation
 185
 186     @see wxAnimationCtrl
 187 */
 188 class wxAnimation : public wxGDIObject
 189 {
 190 public:
 191     wxAnimation();
 192     wxAnimation(const wxAnimation& anim);
 193
 194     /**
 195         Loads an animation from a file.
 196
 197         @param name
 198             The name of the file to load.
 199         @param type
 200             See LoadFile for more info.
 201     */
 202     wxAnimation(const wxString& name,
 203                 wxAnimationType type = wxANIMATION_TYPE_ANY);
 204
 205     /**
 206         Destructor.
 207         See @ref overview_refcount_destruct for more info.
 208     */
 209     ~wxAnimation();
 210
 211     /**
 212         Returns the delay for the i-th frame in milliseconds.
 213         If @c -1 is returned the frame is to be displayed forever.
 214     */
 215     int GetDelay(unsigned int i) const;
 216
 217     /**
 218         Returns the i-th frame as a wxImage.
 219     */
 220     wxImage GetFrame(unsigned int i) const;
 221
 222     /**
 223         Returns the number of frames for this animation.
 224     */
 225     unsigned int GetFrameCount() const;
 226
 227     /**
 228         Returns the size of the animation.
 229     */
 230     wxSize GetSize() const;
 231
 232     /**
 233         Returns @true if animation data is present.
 234     */
 235     bool IsOk() const;
 236
 237     /**
 238         Loads an animation from the given stream.
 239
 240         @param stream
 241             The stream to use to load the animation.
 242         @param type
 243             One of the following values:
 244              @li wxANIMATION_TYPE_GIF: loads an animated GIF file;
 245              @li wxANIMATION_TYPE_ANI: load an ANI file;
 246              @li wxANIMATION_TYPE_ANY: tries to autodetect the filetype.
 247
 248         @returns @true if the operation succeeded, @false otherwise.
 249     */
 250     bool Load(wxInputStream& stream,
 251               wxAnimationType type = wxANIMATION_TYPE_ANY);
 252
 253     /**
 254         Loads an animation from a file.
 255
 256         @param name
 257             A filename.
 258         @param type
 259             One of the wxAnimationType values; wxANIMATION_TYPE_ANY
 260             means that the function should try to autodetect the filetype.
 261
 262         @returns @true if the operation succeeded, @false otherwise.
 263     */
 264     bool LoadFile(const wxString& name,
 265                   wxAnimationType type = wxANIMATION_TYPE_ANY);
 266
 267     /**
 268         Assignment operator, using @ref overview_refcount "reference counting".
 269     */
 270     wxAnimation operator =(const wxAnimation& brush);
 271 };
 272
 273 /**
 274     An empty animation object.
 275 */
 276 wxAnimation wxNullAnimation;
 277