added wxAnimationCtrl (patch 1570325)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@41819 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -68,6 +68,7 @@ All (GUI):
 
 - Support for right-to-left text layout (started by Diaa Sami during Google Summer of
   Code, with a lot of help from Tim Kosse and others).
+- wxAnimationCtrl added (Francesco Montorsi)
 - Added wxAboutBox() function for displaying the standard about dialog
 - Added wxID_PAGE_SETUP standard id.
 - Added wxSize::IncBy() and DecBy() methods.

docs/latex/wx/animatctrl.tex

@@ -0,0 +1,159 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        animatctrl.tex
+%% Purpose:     wxAnimationCtrl documentation
+%% Author:      Francesco Montorsi
+%% Created:     24-9-2006
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2006 Francesco Montorsi
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxAnimationCtrl}}\label{wxanimationctrl}
+
+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 \helpref{wxMediaCtrl}{wxmediactrl}.
+
+This control is useful to display a (small) animation while doing a long task
+(e.g. a "throbber").
+
+It is only available if \texttt{wxUSE\_ANIMATIONCTRL} is set to $1$ (the default).
+
+\wxheading{Derived from}
+
+\helpref{wxControl}{wxcontrol}\\
+\helpref{wxWindow}{wxwindow}\\
+\helpref{wxEvtHandler}{wxevthandler}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/animate.h>
+
+\wxheading{Window styles}
+
+\twocolwidtha{5cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxAC\_DEFAULT\_STYLE}}{The default style: wxNO_BORDER.}
+\twocolitem{\windowstyle{wxAC\_NO_AUTORESIZE}}{By default, the control will adjust
+its size to exactly fit to the size of the animation when \helpref{SetAnimation}{wxanimationctrlsetanimation}
+is called. If this style flag is given, the control will not change its size}
+\end{twocollist}
+
+%\wxheading{Event handling}
+%
+%\twocolwidtha{7cm}%
+%\begin{twocollist}\itemsep=0pt
+%\twocolitem{{\bf EVT\_ANIMATION\_END(id, func)}}{}
+%\end{twocollist}
+
+\wxheading{See also}
+
+\helpref{wxAnimation}{wxanimation}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxAnimationCtrl::wxAnimationCtrl}\label{wxanimationctrl}
+
+\func{}{wxAnimationCtrl}{\param{wxWindow *}{parent},\rtfsp
+\param{wxWindowID}{ id},\rtfsp
+\param{const wxAnimation\& }{anim},\rtfsp
+\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
+\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
+\param{long}{ style = wxAC\_DEFAULT\_STYLE},\rtfsp
+\param{const wxString\& }{name = ``animationctrl"}}
+
+Initializes the object and calls \helpref{Create}{wxanimationctrlcreate} with
+all the parameters.
+
+
+\membersection{wxAnimationCtrl::Create}\label{wxanimationctrlcreate}
+
+\func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
+\param{wxWindowID}{ id},\rtfsp
+\param{const wxAnimation\& }{anim},\rtfsp
+\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
+\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
+\param{long}{ style = wxAC\_DEFAULT\_STYLE},\rtfsp
+\param{const wxString\& }{name = ``animationctrl"}}
+
+\wxheading{Parameters}
+
+\docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
+
+\docparam{id}{The identifier for the control.}
+
+\docparam{anim}{The initial animation shown in the control.}
+
+\docparam{pos}{Initial position.}
+
+\docparam{size}{Initial size.}
+
+\docparam{style}{The window style, see {\tt wxAC\_*} flags.}
+
+\docparam{name}{Control name.}
+
+After control creation you must explicitely call \helpref{Play}{wxanimationctrlplay}
+to start to play the animation. Until that function won't be called, the first frame
+of the animation is displayed.
+
+\wxheading{Return value}
+
+\true if the control was successfully created or \false if creation failed.
+
+
+\membersection{wxAnimationCtrl::GetAnimation}\label{wxanimationctrlgetanimation}
+
+\constfunc{wxAnimation}{GetAnimation}{\void}
+
+Returns the animation associated with this control.
+
+
+\membersection{wxAnimationCtrl::IsPlaying}\label{wxanimationctrlisplaying}
+
+\constfunc{bool}{IsPlaying}{\void}
+
+Returns \true if the animation is being played.
+
+
+\membersection{wxAnimationCtrl::LoadFile}\label{wxanimationctrlloadfile}
+
+\func{bool}{LoadFile}{\param{const wxString \&}{ file}, \param{wxAnimationType }{ animType = wxANIMATION\_TYPE\_ANY}}
+
+Loads the animation from the given file and calls \helpref{SetAnimation}{wxanimationctrlsetanimation}.
+See \helpref{wxAnimation::LoadFile}{wxanimationloadfile} for more info.
+
+
+\membersection{wxAnimationCtrl::Play}\label{wxanimationctrlplay}
+
+\func{bool}{Play}{\void}
+
+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 \helpref{atopped}{wxanimationctrlstop} it while some other frame was
+displayed).
+
+
+\membersection{wxAnimationCtrl::SetAnimation}\label{wxanimationctrlsetanimation}
+
+\func{void}{SetAnimation}{\param{const wxAnimation \&}{ anim}}
+
+Sets the animation to play in this control.
+If the previous animation is being played, it's \helpref{Stopped}{wxanimationctrlstop}.
+
+Until \helpref{Play}{wxanimationctrlplay} isn't called, the first frame
+of the animation is displayed.
+
+If {\tt wxNullAnimation} is given as animation, the control will be cleared to display
+the background colour (see \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour}).
+
+
+\membersection{wxAnimationCtrl::Stop}\label{wxanimationctrlstop}
+
+\func{void}{Stop}{\void}
+
+Stops playing the animation.
+The control will show the last frame rendered of the current animation until
+\helpref{Play}{wxanimationctrlplay} is called.

docs/latex/wx/animation.tex

@@ -0,0 +1,153 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        animation.tex
+%% Purpose:     wxAnimation documentation
+%% Author:      Francesco Montorsi
+%% Created:     24-9-2006
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2006 Francesco Montorsi
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxAnimation}}\label{wxanimation}
+
+This class encapsulates the concept of a platform-dependent animation.
+An animation is a sequence of frames of the same size.
+Sound is not supported by wxAnimation.
+
+\wxheading{Derived from}
+
+\helpref{wxGDIObject}{wxgdiobject}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/animate.h>
+
+\wxheading{Predefined objects}
+
+Objects:
+
+{\bf wxNullAnimation}
+
+\wxheading{See also}
+
+\helpref{wxAnimationCtrl}{wxanimationctrl}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxAnimation::wxAnimation}\label{wxanimationctor}
+
+\func{}{wxAnimation}{\void}
+
+Default constructor.
+
+\func{}{wxAnimation}{\param{const wxAnimation\& }{anim}}
+
+Copy constructor.
+wxAnimation objects are reference counted so that this operation is very fast.
+
+\func{}{wxAnimation}{\param{const wxString\& }{name}, \param{wxAnimationType}{ type = wxANIMATION\_TYPE\_ANY}}
+
+Loads an animation from a file.
+
+\docparam{name}{The name of the file to load.}
+
+\docparam{type}{See \helpref{LoadFile}{wxanimationloadfile} for more info.}
+
+
+\membersection{wxAnimation::\destruct{wxAnimation}}\label{wxanimationdtor}
+
+\func{}{\destruct{wxAnimation}}{\void}
+
+Destroys the wxAnimation object and possibly the underlying animation data.
+Because reference counting is used, the animation may not actually be
+destroyed at this point - only when the reference count is zero will the
+data be deleted.
+
+
+\membersection{wxAnimation::GetDelay}\label{wxanimationgetdelay}
+
+\constfunc{int}{GetDelay}{\param{size_t }{i}}
+
+Returns the delay for the i-th frame in milliseconds.
+If {\tt -1} is returned the frame is to be displayed forever.
+
+
+\membersection{wxAnimation::GetFrameCount}\label{wxanimationgetframecount}
+
+\constfunc{size_t}{GetFrameCount}{\void}
+
+Returns the number of frames for this animation.
+
+
+\membersection{wxAnimation::GetFrame}\label{wxanimationgetframe}
+
+\constfunc{wxImage}{GetFrame}{\param{size_t }{i}}
+
+Returns the i-th frame as a \helpref{wxImage}{wximage}.
+
+
+\membersection{wxAnimation::GetSize}\label{wxanimationgetsize}
+
+\constfunc{wxSize}{GetSize}{\void}
+
+Returns the size of the animation.
+
+
+\membersection{wxAnimation::IsOk}\label{wxanimationisok}
+
+\constfunc{bool}{IsOk}{\void}
+
+Returns \true if animation data is present.
+
+
+\membersection{wxAnimation::Load}\label{wxanimationload}
+
+\func{bool}{Load}{\param{wxInputStream&}{ stream}, \param{wxAnimationType}{ type = wxANIMATION\_TYPE\_ANY}}
+
+Loads an animation from the given stream.
+
+\wxheading{Parameters}
+
+\docparam{stream}{The stream to use to load the animation.}
+
+\docparam{type}{One of the following values:
+
+\twocolwidtha{5cm}
+\begin{twocollist}
+\twocolitem{\indexit{wxANIM\_TYPE\_GIF}}{Load an animated GIF file.}
+\twocolitem{\indexit{wxANIM\_TYPE\_ANI}}{Load an ANI file.}
+\twocolitem{\indexit{wxANIM\_TYPE\_ANY}}{Try to autodetect the filetype.}
+\end{twocollist}
+}
+
+\wxheading{Return value}
+
+\true if the operation succeeded, \false otherwise.
+
+
+\membersection{wxAnimation::LoadFile}\label{wxanimationloadfile}
+
+\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{wxAnimationType}{ type = wxANIMATION\_TYPE\_ANY}}
+
+Loads an animation from a file.
+
+\wxheading{Parameters}
+
+\docparam{name}{A filename.}
+
+\docparam{type}{One of the following values:
+
+\twocolwidtha{5cm}
+\begin{twocollist}
+\twocolitem{\indexit{wxANIM\_TYPE\_GIF}}{Load an animated GIF file.}
+\twocolitem{\indexit{wxANIM\_TYPE\_ANI}}{Load an ANI file.}
+\twocolitem{\indexit{wxANIM\_TYPE\_ANY}}{Try to autodetect the filetype.}
+\end{twocollist}
+}
+
+\wxheading{Return value}
+
+\true if the operation succeeded, \false otherwise.
+

docs/latex/wx/category.tex

@@ -85,6 +85,7 @@ that are not static can have \helpref{validators}{wxvalidator} associated with t
 
 \twocolwidtha{6cm}
 \begin{twocollist}\itemsep=0pt
+\twocolitem{\helpref{wxAnimationCtrl}{wxanimationctrl}}{A control to display an animation}
 \twocolitem{\helpref{wxControl}{wxcontrol}}{The base class for controls}
 \twocolitem{\helpref{wxButton}{wxbutton}}{Push button control, displaying text}
 \twocolitem{\helpref{wxBitmapButton}{wxbitmapbutton}}{Push button control, displaying a bitmap}

docs/latex/wx/classes.tex

@@ -11,6 +11,8 @@
 \input activevt.tex
 \input activexcontainer.tex
 \input activexevt.tex
+\input animation.tex
+\input animatctrl.tex
 \input app.tex
 \input apptraits.tex
 \input archive.tex