+\membersection{Rendering media}\label{renderingmediawxmediactrl}
+
+Depending upon the backend, wxMediaCtrl can render
+and display pretty much any kind of media that the native system can -
+such as an image, mpeg video, or mp3 (without license restrictions -
+sense it relies on native system calls that may not technically
+have mp3 decoding available, for example, it falls outside the
+realm of licensing restrictions).
+
+For general operation, all you need to do is call
+\helpref{wxMediaCtrl::Load}{wxmediactrlload} to load the file
+you want to render, then call \helpref{wxMediaCtrl::Play}{wxmediactrlplay}
+to show the video/audio of the media.
+
+More complex operations are generally more heavily dependant on the
+capabilities of the backend. For example, QuickTime cannot set
+the playback rate of certain streaming media - while DirectShow is
+slightly more flexible in that regard.
+
+\membersection{Operation}\label{operationwxmediactrl}
+
+When wxMediaCtrl plays a file, it plays until the stop position
+is reached (currently the end of the file/stream). Right before
+it hits the end of the stream, it fires off a EVT\_MEDIA\_STOP
+event to its parent window, at which point the event handler
+can choose to veto the event, preventing the stream from actually
+stopping.
+
+Example:
+\begin{verbatim}
+//connect to the media event
+this->Connect(wxMY_ID, wxEVT_MEDIA_STOP, (wxObjectEventFunction)
+(wxEventFunction)(wxMediaEventFunction) &MyFrame::OnMediaStop);
+
+//...
+void MyFrame::OnMediaStop(const wxMediaEvent& evt)
+{
+ if(bUserWantsToSeek)
+ {
+ m_mediactrl->SetPosition(
+ m_mediactrl->GetDuration() << 1
+ );
+ evt.Veto();
+ }
+}
+\end{verbatim}
+
+When wxMediaCtrl stops, either by the EVT\_MEDIA\_STOP not being
+vetoed, or by manually calling
+\helpref{wxMediaCtrl::Stop}{wxmediactrlstop}, where it actually
+stops is not at the beginning, rather, but at the beginning of
+the stream. That is, when it stops and play is called, playback
+is gauranteed to start at the beginning of the media. This is
+because some streams are not seekable, and when stop is called
+on them they return to the beginning, thus wxMediaCtrl tries
+to keep consistant for all types of media.
+
+\membersection{Choosing a backend}\label{choosingbackendwxmediactrl}
+
+Generally, you should almost certainly leave this part up to
+wxMediaCtrl - but if you need a certain backend for a particular
+reason, such as QuickTime for playing .mov files, all you need
+to do to choose a specific backend is to pass the
+name of the backend class to
+\helpref{wxMediaCtrl::Create}{wxmediactrlcreate}.
+
+The following are valid backend identifiers -
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf wxMEDIABACKEND\_DIRECTSHOW}}{
+Use ActiveMovie/DirectShow. Requires wxUSE\_DIRECTSHOW to be
+enabled, requires linkage with the static library strmiids.lib,
+and is available on Windows Only.}
+\twocolitem{{\bf wxMEDIABACKEND\_QUICKTIME}}{
+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. }
+\twocolitem{{\bf wxMEDIABACKEND\_MCI}}{
+Use Media Command Interface. Windows Only. }
+\twocolitem{{\bf wxMEDIABACKEND\_GSTREAMER}}{
+Use GStreamer. Unix Only. }
+\end{twocollist}
projects / wxWidgets.git / blobdiff