+
+ @section class_mediactrl_rendering_media Rendering media
+
+ Depending upon the backend, wxMediaCtrl can render and display pretty much any
+ kind of media that the native system can - such as an image, mpeg video, or mp3
+ (without license restrictions - since it relies on native system calls that may
+ not technically have mp3 decoding available, for example, it falls outside
+ the realm of licensing restrictions).
+
+ For general operation, all you need to do is call Load() to load the file you
+ want to render, catch the @c EVT_MEDIA_LOADED event, and then call Play()
+ to show the video/audio of the media in that event.
+
+ More complex operations are generally more heavily dependant on the capabilities
+ of the backend. For example, QuickTime cannot set the playback rate of certain
+ streaming media - while DirectShow is slightly more flexible in that regard.
+
+ @section class_mediactrl_operation Operation
+
+ When wxMediaCtrl plays a file, it plays until the stop position is reached
+ (currently the end of the file/stream). Right before it hits the end of the stream,
+ it fires off a @c EVT_MEDIA_STOP event to its parent window, at which point the event
+ handler can choose to veto the event, preventing the stream from actually stopping.
+
+ Example:
+
+ @code
+ //connect to the media event
+ this->Connect(wxMY_ID, wxEVT_MEDIA_STOP, (wxObjectEventFunction)
+ (wxEventFunction)(wxMediaEventFunction) &MyFrame::OnMediaStop);
+
+ //...
+ void MyFrame::OnMediaStop(const wxMediaEvent& evt)
+ {
+ if(bUserWantsToSeek)
+ {
+ m_mediactrl->SetPosition(
+ m_mediactrl->GetDuration() << 1
+ );
+ evt.Veto();
+ }
+ }
+ @endcode
+
+ When wxMediaCtrl stops, either by the @c EVT_MEDIA_STOP not being vetoed, or by manually
+ calling Stop(), where it actually stops is not at the beginning, rather, but at the beginning
+ of the stream. That is, when it stops and play is called, playback is gauranteed to start at
+ the beginning of the media. This is because some streams are not seekable, and when stop is
+ called on them they return to the beginning, thus wxMediaCtrl tries to keep consistant for all types
+ of media.
+
+ Note that when changing the state of the media through Play() and other methods, the media may not
+ actually be in the @c wxMEDIASTATE_PLAYING, for example. If you are relying on the media being in
+ certain state catch the event relevant to the state. See wxMediaEvent for the kinds of events that
+ you can catch.
+
+ @section class_mediactrl_video_size Video size
+
+ By default, wxMediaCtrl will scale the size of the video to the requested amount passed to either
+ its constructor or Create(). After calling Load or performing an equivilant operation, you can
+ subsequently obtain the "real" size of the video (if there is any) by calling GetBestSize().
+ Note that the actual result on the display will be slightly different when ShowPlayerControls is
+ activated and the actual video size will be less then specified due to the extra controls provided
+ by the native toolkit. In addition, the backend may modify GetBestSize() to include the size of
+ the extra controls - so if you want the real size of the video just disable ShowPlayerControls().
+
+ The idea with setting GetBestSize() to the size of the video is that GetBestSize() is a wxWindow-derived
+ function that is called when sizers on a window recalculate. What this means is that if you use sizers
+ by default the video will show in its original size without any extra assistance needed from the user.
+
+ @section class_mediactrl_player_controls Player controls
+
+ Normally, when you use wxMediaCtrl it is just a window for the video to play in. However, some toolkits
+ have their own media player interface. For example, QuickTime generally has a bar below the video with
+ a slider. A special feature available to wxMediaCtrl, you can use the toolkits interface instead of making
+ your own by using the ShowPlayerControls() function. There are several options for the flags parameter,
+ with the two general flags being @c wxMEDIACTRLPLAYERCONTROLS_NONE which turns off the native interface,
+ and @c wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets wxMediaCtrl decide what native controls on the interface.
+ Be sure to review the caveats outlined in Video size before doing so.
+
+ @section class_mediactrl_choosing_backend Choosing a backend
+
+ Generally, you should almost certainly leave this part up to wxMediaCtrl - but if you need a certain backend
+ for a particular reason, such as QuickTime for playing .mov files, all you need to do to choose a specific
+ backend is to pass the name of the backend class to Create().
+
+ The following are valid backend identifiers:
+
+ @beginTable
+ @row2col{@b wxMEDIABACKEND_DIRECTSHOW, Use ActiveMovie/DirectShow. Uses the native ActiveMovie (I.E. DirectShow) control. Default backend on Windows and supported by nearly all Windows versions, even some Windows CE versions. May display a windows media player logo while inactive.}
+ @row2col{@b wxMEDIABACKEND_QUICKTIME, Use QuickTime. Mac Only. WARNING: May not working correctly embedded in a wxNotebook.}
+ @row2col{@b wxMEDIABACKEND_GSTREAMER, Use GStreamer. Unix Only. Requires GStreamer 0.8 along with at the very least the xvimagesink, xoverlay, and gst-play modules of gstreamer to function. You need the correct modules to play the relavant files, for example the mad module to play mp3s, etc.}
+ @row2col{@b wxMEDIABACKEND_WMP10, Uses Windows Media Player 10 (Windows only) - works on mobile machines with Windows Media Player 10 and desktop machines with either Windows Media Player 9 or 10}
+ @endTable
+
+ Note that other backends such as wxMEDIABACKEND_MCI can now be found at wxCode(http://wxcode.sourceforge.net/).
+
+ @section class_mediactrl_creating_backend Creating a backend
+
+ Creating a backend for wxMediaCtrl is a rather simple process. Simply derive from wxMediaBackendCommonBase
+ and implement the methods you want. The methods in wxMediaBackend correspond to those in wxMediaCtrl except
+ for CreateControl which does the actual creation of the control, in cases where a custom control is not
+ needed you may simply call wxControl::Create().
+
+ You need to make sure to use the @c DECLARE_CLASS and @c IMPLEMENT_CLASS macros.
+
+ The only real tricky part is that you need to make sure the file in compiled in, which if there are
+ just backends in there will not happen and you may need to use a force link hack
+ (see http://www.wxwidgets.org/wiki/index.php/RTTI).
+
+ This is a rather simple example of how to create a backend in the wxActiveXContainer documentation.
projects / wxWidgets.git / blobdiff