CopperSpice API  1.7.2
QSoundEffect Class Reference

The QSoundEffect class provides a way to play low latency sound effects. More...

Inheritance diagram for QSoundEffect:
QObject

Public Types

enum  Loop
 
enum  Status
 

Public Signals

void categoryChanged ()
 
void loadedChanged ()
 
void loopCountChanged ()
 
void loopsRemainingChanged ()
 
void mutedChanged ()
 
void playingChanged ()
 
void sourceChanged ()
 
void statusChanged ()
 
void volumeChanged ()
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 

Public Slots

void play ()
 
void stop ()
 
- Public Slots inherited from QObject
void deleteLater ()
 

Public Methods

 QSoundEffect (QObject *parent=nullptr)
 
 ~QSoundEffect ()
 
QString category () const
 
bool isLoaded () const
 
bool isMuted () const
 
bool isPlaying () const
 
int loopCount () const
 
int loopsRemaining () const
 
void setCategory (const QString &category)
 
void setLoopCount (int loopCount)
 
void setMuted (bool muted)
 
void setSource (const QUrl &url)
 
void setVolume (qreal volume)
 
QUrl source () const
 
Status status () const
 
qreal volume () const
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &objName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Static Public Methods

static QStringList supportedMimeTypes ()
 
- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 

Properties

 category
 
 loops
 
 loopsRemaining
 
 muted
 
 playing
 
 source
 
 status
 
 volume
 
- Properties inherited from QObject
 objectName
 

Additional Inherited Members

- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Detailed Description

This class allows you to play uncompressed audio files (typically WAV files) in a generally lower latency way, and is suitable for "feedback" type sounds in response to user actions (e.g. virtual keyboard sounds, positive or negative feedback for popup dialogs, or game sounds). If low latency is not important, consider using the QMediaPlayer class instead, since it supports a wider variety of media formats and is less resource intensive.

The following example shows how a looping, somewhat quiet sound effect can be played.

QSoundEffect effect;
effect.setSource(QUrl::fromLocalFile("engine.wav"));
effect.setLoopCount(QSoundEffect::Infinite);
effect.setVolume(0.25f);
effect.play();

Typically the sound effect should be reused, which allows all the parsing and preparation to be done ahead of time, and only triggered when necessary. This assists with lower latency audio playback. Since QSoundEffect requires slightly more resources to achieve lower latency playback, the platform may limit the number of simultaneously playing sound effects.

class MyGame {
public:
MyGame()
: m_explosion(this)
{
m_explosion.setSource(QUrl::fromLocalFile("explosion.wav"));
m_explosion.setVolume(0.25f);
// Set up click handling etc.
connect(clickSource, SIGNAL(clicked()), &m_explosion, SLOT(play()));
}
private:
QSoundEffect m_explosion;
};

Member Enumeration Documentation

ConstantValueDescription
QSoundEffect::Infinite0 Used as a parameter to setLoopCount() for infinite looping
ConstantValueDescription
QSoundEffect::Null0 source has been set or the source is null.
QSoundEffect::Loading0 SoundEffect is trying to load the source.
QSoundEffect::Ready0 Source is loaded and ready for play.
QSoundEffect::Error0 An error occurred during operation, such as failure of loading the source.

Constructor & Destructor Documentation

QSoundEffect::QSoundEffect ( QObject parent = nullptr)
explicit

Creates a QSoundEffect with the given parent.

QSoundEffect::~QSoundEffect ( )

Destroys this sound effect.

Method Documentation

QString QSoundEffect::category ( ) const

Returns the current category for this sound effect.

Some platforms can perform different audio routing for different categories, or may allow the user to set different volume levels for different categories. This setting will be ignored on platforms that do not support audio categories.

See also
setCategory()
void QSoundEffect::categoryChanged ( )
signal

The categoryChanged signal is emitted when the category property has changed.

bool QSoundEffect::isLoaded ( ) const

Returns whether the sound effect has finished loading the data for the source url.

bool QSoundEffect::isMuted ( ) const

Returns whether this sound effect is muted

bool QSoundEffect::isPlaying ( ) const

Returns true if the sound effect is currently playing, or false otherwise

void QSoundEffect::loadedChanged ( )
signal

The loadedChanged signal is emitted when the loading state has changed.

int QSoundEffect::loopCount ( ) const

Returns the total number of times that this sound effect will be played before stopping. Refer to the loopsRemaining() method for the number of loops currently remaining.

