interface/wx/mediactrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        mediactrl.h
   3 // Purpose:     interface of wxMediaEvent, wxMediaCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 enum wxMediaCtrlPlayerControls
  11 {
  12     /** No controls. return wxMediaCtrl to its default state. */
  13     wxMEDIACTRLPLAYERCONTROLS_NONE           =   0,
  14
  15     /** Step controls like fastforward, step one frame etc. */
  16     wxMEDIACTRLPLAYERCONTROLS_STEP           =   1 << 0,
  17
  18     /** Volume controls like the speaker icon, volume slider, etc. */
  19     wxMEDIACTRLPLAYERCONTROLS_VOLUME         =   1 << 1,
  20
  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
  26 };
  27
  28 /**
  29     @class wxMediaEvent
  30
  31     Event wxMediaCtrl uses.
  32
  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.
  51     @endEventTable
  52
  53     @library{wxmedia}
  54     @category{events}
  55 */
  56 class wxMediaEvent : public wxNotifyEvent
  57 {
  58 public:
  59     /** Default ctor. */
  60     wxMediaEvent(wxEventType commandType = wxEVT_NULL, int winid = 0);
  61 };
  62
  63
  64
  65 /**
  66     @class wxMediaCtrl
  67
  68     wxMediaCtrl is a class for displaying types of media, such as videos, audio
  69     files, natively through native codecs.
  70
  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
  73     QuickTime backend.
  74
  75
  76     @section mediactrl_rendering_media Rendering media
  77
  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).
  83
  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.
  87
  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.
  91
  92     @section mediactrl_operation Operation
  93
  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.
  98
  99     Example:
 100
 101     @code
 102     //connect to the media event
 103     this->Connect(wxMY_ID, wxEVT_MEDIA_STOP, (wxObjectEventFunction)
 104     (wxEventFunction)(wxMediaEventFunction) &MyFrame::OnMediaStop);
 105
 106     //...
 107     void MyFrame::OnMediaStop(const wxMediaEvent& evt)
 108     {
 109         if(bUserWantsToSeek)
 110         {
 111             m_mediactrl->SetPosition(
 112                 m_mediactrl->GetDuration() << 1
 113                                     );
 114             evt.Veto();
 115         }
 116     }
 117     @endcode
 118
 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 guaranteed 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 consistent
 125     for all types of media.
 126
 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.
 131
 132
 133     @section mediactrl_video_size Video size
 134
 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 equivalent 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 than 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().
 146
 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.
 152
 153
 154     @section mediactrl_player_controls Player controls
 155
 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.
 166
 167
 168     @section mediactrl_choosing_backend Choosing a backend
 169
 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().
 174
 175     The following are valid backend identifiers:
 176
 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 relevant 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.
 192
 193     Note that other backends such as wxMEDIABACKEND_MCI can now be found at
 194     wxCode (http://wxcode.sourceforge.net/).
 195
 196
 197     @section mediactrl_creating_backend Creating a backend
 198
 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().
 204
 205     You need to make sure to use the @c DECLARE_CLASS and @c IMPLEMENT_CLASS macros.
 206
 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).
 210
 211     This is a rather simple example of how to create a backend in the
 212     wxActiveXContainer documentation.
 213
 214
 215     @library{wxmedia}
 216     @category{media}
 217
 218     @see wxMediaEvent
 219 */
 220 class wxMediaCtrl : public wxControl
 221 {
 222 public:
 223     /**
 224         Default constructor - you MUST call Create() before calling any
 225         other methods of wxMediaCtrl.
 226     */
 227     wxMediaCtrl();
 228
 229     /**
 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.
 233
 234         @param parent
 235             parent of this control.  Must not be @NULL.
 236         @param id
 237             id to use for events
 238         @param fileName
 239             If not empty, the path of a file to open.
 240         @param pos
 241             Position to put control at.
 242         @param size
 243             Size to put the control at and to stretch movie to.
 244         @param style
 245             Optional styles.
 246         @param szBackend
 247             Name of backend you want to use, leave blank to make wxMediaCtrl figure it out.
 248         @param validator
 249             validator to use.
 250         @param name
 251             Window name.
 252     */
 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");
 258
 259     /**
 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.
 263
 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.
 267
 268         @param parent
 269             parent of this control.  Must not be @NULL.
 270         @param id
 271             id to use for events
 272         @param fileName
 273             If not empty, the path of a file to open.
 274         @param pos
 275             Position to put control at.
 276         @param size
 277             Size to put the control at and to stretch movie to.
 278         @param style
 279             Optional styles.
 280         @param szBackend
 281             Name of backend you want to use, leave blank to make wxMediaCtrl figure it out.
 282         @param validator
 283             validator to use.
 284         @param name
 285             Window name.
 286     */
 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");
 292
 293     /**
 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.
 297     */
 298     wxSize GetBestSize() const;
 299
 300     /**
 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.
 304
 305         @return zero on failure.
 306     */
 307     double GetPlaybackRate();
 308
 309     /**
 310         Obtains the state the playback of the media is in -
 311
 312         @beginTable
 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.}
 316         @endTable
 317     */
 318     wxMediaState GetState();
 319
 320     /**
 321         Gets the volume of the media from a 0.0 to 1.0 range.
 322
 323         @note Due to rounding and other errors the value returned may not be the
 324               exact value sent to SetVolume().
 325     */
 326     double GetVolume();
 327
 328     /**
 329         Obtains the length - the total amount of time the movie has in milliseconds.
 330     */
 331     wxFileOffset Length();
 332
 333     /**
 334         Loads the file that fileName refers to. Returns @false if loading fails.
 335     */
 336     bool Load(const wxString& fileName);
 337
 338     /**
 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.
 342     */
 343     bool Load(const wxURI& uri);
 344
 345     /**
 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.
 349     */
 350     bool Load(const wxURI& uri, const wxURI& proxy);
 351
 352     /**
 353         Same as Load(const wxURI& uri). Kept for wxPython compatibility.
 354     */
 355     bool LoadURI(const wxString& fileName);
 356
 357     /**
 358         Same as Load(const wxURI& uri, const wxURI& proxy).
 359         Kept for wxPython compatibility.
 360     */
 361     bool LoadURIWithProxy(const wxString& fileName, const wxString& proxy);
 362
 363     /**
 364         Pauses playback of the movie.
 365     */
 366     bool Pause();
 367
 368     /**
 369         Resumes playback of the movie.
 370     */
 371     bool Play();
 372
 373     /**
 374         Seeks to a position within the movie.
 375
 376         @todo Document the wxSeekMode parameter @a mode, and perhaps also the
 377               wxFileOffset and wxSeekMode themselves.
 378     */
 379     wxFileOffset Seek(wxFileOffset where, wxSeekMode mode = wxFromStart);
 380
 381     /**
 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.
 386     */
 387     bool SetPlaybackRate(double dRate);
 388
 389     /**
 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.
 393
 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.
 397     */
 398     bool SetVolume(double dVolume);
 399
 400     /**
 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.
 409
 410         For more info see @ref mediactrl_player_controls.
 411
 412         Currently only implemented on the QuickTime and DirectShow backends.
 413         The function returns @true on success.
 414     */
 415     bool ShowPlayerControls(wxMediaCtrlPlayerControls flags = wxMEDIACTRLPLAYERCONTROLS_DEFAULT);
 416
 417     /**
 418         Stops the media.
 419
 420         See @ref mediactrl_operation for an overview of how stopping works.
 421     */
 422     bool Stop();
 423
 424     /**
 425         Obtains the current position in time within the movie in milliseconds.
 426     */
 427     wxFileOffset Tell();
 428 };
 429