doc update for wxMediaCtrl

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@30526 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/mediactrl.tex

@@ -1,4 +1,4 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% Name:        mediactrl.tex
 %% Purpose:     wxMediaCtrl docs
 %% Author:      Ryan Norton <wxprojects@comcast.net>
@@ -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,
+wxMediaCtrl is a class that allows a way to convieniently display types of 
-such as videos, audio files, natively through native codecs.
+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
+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.
-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
+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.
-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.
+

docs/latex/wx/mediaevt.tex

@@ -11,8 +11,6 @@
 
 \section{\class{wxMediaEvent}}\label{wxmediaevent}
 
-PRELIMINARY.  Do not rely on in user code.
-
 Event \helpref{wxMediaCtrl}{wxmediactrl} uses.
 
 \wxheading{Derived from}
@@ -27,7 +25,9 @@ Event \helpref{wxMediaCtrl}{wxmediactrl} uses.
 
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
-\twocolitem{{\bf EVT\_MEDIA\_FINISHED(func)}}{Sent when a media has finished playing in a \helpref{wxMediaCtrl}{wxmediactrl}.}
+\twocolitem{{\bf EVT\_MEDIA\_STOP(func)}}{
+Triggerred right before the media stops.  You can Veto this event to prevent it from stopping, causing it to continue playing - even if it has reached that end of the media. }
+\twocolitem{{\bf EVT\_MEDIA\_FINISHED(func)}}{Sent when a media has finished playing in a \helpref{wxMediaCtrl}{wxmediactrl}.  Note that if you connect to this event and don't skip it, it will override the looping behaviour of the media control.}
 \end{twocollist}
 
 \latexignore{\rtfignore{\wxheading{Members}}}