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