+
+ @section 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 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 guaranteed 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 consistent
+ 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 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 wxMediaCtrl::Load or performing an equivalent operation,
+ you can subsequently obtain the "real" size of the video (if there is any)
+ by calling wxMediaCtrl::GetBestSize(). Note that the actual result on the
+ display will be slightly different when wxMediaCtrl::ShowPlayerControls is
+ activated and the actual video size will be less than specified due to the
+ extra controls provided by the native toolkit.
+ In addition, the backend may modify wxMediaCtrl::GetBestSize() to include
+ the size of the extra controls - so if you want the real size of the video
+ just disable wxMediaCtrl::ShowPlayerControls().
+
+ The idea with setting wxMediaCtrl::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 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 @ref mediactrl_video_size before doing so.
+
+
+ @section 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 wxMediaCtrl::Create().
+
+ The following are valid backend identifiers:
+
+ - @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.
+ - @b wxMEDIABACKEND_QUICKTIME: Use QuickTime. Mac Only.
+ WARNING: May not working correctly embedded in a wxNotebook.
+ - @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 relevant files, for example the
+ mad module to play mp3s, etc.
+ - @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.
+
+ Note that other backends such as wxMEDIABACKEND_MCI can now be found at
+ wxCode (http://wxcode.sourceforge.net/).
+
+
+ @section 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
+ wxMediaCtrl::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