docs/latex/wx/mediactrl.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        mediactrl.tex
   3 %% Purpose:     wxMediaCtrl docs
   4 %% Author:      Ryan Norton <wxprojects@comcast.net>
   5 %% Modified by:
   6 %% Created:     11/7/2004
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Ryan Norton
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxMediaCtrl}}\label{wxmediactrl}
  13
  14 wxMediaCtrl is a class that allows a way to convieniently display types of
  15 media, such as videos, audio files, natively through native codecs.
  16
  17 wxMediaCtrl uses native backends to render media, for example on Windows
  18 there is a ActiveMovie/DirectShow backend, and on Macintosh there is a
  19 QuickTime backend.
  20
  21 \wxheading{Derived from}
  22
  23 \helpref{wxControl}{wxcontrol}
  24
  25 \wxheading{Include files}
  26
  27 <wx/mediactrl.h>
  28
  29 \latexignore{\rtfignore{\wxheading{Members}}}
  30
  31 \membersection{Rendering media}\label{renderingmediawxmediactrl}
  32
  33 Depending upon the backend, wxMediaCtrl can render
  34 and display pretty much any kind of media that the native system can -
  35 such as an image, mpeg video, or mp3 (without license restrictions -
  36 since it relies on native system calls that may not technically
  37 have mp3 decoding available, for example, it falls outside the
  38 realm of licensing restrictions).
  39
  40 For general operation, all you need to do is call
  41 \helpref{wxMediaCtrl::Load}{wxmediactrlload} to load the file
  42 you want to render, catch the EVT\_MEDIA\_LOADED event,
  43 and then call \helpref{wxMediaCtrl::Play}{wxmediactrlplay}
  44 to show the video/audio of the media in that event.
  45
  46 More complex operations are generally more heavily dependant on the
  47 capabilities of the backend.  For example, QuickTime cannot set
  48 the playback rate of certain streaming media - while DirectShow is
  49 slightly more flexible in that regard.
  50
  51 \membersection{Operation}\label{operationwxmediactrl}
  52
  53 When wxMediaCtrl plays a file, it plays until the stop position
  54 is reached (currently the end of the file/stream).  Right before
  55 it hits the end of the stream, it fires off a EVT\_MEDIA\_STOP
  56 event to its parent window, at which point the event handler
  57 can choose to veto the event, preventing the stream from actually
  58 stopping.
  59
  60 Example:
  61 \begin{verbatim}
  62 //connect to the media event
  63 this->Connect(wxMY_ID, wxEVT_MEDIA_STOP, (wxObjectEventFunction)
  64 (wxEventFunction)(wxMediaEventFunction) &MyFrame::OnMediaStop);
  65
  66 //...
  67 void MyFrame::OnMediaStop(const wxMediaEvent& evt)
  68 {
  69     if(bUserWantsToSeek)
  70     {
  71         m_mediactrl->SetPosition(
  72             m_mediactrl->GetDuration() << 1
  73                                 );
  74         evt.Veto();
  75     }
  76 }
  77 \end{verbatim}
  78
  79 When wxMediaCtrl stops, either by the EVT\_MEDIA\_STOP not being
  80 vetoed, or by manually calling
  81 \helpref{wxMediaCtrl::Stop}{wxmediactrlstop}, where it actually
  82 stops is not at the beginning, rather, but at the beginning of
  83 the stream.  That is, when it stops and play is called, playback
  84 is gauranteed to start at the beginning of the media.  This is
  85 because some streams are not seekable, and when stop is called
  86 on them they return to the beginning, thus wxMediaCtrl tries
  87 to keep consistant for all types of media.
  88
  89 \membersection{Choosing a backend}\label{choosingbackendwxmediactrl}
  90
  91 Generally, you should almost certainly leave this part up to
  92 wxMediaCtrl - but if you need a certain backend for a particular
  93 reason, such as QuickTime for playing .mov files, all you need
  94 to do to choose a specific backend is to pass the
  95 name of the backend class to
  96 \helpref{wxMediaCtrl::Create}{wxmediactrlcreate}.
  97
  98 The following are valid backend identifiers -
  99 \twocolwidtha{7cm}
 100 \begin{twocollist}\itemsep=0pt
 101 \twocolitem{{\bf wxMEDIABACKEND\_DIRECTSHOW}}{
 102 Use ActiveMovie/DirectShow.  Requires wxUSE\_DIRECTSHOW to be
 103 enabled, requires linkage with the static library strmiids.lib,
 104 and is available on Windows Only.}
 105 \twocolitem{{\bf wxMEDIABACKEND\_QUICKTIME}}{
 106 Use QuickTime.  Windows and Mac Only. NOTE: On Mac Systems lower than OSX 10.2 this defaults to emulating window positioning and suffers from several bugs, including not working correctly embedded in a wxNotebook. }
 107 \twocolitem{{\bf wxMEDIABACKEND\_MCI}}{
 108 Use Media Command Interface.  Windows Only. }
 109 \twocolitem{{\bf wxMEDIABACKEND\_GSTREAMER}}{
 110 Use GStreamer.  Unix Only. }
 111 \end{twocollist}
 112
 113 \membersection{wxMediaCtrl::wxMediaCtrl}\label{wxmediactrlwxmediactrl}
 114
 115 \func{}{wxMediaCtrl}{\void}
 116
 117 Default constructor - you \tt{must} call Create before calling any other methods
 118 of wxMediaCtrl.
 119
 120 \func{}{wxMediaCtrl}{
 121         \param{wxWindow* }{parent},
 122         \param{const wxString\& }{fileName = wxT("")},
 123         \param{wxWindowID }{id},
 124         \param{const wxPoint\& }{pos = wxDefaultPosition},
 125         \param{const wxSize\& }{size = wxDefaultSize},
 126         \param{long }{style = 0},
 127         \param{const wxString\& }{szBackend = wxT("")},
 128         \param{const wxValidator& }{validator = wxDefaultValidator},
 129         \param{const wxString\& }{name = wxPanelNameStr}
 130                    }
 131
 132 Constructor that calls \helpref{Create}{wxmediactrlcreate}.  You may prefer to call \helpref{Create}{wxmediactrlcreate} directly to check to see if wxMediaCtrl is available on the system.
 133
 134 \docparam{parent}{parent of this control.  Must not be NULL.}
 135 \docparam{id}{id to use for events}
 136 \docparam{fileName}{If not empty, the path of a file to open.}
 137 \docparam{pos}{Position to put control at.}
 138 \docparam{size}{Size to put the control at and to stretch movie to.}
 139 \docparam{style}{Optional styles.}
 140 \docparam{szBackend}{Name of backend you want to use, leave blank to make
 141 wxMediaCtrl figure it out.}
 142 \docparam{validator}{validator to use.}
 143 \docparam{name}{Window name.}
 144
 145
 146 \membersection{wxMediaCtrl::Create}\label{wxmediactrlcreate}
 147
 148 \func{bool}{Create}{
 149         \param{wxWindow* }{parent},
 150         \param{const wxString\& }{fileName = wxT("")},
 151         \param{wxWindowID }{id},
 152         \param{const wxPoint\& }{pos = wxDefaultPosition},
 153         \param{const wxSize\& }{size = wxDefaultSize},
 154         \param{long }{style = 0},
 155         \param{const wxString\& }{szBackend = wxT("")},
 156         \param{const wxValidator& }{validator = wxDefaultValidator},
 157         \param{const wxString\& }{name = wxPanelNameStr}
 158                    }
 159
 160 Creates this control.  Returns \tt{false} if it can't load the movie located at \tt{fileName} or it cannot load one of its native backends.
 161
 162 If you specify a file to open via \tt{fileName} and you don't specify a backend to use, wxMediaCtrl tries each of its backends until one that can render the path referred to by \tt{fileName} can be found.
 163
 164 \docparam{parent}{parent of this control.  Must not be NULL.}
 165 \docparam{id}{id to use for events}
 166 \docparam{fileName}{If not empty, the path of a file to open.}
 167 \docparam{pos}{Position to put control at.}
 168 \docparam{size}{Size to put the control at and to stretch movie to.}
 169 \docparam{style}{Optional styles.}
 170 \docparam{szBackend}{Name of backend you want to use, leave blank to make
 171 wxMediaCtrl figure it out.}
 172 \docparam{validator}{validator to use.}
 173 \docparam{name}{Window name.}
 174
 175
 176 \membersection{wxMediaCtrl::Length}\label{wxmediactrlgetduration}
 177
 178 \func{wxFileOffset}{GetDuration}{\void}
 179
 180 Obtains the length - the total amount of time the movie has in milliseconds.
 181
 182
 183 \membersection{wxMediaCtrl::Tell}\label{wxmediactrlgetposition}
 184
 185 \func{wxFileOffset}{GetPosition}{\void}
 186
 187 Obtains the current position in time within the movie in milliseconds.
 188
 189
 190 \membersection{wxMediaCtrl::GetState}\label{wxmediactrlgetstate}
 191
 192 \func{wxMediaCtrlState}{GetState}{\void}
 193
 194 Obtains the state the playback of the movie is in -
 195
 196 \twocolwidtha{7cm}
 197 \begin{twocollist}\itemsep=0pt
 198 \twocolitem{{\bf wxMEDIASTATE\_STOPPED}}{The movie has stopped.}
 199 \twocolitem{{\bf wxMEDIASTATE\_PAUSED}}{The movie is paused.}
 200 \twocolitem{{\bf wxMEDIASTATE\_PLAYING}}{The movie is currently playing.}
 201 \end{twocollist}
 202
 203
 204 \membersection{wxMediaCtrl::Load}\label{wxmediactrlload}
 205
 206 \func{bool}{Load}{\param{const wxString\& }{fileName}}
 207
 208 Loads the file that \tt{fileName} refers to.  Returns false if loading fails.
 209
 210
 211 \membersection{wxMediaCtrl::Load}\label{wxmediactrlloaduri}
 212
 213 \func{bool}{Load}{\param{const wxURI\& }{location}}
 214
 215 Loads the url that \tt{location} refers to.  Returns false if loading fails.
 216
 217 \membersection{wxMediaCtrl::Pause}\label{wxmediactrlpause}
 218
 219 \func{bool}{Pause}{\void}
 220
 221 Pauses playback of the movie.
 222
 223
 224 \membersection{wxMediaCtrl::Play}\label{wxmediactrlplay}
 225
 226 \func{bool}{Play}{\void}
 227
 228 Resumes playback of the movie.
 229
 230
 231 \membersection{wxMediaCtrl::Seek}\label{wxmediactrlsetposition}
 232
 233 \func{wxFileOffset}{Seek}{\param{wxFileOffset }{where}, \param{wxSeekMode }{mode}}
 234
 235 Seeks to a position within the movie.
 236
 237
 238 \membersection{wxMediaCtrl::Stop}\label{wxmediactrlstop}
 239
 240 \func{bool}{Stop}{\void}
 241
 242 Stops the media.
 243
 244 See \helpref{Operation}{operationwxmediactrl} for an overview of how stopping works.
 245
 246
 247 \membersection{wxMediaCtrl::SetVolume}\label{wxmediactrlsetvolume}
 248
 249 \func{bool}{SetVolume}{\param{double }{dVolume}}
 250
 251 Sets the volume of the media from a 0.0 to 1.0 range.
 252
 253
 254 \membersection{wxMediaCtrl::GetVolume}\label{wxmediactrlgetvolume}
 255
 256 \func{double}{GetVolume}{\void}
 257
 258 Gets the volume of the media from a 0.0 to 1.0 range.
 259
 260
 261 \membersection{wxMediaCtrl::GetPlaybackRate}\label{wxmediactrlgetplaybackrate}
 262
 263 \func{double}{GetPlaybackrate}{\void}
 264
 265 Gets the playback rate of the media; for example 2.0 is double speed.
 266 Not implemented on MCI or GStreamer.
 267
 268
 269 \membersection{wxMediaCtrl::SetPlaybackRate}\label{wxmediactrlsetplaybackrate}
 270
 271 \func{bool}{SetPlaybackrate}{\param{double }{dVolume}}
 272
 273 Sets the rate that the media plays; for example 0.5 is half speed.
 274
 275
 276 \membersection{wxMediaCtrl::ShowPlayerControls}\label{wxmediactrlshowplayercontrols}
 277
 278 \func{bool}{ShowPlayerControls}{\param{wxMediaCtrlPlayerControls }{flags}}
 279
 280 Normally, when you use wxMediaCtrl it is just a window for the video to
 281 play in.  However, platforms generally have their own media player interface,
 282 like quicktime has a bar below the video with a slider etc..  If you want that native
 283 interface instead of making your own use this function.  There are several options
 284 for the flags parameter, however you can look at the mediactrl header for these.
 285 The two general flags are wxMEDIACTRLPLAYERCONTROLS\_NONE which turns off the
 286 native interface, and wxMEDIACTRLPLAYERCONTROLS\_DEFAULT which lets wxMediaCtrl
 287 decide what native controls on the interface.