interface/mediactrl.h

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