+\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 -
+since 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, catch the EVT\_MEDIA\_LOADED event,
+and then call \helpref{wxMediaCtrl::Play}{wxmediactrlplay}
+to show the video/audio of the media in that event.
+
+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.
+
+Note that when changing the state of the media through Play()
+and other methods, the media may not actually be in the
+wxMEDIASTATE\_PLAYING, for example. If you are relying on the
+media being in certain state catch the event relevant to the state.
+See \helpref{wxMediaEvent}{wxmediaevent} for the kinds of events
+that you can catch.
+
+
+\membersection{Video size}\label{videosizewxmediactrl}
+
+By default, wxMediaCtrl will scale the size of the video to the
+requested amount passed to either it's constructor or Create().
+After calling Load or performing an equivilant operation, you
+can subsequently obtain the "real" size of the video (if there
+is any) by calling GetBestSize(). Note that the actual result
+on the display will be slightly different when ShowPlayerControls
+is activated and the actual video size will be less then
+specified due to the extra controls provided by the native toolkit.
+In addition, the backend may modify GetBestSize() to include the
+size of the extra controls - so if you want the real size of the
+video just disable ShowPlayerControls().
+
+The idea with setting GetBestSize to the size of the video is
+that GetBestSize is a wxWindow-derived function that is called
+when sizers on a window recalculate. What this means is that
+if you use sizers by default the video will show in it's
+original size without any extra assistance needed from the user.
+
+
+\membersection{Player controls}\label{playercontrolswxmediactrl}
+
+Normally, when you use wxMediaCtrl it is just a window for the video to
+play in. However, some toolkits have their own media player interface.
+For example, QuickTime generally has a bar below the video with a slider.
+A special feature available to wxMediaCtrl, you can use the toolkit's interface instead of
+making your own by using the \helpref{ShowPlayerControls()}{wxmediactrlshowplayercontrols}
+function. There are several options for the flags parameter, with
+the two general flags being wxMEDIACTRLPLAYERCONTROLS\_NONE which turns off
+the native interface, and wxMEDIACTRLPLAYERCONTROLS\_DEFAULT which lets
+wxMediaCtrl decide what native controls on the interface. Be sure to review
+the caveats outlined in \helpref{Video size}{videosizewxmediactrl} before
+doing so.
+
+
+\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. Uses the native ActiveMovie
+(I.E. DirectShow) control. Default backend on Windows and
+supported by nearly all Windows versions, even some
+Windows CE versions. May display a windows media player
+logo while inactive. }
+\twocolitem{{\bf wxMEDIABACKEND\_QUICKTIME}}{
+Use QuickTime. Mac Only.
+WARNING: May not working correctly embedded in a wxNotebook.
+}
+\twocolitem{{\bf wxMEDIABACKEND\_GSTREAMER}}{
+Use GStreamer. Unix Only. Requires GStreamer 0.8 along
+with at the very least the xvimagesink, xoverlay, and
+gst-play modules of gstreamer to function. You need the correct
+modules to play the relavant files, for example the mad module
+to play mp3s, etc.}
+\twocolitem{{\bf wxMEDIABACKEND\_WMP10}}{
+Uses Windows Media Player 10 (Windows only) - works on mobile
+machines with Windows Media Player 10 and desktop machines with
+either Windows Media Player 9 or 10
+}
+\end{twocollist}
+
+Note that other backends such as wxMEDIABACKEND\_MCI can now be
+found at wxCode.
+
+\membersection{Creating a backend}\label{creatingabackendwxmediactrl}
+
+Creating a backend for wxMediaCtrl is a rather simple process. Simply derive
+from wxMediaBackendCommonBase and implement the methods you want. The methods
+in wxMediaBackend correspond to those in wxMediaCtrl except for CreateControl
+which does the actual creation of the control, in cases where a custom control
+is not needed you may simply call wxControl::Create.
projects / wxWidgets.git / blobdiff