]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/mediactrl.tex
Further decorations in changes chapter. Missed methods in their base location.
[wxWidgets.git] / docs / latex / wx / mediactrl.tex
CommitLineData
6f4a67ac 1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
c5550b75
RN
2%% Name: mediactrl.tex
3%% Purpose: wxMediaCtrl docs
4%% Author: Ryan Norton <wxprojects@comcast.net>
5%% Modified by:
6%% Created: 11/7/2004
7%% RCS-ID: $Id$
8%% Copyright: (c) Ryan Norton
9%% License: wxWindows license
6f4a67ac 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
c5550b75
RN
11
12\section{\class{wxMediaCtrl}}\label{wxmediactrl}
13
6f4a67ac
RN
14wxMediaCtrl is a class that allows a way to convieniently display types of
15media, such as videos, audio files, natively through native codecs.
39c5bef0 16
6f4a67ac
RN
17wxMediaCtrl uses native backends to render media, for example on Windows
18there is a ActiveMovie/DirectShow backend, and on Macintosh there is a
19QuickTime backend.
39c5bef0
RN
20
21wxMediaCtrl is not currently available on unix systems.
c5550b75
RN
22
23\wxheading{Derived from}
24
25\helpref{wxControl}{wxcontrol}
26
27\wxheading{Include files}
28
29<wx/mediactrl.h>
30
31\latexignore{\rtfignore{\wxheading{Members}}}
32
6f4a67ac
RN
33\membersection{Rendering media}\label{renderingmediawxmediactrl}
34
35wxMediaCtrl can generally, depending upon the backend, render
36and display pretty much any kind of media that the native system can -
37such as an image, mpeg video, or mp3 (without license restrictions -
38sense it relies on native system calls that may not technically
39have mp3 decoding available, for example, it falls outside the
40realm of licensing restrictions).
41
42For general operation, all you need to do is call
43\helpref{wxMediaCtrl::Load}{wxmediactrlload} to load the file
44you want to render, then call \helpref{wxMediaCtrl::Play}{wxmediactrlplay}
45to show the video/audio of the media.
46
47More complex operations are generally more heavily dependant on the
48capabilities of the backend. For example, QuickTime cannot set
49the playback rate of certain streaming media - while DirectShow is
50slightly more flexible in that regard.
51
52\membersection{Operation}\label{operationwxmediactrl}
53
54When wxMediaCtrl plays a file, it plays until the stop position
55is reached (currently the end of the file/stream). Right before
56it hits the end of the stream, it fires off a EVT\_MEDIA\_STOP
57event to its parent window, at which point the event handler
58can choose to veto the event, preventing the stream from actually
59stopping.
60
61Example:
62\begin{verbatim}
63//connect to the media event
64this->Connect(wxMY_ID, wxEVT_MEDIA_STOP, (wxObjectEventFunction)
65(wxEventFunction)(wxMediaEventFunction) &MyFrame::OnMediaStop);
66
67//...
68void MyFrame::OnMediaStop(const wxMediaEvent& evt)
69{
70 if(bUserWantsToSeek)
71 {
72 m_mediactrl->SetPosition(
73 m_mediactrl->GetDuration() << 1
74 );
75 evt.Veto();
76 }
77}
78\end{verbatim}
79
80When wxMediaCtrl stops, either by the EVT\_MEDIA\_STOP not being
81vetoed, or by manually calling
82\helpref{wxMediaCtrl::Stop}{wxmediactrlstop}, where it actually
83stops is not at the beginning, rather, but at the beginning of
84the stream. That is, when it stops and play is called, playback
85is gauranteed to start at the beginning of the media. This is
86because some streams are not seekable, and when stop is called
87on them they return to the beginning, thus wxMediaCtrl tries
88to keep consistant for all types of media.
89
90\membersection{Choosing a backend}\label{choosingbackendwxmediactrl}
91
92Generally, you should almost certainly leave this part up to
93wxMediaCtrl - but if you need a certain backend for a particular
94reason, such as QuickTime for playing .mov files, all you need
95to do to choose a specific backend is to pass the
96name of the backend class to
97\helpref{wxMediaCtrl::Create}{wxmediactrlcreate}.
98
99The following are valid backend identifiers -
100\twocolwidtha{7cm}
101\begin{twocollist}\itemsep=0pt
102\twocolitem{{\bf wxMEDIABACKEND\_DIRECTSHOW}}{
103Use ActiveMovie/DirectShow. Requires wxUSE\_DIRECTSHOW to be
104enabled, requires linkage with the static library strmiids.lib,
105and is available on Windows Only.}
106\twocolitem{{\bf wxMEDIABACKEND\_QUICKTIME}}{
107Use QuickTime. Windows and Mac Only. }
108\twocolitem{{\bf wxMEDIABACKEND\_MCI}}{
109Use Media Command Interface. Windows Only. }
110\end{twocollist}
c5550b75
RN
111
112\membersection{wxMediaCtrl::wxMediaCtrl}\label{wxmediactrlwxmediactrl}
113
39c5bef0 114\func{}{wxMediaCtrl}{\void}
c5550b75 115
39c5bef0
RN
116Default constructor - you \tt{must} call Create before calling any other methods
117of wxMediaCtrl.
c5550b75 118
6f4a67ac
RN
119\func{}{wxMediaCtrl}{
120 \param{wxWindow* }{parent},
121 \param{const wxString\& }{fileName = wxT("")},
122 \param{wxWindowID }{id},
123 \param{const wxPoint\& }{pos = wxDefaultPosition},
124 \param{const wxSize\& }{size = wxDefaultSize},
125 \param{long }{style = 0},
126 \param{const wxString\& }{szBackend = wxT("")},
127 \param{const wxValidator& }{validator = wxDefaultValidator},
128 \param{const wxString\& }{name = wxPanelNameStr}
129 }
c5550b75 130
6f4a67ac 131Constructor 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.
c5550b75
RN
132
133\docparam{parent}{parent of this control. Must not be NULL.}
134\docparam{id}{id to use for events}
6f4a67ac 135\docparam{fileName}{If not empty, the path of a file to open.}
c5550b75
RN
136\docparam{pos}{Position to put control at.}
137\docparam{size}{Size to put the control at and to stretch movie to.}
138\docparam{style}{Optional styles.}
6f4a67ac
RN
139\docparam{szBackend}{Name of backend you want to use, leave blank to make
140wxMediaCtrl figure it out.}
141\docparam{validator}{validator to use.}
c5550b75
RN
142\docparam{name}{Window name.}
143
144
145\membersection{wxMediaCtrl::Create}\label{wxmediactrlcreate}
146
6f4a67ac
RN
147\func{bool}{Create}{
148 \param{wxWindow* }{parent},
149 \param{const wxString\& }{fileName = wxT("")},
150 \param{wxWindowID }{id},
151 \param{const wxPoint\& }{pos = wxDefaultPosition},
152 \param{const wxSize\& }{size = wxDefaultSize},
153 \param{long }{style = 0},
154 \param{const wxString\& }{szBackend = wxT("")},
155 \param{const wxValidator& }{validator = wxDefaultValidator},
156 \param{const wxString\& }{name = wxPanelNameStr}
157 }
c5550b75 158
6f4a67ac
RN
159Creates 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.
160
161If 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.
c5550b75
RN
162
163\docparam{parent}{parent of this control. Must not be NULL.}
164\docparam{id}{id to use for events}
6f4a67ac 165\docparam{fileName}{If not empty, the path of a file to open.}
c5550b75
RN
166\docparam{pos}{Position to put control at.}
167\docparam{size}{Size to put the control at and to stretch movie to.}
c5550b75 168\docparam{style}{Optional styles.}
6f4a67ac
RN
169\docparam{szBackend}{Name of backend you want to use, leave blank to make
170wxMediaCtrl figure it out.}
171\docparam{validator}{validator to use.}
c5550b75
RN
172\docparam{name}{Window name.}
173
174
175\membersection{wxMediaCtrl::GetDuration}\label{wxmediactrlgetduration}
176
6f4a67ac 177\func{wxLongLong}{GetDuration}{\void}
c5550b75 178
39c5bef0 179Obtains the length - the total amount of time the movie has in milliseconds.
c5550b75
RN
180
181
182\membersection{wxMediaCtrl::GetPosition}\label{wxmediactrlgetposition}
183
6f4a67ac 184\func{wxLongLong}{GetPosition}{\void}
c5550b75 185
39c5bef0 186Obtains the current position in time within the movie in milliseconds.
c5550b75
RN
187
188
189\membersection{wxMediaCtrl::GetState}\label{wxmediactrlgetstate}
190
191\func{wxMediaCtrlState}{GetState}{\void}
192
193Obtains the state the playback of the movie is in -
194
195\twocolwidtha{7cm}
196\begin{twocollist}\itemsep=0pt
197\twocolitem{{\bf wxMEDIASTATE\_STOPPED}}{The movie has stopped.}
198\twocolitem{{\bf wxMEDIASTATE\_PAUSED}}{The movie is paused.}
199\twocolitem{{\bf wxMEDIASTATE\_PLAYING}}{The movie is currently playing.}
200\end{twocollist}
201
202
203\membersection{wxMediaCtrl::Load}\label{wxmediactrlload}
204
205\func{bool}{Load}{\param{const wxString\& }{fileName}}
206
39c5bef0 207Loads the file that \tt{fileName} refers to. Returns false if loading fails.
c5550b75
RN
208
209\membersection{wxMediaCtrl::Pause}\label{wxmediactrlpause}
210
211\func{bool}{Pause}{\void}
212
213Pauses playback of the movie.
214
215
216\membersection{wxMediaCtrl::Play}\label{wxmediactrlplay}
217
218\func{bool}{Play}{\void}
219
220Resumes playback of the movie.
221
222
223\membersection{wxMediaCtrl::SetPosition}\label{wxmediactrlsetposition}
224
6f4a67ac 225\func{bool}{SetPosition}{\param{wxLongLong }{where}}
c5550b75
RN
226
227Seeks to a position within the movie.
228
229
230\membersection{wxMediaCtrl::Stop}\label{wxmediactrlstop}
231
232\func{bool}{Stop}{\void}
233
39c5bef0 234Stops the media.
6f4a67ac
RN
235
236See \helpref{Operation}{operationwxmediactrl} for an overview of how stopping works.
237