X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1d20b7f2c632245f4803e1e6c4b622de8ff9064d..1185254d55900be4585c9454f00d311ab465c29b:/docs/latex/wx/mediactrl.tex

diff --git a/docs/latex/wx/mediactrl.tex b/docs/latex/wx/mediactrl.tex
index 155652ae6f..ef6c49a055 100644
--- a/docs/latex/wx/mediactrl.tex
+++ b/docs/latex/wx/mediactrl.tex
@@ -18,6 +18,10 @@ 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}
@@ -28,6 +32,7 @@ QuickTime backend.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
 \membersection{Rendering media}\label{renderingmediawxmediactrl}
 
 Depending upon the backend, wxMediaCtrl can render
@@ -48,6 +53,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 +92,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 +149,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}
@@ -173,25 +254,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 +295,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 +311,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,54 +358,65 @@ 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}
-
-\func{double}{GetVolume}{\void}
 
-Gets the volume of the media from a 0.0 to 1.0 range.
+\membersection{wxMediaCtrl::ShowPlayerControls}\label{wxmediactrlshowplayercontrols}
 
+\func{bool}{ShowPlayerControls}{\param{wxMediaCtrlPlayerControls }{flags = wxMEDIACTRLPLAYERCONTROLS\_DEFAULT}}
 
-\membersection{wxMediaCtrl::GetPlaybackRate}\label{wxmediactrlgetplaybackrate}
+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:
 
-\func{double}{GetPlaybackrate}{\void}
+\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}
 
-Gets the playback rate of the media; for example 2.0 is double speed.
-Not implemented on MCI or GStreamer.
+For more see \helpref{Player controls}{playercontrolswxmediactrl}. Currently
+only implemented on the QuickTime and DirectShow backends. The function
+returns true on success.
 
 
-\membersection{wxMediaCtrl::SetPlaybackRate}\label{wxmediactrlsetplaybackrate}
+\membersection{wxMediaCtrl::Stop}\label{wxmediactrlstop}
 
-\func{bool}{SetPlaybackrate}{\param{double }{dVolume}}
+\func{bool}{Stop}{\void}
 
-Sets the rate that the media plays; for example 0.5 is half speed.
+Stops the media.
 
+See \helpref{Operation}{operationwxmediactrl} for an overview of how
+stopping works.
 
-\membersection{wxMediaCtrl::ShowPlayerControls}\label{wxmediactrlshowplayercontrols}
 
-\func{bool}{ShowPlayerControls}{\param{wxMediaCtrlPlayerControls }{flags}}
+\membersection{wxMediaCtrl::Tell}\label{wxmediactrlgetposition}
 
-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.
+\func{wxFileOffset}{Tell}{\void}
 
+Obtains the current position in time within the movie in milliseconds.