void QSoundEffect::loopCountChanged ( )
signal

The loopCountChanged signal is emitted when the initial number of loops has changed.

int QSoundEffect::loopsRemaining ( ) const

Returns the remaining number of loops.

void QSoundEffect::loopsRemainingChanged ( )
signal

The loopsRemainingChanged signal is emitted when the remaining number of loops has changed.

void QSoundEffect::mutedChanged ( )
signal

The mutedChanged signal is emitted when the mute state has changed.

void QSoundEffect::play ( )
slot

Start playback of the sound effect, looping the effect for the number of times as specified in the loops property.

void QSoundEffect::playingChanged ( )
signal

The playingChanged signal is emitted when the playing property has changed.

void QSoundEffect::setCategory ( const QString category)

Sets the category of this sound effect to category. Some platforms can perform different audio routing for different categories, or may allow the user to set different volume levels for different categories.

This setting will be ignored on platforms that do not support audio categories.

If this setting is changed while a sound effect is playing it will only take effect when the sound effect has stopped playing.

See also
category()
void QSoundEffect::setLoopCount ( int  loopCount)

Set the total number of times to play this sound effect to loopCount.

Setting the loop count to 0 or 1 means the sound effect will be played only once; pass QSoundEffect::Infinite to repeat indefinitely. The loop count can be changed while the sound effect is playing, in which case it will update the remaining loops to the new loopCount.

See also
loopsRemaining()
void QSoundEffect::setMuted ( bool  muted)

Sets whether to mute this sound effect's playback.

If muted is true, playback will be muted (silenced), and otherwise playback will occur with the currently specified volume().

void QSoundEffect::setSource ( const QUrl url)

Set the current URL to play to url.

void QSoundEffect::setVolume ( qreal  volume)

Sets the volume to play the sound effect at to volume, from 0.0 (silent) to 1.0 (maximum volume).

QUrl QSoundEffect::source ( ) const

Returns the URL of the current source to play

void QSoundEffect::sourceChanged ( )
signal

The sourceChanged signal is emitted when the source has been changed.

QSoundEffect::Status QSoundEffect::status ( ) const

Returns the current status of this sound effect.

void QSoundEffect::statusChanged ( )
signal

This signal is emitted when the status property has changed.

void QSoundEffect::stop ( )
slot

Stop current playback.

QStringList QSoundEffect::supportedMimeTypes ( )
static

Returns a list of the supported mime types for this platform.

qreal QSoundEffect::volume ( ) const

Returns the current volume of this sound effect, from 0.0 (silent) to 1.0 (maximum volume).

void QSoundEffect::volumeChanged ( )
signal

This signal is emitted when the volume has changed.

Property Documentation

QSoundEffect::category

This property contains the category of this sound effect. Some platforms can perform different audio routing for different categories, or may allow the user to set different volume levels for different categories.

This setting will be ignored on platforms that do not support audio categories.

PropertiesClass Methods
read category
write setCategory
notify categoryChanged
QSoundEffect::loops

This property holds the number of times the sound is played. A value of 0 or 1 means the sound will be played only once, set to SoundEffect.Infinite to enable infinite looping.

The value can be changed while the sound effect is playing, in which case it will update the remaining loops to the new value.

PropertiesClass Methods
read loopCount
write setLoopCount
notify loopCountChanged
QSoundEffect::loopsRemaining

This property contains the number of loops remaining before the sound effect stops by itself, or QSoundEffect::Infinite if that is what has been set in QSoundEffect::loops.

PropertiesClass Methods
read loopsRemaining
notify loopsRemainingChanged
QSoundEffect::muted

This property provides a way to control muting. A value of true will mute this effect.

PropertiesClass Methods
read isMuted
write setMuted
notify mutedChanged
QSoundEffect::playing

This property indicates whether the sound effect is playing or not.

PropertiesClass Methods
read isPlaying
notify playingChanged
QSoundEffect::source

This property holds the url for the sound to play. For the SoundEffect to attempt to load the source, the URL must exist and the application must have read permission in the specified directory.

PropertiesClass Methods
read source
write setSource
notify sourceChanged
QSoundEffect::status

This property indicates the current status of the sound effect from the QSoundEffect::Status enumeration.

PropertiesClass Methods
read status
notify statusChanged
QSoundEffect::volume

This property holds the volume of the sound effect playback, from 0.0 (silent) to 1.0 (maximum volume).

PropertiesClass Methods
read volume
write setVolume
notify volumeChanged