1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxMediaEvent
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 enum wxMediaCtrlPlayerControls
12 /** No controls. return wxMediaCtrl to its default state. */
13 wxMEDIACTRLPLAYERCONTROLS_NONE
= 0,
15 /** Step controls like fastfoward, step one frame etc. */
16 wxMEDIACTRLPLAYERCONTROLS_STEP
= 1 << 0,
18 /** Volume controls like the speaker icon, volume slider, etc. */
19 wxMEDIACTRLPLAYERCONTROLS_VOLUME
= 1 << 1,
21 /** Default controls for the toolkit. Currently a combination for
22 @c wxMEDIACTRLPLAYERCONTROLS_STEP and @c wxMEDIACTRLPLAYERCONTROLS_VOLUME. */
23 wxMEDIACTRLPLAYERCONTROLS_DEFAULT
=
24 wxMEDIACTRLPLAYERCONTROLS_STEP
|
25 wxMEDIACTRLPLAYERCONTROLS_VOLUME
31 Event wxMediaCtrl uses.
33 @beginEventTable{wxMediaEvent}
34 @event{EVT_MEDIA_LOADED(id\, func)}
35 Sent when a media has loaded enough data that it can start playing.
36 @event{EVT_MEDIA_STOP(id\, func)}
37 Sent when a media has switched to the @c wxMEDIASTATE_STOPPED state.
38 You may be able to Veto this event to prevent it from stopping,
39 causing it to continue playing - even if it has reached that end of
40 the media (note that this may not have the desired effect - if you
41 want to loop the media, for example, catch the @c EVT_MEDIA_FINISHED
42 and play there instead).
43 @event{EVT_MEDIA_FINISHED(id\, func)}
44 Sent when a media has finished playing in a wxMediaCtrl.
45 @event{EVT_MEDIA_STATECHANGED(id\, func)}
46 Sent when a media has switched its state (from any media state).
47 @event{EVT_MEDIA_PLAY(id\, func)}
48 Sent when a media has switched to the @c wxMEDIASTATE_PLAYING state.
49 @event{EVT_MEDIA_PAUSE(id\, func)}
50 Sent when a media has switched to the @c wxMEDIASTATE_PAUSED state.
56 class wxMediaEvent
: public wxNotifyEvent
60 wxMediaEvent(wxEventType commandType
= wxEVT_NULL
, int winid
= 0);
68 wxMediaCtrl is a class for displaying types of media, such as videos, audio
69 files, natively through native codecs.
71 wxMediaCtrl uses native backends to render media, for example on Windows
72 there is a ActiveMovie/DirectShow backend, and on Macintosh there is a
76 @section mediactrl_rendering_media Rendering media
78 Depending upon the backend, wxMediaCtrl can render and display pretty much any
79 kind of media that the native system can - such as an image, mpeg video, or mp3
80 (without license restrictions - since it relies on native system calls that may
81 not technically have mp3 decoding available, for example, it falls outside
82 the realm of licensing restrictions).
84 For general operation, all you need to do is call Load() to load the file you
85 want to render, catch the @c EVT_MEDIA_LOADED event, and then call Play()
86 to show the video/audio of the media in that event.
88 More complex operations are generally more heavily dependant on the capabilities
89 of the backend. For example, QuickTime cannot set the playback rate of certain
90 streaming media - while DirectShow is slightly more flexible in that regard.
92 @section mediactrl_operation Operation
94 When wxMediaCtrl plays a file, it plays until the stop position is reached
95 (currently the end of the file/stream). Right before it hits the end of the stream,
96 it fires off a @c EVT_MEDIA_STOP event to its parent window, at which point the event
97 handler can choose to veto the event, preventing the stream from actually stopping.
102 //connect to the media event
103 this->Connect(wxMY_ID, wxEVT_MEDIA_STOP, (wxObjectEventFunction)
104 (wxEventFunction)(wxMediaEventFunction) &MyFrame::OnMediaStop);
107 void MyFrame::OnMediaStop(const wxMediaEvent& evt)
111 m_mediactrl->SetPosition(
112 m_mediactrl->GetDuration() << 1
119 When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or
120 by manually calling Stop(), where it actually stops is not at the beginning,
121 rather, but at the beginning of the stream. That is, when it stops and play
122 is called, playback is gauranteed to start at the beginning of the media.
123 This is because some streams are not seekable, and when stop is called on
124 them they return to the beginning, thus wxMediaCtrl tries to keep consistant
125 for all types of media.
127 Note that when changing the state of the media through Play() and other methods,
128 the media may not actually be in the @c wxMEDIASTATE_PLAYING, for example.
129 If you are relying on the media being in certain state catch the event relevant
130 to the state. See wxMediaEvent for the kinds of events that you can catch.
133 @section mediactrl_video_size Video size
135 By default, wxMediaCtrl will scale the size of the video to the requested
136 amount passed to either its constructor or Create().
137 After calling wxMediaCtrl::Load or performing an equivilant operation,
138 you can subsequently obtain the "real" size of the video (if there is any)
139 by calling wxMediaCtrl::GetBestSize(). Note that the actual result on the
140 display will be slightly different when wxMediaCtrl::ShowPlayerControls is
141 activated and the actual video size will be less then specified due to the
142 extra controls provided by the native toolkit.
143 In addition, the backend may modify wxMediaCtrl::GetBestSize() to include
144 the size of the extra controls - so if you want the real size of the video
145 just disable wxMediaCtrl::ShowPlayerControls().
147 The idea with setting wxMediaCtrl::GetBestSize() to the size of the video is
148 that GetBestSize() is a wxWindow-derived function that is called when sizers
149 on a window recalculate.
150 What this means is that if you use sizers by default the video will show in
151 its original size without any extra assistance needed from the user.
154 @section mediactrl_player_controls Player controls
156 Normally, when you use wxMediaCtrl it is just a window for the video to play in.
157 However, some toolkits have their own media player interface.
158 For example, QuickTime generally has a bar below the video with a slider.
159 A special feature available to wxMediaCtrl, you can use the toolkits interface
160 instead of making your own by using the ShowPlayerControls() function.
161 There are several options for the flags parameter, with the two general flags
162 being @c wxMEDIACTRLPLAYERCONTROLS_NONE which turns off the native interface,
163 and @c wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets wxMediaCtrl decide what
164 native controls on the interface.
165 Be sure to review the caveats outlined in @ref mediactrl_video_size before doing so.
168 @section mediactrl_choosing_backend Choosing a backend
170 Generally, you should almost certainly leave this part up to wxMediaCtrl -
171 but if you need a certain backend for a particular reason, such as QuickTime
172 for playing .mov files, all you need to do to choose a specific backend is
173 to pass the name of the backend class to wxMediaCtrl::Create().
175 The following are valid backend identifiers:
177 - @b wxMEDIABACKEND_DIRECTSHOW: Use ActiveMovie/DirectShow.
178 Uses the native ActiveMovie (I.E. DirectShow) control.
179 Default backend on Windows and supported by nearly all Windows versions,
180 even some Windows CE versions.
181 May display a windows media player logo while inactive.
182 - @b wxMEDIABACKEND_QUICKTIME: Use QuickTime. Mac Only.
183 WARNING: May not working correctly embedded in a wxNotebook.
184 - @b wxMEDIABACKEND_GSTREAMER, Use GStreamer. Unix Only.
185 Requires GStreamer 0.8 along with at the very least the xvimagesink, xoverlay,
186 and gst-play modules of gstreamer to function.
187 You need the correct modules to play the relavant files, for example the
188 mad module to play mp3s, etc.
189 - @b wxMEDIABACKEND_WMP10, Uses Windows Media Player 10 (Windows only) -
190 works on mobile machines with Windows Media Player 10 and desktop machines
191 with either Windows Media Player 9 or 10.
193 Note that other backends such as wxMEDIABACKEND_MCI can now be found at
194 wxCode (http://wxcode.sourceforge.net/).
197 @section mediactrl_creating_backend Creating a backend
199 Creating a backend for wxMediaCtrl is a rather simple process.
200 Simply derive from wxMediaBackendCommonBase and implement the methods you want.
201 The methods in wxMediaBackend correspond to those in wxMediaCtrl except for
202 wxMediaCtrl::CreateControl which does the actual creation of the control,
203 in cases where a custom control is not needed you may simply call wxControl::Create().
205 You need to make sure to use the @c DECLARE_CLASS and @c IMPLEMENT_CLASS macros.
207 The only real tricky part is that you need to make sure the file in compiled in,
208 which if there are just backends in there will not happen and you may need to
209 use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI).
211 This is a rather simple example of how to create a backend in the
212 wxActiveXContainer documentation.
220 class wxMediaCtrl
: public wxControl
224 Default constructor - you MUST call Create() before calling any
225 other methods of wxMediaCtrl.
230 Constructor that calls Create().
231 You may prefer to call Create() directly to check to see if
232 wxMediaCtrl is available on the system.
235 parent of this control. Must not be @NULL.
239 If not empty, the path of a file to open.
241 Position to put control at.
243 Size to put the control at and to stretch movie to.
247 Name of backend you want to use, leave blank to make wxMediaCtrl figure it out.
253 wxMediaCtrl(wxWindow
* parent
, wxWindowID id
, const wxString
& fileName
= wxEmptyString
,
254 const wxPoint
& pos
= wxDefaultPosition
, const wxSize
& size
= wxDefaultSize
,
255 long style
= 0, const wxString
& szBackend
= wxEmptyString
,
256 const wxValidator
& validator
= wxDefaultValidator
,
257 const wxString
& name
= "mediaCtrl");
260 Creates this control.
261 Returns @false if it can't load the movie located at @a fileName
262 or it cannot load one of its native backends.
264 If you specify a file to open via @a fileName and you don't specify a
265 backend to use, wxMediaCtrl tries each of its backends until one that
266 can render the path referred to by @a fileName can be found.
269 parent of this control. Must not be @NULL.
273 If not empty, the path of a file to open.
275 Position to put control at.
277 Size to put the control at and to stretch movie to.
281 Name of backend you want to use, leave blank to make wxMediaCtrl figure it out.
287 bool Create(wxWindow
* parent
, wxWindowID id
, const wxString
& fileName
= wxEmptyString
,
288 const wxPoint
& pos
= wxDefaultPosition
, const wxSize
& size
= wxDefaultSize
,
289 long style
= 0, const wxString
& szBackend
= wxEmptyString
,
290 const wxValidator
& validator
= wxDefaultValidator
,
291 const wxString
& name
= "mediaCtrl");
294 Obtains the best size relative to the original/natural size of the
295 video, if there is any.
296 See @ref mediactrl_video_size for more information.
298 wxSize
GetBestSize() const;
301 Obtains the playback rate, or speed of the media. @c 1.0 represents normal
302 speed, while @c 2.0 represents twice the normal speed of the media, for
303 example. Not supported on the GStreamer (Unix) backend.
305 @return zero on failure.
307 double GetPlaybackrate();
310 Obtains the state the playback of the media is in -
313 @row2col{wxMEDIASTATE_STOPPED, The movie has stopped.}
314 @row2col{wxMEDIASTATE_PAUSED, The movie is paused.}
315 @row2col{wxMEDIASTATE_PLAYING, The movie is currently playing.}
318 wxMediaState
GetState();
321 Gets the volume of the media from a 0.0 to 1.0 range.
323 @note Due to rounding and other errors the value returned may not be the
324 exact value sent to SetVolume().
329 Obtains the length - the total amount of time the movie has in milliseconds.
331 wxFileOffset
Length();
334 Loads the file that fileName refers to. Returns @false if loading fails.
336 bool Load(const wxString
& fileName
);
339 Loads the location that uri refers to. Note that this is very
340 implementation-dependant, although HTTP URI/URLs are generally
341 supported, for example. Returns @false if loading fails.
343 bool Load(const wxURI
& uri
);
346 Loads the location that @c uri refers to with the proxy @c proxy.
347 Not implemented on most backends so it should be called with caution.
348 Returns @false if loading fails.
350 bool Load(const wxURI
& uri
, const wxURI
& proxy
);
353 Same as Load(const wxURI& uri). Kept for wxPython compatibility.
355 bool LoadURI(const wxString
& fileName
);
358 Same as Load(const wxURI& uri, const wxURI& proxy).
359 Kept for wxPython compatibility.
361 bool LoadURIWithProxy(const wxString
& fileName
, const wxString
& proxy
);
364 Pauses playback of the movie.
369 Resumes playback of the movie.
374 Seeks to a position within the movie.
376 @todo Document the wxSeekMode parameter @a mode, and perhaps also the
377 wxFileOffset and wxSeekMode themselves.
379 wxFileOffset
Seek(wxFileOffset where
, wxSeekMode mode
= wxFromStart
);
382 Sets the playback rate, or speed of the media, to that referred by @a dRate.
383 @c 1.0 represents normal speed, while @c 2.0 represents twice the normal
384 speed of the media, for example. Not supported on the GStreamer (Unix) backend.
385 Returns @true if successful.
387 bool SetPlaybackRate(double dRate
);
390 Sets the volume of the media from a 0.0 to 1.0 range to that referred
391 by @c dVolume. @c 1.0 represents full volume, while @c 0.5
392 represents half (50 percent) volume, for example.
394 @note The volume may not be exact due to conversion and rounding errors,
395 although setting the volume to full or none is always exact.
396 Returns @true if successful.
398 bool SetVolume(double dVolume
);
401 A special feature to wxMediaCtrl. Applications using native toolkits such as
402 QuickTime usually have a scrollbar, play button, and more provided to
403 them by the toolkit. By default wxMediaCtrl does not do this. However, on
404 the directshow and quicktime backends you can show or hide the native controls
405 provided by the underlying toolkit at will using ShowPlayerControls(). Simply
406 calling the function with default parameters tells wxMediaCtrl to use the
407 default controls provided by the toolkit. The function takes a
408 wxMediaCtrlPlayerControls enumeration, please see available show modes there.
410 For more info see @ref mediactrl_player_controls.
412 Currently only implemented on the QuickTime and DirectShow backends.
413 The function returns @true on success.
415 bool ShowPlayerControls(wxMediaCtrlPlayerControls flags
= wxMEDIACTRLPLAYERCONTROLS_DEFAULT
);
420 See @ref mediactrl_operation for an overview of how stopping works.
425 Obtains the current position in time within the movie in milliseconds.