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, then call \helpref{wxMediaCtrl::Play}{wxmediactrlplay}
  43 to show the video/audio of the media.
  44
  45 More complex operations are generally more heavily dependant on the
  46 capabilities of the backend.  For example, QuickTime cannot set
  47 the playback rate of certain streaming media - while DirectShow is
  48 slightly more flexible in that regard.
  49
  50 \membersection{Operation}\label{operationwxmediactrl}
  51
  52 When wxMediaCtrl plays a file, it plays until the stop position
  53 is reached (currently the end of the file/stream).  Right before
  54 it hits the end of the stream, it fires off a EVT\_MEDIA\_STOP
  55 event to its parent window, at which point the event handler
  56 can choose to veto the event, preventing the stream from actually
  57 stopping.
  58
  59 Example:
  60 \begin{verbatim}
  61 //connect to the media event
  62 this->Connect(wxMY_ID, wxEVT_MEDIA_STOP, (wxObjectEventFunction)
  63 (wxEventFunction)(wxMediaEventFunction) &MyFrame::OnMediaStop);
  64
  65 //...
  66 void MyFrame::OnMediaStop(const wxMediaEvent& evt)
  67 {
  68     if(bUserWantsToSeek)
  69     {
  70         m_mediactrl->SetPosition(
  71             m_mediactrl->GetDuration() << 1
  72                                 );
  73         evt.Veto();
  74     }
  75 }
  76 \end{verbatim}
  77
  78 When wxMediaCtrl stops, either by the EVT\_MEDIA\_STOP not being
  79 vetoed, or by manually calling
  80 \helpref{wxMediaCtrl::Stop}{wxmediactrlstop}, where it actually
  81 stops is not at the beginning, rather, but at the beginning of
  82 the stream.  That is, when it stops and play is called, playback
  83 is gauranteed to start at the beginning of the media.  This is
  84 because some streams are not seekable, and when stop is called
  85 on them they return to the beginning, thus wxMediaCtrl tries
  86 to keep consistant for all types of media.
  87
  88 \membersection{Choosing a backend}\label{choosingbackendwxmediactrl}
  89
  90 Generally, you should almost certainly leave this part up to
  91 wxMediaCtrl - but if you need a certain backend for a particular
  92 reason, such as QuickTime for playing .mov files, all you need
  93 to do to choose a specific backend is to pass the
  94 name of the backend class to
  95 \helpref{wxMediaCtrl::Create}{wxmediactrlcreate}.
  96
  97 The following are valid backend identifiers -
  98 \twocolwidtha{7cm}
  99 \begin{twocollist}\itemsep=0pt
 100 \twocolitem{{\bf wxMEDIABACKEND\_DIRECTSHOW}}{
 101 Use ActiveMovie/DirectShow.  Requires wxUSE\_DIRECTSHOW to be
 102 enabled, requires linkage with the static library strmiids.lib,
 103 and is available on Windows Only.}
 104 \twocolitem{{\bf wxMEDIABACKEND\_QUICKTIME}}{
 105 Use QuickTime.  Windows and Mac Only. WARNING: 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. }
 106 \twocolitem{{\bf wxMEDIABACKEND\_MCI}}{
 107 Use Media Command Interface.  Windows Only. }
 108 \twocolitem{{\bf wxMEDIABACKEND\_GSTREAMER}}{
 109 Use GStreamer.  Unix Only. }
 110 \end{twocollist}
 111
 112 \membersection{wxMediaCtrl::wxMediaCtrl}\label{wxmediactrlwxmediactrl}
 113
 114 \func{}{wxMediaCtrl}{\void}
 115
 116 Default constructor - you \tt{must} call Create before calling any other methods
 117 of wxMediaCtrl.
 118
 119 \func{}{wxMediaCtrl}{
 120         \param{wxWindow* }{parent},
 121         \param{const wxString\& }{fileName = wxT("")},
 122         \param{wxWindowID }{id},
 123         \param{const wxPoint\& }{pos = wxDefaultPosition},
 124         \param{const wxSize\& }{size = wxDefaultSize},
 125         \param{long }{style = 0},
 126         \param{const wxString\& }{szBackend = wxT("")},
 127         \param{const wxValidator& }{validator = wxDefaultValidator},
 128         \param{const wxString\& }{name = wxPanelNameStr}
 129                    }
 130
 131 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.
 132
 133 \docparam{parent}{parent of this control.  Must not be NULL.}
 134 \docparam{id}{id to use for events}
 135 \docparam{fileName}{If not empty, the path of a file to open.}
 136 \docparam{pos}{Position to put control at.}
 137 \docparam{size}{Size to put the control at and to stretch movie to.}
 138 \docparam{style}{Optional styles.}
 139 \docparam{szBackend}{Name of backend you want to use, leave blank to make
 140 wxMediaCtrl figure it out.}
 141 \docparam{validator}{validator to use.}
 142 \docparam{name}{Window name.}
 143
 144
 145 \membersection{wxMediaCtrl::Create}\label{wxmediactrlcreate}
 146
 147 \func{bool}{Create}{
 148         \param{wxWindow* }{parent},
 149         \param{const wxString\& }{fileName = wxT("")},
 150         \param{wxWindowID }{id},
 151         \param{const wxPoint\& }{pos = wxDefaultPosition},
 152         \param{const wxSize\& }{size = wxDefaultSize},
 153         \param{long }{style = 0},
 154         \param{const wxString\& }{szBackend = wxT("")},
 155         \param{const wxValidator& }{validator = wxDefaultValidator},
 156         \param{const wxString\& }{name = wxPanelNameStr}
 157                    }
 158
 159 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.
 160
 161 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.
 162
 163 \docparam{parent}{parent of this control.  Must not be NULL.}
 164 \docparam{id}{id to use for events}
 165 \docparam{fileName}{If not empty, the path of a file to open.}
 166 \docparam{pos}{Position to put control at.}
 167 \docparam{size}{Size to put the control at and to stretch movie to.}
 168 \docparam{style}{Optional styles.}
 169 \docparam{szBackend}{Name of backend you want to use, leave blank to make
 170 wxMediaCtrl figure it out.}
 171 \docparam{validator}{validator to use.}
 172 \docparam{name}{Window name.}
 173
 174
 175 \membersection{wxMediaCtrl::Length}\label{wxmediactrlgetduration}
 176
 177 \func{wxFileOffset}{GetDuration}{\void}
 178
 179 Obtains the length - the total amount of time the movie has in milliseconds.
 180
 181
 182 \membersection{wxMediaCtrl::Tell}\label{wxmediactrlgetposition}
 183
 184 \func{wxFileOffset}{GetPosition}{\void}
 185
 186 Obtains the current position in time within the movie in milliseconds.
 187
 188
 189 \membersection{wxMediaCtrl::GetState}\label{wxmediactrlgetstate}
 190
 191 \func{wxMediaCtrlState}{GetState}{\void}
 192
 193 Obtains the state the playback of the movie is in -
 194
 195 \twocolwidtha{7cm}
 196 \begin{twocollist}\itemsep=0pt
 197 \twocolitem{{\bf wxMEDIASTATE\_STOPPED}}{The movie has stopped.}
 198 \twocolitem{{\bf wxMEDIASTATE\_PAUSED}}{The movie is paused.}
 199 \twocolitem{{\bf wxMEDIASTATE\_PLAYING}}{The movie is currently playing.}
 200 \end{twocollist}
 201
 202
 203 \membersection{wxMediaCtrl::Load}\label{wxmediactrlload}
 204
 205 \func{bool}{Load}{\param{const wxString\& }{fileName}}
 206
 207 Loads the file that \tt{fileName} refers to.  Returns false if loading fails.
 208
 209 \membersection{wxMediaCtrl::Pause}\label{wxmediactrlpause}
 210
 211 \func{bool}{Pause}{\void}
 212
 213 Pauses playback of the movie.
 214
 215
 216 \membersection{wxMediaCtrl::Play}\label{wxmediactrlplay}
 217
 218 \func{bool}{Play}{\void}
 219
 220 Resumes playback of the movie.
 221
 222
 223 \membersection{wxMediaCtrl::Seek}\label{wxmediactrlsetposition}
 224
 225 \func{wxFileOffset}{SetPosition}{\param{wxFileOffset }{where}, \param{wxSeekMode }{mode}}
 226
 227 Seeks to a position within the movie.
 228
 229
 230 \membersection{wxMediaCtrl::Stop}\label{wxmediactrlstop}
 231
 232 \func{bool}{Stop}{\void}
 233
 234 Stops the media.
 235
 236 See \helpref{Operation}{operationwxmediactrl} for an overview of how stopping works.
 237