557002cf81
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@37461 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
423 lines
16 KiB
TeX
423 lines
16 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: mediactrl.tex
|
|
%% Purpose: wxMediaCtrl docs
|
|
%% Author: Ryan Norton <wxprojects@comcast.net>
|
|
%% Modified by:
|
|
%% Created: 11/7/2004
|
|
%% 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 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}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/mediactrl.h>
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
|
\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.
|
|
|
|
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}
|
|
|
|
Default constructor - you \tt{must} call Create before calling any other methods
|
|
of wxMediaCtrl.
|
|
|
|
\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 \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, 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{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{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.
|
|
|
|
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, 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{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::GetBestSize}\label{wxmediactrlgetbestsize}
|
|
|
|
\func{wxSize}{GetBestSize}{\void}
|
|
|
|
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::GetPlaybackRate}\label{wxmediactrlgetplaybackrate}
|
|
|
|
\func{double}{GetPlaybackrate}{\void}
|
|
|
|
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 media is in -
|
|
|
|
\twocolwidtha{7cm}
|
|
\begin{twocollist}\itemsep=0pt
|
|
\twocolitem{{\bf wxMEDIASTATE\_STOPPED}}{The movie has stopped.}
|
|
\twocolitem{{\bf wxMEDIASTATE\_PAUSED}}{The movie is paused.}
|
|
\twocolitem{{\bf wxMEDIASTATE\_PLAYING}}{The movie is currently playing.}
|
|
\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}}
|
|
|
|
Loads the file that \tt{fileName} refers to. Returns false if loading fails.
|
|
|
|
|
|
\membersection{wxMediaCtrl::Load}\label{wxmediactrlloaduri}
|
|
|
|
\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.
|
|
|
|
|
|
\membersection{wxMediaCtrl::Pause}\label{wxmediactrlpause}
|
|
|
|
\func{bool}{Pause}{\void}
|
|
|
|
Pauses playback of the movie.
|
|
|
|
|
|
\membersection{wxMediaCtrl::Play}\label{wxmediactrlplay}
|
|
|
|
\func{bool}{Play}{\void}
|
|
|
|
Resumes playback of the movie.
|
|
|
|
|
|
\membersection{wxMediaCtrl::Seek}\label{wxmediactrlsetposition}
|
|
|
|
\func{wxFileOffset}{Seek}{\param{wxFileOffset }{where}, \param{wxSeekMode }{mode}}
|
|
|
|
Seeks to a position within the movie.
|
|
|
|
|
|
\membersection{wxMediaCtrl::SetPlaybackRate}\label{wxmediactrlsetplaybackrate}
|
|
|
|
\func{bool}{SetPlaybackRate}{\param{double }{dRate}}
|
|
|
|
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 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::ShowPlayerControls}\label{wxmediactrlshowplayercontrols}
|
|
|
|
\func{bool}{ShowPlayerControls}{\param{wxMediaCtrlPlayerControls }{flags = wxMEDIACTRLPLAYERCONTROLS\_DEFAULT}}
|
|
|
|
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}
|
|
|
|
For more see \helpref{Player controls}{playercontrolswxmediactrl}. Currently
|
|
only implemented on the QuickTime and DirectShow backends. The function
|
|
returns true on success.
|
|
|
|
|
|
\membersection{wxMediaCtrl::Stop}\label{wxmediactrlstop}
|
|
|
|
\func{bool}{Stop}{\void}
|
|
|
|
Stops the media.
|
|
|
|
See \helpref{Operation}{operationwxmediactrl} for an overview of how
|
|
stopping works.
|
|
|
|
|
|
\membersection{wxMediaCtrl::Tell}\label{wxmediactrlgetposition}
|
|
|
|
\func{wxFileOffset}{Tell}{\void}
|
|
|
|
Obtains the current position in time within the movie in milliseconds.
|