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

     2 **

     3 ** Copyright (C) 2010 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     \row

   157     \o Symbian

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

   159     are supported also by Qt.

   160     \endtable

   161 

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

   163     This might be fixed in a future Qt version.

   164 */

   165 

   166 /*!

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

   168 

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

   170 */

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

   172 {

   173     server().play(filename);

   174 }

   175 

   176 /*!

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

   178     filename and with the given \a parent.

   179 

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

   181     may also play more immediately (depending on the underlying

   182     platform audio facilities).

   183 

   184     \sa play()

   185 */

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

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

   188 {

   189     server().init(this);

   190 }

   191 

   192 #ifdef QT3_SUPPORT

   193 /*!

   194     \obsolete

   195 

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

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

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

   199 

   200     \oldcode

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

   202     \newcode

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

   204         mySound->setObjectName(name);

   205     \endcode

   206 */

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

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

   209 {

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

   211     server().init(this);

   212 }

   213 #endif

   214 

   215 /*!

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

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

   218     destructed.

   219 

   220     \sa stop(), isFinished()

   221 */

   222 QSound::~QSound()

   223 {

   224     if (!isFinished())

   225         stop();

   226 }

   227 

   228 /*!

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

   230 

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

   232 */

   233 bool QSound::isFinished() const

   234 {

   235     Q_D(const QSound);

   236     return d->looprem == 0;

   237 }

   238 

   239 /*!

   240     \overload

   241 

   242     Starts playing the sound specified by this QSound object.

   243 

   244     The function returns immediately.  Depending on the platform audio

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

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

   247     or replacing previous plays of the sound.

   248 

   249     \sa fileName()

   250 */

   251 void QSound::play()

   252 {

   253     Q_D(QSound);

   254     d->looprem = d->looptotal;

   255     server().play(this);

   256 }

   257 

   258 /*!

   259     Returns the number of times the sound will play.

   260 

   261     \sa loopsRemaining(), setLoops()

   262 */

   263 int QSound::loops() const

   264 {

   265     Q_D(const QSound);

   266     return d->looptotal;

   267 }

   268 

   269 /*!

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

   271     value decreases each time the sound is played).

   272 

   273     \sa loops(), isFinished()

   274 */

   275 int QSound::loopsRemaining() const

   276 {

   277     Q_D(const QSound);

   278     return d->looprem;

   279 }

   280 

   281 /*!

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

   283 

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

   285     played.

   286 

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

   288     indefinitely.

   289 

   290     \sa loops()

   291 */

   292 void QSound::setLoops(int n)

   293 {

   294     Q_D(QSound);

   295     d->looptotal = n;

   296 }

   297 

   298 /*!

   299     Returns the filename associated with this QSound object.

   300 

   301     \sa QSound()

   302 */

   303 QString QSound::fileName() const

   304 {

   305     Q_D(const QSound);

   306     return d->filename;

   307 }

   308 

   309 /*!

   310     Stops the sound playing.

   311 

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

   313     played in a loop.

   314 

   315     \sa play()

   316 */

   317 void QSound::stop()

   318 {

   319     Q_D(QSound);

   320     server().stop(this);

   321     d->looprem = 0;

   322 }

   323 

   324 

   325 /*!

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

   327     returns false.

   328 

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

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

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

   332     bothering the user.

   333 

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

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

   336     or not.

   337 */

   338 bool QSound::isAvailable()

   339 {

   340     return server().okay();

   341 }

   342 

   343 /*!

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

   345     any previous setting.

   346 */

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

   348 {

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

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

   351 }

   352 

   353 /*!

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

   355 */

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

   357 {

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

   359 }

   360 

   361 /*!

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

   363     returning the result.

   364 */

   365 int QAuServer::decLoop(QSound* s)

   366 {

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

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

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

   370 }

   371 

   372 /*!

   373     Initializes the sound. The default implementation does nothing.

   374 */

   375 void QAuServer::init(QSound*)

   376 {

   377 }

   378 

   379 QAuBucket::~QAuBucket()

   380 {

   381 }

   382 /*!

   383     \fn bool QSound::available()

   384 

   385     Use the isAvailable() function instead.

   386 */

   387 

   388 QT_END_NAMESPACE

   389 

   390 #endif // QT_NO_SOUND