X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/39c5bef057f6c72c580630051703b4f5c4f4930f..68d411dc5724b9284455a31ef8a8d6d99c18d224:/docs/latex/wx/mediactrl.tex diff --git a/docs/latex/wx/mediactrl.tex b/docs/latex/wx/mediactrl.tex index be95ff3cb4..77c4ffe93e 100644 --- a/docs/latex/wx/mediactrl.tex +++ b/docs/latex/wx/mediactrl.tex @@ -1,4 +1,4 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Name: mediactrl.tex %% Purpose: wxMediaCtrl docs %% Author: Ryan Norton @@ -7,14 +7,16 @@ %% RCS-ID: $Id$ %% Copyright: (c) Ryan Norton %% License: wxWindows license -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{\class{wxMediaCtrl}}\label{wxmediactrl} -wxMediaCtrl is a class that allows a way to convieniently display types of media, -such as videos, audio files, natively through native codecs. +wxMediaCtrl is a class that allows a way to convieniently display types of +media, such as videos, audio files, natively through native codecs. -On Windows wxMediaCtrl uses DirectShow, and on Macintosh wxMediaCtrl uses QuickTime. +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. wxMediaCtrl is not currently available on unix systems. @@ -28,6 +30,84 @@ wxMediaCtrl is not currently available on unix systems. \latexignore{\rtfignore{\wxheading{Members}}} +\membersection{Rendering media}\label{renderingmediawxmediactrl} + +wxMediaCtrl can generally, depending upon the backend, 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. } +\twocolitem{{\bf wxMEDIABACKEND\_MCI}}{ +Use Media Command Interface. Windows Only. } +\end{twocollist} \membersection{wxMediaCtrl::wxMediaCtrl}\label{wxmediactrlwxmediactrl} @@ -36,48 +116,72 @@ wxMediaCtrl is not currently available on unix systems. Default constructor - you \tt{must} call Create before calling any other methods of wxMediaCtrl. -\func{}{wxMediaCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID }{id}, \param{const wxString\& }{fileName}, \param{const wxString\& }{label = wxT("")}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{long }{driver = 0}, \param{const wxString\& }{name = wxPanelNameStr}} +\func{}{wxMediaCtrl}{ + \param{wxWindow* }{parent}, + \param{const wxString\& }{fileName = wxT("")}, + \param{wxWindowID }{id}, + \param{const wxPoint\& }{pos = wxDefaultPosition}, + \param{const wxSize\& }{size = wxDefaultSize}, + \param{long }{style = 0}, + \param{const wxString\& }{szBackend = wxT("")}, + \param{const wxValidator& }{validator = wxDefaultValidator}, + \param{const wxString\& }{name = wxPanelNameStr} + } -Constructor that calls Create. You may prefer to call Create directly to check to see if wxMediaCtrl is available -on the system. +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. \docparam{parent}{parent of this control. Must not be NULL.} \docparam{id}{id to use for events} -\docparam{fileName}{If not empty, loads this file and starts playing it immediately.} +\docparam{fileName}{If not empty, the path of a file to open.} \docparam{pos}{Position to put control at.} \docparam{size}{Size to put the control at and to stretch movie to.} \docparam{style}{Optional styles.} -\docparam{driver}{Reserved for future use.} +\docparam{szBackend}{Name of backend you want to use, leave blank to make +wxMediaCtrl figure it out.} +\docparam{validator}{validator to use.} \docparam{name}{Window name.} \membersection{wxMediaCtrl::Create}\label{wxmediactrlcreate} -\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id}, \param{const wxString\& }{fileName}, \param{const wxString\& }{label = wxT("")}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{long }{driver = 0}, \param{const wxString\& }{name = wxPanelNameStr}} +\func{bool}{Create}{ + \param{wxWindow* }{parent}, + \param{const wxString\& }{fileName = wxT("")}, + \param{wxWindowID }{id}, + \param{const wxPoint\& }{pos = wxDefaultPosition}, + \param{const wxSize\& }{size = wxDefaultSize}, + \param{long }{style = 0}, + \param{const wxString\& }{szBackend = wxT("")}, + \param{const wxValidator& }{validator = wxDefaultValidator}, + \param{const wxString\& }{name = wxPanelNameStr} + } -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. +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. + +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. \docparam{parent}{parent of this control. Must not be NULL.} \docparam{id}{id to use for events} -\docparam{fileName}{If not empty, loads this file and starts playing it immediately.} +\docparam{fileName}{If not empty, the path of a file to open.} \docparam{pos}{Position to put control at.} \docparam{size}{Size to put the control at and to stretch movie to.} \docparam{style}{Optional styles.} -\docparam{driver}{Reserved for future use.} +\docparam{szBackend}{Name of backend you want to use, leave blank to make +wxMediaCtrl figure it out.} +\docparam{validator}{validator to use.} \docparam{name}{Window name.} \membersection{wxMediaCtrl::GetDuration}\label{wxmediactrlgetduration} -\func{long}{GetDuration}{\void} +\func{wxLongLong}{GetDuration}{\void} Obtains the length - the total amount of time the movie has in milliseconds. \membersection{wxMediaCtrl::GetPosition}\label{wxmediactrlgetposition} -\func{long}{GetPosition}{\void} +\func{wxLongLong}{GetPosition}{\void} Obtains the current position in time within the movie in milliseconds. @@ -118,7 +222,7 @@ Resumes playback of the movie. \membersection{wxMediaCtrl::SetPosition}\label{wxmediactrlsetposition} -\func{bool}{SetPosition}{\param{long }{where}} +\func{bool}{SetPosition}{\param{wxLongLong }{where}} Seeks to a position within the movie. @@ -128,3 +232,6 @@ Seeks to a position within the movie. \func{bool}{Stop}{\void} Stops the media. + +See \helpref{Operation}{operationwxmediactrl} for an overview of how stopping works. +