X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c5191fbd2b543de54aede153c2c6f8dee29119d1..245b9db51823e59bd61f0d7c0c69b419495cf0b7:/docs/latex/wx/mediactrl.tex diff --git a/docs/latex/wx/mediactrl.tex b/docs/latex/wx/mediactrl.tex index 843e3d0f6d..4380d9790f 100644 --- a/docs/latex/wx/mediactrl.tex +++ b/docs/latex/wx/mediactrl.tex @@ -11,23 +11,35 @@ \section{\class{wxMediaCtrl}}\label{wxmediactrl} -wxMediaCtrl is a class that allows a way to convieniently display types of +wxMediaCtrl is a class for displaying types of media, such as videos, audio files, natively through native codecs. wxMediaCtrl uses native backends to render media, for example on Windows there is a ActiveMovie/DirectShow backend, and on Macintosh there is a QuickTime backend. +\wxheading{See also} + +\helpref{wxMediaEvent}{wxmediaevent} + \wxheading{Derived from} -\helpref{wxControl}{wxcontrol} +\helpref{wxControl}{wxcontrol}\\ +\helpref{wxWindow}{wxwindow}\\ +\helpref{wxEvtHandler}{wxevthandler}\\ +\helpref{wxObject}{wxobject} \wxheading{Include files} +\wxheading{Library} + +\helpref{wxMedia}{librarieslist} + \latexignore{\rtfignore{\wxheading{Members}}} + \membersection{Rendering media}\label{renderingmediawxmediactrl} Depending upon the backend, wxMediaCtrl can render @@ -48,6 +60,7 @@ 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 @@ -86,6 +99,50 @@ 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 @@ -99,17 +156,48 @@ 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.} +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. 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. } -\twocolitem{{\bf wxMEDIABACKEND\_MCI}}{ -Use Media Command Interface. Windows Only. } +Use QuickTime. Mac Only. +WARNING: May not working correctly embedded in a wxNotebook. +} \twocolitem{{\bf wxMEDIABACKEND\_GSTREAMER}}{ -Use GStreamer. Unix Only. } +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. + +You need to make sure to use the DECLARE\_CLASS and IMPLEMENT\_CLASS macros. + +The only real tricky part is that you need to make sure the file in compiled +in, which if there are just backends in there will not happen and you may need +to use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI). + +This is a rather simple example of how to create a backend in the +\helpref{wxActiveXContainer}{wxactivexcontainer} documentation. + \membersection{wxMediaCtrl::wxMediaCtrl}\label{wxmediactrlwxmediactrl} \func{}{wxMediaCtrl}{\void} @@ -119,8 +207,8 @@ of wxMediaCtrl. \func{}{wxMediaCtrl}{ \param{wxWindow* }{parent}, - \param{const wxString\& }{fileName = wxT("")}, \param{wxWindowID }{id}, + \param{const wxString\& }{fileName = wxT("")}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, @@ -147,8 +235,8 @@ wxMediaCtrl figure it out.} \func{bool}{Create}{ \param{wxWindow* }{parent}, - \param{const wxString\& }{fileName = wxT("")}, \param{wxWindowID }{id}, + \param{const wxString\& }{fileName = wxT("")}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, @@ -173,25 +261,38 @@ wxMediaCtrl figure it out.} \docparam{name}{Window name.} -\membersection{wxMediaCtrl::Length}\label{wxmediactrlgetduration} +\membersection{wxMediaCtrl::GetBestSize}\label{wxmediactrlgetbestsize} -\func{wxFileOffset}{GetDuration}{\void} +\func{wxSize}{GetBestSize}{\void} -Obtains the length - the total amount of time the movie has in milliseconds. +Obtains the best size relative to the original/natural size of the +video, if there is any. See \helpref{Video size}{videosizewxmediactrl} +for more information. -\membersection{wxMediaCtrl::Tell}\label{wxmediactrlgetposition} +\membersection{wxMediaCtrl::GetPlaybackRate}\label{wxmediactrlgetplaybackrate} -\func{wxFileOffset}{GetPosition}{\void} +\func{double}{GetPlaybackrate}{\void} -Obtains the current position in time within the movie in milliseconds. +Obtains the playback rate, or speed of the media. \tt{1.0} represents normal +speed, while \tt{2.0} represents twice the normal speed of the media, for +example. Not supported on the GStreamer (Unix) backend. +Returns 0 on failure. + + +\membersection{wxMediaCtrl::GetVolume}\label{wxmediactrlgetvolume} + +\func{double}{GetVolume}{\void} + +Gets the volume of the media from a 0.0 to 1.0 range. Note that due to rounding +and other errors this may not be the exact value sent to SetVolume. \membersection{wxMediaCtrl::GetState}\label{wxmediactrlgetstate} \func{wxMediaCtrlState}{GetState}{\void} -Obtains the state the playback of the movie is in - +Obtains the state the playback of the media is in - \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt @@ -201,6 +302,13 @@ Obtains the state the playback of the movie is in - \end{twocollist} +\membersection{wxMediaCtrl::Length}\label{wxmediactrllength} + +\func{wxFileOffset}{Length}{\void} + +Obtains the length - the total amount of time the movie has in milliseconds. + + \membersection{wxMediaCtrl::Load}\label{wxmediactrlload} \func{bool}{Load}{\param{const wxString\& }{fileName}} @@ -210,9 +318,31 @@ Loads the file that \tt{fileName} refers to. Returns false if loading fails. \membersection{wxMediaCtrl::Load}\label{wxmediactrlloaduri} -\func{bool}{Load}{\param{const wxURI\& }{location}} +\func{bool}{Load}{\param{const wxURI\& }{uri}} + +Loads the location that \tt{uri} refers to. Note that this is very implementation-dependant, although HTTP URI/URLs are generally supported, for example. Returns false if loading fails. + + +\membersection{wxMediaCtrl::Load}\label{wxmediactrlloaduriwithproxy} + +\func{bool}{Load}{\param{const wxURI\& }{uri}, \param{const wxURI\& }{proxy}} + +Loads the location that \tt{uri} refers to with the proxy \tt{proxy}. Not implemented on most backends so it should be called with caution. Returns false if loading fails. + + +\membersection{wxMediaCtrl::LoadURI}\label{wxmediactrlloaduriliteral} + +\func{bool}{LoadURI}{\param{const wxURI\& }{uri}} + +Same as \helpref{Load}{wxmediactrlloaduri}. Kept for wxPython compatability. + + +\membersection{wxMediaCtrl::LoadURIWithProxy}\label{wxmediactrlloaduriwithproxyliteral} + +\func{bool}{LoadURIWithProxy}{\param{const wxURI\& }{uri}, \param{const wxURI\& }{proxy}} + +Same as \helpref{Load}{wxmediactrlloaduriwithproxy}. Kept for wxPython compatability. -Loads the url that \tt{location} refers to. Returns false if loading fails. \membersection{wxMediaCtrl::Pause}\label{wxmediactrlpause} @@ -235,53 +365,66 @@ Resumes playback of the movie. Seeks to a position within the movie. -\membersection{wxMediaCtrl::Stop}\label{wxmediactrlstop} - -\func{bool}{Stop}{\void} +\membersection{wxMediaCtrl::SetPlaybackRate}\label{wxmediactrlsetplaybackrate} -Stops the media. +\func{bool}{SetPlaybackRate}{\param{double }{dRate}} -See \helpref{Operation}{operationwxmediactrl} for an overview of how stopping works. +Sets the playback rate, or speed of the media, to that referred by \tt{dRate}. +\tt{1.0} represents normal speed, while \tt{2.0} represents twice the normal +speed of the media, for example. Not supported on the GStreamer (Unix) backend. +Returns true if successful. \membersection{wxMediaCtrl::SetVolume}\label{wxmediactrlsetvolume} \func{bool}{SetVolume}{\param{double }{dVolume}} -Sets the volume of the media from a 0.0 to 1.0 range. +Sets the volume of the media from a 0.0 to 1.0 range to that referred +by \tt{dVolume}. \tt{1.0} represents full volume, while \tt{0.5} +represents half (50 percent) volume, for example. Note that this may not be +exact due to conversion and rounding errors, although setting the volume to +full or none is always exact. Returns true if successful. -\membersection{wxMediaCtrl::GetVolume}\label{wxmediactrlgetvolume} +\membersection{wxMediaCtrl::ShowPlayerControls}\label{wxmediactrlshowplayercontrols} -\func{double}{GetVolume}{\void} +\func{bool}{ShowPlayerControls}{\param{wxMediaCtrlPlayerControls }{flags = wxMEDIACTRLPLAYERCONTROLS\_DEFAULT}} -Gets the volume of the media from a 0.0 to 1.0 range. +A special feature to wxMediaCtrl. Applications using native toolkits such as +QuickTime usually have a scrollbar, play button, and more provided to +them by the toolkit. By default wxMediaCtrl does not do this. However, on +the directshow and quicktime backends you can show or hide the native controls +provided by the underlying toolkit at will using ShowPlayerControls. Simply +calling the function with default parameters tells wxMediaCtrl to use the +default controls provided by the toolkit. The function takes a +\tt{wxMediaCtrlPlayerControls} enumeration as follows: +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxMEDIACTRLPLAYERCONTROLS\_NONE}}{No controls. return wxMediaCtrl to it's default state.} +\twocolitem{{\bf wxMEDIACTRLPLAYERCONTROLS\_STEP}}{Step controls like fastfoward, step one frame etc.} +\twocolitem{{\bf wxMEDIACTRLPLAYERCONTROLS\_VOLUME}}{Volume controls like the speaker icon, volume slider, etc.} +\twocolitem{{\bf wxMEDIACTRLPLAYERCONTROLS\_DEFAULT}}{Default controls for the toolkit. Currently a typedef for wxMEDIACTRLPLAYERCONTROLS\_STEP and wxMEDIACTRLPLAYERCONTROLS\_VOLUME.} +\end{twocollist} -\membersection{wxMediaCtrl::GetPlaybackRate}\label{wxmediactrlgetplaybackrate} +For more see \helpref{Player controls}{playercontrolswxmediactrl}. Currently +only implemented on the QuickTime and DirectShow backends. The function +returns true on success. -\func{double}{GetPlaybackrate}{\void} -Gets the playback rate of the media; for example 2.0 is double speed. -Not implemented on MCI or GStreamer. +\membersection{wxMediaCtrl::Stop}\label{wxmediactrlstop} +\func{bool}{Stop}{\void} -\membersection{wxMediaCtrl::SetPlaybackRate}\label{wxmediactrlsetplaybackrate} +Stops the media. -\func{bool}{SetPlaybackrate}{\param{double }{dVolume}} +See \helpref{Operation}{operationwxmediactrl} for an overview of how +stopping works. -Sets the rate that the media plays; for example 0.5 is half speed. +\membersection{wxMediaCtrl::Tell}\label{wxmediactrlgetposition} -\membersection{wxMediaCtrl::ShowPlayerControls}\label{wxmediactrlshowplayercontrols} +\func{wxFileOffset}{Tell}{\void} -\func{bool}{ShowPlayerControls}{\param{wxMediaCtrlPlayerControls }{flags}} +Obtains the current position in time within the movie in milliseconds. -Normally, when you use wxMediaCtrl it is just a window for the video to -play in. However, platforms generally have their own media player interface, -like quicktime has a bar below the video with a slider etc.. If you want that native -interface instead of making your own use this function. There are several options -for the flags parameter, however you can look at the mediactrl header for these. -The two general flags are wxMEDIACTRLPLAYERCONTROLS\_NONE which turns off the -native interface, and wxMEDIACTRLPLAYERCONTROLS\_DEFAULT which lets wxMediaCtrl -decide what native controls on the interface.