interface/wx/mediactrl.h

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