1 // This may look like C code, but it's really -*- C++ -*- 2 /* 3 * Copyright (C) 2010 Emweb bv, Herent, Belgium. 4 * 5 * See the LICENSE file for terms of use. 6 */ 7 #ifndef WAUDIO_H_ 8 #define WAUDIO_H_ 9 10 #include <Wt/WAbstractMedia.h> 11 12 namespace Wt { 13 14 /*! \class WAudio Wt/WAudio.h Wt/WAudio.h 15 * \brief A widget that plays audio. 16 * 17 * This is a low-level widget, mapping directly onto a 18 * <tt><audio></tt> element available in HTML5 compliant 19 * browsers. 20 * 21 * In almost every situation you should use the WMediaPlayer widget 22 * if you want the user to be able to interact with the audio, or 23 * WSound for simple sound feed-back. 24 * 25 * Usage of the audio element consists of adding one or more audio 26 * sources and setting some options. Since not every browser supports 27 * HTML5 audio, the class provides a mechanism to display alternative 28 * content in browsers that cannot play the video. 29 * 30 * \if cpp 31 * Usage example: 32 * \code 33 * WAudio *a = parent->addChild(std::make_unique<WAudio>()); 34 * a->setOptions(WAudio::Controls); 35 * // Addsources may be called multiple times for different formats: 36 * // Firefox only plays ogg 37 * a->addSource("the_wt_song.ogg"); 38 * // many others play mp3 39 * a->addSource("the_wt_song.mp3", "audio/mp3"); 40 * // You may display a simple text to explain that you need html5 support... 41 * // a->setAlternativeContent(new WText("You have no HTML5 Audio!")); 42 * // ... or provide an alternative player, e.g. Flash-based 43 * auto f = std::make_unique<WFlashObject>("player.swf"); 44 * f->setFlashVariable("src", "the_wt_song.mp3"); 45 * v->setAlternativeContent(std::move(f)); 46 * \endcode 47 * \endif 48 * 49 * There are two reasons why the a browser may use the alternative 50 * content: either because the browser does not support the HTML5 51 * audio tag (alternative content is displayed even when JavaScript 52 * is not available), or because none of the specified sources contain 53 * an audio format that is understood by the browser (requires 54 * JavaScript to display the alternative content). 55 * 56 * The addSource() and setAlternativeContent() may not be called after 57 * the widget is rendered. 58 * 59 * \sa WMediaPlayer 60 */ 61 class WT_API WAudio : public WAbstractMedia 62 { 63 public: 64 /*! \brief Creates a audio widget. 65 * 66 * A freshly constructed Audio widget has no media sources, 67 * no options, and has preload mode set to PreloadAuto. 68 */ 69 WAudio(); 70 71 /*! \brief Returns the JavaScript reference to the audio object, or null. 72 * 73 * It is possible, for browser compatibility reasons, that jsRef() is 74 * not the HTML5 audio element. jsAudioRef() is guaranteed to be an 75 * expression that evaluates to the media object. This expression may 76 * yield null, if the video object is not rendered at all (e.g. on 77 * older versions of Internet Explorer). 78 */ 79 std::string jsAudioRef() const; 80 81 protected: 82 virtual DomElement *createMediaDomElement() override; 83 DomElementType domElementType() const override; 84 85 }; 86 87 } 88 89 #endif // WAUDIO_H_ 90 91