// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2009 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WSOUND_H_
#define WSOUND_H_

#include <Wt/WObject>

namespace Wt {
class SoundManager;

/*! \class WSound Wt/WSound Wt/WSound
 * \brief A value class to play a sound effect.
 *
 * This class provides a way to play an MP3 sound asynchonously (if
 * the browser supports this). It is intended as a simple way to play
 * event sounds (not quite for a media center).
 *
 * This class uses a WMediaPlayer to play the sound (using HTML
 * &lt;audio&gt; or a flash player).
 *
 * \if cpp
 * Usage example:
 * \code
 * WSound *s = new WSound("djing.mp3", parent);
 * s->setLoops(3);
 * s->play();
 * playButton->clicked().connect(s, &WSound::play);
 * stopButton->clicked().connect(s, &WSound::stop);
 * \endcode
 * \endif
 */
class WT_API WSound : public WObject
{
public:
  /*! \brief Constructs a sound object that will play the given URL.
   *
   * \note As of %Wt 3.1.10, the \p url must specify an MP3 file.
   */
  WSound(const std::string &url, WObject *parent = 0);

  /*! \brief Destructor.
   *
   * Deleting a sound also stops it (if it was playing). 
   */
  ~WSound();

  /*! \brief Returns the sound url.
   *
   * \sa WSound()
   */
  const std::string &url() const;

  /*! \brief Sets the amount of times the sound has to be repeated.
   *
   * A call to play() will play the sound \p number of times.
   * The default value is 1 (no repeats).
   */
  void setLoops(int number);

  /*! \brief Returns the configured number of repeats.
   *
   * \a setLoops()
   */
  int loops() const;

  /*! \brief Start asynchronous playback of the sound.
   *
   * This method returns immediately. It will cause the sound to be
   * played for the configured amount of loops().
   *
   * The behavior of play() when a sound is already playing is
   * undefind: it may be intermixed, sequentially queued, or a current
   * playing sound may be stopped. It is recommended to call stop()
   * before play() if you want to avoid mixing multiple instances of a
   * single WSound object.
   */
  void play();

  /*! \brief Stops playback of the sound.
   *
   * This method returns immediately. It causes the current playback (if any)
   * of the sound to be stopped.
   */
  void stop();

private:
  std::string   url_;
  int           loops_;
  SoundManager *sm_;
};

}

#endif // WSOUND_H_

