X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..42013f4c2866589e8a0ce6eba992f6745aebb857:/interface/animate.h?ds=sidebyside diff --git a/interface/animate.h b/interface/animate.h index 24dbe307af..7fb3a9a3d5 100644 --- a/interface/animate.h +++ b/interface/animate.h @@ -1,18 +1,35 @@ ///////////////////////////////////////////////////////////////////////////// // Name: animate.h -// Purpose: documentation for wxAnimationCtrl class +// Purpose: interface of wxAnimation* classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + Supported animation types. +*/ +enum wxAnimationType +{ + wxANIMATION_TYPE_INVALID, + + /** represents an animated GIF file. */ + wxANIMATION_TYPE_GIF, + + /** represents an ANI file. */ + wxANIMATION_TYPE_ANI, + + /** autodetect the filetype. */ + wxANIMATION_TYPE_ANY +}; + /** @class wxAnimationCtrl @wxheader{animate.h} This is a static control which displays an animation. - wxAnimationCtrl API is simple as possible and won't give you full control on the - animation; if you need it then use wxMediaCtrl. + wxAnimationCtrl API is as simple as possible and won't give you full control + on the animation; if you need it then use wxMediaCtrl. This control is useful to display a (small) animation while doing a long task (e.g. a "throbber"). @@ -30,10 +47,12 @@ @library{wxadv} @category{ctrl} + + @nativeimpl{wxgtk,wxmsw} + @appearance{animationctrl.png} - @seealso - wxAnimation + @see wxAnimation */ class wxAnimationCtrl : public wxControl { @@ -43,18 +62,19 @@ public: all the parameters. */ wxAnimationCtrl(wxWindow* parent, wxWindowID id, - const wxAnimation& anim, + const wxAnimation& anim = wxNullAnimation, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxAC_DEFAULT_STYLE, - const wxString& name = "animationctrl"); + const wxString& name = wxAnimationCtrlNameStr); /** - After control creation you must explicitely call Play() - to start to play the animation. Until that function won't be called, the first - frame + Creates the control with the given @a anim animation. + + After control creation you must explicitely call Play() to start to play + the animation. Until that function won't be called, the first frame of the animation is displayed. - + @param parent Parent window, must be non-@NULL. @param id @@ -69,87 +89,85 @@ public: The window style, see wxAC_* flags. @param name Control name. - + @returns @true if the control was successfully created or @false if creation failed. */ bool Create(wxWindow* parent, wxWindowID id, - const wxAnimation& anim, + const wxAnimation& anim = wxNullAnimation, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxAC_DEFAULT_STYLE, - const wxString& name = "animationctrl"); + const wxString& name = wxAnimationCtrlNameStr); /** Returns the animation associated with this control. */ - wxAnimation GetAnimation(); + virtual wxAnimation GetAnimation() const; /** Returns the inactive bitmap shown in this control when the; see SetInactiveBitmap() for more info. */ - wxBitmap GetInactiveBitmap(); + wxBitmap GetInactiveBitmap() const; /** Returns @true if the animation is being played. */ - bool IsPlaying(); + virtual bool IsPlaying() const; /** Loads the animation from the given file and calls SetAnimation(). See wxAnimation::LoadFile for more info. */ - bool LoadFile(const wxString& file, - wxAnimationType animType = wxANIMATION_TYPE_ANY); + virtual bool LoadFile(const wxString& file, + wxAnimationType animType = wxANIMATION_TYPE_ANY); /** Starts playing the animation. + The animation is always played in loop mode (unless the last frame of the - animation - has an infinite delay time) and always start from the first frame - (even if you @ref stop() stopped it while some other frame was - displayed). + animation has an infinite delay time) and always start from the first frame + even if you @ref Stop "stopped" it while some other frame was displayed. */ - bool Play(); + virtual bool Play(); /** Sets the animation to play in this control. - If the previous animation is being played, it's @ref stop() Stopped. - Until Play() isn't called, a static image, the first - frame of the given animation or the background colour will be shown + + If the previous animation is being played, it's @ref Stop() stopped. + Until Play() isn't called, a static image, the first frame of the given + animation or the background colour will be shown (see SetInactiveBitmap() for more info). */ - void SetAnimation(const wxAnimation& anim); + virtual void SetAnimation(const wxAnimation& anim); /** Sets the bitmap to show on the control when it's not playing an animation. - If you set as inactive bitmap @c wxNullBitmap (which is the default), then the - first frame of the animation is instead shown when the control is inactive; in - this case, - if there's no valid animation associated with the control (see - wxAnimationCtrl::SetAnimation), - then the background colour of the window is shown. + + If you set as inactive bitmap ::wxNullBitmap (which is the default), then the + first frame of the animation is instead shown when the control is inactive; + in this case, if there's no valid animation associated with the control + (see SetAnimation()), then the background colour of the window is shown. + If the control is not playing the animation, the given bitmap will be - immediately - shown, otherwise it will be shown as soon as Stop() - is called. + immediately shown, otherwise it will be shown as soon as Stop() is called. + Note that the inactive bitmap, if smaller than the control's size, will be - centered in - the control; if bigger, it will be stretched to fit it. + centered in the control; if bigger, it will be stretched to fit it. */ - void SetInactiveBitmap(const wxBitmap& bmp); + virtual void SetInactiveBitmap(const wxBitmap& bmp); /** Stops playing the animation. The control will show the first frame of the animation, a custom static image or - the window's background colour as specified by the - last SetInactiveBitmap() call. + the window's background colour as specified by the last SetInactiveBitmap() call. */ - void Stop(); + virtual void Stop(); }; + /** @class wxAnimation @wxheader{animate.h} @@ -159,164 +177,107 @@ public: Sound is not supported by wxAnimation. @library{wxadv} - @category{FIXME} + @category{gdi} @stdobjects - Objects: - wxNullAnimation + ::wxNullAnimation - @seealso - wxAnimationCtrl + @see wxAnimationCtrl */ class wxAnimation : public wxGDIObject { public: - //@{ + /** + Copy ctor. + */ + wxAnimation(const wxAnimation& anim); + /** Loads an animation from a file. - + @param name The name of the file to load. @param type See LoadFile for more info. */ - wxAnimation(); - wxAnimation(const wxAnimation& anim); wxAnimation(const wxString& name, wxAnimationType type = wxANIMATION_TYPE_ANY); - //@} /** Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. + See @ref overview_refcount_destruct for more info. */ - ~wxAnimation(); + virtual ~wxAnimation(); /** Returns the delay for the i-th frame in milliseconds. If @c -1 is returned the frame is to be displayed forever. */ - int GetDelay(unsigned int i); + virtual int GetDelay(unsigned int i) const; /** Returns the i-th frame as a wxImage. */ - wxImage GetFrame(unsigned int i); + virtual wxImage GetFrame(unsigned int i) const; /** Returns the number of frames for this animation. */ - unsigned int GetFrameCount(); + virtual unsigned int GetFrameCount() const; /** Returns the size of the animation. */ - wxSize GetSize(); + virtual wxSize GetSize() const; /** Returns @true if animation data is present. */ - bool IsOk(); + virtual bool IsOk() const; /** Loads an animation from the given stream. - + @param stream The stream to use to load the animation. @param type One of the following values: - - - - - - - - wxANIMATION_TYPE_GIF - - - - - Load an animated GIF file. - - - - - - wxANIMATION_TYPE_ANI - - - - - Load an ANI file. - - - - - - wxANIMATION_TYPE_ANY - - - - - Try to autodetect the filetype. - + @li wxANIMATION_TYPE_GIF: loads an animated GIF file; + @li wxANIMATION_TYPE_ANI: load an ANI file; + @li wxANIMATION_TYPE_ANY: tries to autodetect the filetype. + @returns @true if the operation succeeded, @false otherwise. */ - bool Load(wxInputStream& stream, - wxAnimationType type = wxANIMATION_TYPE_ANY); + virtual bool Load(wxInputStream& stream, + wxAnimationType type = wxANIMATION_TYPE_ANY); /** Loads an animation from a file. - + @param name A filename. @param type - One of the following values: - - - - - - - - wxANIMATION_TYPE_GIF - - - - - Load an animated GIF file. - - - - - - wxANIMATION_TYPE_ANI - - - - - Load an ANI file. - - - - - - wxANIMATION_TYPE_ANY - - - - - Try to autodetect the filetype. - + One of the wxAnimationType values; wxANIMATION_TYPE_ANY + means that the function should try to autodetect the filetype. + @returns @true if the operation succeeded, @false otherwise. */ - bool LoadFile(const wxString& name, - wxAnimationType type = wxANIMATION_TYPE_ANY); + virtual bool LoadFile(const wxString& name, + wxAnimationType type = wxANIMATION_TYPE_ANY); /** - Assignment operator, using @ref overview_trefcount "reference counting". + Assignment operator, using @ref overview_refcount "reference counting". */ - wxAnimation operator =(const wxAnimation& brush); + wxAnimation& operator =(const wxAnimation& brush); }; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + An empty animation object. +*/ +wxAnimation wxNullAnimation; +