1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtGui module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qsound.h"
41#include "qsoundeffect.h"
42#include "qcoreapplication.h"
43
44
45/*!
46 \class QSound
47 \brief The QSound class provides a method to play .wav sound files.
48 \inmodule QtMultimedia
49 \ingroup multimedia
50 \ingroup multimedia_audio
51
52 Qt provides the most commonly required audio operation in GUI
53 applications: asynchronously playing a sound file. This is most
54 easily accomplished using the static play() function:
55
56 \snippet multimedia-snippets/qsound.cpp 0
57
58 Alternatively, create a QSound object from the sound file first
59 and then call the play() slot:
60
61 \snippet multimedia-snippets/qsound.cpp 1
62
63 In both cases, the file may either be a local file or in a
64 \l{The Qt Resource System}{resource}.
65
66 Once created a QSound object can be queried for its fileName() and
67 total number of loops() (i.e. the number of times the sound will
68 play). The number of repetitions can be altered using the
69 setLoops() function. While playing the sound, the loopsRemaining()
70 function returns the remaining number of repetitions. Use the
71 isFinished() function to determine whether the sound has finished
72 playing.
73
74 Sounds played using a QSound object may use more memory than the
75 static play() function, but it may also play more immediately
76 (depending on the underlying platform audio facilities).
77
78 If you require finer control over playing sounds, consider the
79 \l QSoundEffect or \l QAudioOutput classes.
80
81 \sa QSoundEffect
82*/
83
84/*!
85 \enum QSound::Loop
86
87 \value Infinite Can be used as a parameter to \l setLoops() to loop infinitely.
88*/
89
90
91/*!
92 Plays the sound stored in the file specified by the given \a filename.
93
94 The file can either be a local file or in a \l{The Qt Resource System}{resource}.
95
96 \sa stop(), loopsRemaining(), isFinished()
97*/
98void QSound::play(const QString &filename)
99{
100 // Object destruction is generally handled via deleteOnComplete
101 // Unexpected cases will be handled via parenting of QSound objects to qApp
102 QSound *sound = new QSound(filename, qApp);
103 sound->connect(sender: sound->m_soundEffect, signal: &QSoundEffect::playingChanged,
104 receiver: sound, slot: &QSound::deleteOnComplete);
105 sound->play();
106}
107
108/*!
109 Constructs a QSound object from the file specified by the given \a
110 filename and with the given \a parent.
111
112 The file can either be a local file or in a \l{The Qt Resource System}{resource}.
113
114 \sa play()
115*/
116QSound::QSound(const QString &filename, QObject *parent)
117 : QObject(parent)
118{
119 m_soundEffect = new QSoundEffect(this);
120 const bool isQrc = filename.startsWith(s: QLatin1String("qrc:"), cs: Qt::CaseInsensitive);
121 const QUrl url = isQrc ? QUrl(filename) : QUrl::fromLocalFile(localfile: filename);
122 m_soundEffect->setSource(url);
123}
124
125/*!
126 Destroys this sound object. If the sound is not finished playing,
127 the stop() function is called before the sound object is
128 destroyed.
129
130 \sa stop(), isFinished()
131*/
132QSound::~QSound()
133{
134 if (!isFinished())
135 stop();
136}
137
138/*!
139 Returns true if the sound has finished playing; otherwise returns false.
140*/
141bool QSound::isFinished() const
142{
143 return !m_soundEffect->isPlaying();
144}
145
146/*!
147 \overload
148
149 Starts playing the sound specified by this QSound object.
150
151 The function returns immediately. Depending on the platform audio
152 facilities, other sounds may stop or be mixed with the new
153 sound. The sound can be played again at any time, possibly mixing
154 or replacing previous plays of the sound.
155
156 \sa fileName()
157*/
158void QSound::play()
159{
160 m_soundEffect->play();
161}
162
163/*!
164 Returns the number of times the sound will play.
165 Return value of \c QSound::Infinite indicates infinite number of loops
166
167 \sa loopsRemaining(), setLoops()
168*/
169int QSound::loops() const
170{
171 // retain old API value for infinite loops
172 int loopCount = m_soundEffect->loopCount();
173 if (loopCount == QSoundEffect::Infinite)
174 loopCount = Infinite;
175
176 return loopCount;
177}
178
179/*!
180 Returns the remaining number of times the sound will loop (for all
181 positive values this value decreases each time the sound is played).
182 Return value of \c QSound::Infinite indicates infinite number of loops
183
184 \sa loops(), isFinished()
185*/
186int QSound::loopsRemaining() const
187{
188 // retain old API value for infinite loops
189 int loopsRemaining = m_soundEffect->loopsRemaining();
190 if (loopsRemaining == QSoundEffect::Infinite)
191 loopsRemaining = Infinite;
192
193 return loopsRemaining;
194}
195
196/*!
197 \fn void QSound::setLoops(int number)
198
199 Sets the sound to repeat the given \a number of times when it is
200 played.
201
202 Note that passing the value \c QSound::Infinite will cause the sound to loop
203 indefinitely.
204
205 \sa loops()
206*/
207void QSound::setLoops(int n)
208{
209 if (n == Infinite)
210 n = QSoundEffect::Infinite;
211
212 m_soundEffect->setLoopCount(n);
213}
214
215/*!
216 Returns the filename associated with this QSound object.
217
218 \sa QSound()
219*/
220QString QSound::fileName() const
221{
222 return m_soundEffect->source().toLocalFile();
223}
224
225/*!
226 Stops the sound playing.
227
228 \sa play()
229*/
230void QSound::stop()
231{
232 m_soundEffect->stop();
233}
234
235/*!
236 \internal
237*/
238void QSound::deleteOnComplete()
239{
240 if (!m_soundEffect->isPlaying())
241 deleteLater();
242}
243
244#include "moc_qsound.cpp"
245

source code of qtmultimedia/src/multimedia/audio/qsound.cpp