1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: mediactrl.h 3 // Purpose: interface of wxMediaEvent, wxMediaCtrl 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 /** 9 Describes the current state of the media. 10 11 @see wxMediaCtrl::GetState() 12 */ 13 enum wxMediaState 14 { 15 /** No media is being currently played. */ 16 wxMEDIASTATE_STOPPED, 17 18 /** Current media is paused. */ 19 wxMEDIASTATE_PAUSED, 20 21 /** There is media currently playing. */ 22 wxMEDIASTATE_PLAYING 23 }; 24 25 enum wxMediaCtrlPlayerControls 26 { 27 /** No controls. return wxMediaCtrl to its default state. */ 28 wxMEDIACTRLPLAYERCONTROLS_NONE = 0, 29 30 /** Step controls like fastforward, step one frame etc. */ 31 wxMEDIACTRLPLAYERCONTROLS_STEP = 1 << 0, 32 33 /** Volume controls like the speaker icon, volume slider, etc. */ 34 wxMEDIACTRLPLAYERCONTROLS_VOLUME = 1 << 1, 35 36 /** Default controls for the toolkit. Currently a combination for 37 @c wxMEDIACTRLPLAYERCONTROLS_STEP and @c wxMEDIACTRLPLAYERCONTROLS_VOLUME. */ 38 wxMEDIACTRLPLAYERCONTROLS_DEFAULT = 39 wxMEDIACTRLPLAYERCONTROLS_STEP | 40 wxMEDIACTRLPLAYERCONTROLS_VOLUME 41 }; 42 43 /** 44 @class wxMediaEvent 45 46 Event wxMediaCtrl uses. 47 48 @beginEventTable{wxMediaEvent} 49 @event{EVT_MEDIA_LOADED(id\, func)} 50 Sent when a media has loaded enough data that it can start playing. 51 Processes a @c wxEVT_MEDIA_LOADED event type. 52 @event{EVT_MEDIA_STOP(id\, func)} 53 Sent when a media has switched to the @c wxMEDIASTATE_STOPPED state. 54 You may be able to Veto this event to prevent it from stopping, 55 causing it to continue playing - even if it has reached that end of 56 the media (note that this may not have the desired effect - if you 57 want to loop the media, for example, catch the @c EVT_MEDIA_FINISHED 58 and play there instead). 59 Processes a @c wxEVT_MEDIA_STOP event type. 60 @event{EVT_MEDIA_FINISHED(id\, func)} 61 Sent when a media has finished playing in a wxMediaCtrl. 62 Processes a @c wxEVT_MEDIA_FINISHED event type. 63 @event{EVT_MEDIA_STATECHANGED(id\, func)} 64 Sent when a media has switched its state (from any media state). 65 Processes a @c wxEVT_MEDIA_STATECHANGED event type. 66 @event{EVT_MEDIA_PLAY(id\, func)} 67 Sent when a media has switched to the @c wxMEDIASTATE_PLAYING state. 68 Processes a @c wxEVT_MEDIA_PLAY event type. 69 @event{EVT_MEDIA_PAUSE(id\, func)} 70 Sent when a media has switched to the @c wxMEDIASTATE_PAUSED state. 71 Processes a @c wxEVT_MEDIA_PAUSE event type. 72 @endEventTable 73 74 @library{wxmedia} 75 @category{events} 76 */ 77 class wxMediaEvent : public wxNotifyEvent 78 { 79 public: 80 /** Default ctor. */ 81 wxMediaEvent(wxEventType commandType = wxEVT_NULL, int winid = 0); 82 }; 83 84 85 86 /** 87 @class wxMediaCtrl 88 89 wxMediaCtrl is a class for displaying types of media, such as videos, audio 90 files, natively through native codecs. 91 92 wxMediaCtrl uses native backends to render media, for example on Windows 93 there is a ActiveMovie/DirectShow backend, and on Macintosh there is a 94 QuickTime backend. 95 96 97 @section mediactrl_rendering_media Rendering media 98 99 Depending upon the backend, wxMediaCtrl can render and display pretty much any 100 kind of media that the native system can - such as an image, mpeg video, or mp3 101 (without license restrictions - since it relies on native system calls that may 102 not technically have mp3 decoding available, for example, it falls outside 103 the realm of licensing restrictions). 104 105 For general operation, all you need to do is call Load() to load the file you 106 want to render, catch the @c EVT_MEDIA_LOADED event, and then call Play() 107 to show the video/audio of the media in that event. 108 109 More complex operations are generally more heavily dependent on the capabilities 110 of the backend. For example, QuickTime cannot set the playback rate of certain 111 streaming media - while DirectShow is slightly more flexible in that regard. 112 113 @section mediactrl_operation Operation 114 115 When wxMediaCtrl plays a file, it plays until the stop position is reached 116 (currently the end of the file/stream). Right before it hits the end of the stream, 117 it fires off a @c EVT_MEDIA_STOP event to its parent window, at which point the event 118 handler can choose to veto the event, preventing the stream from actually stopping. 119 120 Example: 121 122 @code 123 //connect to the media event 124 this->Connect(wxMY_ID, wxEVT_MEDIA_STOP, (wxObjectEventFunction) 125 (wxEventFunction)(wxMediaEventFunction) &MyFrame::OnMediaStop); 126 127 //... 128 void MyFrame::OnMediaStop(const wxMediaEvent& evt) 129 { 130 if(bUserWantsToSeek) 131 { 132 m_mediactrl->SetPosition( 133 m_mediactrl->GetDuration() << 1 134 ); 135 evt.Veto(); 136 } 137 } 138 @endcode 139 140 When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or 141 by manually calling Stop(), where it actually stops is not at the beginning, 142 rather, but at the beginning of the stream. That is, when it stops and play 143 is called, playback is guaranteed to start at the beginning of the media. 144 This is because some streams are not seekable, and when stop is called on 145 them they return to the beginning, thus wxMediaCtrl tries to keep consistent 146 for all types of media. 147 148 Note that when changing the state of the media through Play() and other methods, 149 the media may not actually be in the @c wxMEDIASTATE_PLAYING, for example. 150 If you are relying on the media being in certain state catch the event relevant 151 to the state. See wxMediaEvent for the kinds of events that you can catch. 152 153 154 @section mediactrl_video_size Video size 155 156 By default, wxMediaCtrl will scale the size of the video to the requested 157 amount passed to either its constructor or Create(). 158 After calling wxMediaCtrl::Load or performing an equivalent operation, 159 you can subsequently obtain the "real" size of the video (if there is any) 160 by calling wxMediaCtrl::GetBestSize(). Note that the actual result on the 161 display will be slightly different when wxMediaCtrl::ShowPlayerControls is 162 activated and the actual video size will be less than specified due to the 163 extra controls provided by the native toolkit. 164 In addition, the backend may modify wxMediaCtrl::GetBestSize() to include 165 the size of the extra controls - so if you want the real size of the video 166 just disable wxMediaCtrl::ShowPlayerControls(). 167 168 The idea with setting wxMediaCtrl::GetBestSize() to the size of the video is 169 that GetBestSize() is a wxWindow-derived function that is called when sizers 170 on a window recalculate. 171 What this means is that if you use sizers by default the video will show in 172 its original size without any extra assistance needed from the user. 173 174 175 @section mediactrl_player_controls Player controls 176 177 Normally, when you use wxMediaCtrl it is just a window for the video to play in. 178 However, some toolkits have their own media player interface. 179 For example, QuickTime generally has a bar below the video with a slider. 180 A special feature available to wxMediaCtrl, you can use the toolkits interface 181 instead of making your own by using the ShowPlayerControls() function. 182 There are several options for the flags parameter, with the two general flags 183 being @c wxMEDIACTRLPLAYERCONTROLS_NONE which turns off the native interface, 184 and @c wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets wxMediaCtrl decide what 185 native controls on the interface. 186 Be sure to review the caveats outlined in @ref mediactrl_video_size before doing so. 187 188 189 @section mediactrl_choosing_backend Choosing a backend 190 191 Generally, you should almost certainly leave this part up to wxMediaCtrl - 192 but if you need a certain backend for a particular reason, such as QuickTime 193 for playing .mov files, all you need to do to choose a specific backend is 194 to pass the name of the backend class to wxMediaCtrl::Create(). 195 196 The following are valid backend identifiers: 197 198 - @b wxMEDIABACKEND_DIRECTSHOW: Use ActiveMovie/DirectShow. 199 Uses the native ActiveMovie (I.E. DirectShow) control. 200 Default backend on Windows and supported by nearly all Windows versions, 201 even some Windows CE versions. 202 May display a windows media player logo while inactive. 203 - @b wxMEDIABACKEND_QUICKTIME: Use QuickTime. Mac Only. 204 WARNING: May not working correctly embedded in a wxNotebook. 205 - @b wxMEDIABACKEND_GSTREAMER, Use GStreamer. Unix Only. 206 Requires GStreamer 0.8 along with at the very least the xvimagesink, xoverlay, 207 and gst-play modules of gstreamer to function. 208 You need the correct modules to play the relevant files, for example the 209 mad module to play mp3s, etc. 210 - @b wxMEDIABACKEND_WMP10, Uses Windows Media Player 10 (Windows only) - 211 works on mobile machines with Windows Media Player 10 and desktop machines 212 with either Windows Media Player 9 or 10. 213 214 Note that other backends such as wxMEDIABACKEND_MCI can now be found at 215 wxCode (http://wxcode.sourceforge.net/). 216 217 218 @section mediactrl_creating_backend Creating a backend 219 220 Creating a backend for wxMediaCtrl is a rather simple process. 221 Simply derive from wxMediaBackendCommonBase and implement the methods you want. 222 The methods in wxMediaBackend correspond to those in wxMediaCtrl except for 223 wxMediaCtrl::CreateControl which does the actual creation of the control, 224 in cases where a custom control is not needed you may simply call wxControl::Create(). 225 226 You need to make sure to use the @c DECLARE_CLASS and @c IMPLEMENT_CLASS macros. 227 228 The only real tricky part is that you need to make sure the file in compiled in, 229 which if there are just backends in there will not happen and you may need to 230 use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI). 231 232 This is a rather simple example of how to create a backend in the 233 wxActiveXContainer documentation. 234 235 236 @library{wxmedia} 237 @category{media} 238 239 @see wxMediaEvent 240 */ 241 class wxMediaCtrl : public wxControl 242 { 243 public: 244 /** 245 Default constructor - you MUST call Create() before calling any 246 other methods of wxMediaCtrl. 247 */ 248 wxMediaCtrl(); 249 250 /** 251 Constructor that calls Create(). 252 You may prefer to call Create() directly to check to see if 253 wxMediaCtrl is available on the system. 254 255 @param parent 256 parent of this control. Must not be @NULL. 257 @param id 258 id to use for events 259 @param fileName 260 If not empty, the path of a file to open. 261 @param pos 262 Position to put control at. 263 @param size 264 Size to put the control at and to stretch movie to. 265 @param style 266 Optional styles. 267 @param szBackend 268 Name of backend you want to use, leave blank to make wxMediaCtrl figure it out. 269 @param validator 270 validator to use. 271 @param name 272 Window name. 273 */ 274 wxMediaCtrl(wxWindow* parent, wxWindowID id, const wxString& fileName = wxEmptyString, 275 const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, 276 long style = 0, const wxString& szBackend = wxEmptyString, 277 const wxValidator& validator = wxDefaultValidator, 278 const wxString& name = "mediaCtrl"); 279 280 /** 281 Creates this control. 282 Returns @false if it can't load the movie located at @a fileName 283 or it cannot load one of its native backends. 284 285 If you specify a file to open via @a fileName and you don't specify a 286 backend to use, wxMediaCtrl tries each of its backends until one that 287 can render the path referred to by @a fileName can be found. 288 289 @param parent 290 parent of this control. Must not be @NULL. 291 @param id 292 id to use for events 293 @param fileName 294 If not empty, the path of a file to open. 295 @param pos 296 Position to put control at. 297 @param size 298 Size to put the control at and to stretch movie to. 299 @param style 300 Optional styles. 301 @param szBackend 302 Name of backend you want to use, leave blank to make wxMediaCtrl figure it out. 303 @param validator 304 validator to use. 305 @param name 306 Window name. 307 */ 308 bool Create(wxWindow* parent, wxWindowID id, const wxString& fileName = wxEmptyString, 309 const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, 310 long style = 0, const wxString& szBackend = wxEmptyString, 311 const wxValidator& validator = wxDefaultValidator, 312 const wxString& name = "mediaCtrl"); 313 314 /** 315 Obtains the best size relative to the original/natural size of the 316 video, if there is any. 317 See @ref mediactrl_video_size for more information. 318 */ 319 wxSize GetBestSize() const; 320 321 /** 322 Obtains the playback rate, or speed of the media. @c 1.0 represents normal 323 speed, while @c 2.0 represents twice the normal speed of the media, for 324 example. Not supported on the GStreamer (Unix) backend. 325 326 @return zero on failure. 327 */ 328 double GetPlaybackRate(); 329 330 /** 331 Obtains the state the playback of the media is in. 332 333 @beginTable 334 @row2col{wxMEDIASTATE_STOPPED, The movie has stopped.} 335 @row2col{wxMEDIASTATE_PAUSED, The movie is paused.} 336 @row2col{wxMEDIASTATE_PLAYING, The movie is currently playing.} 337 @endTable 338 */ 339 wxMediaState GetState(); 340 341 /** 342 Gets the volume of the media from a 0.0 to 1.0 range. 343 344 @note Due to rounding and other errors the value returned may not be the 345 exact value sent to SetVolume(). 346 */ 347 double GetVolume(); 348 349 /** 350 Obtains the length - the total amount of time the movie has in milliseconds. 351 */ 352 wxFileOffset Length(); 353 354 /** 355 Loads the file that fileName refers to. Returns @false if loading fails. 356 */ 357 bool Load(const wxString& fileName); 358 359 /** 360 Loads the location that uri refers to. Note that this is very 361 implementation-dependent, although HTTP URI/URLs are generally 362 supported, for example. Returns @false if loading fails. 363 */ 364 bool Load(const wxURI& uri); 365 366 /** 367 Loads the location that @c uri refers to with the proxy @c proxy. 368 Not implemented on most backends so it should be called with caution. 369 Returns @false if loading fails. 370 */ 371 bool Load(const wxURI& uri, const wxURI& proxy); 372 373 /** 374 Same as Load(const wxURI& uri). Kept for wxPython compatibility. 375 */ 376 bool LoadURI(const wxString& uri); 377 378 /** 379 Same as Load(const wxURI& uri, const wxURI& proxy). 380 Kept for wxPython compatibility. 381 */ 382 bool LoadURIWithProxy(const wxString& uri, const wxString& proxy); 383 384 /** 385 Pauses playback of the movie. 386 */ 387 bool Pause(); 388 389 /** 390 Resumes playback of the movie. 391 */ 392 bool Play(); 393 394 /** 395 Seeks to a position within the movie. 396 397 @todo Document the wxSeekMode parameter @a mode, and perhaps also the 398 wxFileOffset and wxSeekMode themselves. 399 */ 400 wxFileOffset Seek(wxFileOffset where, wxSeekMode mode = wxFromStart); 401 402 /** 403 Sets the playback rate, or speed of the media, to that referred by @a dRate. 404 @c 1.0 represents normal speed, while @c 2.0 represents twice the normal 405 speed of the media, for example. Not supported on the GStreamer (Unix) backend. 406 Returns @true if successful. 407 */ 408 bool SetPlaybackRate(double dRate); 409 410 /** 411 Sets the volume of the media from a 0.0 to 1.0 range to that referred 412 by @c dVolume. @c 1.0 represents full volume, while @c 0.5 413 represents half (50 percent) volume, for example. 414 415 @note The volume may not be exact due to conversion and rounding errors, 416 although setting the volume to full or none is always exact. 417 Returns @true if successful. 418 */ 419 bool SetVolume(double dVolume); 420 421 /** 422 A special feature to wxMediaCtrl. Applications using native toolkits such as 423 QuickTime usually have a scrollbar, play button, and more provided to 424 them by the toolkit. By default wxMediaCtrl does not do this. However, on 425 the directshow and quicktime backends you can show or hide the native controls 426 provided by the underlying toolkit at will using ShowPlayerControls(). Simply 427 calling the function with default parameters tells wxMediaCtrl to use the 428 default controls provided by the toolkit. The function takes a 429 wxMediaCtrlPlayerControls enumeration, please see available show modes there. 430 431 For more info see @ref mediactrl_player_controls. 432 433 Currently only implemented on the QuickTime and DirectShow backends. 434 The function returns @true on success. 435 */ 436 bool ShowPlayerControls(wxMediaCtrlPlayerControls flags = wxMEDIACTRLPLAYERCONTROLS_DEFAULT); 437 438 /** 439 Stops the media. 440 441 See @ref mediactrl_operation for an overview of how stopping works. 442 */ 443 bool Stop(); 444 445 /** 446 Obtains the current position in time within the movie in milliseconds. 447 */ 448 wxFileOffset Tell(); 449 }; 450 451 wxEventType wxEVT_MEDIA_LOADED; 452 wxEventType wxEVT_MEDIA_STOP; 453 wxEventType wxEVT_MEDIA_FINISHED; 454 wxEventType wxEVT_MEDIA_STATECHANGED; 455 wxEventType wxEVT_MEDIA_PLAY; 456 wxEventType wxEVT_MEDIA_PAUSE; 457