docs/latex/wx/animatctrl.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        animatctrl.tex
   3 %% Purpose:     wxAnimationCtrl documentation
   4 %% Author:      Francesco Montorsi
   5 %% Created:     24-9-2006
   6 %% RCS-ID:      $Id$
   7 %% Copyright:   (c) 2006 Francesco Montorsi
   8 %% License:     wxWindows license
   9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  10
  11 \section{\class{wxAnimationCtrl}}\label{wxanimationctrl}
  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 \helpref{wxMediaCtrl}{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 \texttt{wxUSE\_ANIMATIONCTRL} is set to $1$ (the default).
  21
  22 \wxheading{Derived from}
  23
  24 \helpref{wxControl}{wxcontrol}\\
  25 \helpref{wxWindow}{wxwindow}\\
  26 \helpref{wxEvtHandler}{wxevthandler}\\
  27 \helpref{wxObject}{wxobject}
  28
  29 \wxheading{Include files}
  30
  31 <wx/animate.h>
  32
  33 \wxheading{Window styles}
  34
  35 \twocolwidtha{5cm}%
  36 \begin{twocollist}\itemsep=0pt
  37 \twocolitem{\windowstyle{wxAC\_DEFAULT\_STYLE}}{The default style: wxNO\_BORDER.}
  38 \twocolitem{\windowstyle{wxAC\_NO\_AUTORESIZE}}{By default, the control will adjust
  39 its size to exactly fit to the size of the animation when \helpref{SetAnimation}{wxanimationctrlsetanimation}
  40 is called. If this style flag is given, the control will not change its size}
  41 \end{twocollist}
  42
  43 %\wxheading{Event handling}
  44 %
  45 %\twocolwidtha{7cm}%
  46 %\begin{twocollist}\itemsep=0pt
  47 %\twocolitem{{\bf EVT\_ANIMATION\_END(id, func)}}{}
  48 %\end{twocollist}
  49
  50 \wxheading{See also}
  51
  52 \helpref{wxAnimation}{wxanimation}
  53
  54
  55 \latexignore{\rtfignore{\wxheading{Members}}}
  56
  57 \membersection{wxAnimationCtrl::wxAnimationCtrl}\label{wxanimationctrl}
  58
  59 \func{}{wxAnimationCtrl}{\param{wxWindow *}{parent},\rtfsp
  60 \param{wxWindowID}{ id},\rtfsp
  61 \param{const wxAnimation\& }{anim},\rtfsp
  62 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  63 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  64 \param{long}{ style = wxAC\_DEFAULT\_STYLE},\rtfsp
  65 \param{const wxString\& }{name = ``animationctrl"}}
  66
  67 Initializes the object and calls \helpref{Create}{wxanimationctrlcreate} with
  68 all the parameters.
  69
  70
  71 \membersection{wxAnimationCtrl::Create}\label{wxanimationctrlcreate}
  72
  73 \func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
  74 \param{wxWindowID}{ id},\rtfsp
  75 \param{const wxAnimation\& }{anim},\rtfsp
  76 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  77 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  78 \param{long}{ style = wxAC\_DEFAULT\_STYLE},\rtfsp
  79 \param{const wxString\& }{name = ``animationctrl"}}
  80
  81 \wxheading{Parameters}
  82
  83 \docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
  84
  85 \docparam{id}{The identifier for the control.}
  86
  87 \docparam{anim}{The initial animation shown in the control.}
  88
  89 \docparam{pos}{Initial position.}
  90
  91 \docparam{size}{Initial size.}
  92
  93 \docparam{style}{The window style, see {\tt wxAC\_*} flags.}
  94
  95 \docparam{name}{Control name.}
  96
  97 After control creation you must explicitely call \helpref{Play}{wxanimationctrlplay}
  98 to start to play the animation. Until that function won't be called, the first frame
  99 of the animation is displayed.
 100
 101 \wxheading{Return value}
 102
 103 \true if the control was successfully created or \false if creation failed.
 104
 105
 106 \membersection{wxAnimationCtrl::GetAnimation}\label{wxanimationctrlgetanimation}
 107
 108 \constfunc{wxAnimation}{GetAnimation}{\void}
 109
 110 Returns the animation associated with this control.
 111
 112
 113 \membersection{wxAnimationCtrl::GetInactiveBitmap}\label{wxanimationctrlgetinactivebitmap}
 114
 115 \constfunc{wxBitmap}{GetInactiveBitmap}{\void}
 116
 117 Returns the inactive bitmap shown in this control when the;
 118 see \helpref{SetInactiveBitmap}{wxanimationctrlsetinactivebitmap} for more info.
 119
 120
 121 \membersection{wxAnimationCtrl::IsPlaying}\label{wxanimationctrlisplaying}
 122
 123 \constfunc{bool}{IsPlaying}{\void}
 124
 125 Returns \true if the animation is being played.
 126
 127
 128 \membersection{wxAnimationCtrl::LoadFile}\label{wxanimationctrlloadfile}
 129
 130 \func{bool}{LoadFile}{\param{const wxString \&}{ file}, \param{wxAnimationType }{ animType = wxANIMATION\_TYPE\_ANY}}
 131
 132 Loads the animation from the given file and calls \helpref{SetAnimation}{wxanimationctrlsetanimation}.
 133 See \helpref{wxAnimation::LoadFile}{wxanimationloadfile} for more info.
 134
 135
 136 \membersection{wxAnimationCtrl::Play}\label{wxanimationctrlplay}
 137
 138 \func{bool}{Play}{\void}
 139
 140 Starts playing the animation.
 141 The animation is always played in loop mode (unless the last frame of the animation
 142 has an infinite delay time) and always start from the first frame
 143 (even if you \helpref{atopped}{wxanimationctrlstop} it while some other frame was
 144 displayed).
 145
 146
 147 \membersection{wxAnimationCtrl::SetAnimation}\label{wxanimationctrlsetanimation}
 148
 149 \func{void}{SetAnimation}{\param{const wxAnimation \&}{ anim}}
 150
 151 Sets the animation to play in this control.
 152 If the previous animation is being played, it's \helpref{Stopped}{wxanimationctrlstop}.
 153
 154 Until \helpref{Play}{wxanimationctrlplay} isn't called, a static image, the first
 155 frame of the given animation or the background colour will be shown
 156 (see \helpref{SetInactiveBitmap}{wxanimationctrlsetinactivebitmap} for more info).
 157
 158
 159 \membersection{wxAnimationCtrl::SetInactiveBitmap}\label{wxanimationctrlsetinactivebitmap}
 160
 161 \func{void}{SetInactiveBitmap}{\param{const wxBitmap\& }{bmp}}
 162
 163 Sets the bitmap to show on the control when it's not playing an animation.
 164 If you set as inactive bitmap {\tt wxNullBitmap} (which is the default), then the
 165 first frame of the animation is instead shown when the control is inactive; in this case,
 166 if there's no valid animation associated with the control (see \helpref{SetAnimation}{wxanimationctrlsetanimation}),
 167 then the background colour of the window is shown.
 168
 169 If the control is not playing the animation, the given bitmap will be immediately
 170 shown, otherwise it will be shown as soon as \helpref{Stop}{wxanimationctrlstop}
 171 is called.
 172
 173 \membersection{wxAnimationCtrl::Stop}\label{wxanimationctrlstop}
 174
 175 \func{void}{Stop}{\void}
 176
 177 Stops playing the animation.
 178 The control will show the first frame of the animation, a custom static image or
 179 the window's background colour as specified by the
 180 last \helpref{SetInactiveBitmap}{wxanimationctrlsetinactivebitmap} call.
 181