1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qsound.h"

    43 

    44 #ifndef QT_NO_SOUND

    45 

    46 #include "qlist.h"

    47 #include <private/qobject_p.h>

    48 #include "qsound_p.h"

    49 

    50 QT_BEGIN_NAMESPACE

    51 

    52 static QList<QAuServer*> *servers=0;

    53 

    54 QAuServer::QAuServer(QObject* parent)

    55     : QObject(parent)

    56 {

    57     if (!servers)

    58         servers = new QList<QAuServer*>;

    59     servers->prepend(this);

    60 }

    61 

    62 QAuServer::~QAuServer()

    63 {

    64     servers->removeAll(this);

    65     if (servers->count() == 0) {

    66         delete servers;

    67         servers = 0;

    68     }

    69 }

    70 

    71 void QAuServer::play(const QString& filename)

    72 {

    73     QSound s(filename);

    74     play(&s);

    75 }

    76 

    77 extern QAuServer* qt_new_audio_server();

    78 

    79 static QAuServer& server()

    80 {

    81     if (!servers) qt_new_audio_server();

    82     return *servers->first();

    83 }

    84 

    85 class QSoundPrivate : public QObjectPrivate

    86 {

    87 public:

    88     QSoundPrivate(const QString& fname)

    89         : filename(fname), bucket(0), looprem(0), looptotal(1)

    90     {

    91     }

    92 

    93     ~QSoundPrivate()

    94     {

    95         delete bucket;

    96     }

    97 

    98     QString filename;

    99     QAuBucket* bucket;

   100     int looprem;

   101     int looptotal;

   102 };

   103 

   104 /*!

   105     \class QSound

   106     \brief The QSound class provides access to the platform audio facilities.

   107 

   108     \ingroup multimedia

   109 

   110 

   111     Qt provides the most commonly required audio operation in GUI

   112     applications: asynchronously playing a sound file. This is most

   113     easily accomplished using the static play() function:

   114 

   115     \snippet doc/src/snippets/code/src_gui_kernel_qsound.cpp 0

   116 

   117     Alternatively, create a QSound object from the sound file first

   118     and then call the play() slot:

   119 

   120     \snippet doc/src/snippets/code/src_gui_kernel_qsound.cpp 1

   121 

   122     Once created a QSound object can be queried for its fileName() and

   123     total number of loops() (i.e. the number of times the sound will

   124     play). The number of repetitions can be altered using the

   125     setLoops() function. While playing the sound, the loopsRemaining()

   126     function returns the remaining number of repetitions. Use the

   127     isFinished() function to determine whether the sound has finished

   128     playing.

   129 

   130     Sounds played using a QSound object may use more memory than the

   131     static play() function, but it may also play more immediately

   132     (depending on the underlying platform audio facilities). Use the

   133     static isAvailable() function to determine whether sound

   134     facilities exist on the platform. Which facilities that are

   135     actually used varies:

   136 

   137     \table

   138     \header \o Platform \o Audio Facility

   139     \row

   140     \o Microsoft Windows

   141     \o The underlying multimedia system is used; only WAVE format sound files

   142     are supported.

   143     \row

   144     \o X11

   145     \o The \l{ftp://ftp.x.org/contrib/audio/nas/}{Network Audio System}

   146     is used if available, otherwise all operations work silently. NAS

   147     supports WAVE and AU files.

   148     \row

   149     \o Mac OS X

   150     \o NSSound is used. All formats that NSSound supports, including QuickTime formats, 

   151     are supported by Qt for Mac OS X.

   152     \row

   153     \o Qt for Embedded Linux

   154     \o A built-in mixing sound server is used, accessing \c /dev/dsp

   155     directly. Only the WAVE format is supported.

   156     \o Symbian

   157     \o CMdaAudioPlayerUtility is used. All formats that Symbian OS or devices support

   158     are supported also by Qt.

   159     \endtable

   160 

   161     Note that QSound does not support \l{resources.html}{resources}.

   162     This might be fixed in a future Qt version.

   163 */

   164 

   165 /*!

   166     Plays the sound stored in the file specified by the given \a filename.

   167 

   168     \sa stop(), loopsRemaining(), isFinished()

   169 */

   170 void QSound::play(const QString& filename)

   171 {

   172     server().play(filename);

   173 }

   174 

   175 /*!

   176     Constructs a QSound object from the file specified by the given \a

   177     filename and with the given \a parent.

   178 

   179     This may use more memory than the static play() function, but it

   180     may also play more immediately (depending on the underlying

   181     platform audio facilities).

   182 

   183     \sa play()

   184 */

   185 QSound::QSound(const QString& filename, QObject* parent)

   186     : QObject(*new QSoundPrivate(filename), parent)

   187 {

   188     server().init(this);

   189 }

   190 

   191 #ifdef QT3_SUPPORT

   192 /*!

   193     \obsolete

   194 

   195     Constructs a QSound object from the file specified by the given \a

   196     filename and with the given \a parent and \a name. Use the

   197     QSound() construcor and QObject::setObjectName() instead.

   198 

   199     \oldcode

   200         QSound *mySound = new QSound(filename, parent, name);

   201     \newcode

   202         QSounc *mySound = new QSound(filename, parent);

   203         mySound->setObjectName(name);

   204     \endcode

   205 */

   206 QSound::QSound(const QString& filename, QObject* parent, const char* name)

   207     : QObject(*new QSoundPrivate(filename), parent)

   208 {

   209     setObjectName(QString::fromAscii(name));

   210     server().init(this);

   211 }

   212 #endif

   213 

   214 /*!

   215     Destroys this sound object. If the sound is not finished playing,

   216     the stop() function is called before the sound object is

   217     destructed.

   218 

   219     \sa stop(), isFinished()

   220 */

   221 QSound::~QSound()

   222 {

   223     if (!isFinished())

   224         stop();

   225 }

   226 

   227 /*!

   228     Returns true if the sound has finished playing; otherwise returns false.

   229 

   230     \warning On Windows this function always returns true for unlooped sounds.

   231 */

   232 bool QSound::isFinished() const

   233 {

   234     Q_D(const QSound);

   235     return d->looprem == 0;

   236 }

   237 

   238 /*!

   239     \overload

   240 

   241     Starts playing the sound specified by this QSound object.

   242 

   243     The function returns immediately.  Depending on the platform audio

   244     facilities, other sounds may stop or be mixed with the new

   245     sound. The sound can be played again at any time, possibly mixing

   246     or replacing previous plays of the sound.

   247 

   248     \sa fileName()

   249 */

   250 void QSound::play()

   251 {

   252     Q_D(QSound);

   253     d->looprem = d->looptotal;

   254     server().play(this);

   255 }

   256 

   257 /*!

   258     Returns the number of times the sound will play.

   259 

   260     \sa loopsRemaining(), setLoops()

   261 */

   262 int QSound::loops() const

   263 {

   264     Q_D(const QSound);

   265     return d->looptotal;

   266 }

   267 

   268 /*!

   269     Returns the remaining number of times the sound will loop (this

   270     value decreases each time the sound is played).

   271 

   272     \sa loops(), isFinished()

   273 */

   274 int QSound::loopsRemaining() const

   275 {

   276     Q_D(const QSound);

   277     return d->looprem;

   278 }

   279 

   280 /*!

   281     \fn void QSound::setLoops(int number)

   282 

   283     Sets the sound to repeat the given \a number of times when it is

   284     played.

   285 

   286     Note that passing the value -1 will cause the sound to loop

   287     indefinitely.

   288 

   289     \sa loops()

   290 */

   291 void QSound::setLoops(int n)

   292 {

   293     Q_D(QSound);

   294     d->looptotal = n;

   295 }

   296 

   297 /*!

   298     Returns the filename associated with this QSound object.

   299 

   300     \sa QSound()

   301 */

   302 QString QSound::fileName() const

   303 {

   304     Q_D(const QSound);

   305     return d->filename;

   306 }

   307 

   308 /*!

   309     Stops the sound playing.

   310 

   311     Note that on Windows the current loop will finish if a sound is

   312     played in a loop.

   313 

   314     \sa play()

   315 */

   316 void QSound::stop()

   317 {

   318     Q_D(QSound);

   319     server().stop(this);

   320     d->looprem = 0;

   321 }

   322 

   323 

   324 /*!

   325     Returns true if sound facilities exist on the platform; otherwise

   326     returns false.

   327 

   328     If no sound is available, all QSound operations work silently and

   329     quickly. An application may choose either to notify the user if

   330     sound is crucial to the application or to operate silently without

   331     bothering the user.

   332 

   333     Note: On Windows this always returns true because some sound card

   334     drivers do not implement a way to find out whether it is available

   335     or not.

   336 */

   337 bool QSound::isAvailable()

   338 {

   339     return server().okay();

   340 }

   341 

   342 /*!

   343     Sets the internal bucket record of sound \a s to \a b, deleting

   344     any previous setting.

   345 */

   346 void QAuServer::setBucket(QSound* s, QAuBucket* b)

   347 {

   348     delete s->d_func()->bucket;

   349     s->d_func()->bucket = b;

   350 }

   351 

   352 /*!

   353     Returns the internal bucket record of sound \a s.

   354 */

   355 QAuBucket* QAuServer::bucket(QSound* s)

   356 {

   357     return s->d_func()->bucket;

   358 }

   359 

   360 /*!

   361     Decrements the QSound::loopRemaining() value for sound \a s,

   362     returning the result.

   363 */

   364 int QAuServer::decLoop(QSound* s)

   365 {

   366     if (s->d_func()->looprem > 0)

   367         --s->d_func()->looprem;

   368     return s->d_func()->looprem;

   369 }

   370 

   371 /*!

   372     Initializes the sound. The default implementation does nothing.

   373 */

   374 void QAuServer::init(QSound*)

   375 {

   376 }

   377 

   378 QAuBucket::~QAuBucket()

   379 {

   380 }

   381 /*!

   382     \fn bool QSound::available()

   383 

   384     Use the isAvailable() function instead.

   385 */

   386 

   387 QT_END_NAMESPACE

   388 

   389 #endif // QT_NO_SOUND