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{wxanimationctrlctor}
  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 After control creation you must explicitely call \helpref{Play}{wxanimationctrlplay}
  86 to start to play the animation. Until that function won't be called, the first frame
  87 of the animation is displayed.
  88
  89 \wxheading{Parameters}
  90
  91 \docparam{parent}{Parent window, must be non-\NULL.}
  92
  93 \docparam{id}{The identifier for the control.}
  94
  95 \docparam{anim}{The initial animation shown in the control.}
  96
  97 \docparam{pos}{Initial position.}
  98
  99 \docparam{size}{Initial size.}
 100
 101 \docparam{style}{The window style, see {\tt wxAC\_*} flags.}
 102
 103 \docparam{name}{Control name.}
 104
 105
 106 \wxheading{Return value}
 107
 108 \true if the control was successfully created or \false if creation failed.
 109
 110
 111 \membersection{wxAnimationCtrl::GetAnimation}\label{wxanimationctrlgetanimation}
 112
 113 \constfunc{wxAnimation}{GetAnimation}{\void}
 114
 115 Returns the animation associated with this control.
 116
 117
 118 \membersection{wxAnimationCtrl::GetInactiveBitmap}\label{wxanimationctrlgetinactivebitmap}
 119
 120 \constfunc{wxBitmap}{GetInactiveBitmap}{\void}
 121
 122 Returns the inactive bitmap shown in this control when the;
 123 see \helpref{SetInactiveBitmap}{wxanimationctrlsetinactivebitmap} for more info.
 124
 125
 126 \membersection{wxAnimationCtrl::IsPlaying}\label{wxanimationctrlisplaying}
 127
 128 \constfunc{bool}{IsPlaying}{\void}
 129
 130 Returns \true if the animation is being played.
 131
 132
 133 \membersection{wxAnimationCtrl::LoadFile}\label{wxanimationctrlloadfile}
 134
 135 \func{bool}{LoadFile}{\param{const wxString \&}{ file}, \param{wxAnimationType }{ animType = wxANIMATION\_TYPE\_ANY}}
 136
 137 Loads the animation from the given file and calls \helpref{SetAnimation}{wxanimationctrlsetanimation}.
 138 See \helpref{wxAnimation::LoadFile}{wxanimationloadfile} for more info.
 139
 140
 141 \membersection{wxAnimationCtrl::Play}\label{wxanimationctrlplay}
 142
 143 \func{bool}{Play}{\void}
 144
 145 Starts playing the animation.
 146 The animation is always played in loop mode (unless the last frame of the animation
 147 has an infinite delay time) and always start from the first frame
 148 (even if you \helpref{stopped}{wxanimationctrlstop} it while some other frame was
 149 displayed).
 150
 151
 152 \membersection{wxAnimationCtrl::SetAnimation}\label{wxanimationctrlsetanimation}
 153
 154 \func{void}{SetAnimation}{\param{const wxAnimation \&}{ anim}}
 155
 156 Sets the animation to play in this control.
 157 If the previous animation is being played, it's \helpref{Stopped}{wxanimationctrlstop}.
 158
 159 Until \helpref{Play}{wxanimationctrlplay} isn't called, a static image, the first
 160 frame of the given animation or the background colour will be shown
 161 (see \helpref{SetInactiveBitmap}{wxanimationctrlsetinactivebitmap} for more info).
 162
 163
 164 \membersection{wxAnimationCtrl::SetInactiveBitmap}\label{wxanimationctrlsetinactivebitmap}
 165
 166 \func{void}{SetInactiveBitmap}{\param{const wxBitmap\& }{bmp}}
 167
 168 Sets the bitmap to show on the control when it's not playing an animation.
 169 If you set as inactive bitmap {\tt wxNullBitmap} (which is the default), then the
 170 first frame of the animation is instead shown when the control is inactive; in this case,
 171 if there's no valid animation associated with the control (see \helpref{SetAnimation}{wxanimationctrlsetanimation}),
 172 then the background colour of the window is shown.
 173
 174 If the control is not playing the animation, the given bitmap will be immediately
 175 shown, otherwise it will be shown as soon as \helpref{Stop}{wxanimationctrlstop}
 176 is called.
 177
 178 Note that the inactive bitmap, if smaller than the control's size, will be centered in
 179 the control; if bigger, it will be stretched to fit it.
 180
 181
 182 \membersection{wxAnimationCtrl::Stop}\label{wxanimationctrlstop}
 183
 184 \func{void}{Stop}{\void}
 185
 186 Stops playing the animation.
 187 The control will show the first frame of the animation, a custom static image or
 188 the window's background colour as specified by the
 189 last \helpref{SetInactiveBitmap}{wxanimationctrlsetinactivebitmap} call.
 190