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
  61         @param id
  62         The identifier for the control.
  63
  64         @param anim
  65         The initial animation shown in the control.
  66
  67         @param pos
  68         Initial position.
  69
  70         @param size
  71         Initial size.
  72
  73         @param style
  74         The window style, see wxAC_* flags.
  75
  76         @param name
  77         Control name.
  78
  79         @returns @true if the control was successfully created or @false if
  80                    creation failed.
  81     */
  82     bool Create(wxWindow * parent, wxWindowID id,
  83                 const wxAnimation& anim,
  84                 const wxPoint& pos = wxDefaultPosition,
  85                 const wxSize& size = wxDefaultSize,
  86                 long style = wxAC_DEFAULT_STYLE,
  87                 const wxString& name = "animationctrl");
  88
  89     /**
  90         Returns the animation associated with this control.
  91     */
  92     wxAnimation GetAnimation();
  93
  94     /**
  95         Returns the inactive bitmap shown in this control when the;
  96         see SetInactiveBitmap() for more info.
  97     */
  98     wxBitmap GetInactiveBitmap();
  99
 100     /**
 101         Returns @true if the animation is being played.
 102     */
 103     bool IsPlaying();
 104
 105     /**
 106         Loads the animation from the given file and calls SetAnimation().
 107         See wxAnimation::LoadFile for more info.
 108     */
 109     bool LoadFile(const wxString & file,
 110                   wxAnimationType animType = wxANIMATION_TYPE_ANY);
 111
 112     /**
 113         Starts playing the animation.
 114         The animation is always played in loop mode (unless the last frame of the
 115         animation
 116         has an infinite delay time) and always start from the first frame
 117         (even if you @ref stop() stopped it while some other frame was
 118         displayed).
 119     */
 120     bool Play();
 121
 122     /**
 123         Sets the animation to play in this control.
 124         If the previous animation is being played, it's @ref stop() Stopped.
 125
 126         Until Play() isn't called, a static image, the first
 127         frame of the given animation or the background colour will be shown
 128         (see SetInactiveBitmap() for more info).
 129     */
 130     void SetAnimation(const wxAnimation & anim);
 131
 132     /**
 133         Sets the bitmap to show on the control when it's not playing an animation.
 134         If you set as inactive bitmap @c wxNullBitmap (which is the default), then the
 135         first frame of the animation is instead shown when the control is inactive; in
 136         this case,
 137         if there's no valid animation associated with the control (see
 138         wxAnimationCtrl::SetAnimation),
 139         then the background colour of the window is shown.
 140
 141         If the control is not playing the animation, the given bitmap will be
 142         immediately
 143         shown, otherwise it will be shown as soon as Stop()
 144         is called.
 145
 146         Note that the inactive bitmap, if smaller than the control's size, will be
 147         centered in
 148         the control; if bigger, it will be stretched to fit it.
 149     */
 150     void SetInactiveBitmap(const wxBitmap& bmp);
 151
 152     /**
 153         Stops playing the animation.
 154         The control will show the first frame of the animation, a custom static image or
 155         the window's background colour as specified by the
 156         last SetInactiveBitmap() call.
 157     */
 158     void Stop();
 159 };
 160
 161
 162 /**
 163     @class wxAnimation
 164     @wxheader{animate.h}
 165
 166     This class encapsulates the concept of a platform-dependent animation.
 167     An animation is a sequence of frames of the same size.
 168     Sound is not supported by wxAnimation.
 169
 170     @library{wxadv}
 171     @category{FIXME}
 172
 173     @stdobjects
 174     Objects:
 175     wxNullAnimation
 176
 177     @seealso
 178     wxAnimationCtrl
 179 */
 180 class wxAnimation : public wxGDIObject
 181 {
 182 public:
 183     //@{
 184     /**
 185         Loads an animation from a file.
 186
 187         @param name
 188         The name of the file to load.
 189
 190         @param type
 191         See LoadFile for more info.
 192     */
 193     wxAnimation();
 194     wxAnimation(const wxAnimation& anim);
 195     wxAnimation(const wxString& name,
 196                 wxAnimationType type = wxANIMATION_TYPE_ANY);
 197     //@}
 198
 199     /**
 200         Destructor.
 201         See @ref overview_refcountdestruct "reference-counted object destruction" for
 202         more info.
 203     */
 204     ~wxAnimation();
 205
 206     /**
 207         Returns the delay for the i-th frame in milliseconds.
 208         If @c -1 is returned the frame is to be displayed forever.
 209     */
 210     int GetDelay(unsigned int i);
 211
 212     /**
 213         Returns the i-th frame as a wxImage.
 214     */
 215     wxImage GetFrame(unsigned int i);
 216
 217     /**
 218         Returns the number of frames for this animation.
 219     */
 220     unsigned int GetFrameCount();
 221
 222     /**
 223         Returns the size of the animation.
 224     */
 225     wxSize GetSize();
 226
 227     /**
 228         Returns @true if animation data is present.
 229     */
 230 #define bool IsOk()     /* implementation is private */
 231
 232     /**
 233         Loads an animation from the given stream.
 234
 235         @param stream
 236         The stream to use to load the animation.
 237
 238         @param type
 239         One of the following values:
 240
 241
 242         wxANIMATION_TYPE_GIF
 243
 244
 245         Load an animated GIF file.
 246
 247         wxANIMATION_TYPE_ANI
 248
 249
 250         Load an ANI file.
 251
 252         wxANIMATION_TYPE_ANY
 253
 254
 255         Try to autodetect the filetype.
 256
 257         @returns @true if the operation succeeded, @false otherwise.
 258     */
 259     bool Load(wxInputStream& stream,
 260               wxAnimationType type = wxANIMATION_TYPE_ANY);
 261
 262     /**
 263         Loads an animation from a file.
 264
 265         @param name
 266         A filename.
 267
 268         @param type
 269         One of the following values:
 270
 271
 272         wxANIMATION_TYPE_GIF
 273
 274
 275         Load an animated GIF file.
 276
 277         wxANIMATION_TYPE_ANI
 278
 279
 280         Load an ANI file.
 281
 282         wxANIMATION_TYPE_ANY
 283
 284
 285         Try to autodetect the filetype.
 286
 287         @returns @true if the operation succeeded, @false otherwise.
 288     */
 289     bool LoadFile(const wxString& name,
 290                   wxAnimationType type = wxANIMATION_TYPE_ANY);
 291
 292     /**
 293         Assignment operator, using @ref overview_trefcount "reference counting".
 294     */
 295     wxAnimation operator =(const wxAnimation& brush);
 296 };