diff options
Diffstat (limited to 'doc/src/phonon-api.qdoc')
| -rw-r--r-- | doc/src/phonon-api.qdoc | 4993 |
1 files changed, 4993 insertions, 0 deletions
diff --git a/doc/src/phonon-api.qdoc b/doc/src/phonon-api.qdoc new file mode 100644 index 0000000..01f7c8a --- /dev/null +++ b/doc/src/phonon-api.qdoc @@ -0,0 +1,4993 @@ +/* + This file is part of the KDE project + Copyright (C) 2005-2007 Matthias Kretz <kretz@kde.org> + Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). + Contact: Qt Software Information (qt-info@nokia.com) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + + +/*! + \enum Phonon::DiscType + Enum to identify the media discs supported by MediaObject. + + \value NoDisc + No disc was selected. This is only useful as a return value from + MediaSource::diskType(). + \value Cd Identifies Audio CDs. + \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs). + \value Vcd Identifies Video CDs. + + \sa MediaSource, MediaObject +*/ + +/*! + \enum Phonon::MetaData + + Provided as keys for Phonon::MediaObject::metaData(). The enum + values matches strings defined in the Ogg Vorbis specification + + \value ArtistMetaData + \value AlbumMetaData + \value TitleMetaData + \value DateMetaData + \value GenreMetaData + \value TracknumberMetaData + \value DescriptionMetaData + \value MusicBrainzDiscIdMetaData +*/ + +/*! + \enum Phonon::State + \since 4.4 + + The state enum describes the different states a media object can + take. Several functions of \l{Phonon::}{MediaObject} are + asynchronous, so even if a you have requested a state change + through a function call, e.g., through + \l{Phonon::MediaObject::}{play()}, you cannot be sure that the + change has taken place before you receive the + \l{Phonon::MediaObject::}{stateChanged()} signal. + + A media object can at any time change into any state, regardless + of the state it previously had. \omit In the + \l{Phonon::}{MediaObject} class description explains the typical + state changes in the life of a media object. \endomit + + \value LoadingState + After construction it might take a while before the media object + is ready to \l{Phonon::MediaObject::}{play()}. This state is + commonly used by backends to initialize the \l{Phonon + Overview}{media graph} and loading the source. When + the object leaves the loading state, it will enter the + StoppedState unless an error occurred or another state is + requested through a function call, e.g., + \l{Phonon::}{MediaObject::play()}. + + \value StoppedState + In the stopped state, the media object is ready to play its + current media source. The current + \l{MediaObject::seek()}{position} in the media stream is then 0. + + \value PlayingState + The media object is playing back its media source. + + \value BufferingState + The Player is waiting for data to be able to start or continue + playing. This state is commonly used to wait for media data over a + network connection. + + \value PausedState + The media player has currently paused its playback, i.e., it + stops playing but keeps the current playback position in the + stream. + + \value ErrorState + When a media object enters the error state a problem with the + playback has occurred. The possible errors are grouped into + two categories by Phonon::ErrorType, and the type can be + queried through \l{Phonon::MediaObject::}{errorType()}. A + \l{Phonon::}{FatalError} implies that the playback + cannot continue, but one can still try with a new media + source. With a \l{Phonon::}{NormalError} it might + be possible to continue playback, and a media object may + therefore change state from the ErrorState. + + \sa MediaObject +*/ + +/*! + \enum Phonon::Category + + Sets the category your program should be listed in in the mixer. + + \value NoCategory + Will make use of the default device. + \value NotificationCategory + If the sounds produced are notifications (ping, beep and such) you + should use this category. + \value MusicCategory + If your application is a music player (like a jukebox or media player + playing an audio file). + \value VideoCategory + If the sound is the audio channel of a video. + \value CommunicationCategory + If your applications produces sounds from communication with somebody + else (VoIP, voice chat). + \value GameCategory + Sound produced by a computer game should go into this category. + \value AccessibilityCategory + Sounds produced for accessibility (e.g., Text-To-Speech) + \omitvalue LastCategory + Holds the largest value of categories. + \omitvalue AccessibilityCategory + + A Jukebox will set this to Music, a VoIP program to Communication, a + DVD player to video, and so on. + + \note These categories can also become useful for an application that + controls the volumes automatically, like turning down the music when a call + comes in, or turning down the notifications when the media player knows + it's playing classical music. +*/ + +/*! + \enum Phonon::ErrorType + + This enum describes the severity when an error has occurred during + playback. + + After a media object has entered the \l{Phonon::}{ErrorState}, one + can query the type of error from + \l{Phonon::}{MediaObject::errorType()}. Note that you should query + the error when receiving the + \l{Phonon::}{MediaObject::stateChanged()} signal, because the + error type will be lost if the media object leaves the error + state. + + \value NoError No error. MediaObject::errorType() returns this if + MediaObject::state() != Phonon::ErrorState. + + \value NormalError An error has occurred with the playback of the current + source. It might be possible to continue playback, for instance, if only the + audio stream in a video cannot be played back. The media object will then + leave the error state again. + + \value FatalError. Something important does not work. Your program cannot continue + the playback of the current source, but it might be possible to try another. + + \sa MediaObject::errorType() +*/ + +/*! + \fn QString Phonon::categoryToString(Category c) + + Returns a (translated) string to show to the user identifying the given + Category (\a c). +*/ + +/*! + \enum Phonon::ObjectDescriptionType + \relates Phonon::ObjectDescription + + This enum defines the type of information that is contained in a + \l{Phonon::}{ObjectDescription} object. + + \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}). + This can be soundcards (with different drivers), + sound servers, or other virtual outputs like playback on a different + computer on the network. + + \value EffectType An audio effect (\l{Phonon::}{EffectDescription}). + \omitvalue SubtitleType + \omitvalue AudioCaptureDeviceType + \omitvalue AudioChannelType +*/ + +/*! + \typedef Phonon::AudioOutputDevice + \relates Phonon::ObjectDescription + + This typedef of \l{Phonon::}{ObjectDescription} describes an audio output + device, such as soundcards (with different drivers), sound servers, or other + virtual outputs like playback on a different computer on the network. + + \omit + For Hardware devices the backend should use libkaudiodevicelist + (AudioDevice and AudioDeviceEnumerator) which will list removable + devices even when they are unplugged and provide a unique identifier + that can make backends use the same identifiers. + \endomit + + A list of available devices is given by the backend with + Backendcapabilities::availableAudioOutputDevices() + + \snippet doc/src/snippets/phononobjectdescription.cpp 1 + +*/ + +/*! + \fn Phonon::phononVersion() + \inmodule Phonon + \since 4.5 + + Returns the Phonon version. +*/ + +/*! + \class Phonon::ObjectDescription + \inmodule Phonon + \inheaderfile Phonon/ObjectDescription + \since 4.4 + \brief The ObjectDescription class provides information about Phonon objects. + + Phonon currently uses this class to describe audio effects and + audio output devices - using the typedefs AudioOutputDevice and + EffectDescription. The type of an ObjectDescription is also + described through the \l{Phonon::}{ObjectDescriptionType} enum. + Objects of the same \l{Phonon::ObjectDescriptionType}{type} are + uniquely identified by an index(). + + The class gives a description() and a name() of the object, both + of which are strings appropriate for end users of a Phonon + application. You can also check whether the device or effect + described is \l{isValid()}{valid}. This does not guarantee that + the device or effect functions as expected, but that the + ObjectDescription describes an existing device or effect. + + Audio output devices and effect descriptions are used to select + the audio output device to be used for playback and to create + effects; we show examples of this in the snippet below. The + available descriptions can be fetched with + \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} + and \l{Phonon::BackendCapabilities::}{availableAudioEffects()} + static functions in the Phonon::BackendCapabilities namespace + + \snippet doc/src/snippets/phononobjectdescription.cpp 0 + + Other types of ObjectDescriptions might be possible in the future, + e.g., descriptions of audio capture devices, such as microphones. + + \omit Not implemented yet. + Need a new paragraph on that some descriptions 'belong + together', such as chained audio effects. + + Some parts give the end user choices, e.g. what source to capture + audio from. These choices are described by the name and + description methods of this class and identified with the id + method. Subclasses then define additional information like which + audio and video choices belong together. \endomit + + \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module} +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription() + \brief constructs a new object description. + \internal +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash<QByteArray, QVariant> & properties) + \internal +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd) + \internal +*/ + +/*! + \fn static inline ObjectDescription<T> Phonon::ObjectDescription::fromIndex(int index) + \internal + + \omit Currently indices are not unique for all ObjectDescription types, making + the behavior of this function undefined. \endomit + + Returns a new description object that describes the + device/effect/codec/... with the given \a index. +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const + + Returns \c true if this ObjectDescription describes the same + object as \a otherDescription; otherwise, returns \c false. +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const + Returns \c false if this ObjectDescription describes the same + as \a otherDescription; otherwise, returns \c true. +*/ + +/*! + \fn inline QString Phonon::ObjectDescription::name() const + + Returns a string appropriate for a user to select between + object descriptions, e.g., from a QComboBox. + + \sa description() +*/ + +/*! + \fn inline QString Phonon::ObjectDescription::description() const + + Returns a more extensive description than the name() function. + + For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this + text should make clear which sound source is described; this is + sometimes hard to describe or understand from just the name. + + The text is appropriate to present to an end user in for example + tool tips of items, with the name()'s as text, in a QComboBox. + +*/ + +/*! + \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const + + Returns the property named \a name. A property can be used for + extended information, such as the manufacturer of a sound card. The + information will usually be given as text. + + If the property is not set an invalid QVariant is returned. + + Qt's backends do not use properties at the time of this writing. + + \sa propertyNames() +*/ + +/*! + \fn inline QList<QByteArray> Phonon::ObjectDescription::propertyNames() const + + Properties can be used for extended information about a + ObjectDescription, e.g., a manufacturer of a sound card. The + information will usually be given text. + + This function returns all names that return valid data when + property() is called. + + Currently, Qt backends do not use properties for their object + descriptions. + + \sa property() +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::isValid() const + + Returns true if the device or effect described exists. + + An ObjectDescription that is invalid, will also have an + index() of -1. + + \sa index() +*/ + +/*! + \fn inline int Phonon::ObjectDescription::index() const + + Returns a unique identifier for this ObjectDescription. Used + internally to distinguish between the descriptions. + + Notice that the identifiers are only unique to the type of + description, e.g., \l{Phonon::}{AudioOutputDevice} or + \l{Phonon::}{EffectDescription}. +*/ + +/*! + \class Phonon::ObjectDescriptionPrivate + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::StreamInterface + \inmodule Phonon + \since 4.4 + \brief Backend interface to handle media streams (AbstractMediaStream). + \internal +*/ + +/*! + \fn virtual Phonon::StreamInterface::~StreamInterface() +*/ + +/*! + \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::endOfData() = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0 + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource) + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::needData() + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::enoughData() + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::seekStream(qint64) + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::reset() + \internal +*/ + +/*! + \fn Phonon::StreamInterface::StreamInterface() + \internal + \omit + For subclasses. + \endomit +*/ + +/*! + \class StreamInterfacePrivate + \inmodule Phonon + \internal +*/ + +/*! + \class Phonon::AbstractVideoOutput + \inmodule Phonon + \internal + \since 4.4 + \brief The AbstractVideoOutput class is the common base class for all video output classes. + + \sa VideoWidget +*/ + +/*! + \namespace Phonon::Experimental + \internal +*/ + +/*! + \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d) + \internal + + Constructor that is called from derived classes. + + \param parent Standard QObject parent. +*/ + +/*! + \class Phonon::AbstractVideoOutputPrivate + \inmodule Phonon + \internal + \since 4.4 +*/ + +/*! + \class Phonon::VolumeFaderEffect + \inmodule Phonon + \internal + \since 4.4 + + This effect differs from gradually changing the output volume in that + a dedicated effect can change the volume in the smallest possible + steps while every other volume control will make more or less + noticeable steps. + + \sa AudioOutput::volume() +*/ + +/*! + \property Phonon::VolumeFaderEffect::volume + + This is the current volume of the output as voltage factor. + Setting this property changes the volume immediately. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% + + \sa volumeDecibel +*/ + +/*! + \property Phonon::VolumeFaderEffect::volumeDecibel + + This is the current volume of the output in decibel. + Setting this property changes the volume immediately. + + 0 dB means no change in volume, -6dB means an attenuation of the + voltage to 50% and an attenuation of the power to 25%, -inf dB means + silence. + + \sa volume +*/ + +/*! + \property Phonon::VolumeFaderEffect::fadeCurve + + This property holds the fade curve to be used for the fadeIn(), fadeOut() + and fadeTo() slots. + + Defaults to Fade3Decibel. + + \sa FadeCurve +*/ + +/*! + \enum Phonon::VolumeFaderEffect::FadeCurve + Determines the curve of the volume change. + + \value Fade3Decibel Crossfade curve/fast fade out. + This is the default fade curve. + \value Fade6Decibel Linear fade out. + \value Fade9Decibel Slow fade out. + \value Fade12Decibel A more extreme version of the -9dB fade. + + \bold{Notes:} + + \c Fade3Decibel is often the best fade for a crossfade, as after half + of the time the volume reached -3dB. This means that half the + possible power (which is proportional to the square of the + voltage) is reached. Summed, the maximum power of two audio + signals fading with a -3dB curve will always be equal. + + For fading in or out the -3dB curve is too abrupt in the end. + + With a -6dB fade curve, a volume of -6dB is reached after half of + the fading time. -6dB is equal to half of the voltage meaning + that the voltage multiplier changes linearly from the start + of the fade to the end. + + With the \c Fade9Decibel fade, a volume of -9dB is reached after + half of the fade time, so the fade is fast in the beginning and + slow at the end. This is a good fade for ending music. +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime) + + Tells the Fader to change the volume from the current volume to 100% + in \a fadeTime milliseconds. + + Short for \c fadeTo(1.0, fadeTime). + + \param fadeTime the fade duration in milliseconds + + \sa fadeTo(), volume +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime) + + Tells the Fader to change the volume from the current volume to 0% + in \a fadeTime milliseconds. + Short for \c fadeTo(0.0, fadeTime). + + \param fadeTime the fade duration in milliseconds + + \sa fadeTo +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime) + + Tells the Fader to change the volume from the current value to + \a volume in \a fadeTime milliseconds. + + \sa fadeIn(), fadeOut() +*/ + +/*! + \class Phonon::VolumeFaderEffectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::VolumeFaderInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface() + \internal +*/ + +/*! + \fn virtual float Phonon::VolumeFaderInterface::volume() const + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::setVolume(float) + \internal +*/ + +/*! + \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve) + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int) + \internal +*/ + +/*! + \class Phonon::AbstractMediaStream + \inmodule Phonon + \internal + \since 4.4 + \brief The AbstractMediaStream class is the base class for custom media data streams. + \inheaderfile Phonon/AbstractMediaStream + + This class is subclassed to provide custom data streams for + \l{Phonon::}{MediaSource}s. + + The \l{Phonon::}{MediaSource} knows how to handle the most common + media sources, such as files and CD. If you need to fetch + multimedia from other sources, you can reimplement this class, + which can be used by a \l{Phonon::}{MediaSource}. + + When a backend needs more data from the stream, needData() will be + called. You must then use writeData() to write the data to the + backend. You can either write one time and wait for a new + needData() call, or continue to write data until you receive an + enoughData() call. When the stream is at its end, call endOfData() + instead of writeData(). + + Before the custom stream is passed to a \l{Phonon::}{MediaSource}, + setStreamSize() needs to be called, and also setStreamSeekable() + (if the stream is seekable). A good place to do this work is in + the constructor. A seekable stream must also reimplement + seekStream(). + + We show two examples. The first writes data repeatedly until it + receives the enoughData() call, while the second only writes once + and waits for a new needData() call. + + Example where data is written repeatedly. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 0 + + Example where data is written once: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 1 + + \sa Phonon::MediaSource, Phonon::MediaObject + +*/ + +/*! + \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0) + \internal + + Constructs an AbstractMediaStream object with the given \a parent. + +*/ + +/*! + \fn qint64 Phonon::AbstractMediaStream::streamSize() const + + Returns the stream size that was set with setStreamSize(). + + A negative value means that the length of the stream cannot be known. + + Defaults to 0. + + \sa setStreamSize() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size) + + Sets the \a size of the stream in number of bytes. + + A negative value means that the length of the stream cannot be known. + + Defaults to 0. + + This function has to be called. A backend will not call needData() + until the stream size is set. + + \sa streamSize() + +*/ + +/*! + \fn bool Phonon::AbstractMediaStream::streamSeekable() const + + Returns whether your data stream is set as seekable. + + Defaults to \c false. + + \sa setStreamSeekable() + +*/ + +/*! + \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s) + + Sets whether your data stream is seekable. \a s should be true if + the stream is seekable; otherwise false. + + Defaults to \c false. + + If you set this to \c true you have to implement the seekStream() + function. + + \sa streamSeekable() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data) + + Sends the media \a data to the backend for decoding. + + Use this function to send data to the backend after needData() has + been called. + + If your stream is a push stream, data should be written until the + enoughData() function is called. For a pull stream, write data + once before the call to needData() function returns. + + If the data is depleted, call endOfData() instead of writeData(). + + \warning Don't call this function before the first needData() is emitted. + + \sa needData(), endOfData() + +*/ + +/*! + \fn void Phonon::AbstractMediaStream::endOfData() + + Tells the backend that the media data stream is at its end. + + \warning Don't call this function before the first needData() is emitted. + + \sa writeData(), needData() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString) + + If an I/O error occurs you should call this function to make + MediaObject go into ErrorState. \c errorType classifies the error, + while \a errorString is a textual description of the error suitable + for users of Phonon applications. + + \sa MediaObject::errorType(), MediaObject::errorString() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::reset() = 0 + + Reimplement this function to reset the stream. Subsequent calls to writeData should start + from the first position of the data unless a seek is requested. + + The function is necessary for the case where a non-seekable MediaStream is + played more than once. For a seekable stream the implementation can simply call + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 2 + + \sa writeData(), needData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::needData() = 0 + + Reimplement this function to be notified when the backend needs data. + + When this function is called you should write data to the backend + (See writeData()). + + \sa writeData(), endOfData(), enoughData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::enoughData() + + If your stream is a push stream, reimplement this function to be + notified when the backend has enough data and your stream object + may take a break. + + This method is important for pushing data to the backend in order + to not fill the backend buffer unnecessarily. + + \sa needData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset) + + Reimplement this function if your stream is seekable. + + When this function is called the next call to writeData has to be at the + requested \a offset. + + \warning Do not call the parent implementation. + + \sa setStreamSeekable(), streamSeekable(), needData() +*/ + +/*! + \class Phonon::BackendInterface + \inmodule Phonon + \since 4.4 + \brief Main Backend class interface + \internal + + This interface defines the main factory of the backend. The createObject() function creates all the + objects needed by the frontend. + + The objectDescriptionIndexes and objectDescriptionProperties functions return information about + available devices, effects and codecs. + + An implementation could look like this: + \snippet snippets/phonon/samplebackend/main.cpp snippet + +*/ + +/*! + \fn virtual Phonon::BackendInterface::~BackendInterface() + \internal + + Silence gcc's warning. +*/ + +/*! + \enum Phonon::BackendInterface::Class + \internal + + Classes that the createObject() function has to handle. + + \value MediaObjectClass Request to return a \c MediaObject object. + \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect + object. + \value AudioOutputClass Request to return an \c AudioOutput object. + \value AudioDataOutputClass Request to return an \c AudioDataOutput object. + \value VisualizationClass Request to return a \c Visualization object. + \value VideoDataOutputClass Request to return a \c VideoDataOutput object. + \value EffectClass Request to return a \c Effect object. + Takes an additional int that specifies the effect ID. + \value VideoWidgetClass Request to return a \c VideoWidget object. +*/ + +/*! + \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList<QVariant> &args = QList<QVariant>()) = 0 + \internal + + Returns a new instance of the requested class. + + \param c The requested class. + \param parent The parent object. + \param args Additional arguments (documented in Class). +*/ + + +/*! + \fn virtual QList<int> Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0 + \internal + + Returns the unique identifiers for the devices/effects/codecs of the given \a type. + + \param type see ObjectDescriptionType +*/ + +/*! + \fn virtual QHash<QByteArray, QVariant> Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0 + \internal + + Given a unique identifier that was returned from objectDescriptionIndexes this function + returns a hash mapping property names to values. + + The property "name" must always be present. All other properties are optional. + + \table + \header \o Property \o Description + \row \o name \o The name of the device/effect/codec/... + \row \o description \o A text explaining what this device/effect/codec/... is/can do + \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this + device/effect/codec/... + \row \o available \o A bool telling whether the device is present or unplugged. + \endtable + + \param type see ObjectDescriptionType + \param index The unique identifier that is returned from objectDescriptionIndexes +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet<QObject *>) = 0; + \internal + + When this function is called the nodes given in the parameter list should + not lose any signal data when connections are changed. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0 + \internal + + Defines a signal connection between the two given nodes. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0 + \internal + + Cuts a signal connection between the two given nodes. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet<QObject *>) = 0 + \internal + + When this function is called the nodes given in the parameter list may lose + signal data when a port is not connected. +*/ + +/*! + \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0 + \internal + + Returns all available MIME types. +*/ + +/*! + \class Phonon::MediaSource + \inmodule Phonon + \inheaderfile Phonon/MediaSource + \since 4.4 + \brief The MediaSource class provides multimedia data for media objects. + + The MediaSource class manages a source of multimedia content, such + as a music or video file, of which data is given to a + \l{Phonon::}{MediaObject}. + + The media source knows how fetch its data from several sources, + e.g., from files, a QIODevice, or a CD. The possible source types + are described by the \l{MediaSource::}{Type} enum. The type of the + source is set by the media source itself, and is dependent on the + constructor used to create it. Note that it is possible to provide + data from any source by implementing a QIODevice. + + The class has several functions to acquire information about the + source it manages, e.g., fileName() and url(). The return from + these functions are dependent on the type() of the media source. + + Normally, a programmer does not need to be concerned with media + sources. It's constructors are implicit, so one can, for instance, + send an URL or filename directly to the constructors of the + \l{Phonon::}{MediaObject}. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 3 + + A MediaSource object cannot be reused for another multimedia + source. It is possible to play the same source again, and also + stop and start a non-seekable media source, such as a radio + stream, with the same MediaSource object. + + \section1 Qt Backends + + Currently, Qt's backends support files in local and remote + locations. Support for other sources, such as CD/DVD, are planned + for the future. + + \sa MediaObject, {Phonon Module} +*/ + +/*! + \enum Phonon::MediaSource::Type + + Identifies the type of media described by the MediaSource object. + + \value Invalid The MediaSource object does not describe any valid source. + \value LocalFile The MediaSource object describes a local file. + \value Url The MediaSource object describes an URL, which can be either a + local file or a file on the network. + \value Disc The MediaSource object describes a disc, e.g., a CD. + \value Stream The MediaSource object describes a data stream. + This is the type used for \l{QIODevice}s. Note + that a stream opened with a QUrl, will still be of the Url type. + + \sa MediaSource::type() +*/ + +/*! + \fn Phonon::MediaSource::MediaSource() + \internal + + Creates an invalid MediaSource object. + + \sa Invalid +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const QString &fileName) + + Creates a MediaSource object for the file specified by \a + fileName. You can also use this constructor with \l{The Qt + Resource System}{Qt resources} + + \omit + \param fileName file name of a local media file or a Qt resource that was compiled in. + \endomit +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const QUrl &url) + + Creates a MediaSource object for a the URL specified by \a url. + + If the multimedia content you would like to play back is on a + remote network location, you should use this constructor; though, + it also possible to specify an URL to a local file. + + \sa QUrl +*/ + + +/*! + \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString()) + + Creates a MediaSource object for the type of disc specified by \a discType in the named + device referred to by \a deviceName. + + \note \a deviceName is a platform dependent device name. It can be useful to specify this + if the computer has more than one CD drive. On KDE, it is recommended to use the Solid + hardware discovery framework to retrieve the device name in a portable way. +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream) + \internal + Creates a MediaSource object for a data stream. + + Your application can provide the media data by subclassing AbstractMediaStream and + passing a pointer to that object. Phonon will never delete the \a stream. + + \param stream The AbstractMediaStream subclass to provide the media data. + + \sa setAutoDelete +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice) + + Creates a MediaSource object for the QIODevice specified by \a ioDevice. + + This constructor can be very handy in the combination of + QByteArray and QBuffer. + + If you need to fetch multimedia data from a source that is not + supported by MediaSource, you should subclass QIODevice and use + this MediaSource constructor. It is important that you reimplement + QIODevice::isSequential(), as it is used by MediaSource to + determine if the media source is seekable. + + \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened + MediaSource will open it as QIODevice::ReadOnly. + + \note Sequential devices can also be used, but MediaObject::isSeekable() will + return false as a result. + + \sa setAutoDelete() +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &) + \internal +*/ + +/*! + \fn Phonon::MediaSource::~MediaSource() + + Destroys the MediaSource object. You should never delete a + MediaSource yourself, the MediaObject will handle this. + +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const MediaSource &other) + + Constructs a copy of the \a other media source. + + This constructor is fast thanks to explicit sharing. +*/ + +/*! + \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other) + + Assigns the \a other media source to this media source and returns a + reference to it. + + This operation is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const + + Returns true if this media source is equal to the \a other media source; + otherwise returns false. +*/ + +/*! + \fn void Phonon::MediaSource::setAutoDelete(bool enable) + + If \a enable is true, the media source will take ownership of the + object passed in the \l{Phonon::}{MediaSource}'s constructor + object that was passed in the constructor; otherwise, the + programmer is responsible for deletion of this object. + + This setting is false by default. If you enable it, you should + only access the stream or device as long as you keep the media + source object around. As long as you keep the media source + wrapping the stream or device, the object will not get deleted. + + \sa autoDelete() +*/ + +/*! + \fn bool Phonon::MediaSource::autoDelete() const + + Returns the setting of the auto-delete option. The default is + false. + + \sa setAutoDelete() +*/ + +/*! + \fn Type Phonon::MediaSource::type() const + + Returns the type of the MediaSource (depends on the constructor + that was used). + + \sa Type +*/ + +/*! + \fn QString Phonon::MediaSource::fileName() const + + Returns the file name of the MediaSource if type() == + LocalFile; otherwise, returns QString(). + + \sa type() +*/ + +/*! + \fn QUrl Phonon::MediaSource::url() const + Returns the URL of the MediaSource if type() == URL or type() == LocalFile; + otherwise returns QUrl(). + + \sa type() +*/ + +/*! + \fn Phonon::DiscType Phonon::MediaSource::discType() const + Returns the disc type of the MediaSource if type() == Disc; otherwise + returns NoDisc. + + \sa type() +*/ + +/*! + \fn QString Phonon::MediaSource::deviceName() const + + Returns the device name of the MediaSource if type() == Disc; otherwise + returns QString(). + + \sa type() +*/ + +/*! + \fn AbstractMediaStream *Phonon::MediaSource::stream() const + \internal + Returns the media stream of the MediaSource if type() == Stream; otherwise + returns 0. + QIODevices are handled as streams, too. +*/ + +/*! + \class Phonon::MediaSourcePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::SeekSlider + \inmodule Phonon + \inheaderfile Phonon/SeekSlider + \since 4.4 + \brief The SeekSlider class provides a slider for seeking to positions in media streams. + + The SeekSlider connects to a \l{Phonon::}{MediaObject}, and + controls the seek position in the object's media stream. + + The slider will connect to the necessary signals to keep track of + the sliders maximum, minimum, and current values. It will also + disable itself for non-seekable streams, and update the media + object when the current value of the slider changes. + + Here follows a typical example of SeekSlider usage: + + \snippet doc/src/snippets/seekslider.cpp 0 + + \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module} + +*/ + +/*! + \property Phonon::SeekSlider::iconVisible + \brief whether the icon next to the slider is visible + + By default the icon is visible if the platform provides an icon; else + it's hidden. + +*/ + +/*! + \property Phonon::SeekSlider::tracking + \brief whether slider tracking is enabled + + If tracking is enabled (the default), the media seeks + while the slider is being dragged. If tracking is + disabled, the media seeks only when the user + releases the slider. +*/ + +/*! + \property Phonon::SeekSlider::pageStep + \brief the page step interval + + The larger of two natural steps that a slider provides and + typically corresponds to the user pressing PageUp or PageDown. + + Defaults to 5 seconds. +*/ + +/*! + \property Phonon::SeekSlider::singleStep + \brief the single step interval + + The smaller of two natural steps that a slider provides and + typically corresponds to the user pressing an arrow key. + + Defaults to 0.5 seconds. +*/ + +/*! + \property Phonon::SeekSlider::orientation + \brief the orientation of the slider + + The orientation must be Qt::Vertical or Qt::Horizontal (the default). +*/ + +/*! + \property Phonon::SeekSlider::iconSize + \brief the icon size used for the mute button/icon. + + The default size is defined by the GUI style. +*/ + +/*! + \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0) + + Constructs a seek slider widget with the given \a parent. +*/ + +/*! + \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0) + + Constructs a seek slider widget for the specified \a media with the + given \a parent. +*/ + +/*! + \fn Phonon::SeekSlider::~SeekSlider() + Destroys the seek slider. +*/ + +/*! + \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const + + Return the media object this SeekSlider controls. +*/ + +/*! + \class Phonon::SeekSliderPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media) + + Sets the media object to be controlled by this slider to the \a media specified. +*/ + +/*! + \class Phonon::VideoPlayer + \inmodule Phonon + \inheaderfile Phonon/VideoPlayer + \since 4.4 + \brief The VideoPlayer widget is used to perform playback of video. + + With VideoPlayer you can get results quickly and easily. You can + do the standard playback tasks like play(), pause(), and stop(), + but also set a playback volume and seek - if the media and backend + supports seeking. + + VideoPlayer is provided for convenience and removes the need to + create a media graph with a \l{Phonon::}{MediaObject}, + \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If + you need functionality not supported by the player, you can build + this \l{Building Graphs}{graph} yourself. + + Keep in mind that when the VideoPlayer instance is deleted the + playback will stop. + + Note also that most of the functions in this class are + asynchronous. For instance, a media source may not play + immediately after you call the play() function. + + A play and forget code example: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 4 + + \sa {Phonon Module}, MediaObject +*/ + +/*! + \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0) + + Constructs a new video widget with a \a parent using + Phonon::VideoCategory as its category. + + \param parent The QObject parent. +*/ + +/*! + \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0) + + Constructs a new VideoPlayer instance with the specified \a + parent. + + \a category is the category used for the audio output device. +*/ + +/*! + \fn Phonon::VideoPlayer::~VideoPlayer() + + On destruction the playback is stopped, also the audio output is + removed so that the desktop mixer will not show the application + anymore. If you need a persistent audio output don't use + VideoPlayer but MediaObject, VideoPath and VideoOutput. +*/ + +/*! + \fn qint64 Phonon::VideoPlayer::totalTime() const + + Get the total time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn qint64 Phonon::VideoPlayer::currentTime() const + + Get the current time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn float Phonon::VideoPlayer::volume() const + + This is the current volume of the output as voltage factor. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% +*/ + +/*! + \fn bool Phonon::VideoPlayer::isPlaying() const + + Returns true if it is currently playing; otherwise returns false if it + is currently stopped or paused +*/ + +/*! + \fn bool Phonon::VideoPlayer::isPaused() const + + Returns true if it is currently paused; otherwise returns false if it + is currently playing or stopped. +*/ + +/*! + \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source) + + Starts pre-loading the media data from the specified \a source and + filling audio buffers in the backend. + + When there's already a media playing (or paused) it will be stopped + (the finished signal will not be emitted). + + \sa MediaObject::setCurrentSource() +*/ + +/*! + \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source) + + Plays the media from the given \a source. Starts playback as fast as + possible. + This can take a considerable time depending on the URL and the + backend. + + If you need low latency between calling play() and the sound actually + starting to play on your output device you need to use MediaObject + and be able to set the URL before calling play(). Note that + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 5 + doesn't make a difference: the application should be idle between the + load and play calls so that the backend can start preloading the + media and fill audio buffers. +*/ + +/*! + \fn void Phonon::VideoPlayer::play() + + Continues playback of paused media. Restarts playback of a stopped + (or newly loaded) media. + + \sa MediaObject::play(), play() +*/ + +/*! + \fn void Phonon::VideoPlayer::pause() + + Pauses the playback. + + \sa MediaObject::pause() +*/ + +/*! + \fn void Phonon::VideoPlayer::stop() + + Stops the playback. + + \sa MediaObject::stop() +*/ + +/*! + \fn void Phonon::VideoPlayer::seek(qint64 ms) + + Seeks to the requested time. Note that the backend is free to + ignore the seek request if the media source isn't seekable; you + can check this by asking the media object of the VideoPlayer. + + \snippet doc/src/snippets/videomedia.cpp 0 + + The \a ms parameter is the time in milliseconds from the start of + the media. + + The call is asynchronous, so currentTime() can still be the old + value right after this method was called. If all you need is a + slider that shows the current position and allows the user to + seek, use the class SeekSlider. + + \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject() +*/ + +/*! + \fn void Phonon::VideoPlayer::setVolume(float volume) + + Sets the \a volume of the output as voltage factor. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% +*/ + +/*! + \fn MediaObject *Phonon::VideoPlayer::mediaObject() const + + Returns the media object being used by the player. + + The media object can be accessed directly instead of using the + \l{VideoPlayer}s convenience functions, e.g., play() and stop(). + It is also possible to give the object to other Phonon widgets, + e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}. + + \sa Phonon::SeekSlider, Phonon::MediaObject +*/ + +/*! + \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const + + Returns the audio output object being used by the player. + +*/ + +/*! + \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const + + Returns the video widget being used by the player. +*/ + +/*! + \fn void Phonon::VideoPlayer::finished() + + This signal is emitted when the playback finished. + +*/ + +/*! + \class Phonon::VideoWidgetPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaObject + \inmodule Phonon + \inheaderfile Phonon/MediaObject + \since 4.4 + \brief The MediaObject class provides an interface for media playback. + + + The media object manages a \l{Phonon::}{MediaSource}, which + supplies the media object with multimedia content, e.g., from a + file. A playback in Phonon is always started by calling the + \l{Phonon::MediaObject::}{play()} function. + + The state of play (play, pause, stop, seek) is controlled by the + media object, and you can also query the current + \l{Phonon::MediaObject::}{state()}. It keeps track of the playback + position in the media stream, and emits the + \l{Phonon::MediaObject::}{tick()} signal when the current position + in the stream changes. + + Notice that most functions of this class are asynchronous, so you + cannot rely on that a state is entered after a function call + before you receive the \l{Phonon::MediaObject::}{stateChanged()} + signal. The description of the \l{Phonon::}{State} enum gives a + description of the different states. + + Before play() is called, the media object should be connected to + \l{Sinks}{output nodes}, which outputs the media to the + underlying hardware. The output nodes required are dependent on + the contents of the multimedia file that is played back. Phonon + has currently two output nodes: the \l{Phonon::}{AudioOutput} for + audio content and \l{Phonon::}{VideoWidget} for video content. If + a \l{Phonon::}{MediaSource} contains both audio and video, both + nodes need to be connected to the media object. + + \snippet snippets/phonon.cpp 4 + \snippet snippets/phonon.cpp 5 + + The media object can queue sources for playback. When it has + finished to play one source, it will start playing the next in the + queue; the new source is then removed from the queue. The + queue can be altered at any time. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 7 + + You can also make use of the + \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is + guaranteed to be emitted in time for altering the queue. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 8 + + When playback is finishing, i.e., when a media source has been + played to the end and the queue is empty, several signals are + emitted. First, the media object will emit aboutToFinish() - + shortly before the playback has finished - and then finished(). + The stateChanged() signal will also be emitted with + \l{Phonon::}{PausedState}, which is the state the media object + takes when the playback is finished. If you wish to enter another + state, you can connect a slot to finished() and set a new state + there. + + The media object resolves the meta information, such as title, + artist, and album. The meta data is not resolved immediately after + a new source is provided, but will be resolved before the object + leaves the \l{Phonon::}{LoadingState}. The data is queried by + string keys - which should follow the Ogg Vorbis specification + \l http://xiph.org/vorbis/doc/v-comment.html - or by using the + \l{Phonon::}{MetaData} enum. The data available will depend on the + type and content of the individual media files. metaDataChanged() + will be emitted when the media object has resolved new meta data. + + Errors encountered during playback and loading of media sources + are reported by emitting a state changed signal with + \l{Phonon::}{ErrorState}. The severity of the error can be queried + by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError}, + it might be possible to continue the playback, for instance, if + only audio playback fails for a media source which also has video. + A \l{Phonon::}{FatalError} indicates that Phonon cannot continue + playback of the current source, but it is possible to try with a + different one. A user readable error message is given by + errorString(). + + \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget, + {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer, + Phonon::createPlayer(), {Phonon Module} + +*/ + +/*! + \property Phonon::MediaObject::transitionTime + \brief Defines the time between playback of two media sources + in the media queue. + + A positive transition time defines a gap of silence between queued + media sources. + + A transition time of 0 ms requests gapless playback (i.e., the + next source in the media queue starts immediately after the + playback of the current source finishes). + + A negative transition time defines a crossfade between the queued + media sources. + + Defaults to 0 (gapless playback). + + \warning This feature might not work reliably with every + backend. +*/ + +/*! + \property Phonon::MediaObject::prefinishMark + \brief the time when the prefinishMarkReached signal is emitted before playback ends. + + This property specifies the time in milliseconds the + prefinishMarkReached() signal is emitted before the playback + finishes. A value of \c 0 disables the signal. The signal is only + emitted for the last source in the \l{queue()}{media queue}. + + Defaults to \c 0 (disabled). + + \warning For some media data the total time cannot be determined + accurately, therefore the accuracy of the prefinishMarkReached signal + can be bad sometimes. Still, it is better to use this method than to + look at totalTime() and currentTime() to emulate the behavior + because the backend might have more information available than your + application does through totalTime() and currentTime(). + + \sa prefinishMarkReached() +*/ + +/*! + \property Phonon::MediaObject::tickInterval + \brief The time interval in milliseconds between two ticks. + + The tick() signal is emitted continuously during playback. + The tick interval is the time that elapses between the emission of two tick signals. + If you set the interval to \c 0 the tick signal gets disabled. + + The tick() signal can, for instance, be used to update widgets + that show the current position in the playback of a media source. + + Defaults to \c 0 (disabled). + + \warning The back-end is free to choose a different tick interval close + to what you asked for. This means that the following code \c may fail: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 9 + On the other hand the following is guaranteed: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 10 + + \sa tick() +*/ + +/*! + \fn Phonon::MediaObject::~MediaObject() + + Destroys the MediaObject. +*/ + +/*! + \fn State Phonon::MediaObject::state() const + + Returns the current Phonon::State of the object. + + \sa Phonon::State, stateChanged() +*/ + +/*! + \fn bool Phonon::MediaObject::hasVideo() const + + Check whether the current media source includes a video stream. + + \warning This information is not resolved immediately after a + media object gets a new source. Listen to the hasVideoChanged() + signal instead. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 11 + + Returns \c true if the media contains video data; otherwise, + returns \c false. + + \sa hasVideoChanged() +*/ + +/*! + \fn bool Phonon::MediaObject::isSeekable() const + + Check whether it is possible to seek, i.e., change the + playback position in the media stream. + + \warning This information is not solved immediately after the + media object gets a new media source. The hasVideoChanged() signal + is emitted after this information is available. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 12 + + Returns \c true if the current media may be seeked; otherwise, + returns \c false. + + \sa seekableChanged() +*/ + +/*! + \fn QStringList Phonon::MediaObject::metaData(const QString &key) const + + Returns the strings associated with the given \a key. + + Backends should use the keys specified in the Ogg Vorbis + documentation: \l http://xiph.org/vorbis/doc/v-comment.html + + Therefore the following should work with every backend: + + Note that meta data is not resolved before the \c + metaDataChanged() signal is emitted. + + A typical usage looks like this: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 13 +*/ + +/*! + \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const + + Returns the strings associated with the given \a key. + + Same as above except that the keys are defined in the + Phonon::MetaData enum. + + \sa metaDataChanged() +*/ + +/*! + \fn QMultiMap<QString, QString> Phonon::MediaObject::metaData() const + + Returns all meta data in a multi map. + + \sa metaDataChanged() +*/ + +/*! + \fn QString Phonon::MediaObject::errorString() const + + Returns a human-readable description of the last error that occurred. + The strings given may vary between backends. + + The error description can be used to give a message to the user - + and the developer - when the stateChanged() signal is emitted with + \l{Phonon::}{ErrorState}. + + \section1 Qt Backends + + On Windows, Qt fetches its error messages from the DirectShow + backend. This usually includes an error number, which can be + looked up in the DirectShow documentation: + \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}. + + On Linux and Mac, the error strings are not fetched directly from + the backend, but are created in the backend. + + \sa Phonon::ErrorState, stateChanged() +*/ + +/*! + \fn ErrorType Phonon::MediaObject::errorType() const + + Tells your program what to do about the last error that occurred. + Use this function after receiving a stateChanged() signal with + \l{Phonon::}{ErrorState}. + + \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged() +*/ + +/*! + \fn MediaSource Phonon::MediaObject::currentSource() const + + Returns the current media source, i.e., the media source that is + being played back. The current source is either set with + setCurrentSource() or taken from the media queue() when a media + source has finished playing. + + \sa setCurrentSource() +*/ + +/*! + \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source) + + Set the media source the MediaObject should use. + + After the media object receives a new source, it will enter the + \l{Phonon::}{LoadingState}. When it is ready to play, it + enters the \l{Phonon::}{StoppedState} unless another state + has been requested, e.g., by calling play(). + + \a source is the MediaSource object to the media data. You can + just as well use a QUrl or QString (for a local file) here. + + We show an example: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 14 + + \sa currentSource() +*/ + +/*! + \fn QList<MediaSource> Phonon::MediaObject::queue() const + + Returns the queued media sources. + + This does list does not include the current source, + returned by currentSource(). + + \sa enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::setQueue(const QList<MediaSource> &sources) + + Set the \a sources to play when the current source has finished. + + This function will overwrite the current queue. + + \sa clearQueue(), enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::setQueue(const QList<QUrl> &urls) + + Set the \a urls to play when the current media has finished. + + This function overwrites the current queue. + + \sa clearQueue(), enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const MediaSource &source) + + Appends \a source to the queue. + + You can use this function to provide the next source after the + aboutToFinish() signal has been emitted. + + \sa aboutToFinish(), setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const QList<MediaSource> &sources) + + Appends multiple \a sources to the queue. + + \sa setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const QList<QUrl> &urls) + + Appends the URLs in \a urls to the media source queue. + + The function will create \l{MediaSource}s from the \l{QUrl}s, and + append these to the queue. + + \sa setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::clearQueue() + + Clears the queue of media sources. + + \sa queue(), enqueue() +*/ + +/*! + \fn qint64 Phonon::MediaObject::currentTime() const + + Returns the current time (in milliseconds), i.e., position in the + media stream, of the file currently being played. + + \sa tick(), totalTime(), remainingTime() +*/ + +/*! + \fn qint64 Phonon::MediaObject::totalTime() const + + Get the total time (in milliseconds) of the file currently being played. + + Returns the total time in milliseconds. + + \warning The total time is not defined before the media object + enters the \l{Phonon::}{LoadingState}. + + \sa totalTimeChanged() +*/ + +/*! + \fn qint64 Phonon::MediaObject::remainingTime() const + + Get the remaining time (in milliseconds) of the file currently being played. + + Returns the remaining time in milliseconds. + + \sa totalTime(), currentTime(), totalTimeChanged() +*/ + +/*! + \fn void Phonon::MediaObject::play() + + Requests playback of the media data to start. + + Playback starts when the stateChanged() signal is emitted with + \l{Phonon::}{PlayingState}. + + If the media object is already in a + \l{Phonon::}{PlayingState}, nothing happens. + + \sa stop(), pause(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::pause() + + Requests playback to pause, and the media object to enter the + \l{Phonon::}{PausedState}. If it was paused already, nothing + changes. + + This function is asynchronous and the media might not be paused + immediately. + + \sa play(), stop(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::stop() + + Requests playback to stop, and the media object to enter the + \l{Phonon::}{StoppedState}. If it was stopped before + nothing changes. + + This function is asynchronous and the media might not be + stopped immediately. + + \sa play(), pause(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::seek(qint64 time) + + Requests a seek to the \a time indicated, specified in milliseconds. + + You can only seek if state() is PlayingState, BufferingState or PausedState. + + The call is asynchronous, so currentTime can still be the old + value right after this method was called. If all you need is a + slider that shows the current position and allows the user to + seek, use the class SeekSlider. + + If the current source of the media object is not seekable, calls + to this functions do nothing. + + \sa SeekSlider, tick() +*/ + +/*! + \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate) + + This signal is emitted when the state of the MediaObject has changed. + The \a oldstate and \a newstate parameters indicate the previous + state and current state of the media object. + + If you are only interested in the new state of the media object, you can + connect this signal to a slot that accepts only one State argument. +*/ + +/*! + \fn void Phonon::MediaObject::tick(qint64 time) + + This signal is emitted in intervals defined by the + \l{tickInterval} property. The current position of the media + object in the stream is given by the \a time parameter. The \a + time is specified in milliseconds. + + \sa tickInterval +*/ + +/*! + \fn void Phonon::MediaObject::metaDataChanged() + + This signal is emitted when the media object has resolved new meta + data. This will happen before the media object leaves the + \l{Phonon::}{LoadingState} after a new source has been set. + + This signal is not emitted when the media object removes the + current data, i.e., when a new source is set or an error has + occurred. If you need to know this, you can listen for the + \l{Phonon::}{ErrorState}, and connect to the + \l{Phonon::MediaObject::}{currentSourceChanged()} signal. + + You can get the new meta data with the metaData methods. + + \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State +*/ + +/*! + \fn void Phonon::MediaObject::seekableChanged(bool isSeekable) + + This signal is emitted when the media object's ability to seek in + the media stream changes. \a isSeekable is true if it is possible + to seek(); otherwise, it is false. + + Change in the ability to seek in the stream usually happens when + the current source changes or when an error occurs. + + \omit Emitted whenever the return value of isSeekable() + changes. \endomit + + Normally you'll check isSeekable() after setting a new media + source, and then let this signal tell you when seeking is + possible. That way you don't have to poll isSeekable(). +*/ + +/*! + \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo) + + Emitted whenever the return value of hasVideo() changes, i.e., + the media source being played back contains video. + + Normally you'll check hasVideo() first and then let this signal + tell you whether video is available now or not. That way you + don't have to poll hasVideo(). + + \a hasVideo is true when the stream contains video and adding a + VideoWidget will show a video, and false if there is no video data + in the stream and adding a VideoWidget will show an empty (black) + VideoWidget. +*/ + +/*! + \fn void Phonon::MediaObject::bufferStatus(int percentFilled) + + Provides information about the status of the buffer. + + When a MediaObject is in the \l{Phonon::}{BufferingState}, it will + send this signal regularly. \a percentFilled is a number between 0 + and 100 telling you how much the buffer is filled. + + You can use this signal to show a progress bar to the user when + in BufferingState: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 15 + + Note that the \l{Phonon::}{BufferingState} is commonly used when + waiting for data over a network connection, but this might not be + true for all backends. +*/ + +/*! + \fn void Phonon::MediaObject::finished() + + Emitted when the object has finished playback. It is not emitted + if you call stop(), pause() or load(). It is emitted only when the + current media source has finished playing and the media queue() is + empty, or when a \l{Phonon::FatalError}{fatal error} occurs. + + \warning This signal is not emitted when the current source has + finished and there's another source in the queue. It is only + emitted when the queue is empty. + + \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached() +*/ + +/*! + \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource) + + Emitted when the MediaObject fetches a new MediaSource from the + queue() and before it enters the \l{Phonon::}{LoadingState} for + the new source. The media object will take a new source from the + queue() when it has finished the playback of the + \l{currentSource()}{current source}. + + \a newSource is the source that starts to play at the time the + signal is emitted. +*/ + +/*! + \fn void Phonon::MediaObject::aboutToFinish() + + Emitted before the playback of the whole queue ends. When this + signal is emitted you still have time to enqueue() a new + MediaSource, so that playback continues. + + If you need a signal to be emitted at a specific time before + playback is finished, you should use the prefinishMarkReached() + signal instead. + + \sa enqueue(), prefinishMark, prefinishMarkReached() +*/ + +/*! + \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd) + + Emitted when there are only \a msecToEnd milliseconds left + of playback. + + \warning This signal is not emitted when there is another source + in the queue. It is only emitted when the queue is empty. + + \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished() +*/ + +/*! + \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime) + + This signal is emitted as soon as the total time of the media file is + known or has changed. For most non-local media data the total + time of the media can only be known after some time. At that time the + totalTime function can not return useful information. You have + to wait for this signal to know the real total time. + + \a newTotalTime is the length of the media file in milliseconds. + + \sa totalTime() +*/ + +/*! + \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource()) + + Convenience function to create a MediaObject and AudioOutput + connected by a path. The \l{Phonon::}{MediaObject} return will + have \a source set as its current source and the specified \a + category. + +*/ + +/*! + \class Phonon::MediaObjectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \namespace Phonon::BackendCapabilities + \inmodule Phonon + \since 4.4 + \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend. + +*/ + +/*! + \class Phonon::BackendCapabilitiesPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::BackendCapabilities::Notifier + \since 4.4 + \inmodule Phonon + \inheaderfile Phonon/BackendCapabilities + + Notifications about backend capabilities. +*/ + +/*! + \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged() + + This signal is emitted if the capabilities have changed. This can + happen if the user has requested a backend change. +*/ + +/*! + \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged() + + This signal is emitted when audio output devices were plugged or + unplugged. + + Check BackendCapabilities::availableAudioOutputDevices to get the + current list of available devices. +*/ + +/*! + \fn Notifier *Phonon::BackendCapabilities::notifier() + + Use this function to get a QObject pointer to connect to the capabilitiesChanged signal. + + \return a pointer to a QObject. + + The capabilitiesChanged signal is emitted if the capabilities have changed. This can + happen if the user has requested a backend change. + + To connect to this signal do the following: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 16 + + \sa Notifier::capabilitiesChanged() +*/ + +/*! + \fn QStringList Phonon::BackendCapabilities::availableMimeTypes() + + Returns a list of mime types that the Backend can decode. + + \sa isMimeTypeAvailable() +*/ + +/*! + \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType) + + Often all you want to know is whether one given MIME type can be + decoded by the backend. Use this method in favor of + availableMimeTypes() as it can give you a negative answer without + having a backend loaded. + + Returns true if the given \a mimeType is supported by the backend; + otherwise, returns false. + + \sa availableMimeTypes() +*/ + +/*! + \fn QList<AudioOutputDevice> Phonon::BackendCapabilities::availableAudioOutputDevices() + + Returns the audio output devices the backend supports. + + \return A list of AudioOutputDevice objects that give a name and + description for every supported audio output device. +*/ + +/*! + \fn QList<EffectDescription> Phonon::BackendCapabilities::availableAudioEffects() + + Returns descriptions for the audio effects the backend supports. + + \return A list of AudioEffectDescription objects that give a name and + description for every supported audio effect. +*/ + +/*! + \internal + \class ObjectDescriptionModelData + \internal + \inmodule Phonon + \brief Data class for models for ObjectDescription objects. +*/ + +/*! + \typedef Phonon::EffectDescription + \relates Phonon::ObjectDescription + + EffectDescription gives a description of an \l{Processors}{audio + effect}. It is a typedef of the \l{Phonon::}{ObjectDescription} + class. Please see its class description for details. + + EffectDescription is used to create audio \l{Phonon::}{Effect}s, + which can be inserted into a media graph, altering an audio + stream. + + \sa Phonon::ObjectDescription, {Capabilities Example}, {Media + Player} + +*/ + +/*! + \class Phonon::ObjectDescriptionModel + \inmodule Phonon + \internal + \since 4.4 + \brief The ObjectDescriptionModel class provides a model from + a list of ObjectDescription objects. + + ObjectDescriptionModel is a read only model that supplies a list + using ObjectDescription::name() for the text and + ObjectDescription::description() for the tooltip. If set the properties + "icon" and "available" are used to set the decoration and disable the + item (disabled only visually, you can still select and drag it). + + It also provides the methods moveUp() and moveDown() to order the list. + Additionally drag and drop is possible so that + QAbstractItemView::InternalMove can be used. + The resulting order of the ObjectDescription::index() values can then be + retrieved using tupleIndexOrder(). + + An example use case would be to give the user a QComboBox to select + the output device: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 17 + + And to retrieve the selected AudioOutputDevice: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 18 + +*/ + +/*! + \fn inline int Phonon::ObjectDescriptionModel::rowCount(const QModelIndex &parent = QModelIndex()) const + + Returns the number of rows in the model. This value corresponds + to the size of the list passed through setModelData. + + \param parent The optional \a parent argument is used in most models to specify + the parent of the rows to be counted. Because this is a list if a + valid parent is specified the result will always be 0. + + Reimplemented from QAbstractItemModel. + + \sa QAbstractItemModel::rowCount() +*/ + +/*! + \fn inline QVariant Phonon::ObjectDescriptionModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const + + Returns data from the item with the given \a index for the specified + \a role. + If the view requests an invalid index, an invalid variant is + returned. + + Reimplemented from QAbstractItemModel. + + \sa QAbstractItemModel::data(), Qt::ItemDataRole +*/ + +/*! + \fn inline Qt::ItemFlags Phonon::ObjectDescriptionModel::flags(const QModelIndex &index) const + \internal + + Reimplemented to show unavailable devices as disabled (but still + selectable). The \a index of the model index for which to return + flags. + +*/ + +/*! + \fn inline QList<int> Phonon::ObjectDescriptionModel::tupleIndexOrder() const + + Returns a list of indexes in the same order as they are in the + model. The indexes come from the ObjectDescription::index + method. + + This is useful to let the user define a list of preference. +*/ + +/*! + \fn inline int Phonon::ObjectDescriptionModel::tupleIndexAtPositionIndex(int positionIndex) const + + Returns the ObjectDescription::index for the tuple + at the given position \a positionIndex. For example a + QComboBox will give you the currentIndex as the + position in the list. But to select the according + AudioOutputDevice using AudioOutputDevice::fromIndex + you can use this method. + + \param positionIndex The position in the list. +*/ + +/*! + \class Phonon::ObjectDescriptionModelDataPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn inline QMimeData *Phonon::ObjectDescriptionModel::mimeData(const QModelIndexList &indexes) const + \internal + + Returns the MIME data that dropMimeData() can use to create new + items. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::moveUp(const QModelIndex &index) + + Moves the item at the given \a index up. In the resulting list + the items at index.row() and index.row() - 1 are swapped. + + Connected views are updated automatically. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::moveDown(const QModelIndex &index) + + Moves the item at the given \a index down. In the resulting list + the items at index.row() and index.row() + 1 are swapped. + + Connected views are updated automatically. +*/ + +/*! + \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(QObject *parent = 0) + + Constructs a ObjectDescription model with the + given \a parent. +*/ + +/*! + \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(const QList<ObjectDescription<type> > &data, QObject *parent = 0) + + Constructs a ObjectDescription model with the + given \a parent and the given \a data. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::setModelData(const QList<ObjectDescription<type> > &data) + + Sets the model data using the list provided by \a data. + + All previous model data is cleared. +*/ + +/*! + \fn inline QList<ObjectDescription<type> > Phonon::ObjectDescriptionModel::modelData() const + + Returns the model data. + + As the order of the list might have changed this can be different + to what was set using setModelData(). +*/ + +/*! + \fn inline ObjectDescription<type> Phonon::ObjectDescriptionModel::modelData(const QModelIndex &index) const + + Returns one ObjectDescription of the model data for the given \a index. +*/ + +/*! + \fn inline Qt::DropActions Phonon::ObjectDescriptionModel::supportedDropActions() const + + This model supports drag and drop to copy or move + items. +*/ + +/*! + \fn inline bool Phonon::ObjectDescriptionModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) + + Accept drops from other models of the same ObjectDescriptionType. + + The \a data is dropped at the given \a row and \a column; you + also receive the \a parent model index. + + If a valid \a parent is given the dropped items will be inserted + above that item. +*/ + +/*! + \fn inline bool Phonon::ObjectDescriptionModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex()) + + Removes count rows starting with the given row. + + If a valid \a parent is given no rows are removed since this is a + list model. + + Returns true if the rows were successfully removed; otherwise returns false. +*/ + +/*! + \fn inline QStringList Phonon::ObjectDescriptionModel::mimeTypes() const + + Returns a list of supported drag and drop MIME types. Currently + it only supports one type used internally. +*/ + +/*! + \class Phonon::EffectInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::Effect + \inmodule Phonon + \inheaderfile Phonon/Effect + \since 4.4 + \brief The Effect class is used to transform audio streams. + + An effect is a media node which is inserted into a path between a + \l{Phonon::}{MediaObject} and an audio output node, for instance, + an \l{Phonon::}{AudioOutput}. The Effect transforms the media + stream on that path. + + Examples may include simple modifiers, such as fading or pitch + shifting, and more complex mathematical transformations. You can + query the backend for available effects with + BackendCapabilities::availableAudioEffects(). Note that the + effects available is dependent on the underlying system + (DirectDraw, GStreamer, or QuickTime). + + In order to use an effect, insert it into the path as follows: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 19 + + The effect will immediately begin applying it's transformations on + the path. To stop it, remove the Effect from the path. + + To create an effect, you use the \l{Phonon::}{EffectDescription} + class, which you get from + \l{BackendCapabilities::}{availableAudioEffects()}. We give a code + example below. + + \snippet doc/src/snippets/audioeffects.cpp 0 + + An effect can have one or more parameters, which let you alter how + the effect works, for instance, by specifying the depth of a + reverb effect. See the EffectParameter class description for + details. + + Phonon also provides EffectWidget, which lets the user modify the + parameters of an effect an the fly, e.g., with comboboxes. + + \sa {Phonon Module}, EffectWidget +*/ + +/*! + \fn explicit Phonon::Effect::Effect(const EffectDescription &description, QObject *parent = 0) + + Constructs a new effect object with the given \a description and \a parent object. + + The EffectDescription object determines the type of the effect. + + \sa {Phonon::BackendCapabilities::availableAudioEffects()} +*/ + +/*! + \fn Phonon::Effect::Effect(EffectPrivate &dd, QObject *parent) + \internal +*/ + +/*! + \fn Phonon::Effect::~Effect() + \internal +*/ + +/*! + \fn QVariant Phonon::Effect::parameterValue(const EffectParameter ¶meter) const + + Returns the value of the given effect \a parameter. You can fetch + the available parameters for an effect with parameters(). + + \sa setParameterValue(), EffectParameter +*/ + +/*! + \fn void Phonon::Effect::setParameterValue(const EffectParameter ¶meter, const QVariant &value) + + Sets the given effect \a parameter to the specified \a value. + + Parameters for an effect are returned by parameters(). You can + check which QVariant::Type an EffectParameter takes with the + EffectParameter::type() function. + + \sa parameterValue(), EffectParameter +*/ + +/*! + \fn EffectDescription Phonon::Effect::description() const; + + Returns the description of this effect. This is the same + description that was passed to the constructor. +*/ + +/*! + \fn QList<EffectParameter> Phonon::Effect::parameters() const; + + Returns a list of parameters that this effect provides to control + its behavior. + + \sa EffectParameter, EffectWidget +*/ + +/*! + \class Phonon::EffectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::AudioOutput + \inmodule Phonon + \inheaderfile Phonon/AudioOutput + \since 4.4 + \brief The AudioOutput class is used to send data to audio output devices. + + The AudioOutput class plays sound over a sound device. The audio + output needs to be connected to a \l{Phonon::}{MediaObject} using + \l{Phonon::}{createPath()}. To start playback, you call + \l{Phonon::MediaObject::}{play()} on the media object. + + \snippet snippets/phonon.cpp 2 + + The class supports changing the volume(). It is also possible to + mute the sound. + + To find out what \l{Phonon::}{AudioOutputDevice}s are available + for AudioOutput, you can call + BackendCapabilities::availableAudioDevices(). A default device is + selected by the backend, but it is possible to set the device to + be used with setOutputDevice(). The outputDeviceChanged() signal + will be emitted if the device changes. + + If an error occurs with the playback, for instance, if no valid + output device is found, the media object will receive a + stateChanged() signal with the \l{Phonon::}{ErrorState}. + + Note that the default values of properties are dependent on the + backend. + + \sa Phonon::VolumeSlider, {Music Player Example}, BackendCapabilities, {Phonon Module} +*/ + +/*! + \property Phonon::AudioOutput::name + + This is the name that appears in Mixer applications that control + the volume of this output. + +*/ + +/*! + \property Phonon::AudioOutput::volume + + This is the current loudness of the output. \omit The volume is a + real value between 0.0 (minimum) and 1.0 (maximum). The volume + follows the sound device used, with 1.0 being the maximum volume + the device can produce. \endomit + + (it is using Stevens' law + to calculate the change in voltage internally). + + \sa volumeDecibel +*/ + +/*! + \property Phonon::AudioOutput::volumeDecibel + + This is the current volume of the output in decibel. + + 0 dB means no change in volume, -6dB means an attenuation of the + voltage to 50% and an attenuation of the power to 25%, -inf dB means + silence. + + \sa volume +*/ + +/*! + \property Phonon::AudioOutput::outputDevice + This property holds the (hardware) destination for the output. + + The default device is determined by the \l{Phonon::}{Category} and the global + configuration for that category. Normally you don't need + to override this setting - letting the user change the global + configuration is the right choice. You can still override the + device though, if you have good reasons to do so. + + \sa outputDeviceChanged() +*/ + +/*! + \property Phonon::AudioOutput::muted + This property tells whether the output is muted. + + Muting the output has the same effect as calling setVolume(0.0). +*/ + +/*! + \fn explicit Phonon::AudioOutput::AudioOutput(Phonon::Category category, QObject *parent = 0) + + Creates a new AudioOutput with the given \a parent that defines + output to a physical device. + + The \a category can be used by mixer applications to group volume + controls of applications into categories. That makes it easier for + the user to identify the programs. + The category is also used for the default output device that is + configured centrally. As an example: often users want to have the + audio signal of a VoIP application go to their USB headset while + all other sounds should go to the internal soundcard. + + \sa Phonon::categoryToString(), outputDevice +*/ + +/*! + \fn explicit Phonon::AudioOutput::AudioOutput(QObject *parent = 0) + + Creates a new AudioOutput that defines output to the system + default device with the \{Phonon::Category::}{NoCategory} category + + \sa Phonon::categoryToString(), outputDevice +*/ + +/*! + \fn Phonon::Category Phonon::AudioOutput::category() const + + Returns the category of this output. + + \sa Phonon::AudioOutput::AudioOutput() +*/ + +/*! + \fn void Phonon::AudioOutput::volumeChanged(qreal newVolume) + + This signal is emitted whenever the volume has changed. As the + volume can change without a call to setVolume (calls over dbus) + this is important to keep a widget showing the current volume up + to date. + + \a newVolume is the new volume level. + + \sa setVolume(), volume() +*/ + +/*! + \fn void Phonon::AudioOutput::mutedChanged(bool muted) + + This signal is emitted when the muted property has changed. The \a muted + value passed by the signal indicates the state of the muted property. + As this property can change by IPC (DBus) calls a UI element showing + the muted property should listen to this signal. +*/ + +/*! + \fn void Phonon::AudioOutput::outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice) + + This signal is emitted when the (hardware) device for the output + has changed. \a newAudioOutputDevice is the new device. + + The change can happen either through setOutputDevice or if the + global configuration for the used category has changed. + + \sa outputDevice +*/ + +/*! + \class Phonon::AudioOutputPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectParameter + \inmodule Phonon + \inheaderfile Phonon/EffectParameter + \since 4.4 + \brief The EffectParameter class describes one parameter of an effect. + + You fetch the parameters of an \l{Phonon::}{Effect} with + \l{Phonon::}{Effect::parameters()}. + + \snippet doc/src/snippets/phononeffectparameter.cpp 0 + + To describe itself, an effect parameter gives a name() and + possibly description() (depending on the backend used). These are + suited to present the effect parameter to the user of a Phonon + application. + + Note that effects are created by the backend, and that + their name and descriptions may vary. + + The value of an effect parameter is stored in a \l{QVariant}, + of which type() is usually \c int or \c double. + + The value is retrieved with \l{Phonon::}{Effect::parameterValue()} + and set with \l{Phonon::Effect::}{setParameterValue()} - both of + which takes the EffectParameter as argument. Note that not all + effect parameters support setting of their value. + + You get the values a parameter can take with possibleValues(); an + empty list is returned if the values are continuous. + + A parameter may also specify default(), minimum(), and maximum() + values. Values are returned as \l{QVariant}s. If the parameter + does not have the requested value, an \l{QVariant::Invalid} + invalid QVariant is returned from these functions. + + The \l{Phonon::}{EffectWidget} provides a widget with which one + can control the parameters of an \l{Phonon::}{Effect}. + + \snippet doc/src/snippets/phononeffectparameter.cpp 1 + + \sa Effect, EffectWidget, {Capabilities Example}, {Phonon Module} +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter() + \internal + + Creates an invalid effect parameter. +*/ + +/*! + \fn Phonon::EffectParameter::~EffectParameter() + + Destroys the effect parameter. +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter(const EffectParameter &other) + + Constructs a copy of the \a other effect parameter. +*/ + +/*! + \fn const QString &Phonon::EffectParameter::name() const + + The name of the parameter. Can be used as the label. + + \return A label for the parameter. +*/ + +/*! + \fn const QString &Phonon::EffectParameter::description() const + + The parameter may come with a description (LADSPA doesn't have a + field for this, so don't expect many effects to provide a + description). + + The description can be used for a tooltip or WhatsThis help. + + \return A text describing the parameter. +*/ + +/*! + \fn QVariant::Type Phonon::EffectParameter::type() const + + Returns the parameter type. + + Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When + QVariant::String is returned you get the possible values from possibleValues. +*/ + +/*! + \fn bool Phonon::EffectParameter::isLogarithmicControl() const + + Returns whether the parameter should be + displayed using a logarithmic scale. This is particularly useful for + frequencies and gains. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::minimumValue() const + + The minimum value to be used for the control to edit the parameter. + + If the returned QVariant is invalid the value is not bounded from + below. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::maximumValue() const + + The maximum value to be used for the control to edit the parameter. + + If the returned QVariant is invalid the value is not bounded from + above. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::defaultValue() const + + The default value. +*/ + +/*! + \fn QVariantList Phonon::EffectParameter::possibleValues() const + + The possible values to be used for the control to edit the parameter. + + if the value of this parameter is to be picked from predefined values + this returns the list (otherwise it returns an empty QVariantList). +*/ + +/*! + \fn bool Phonon::EffectParameter::operator<(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn bool Phonon::EffectParameter::operator>(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn bool Phonon::EffectParameter::operator==(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn Phonon::EffectParameter &Phonon::EffectParameter::operator=(const EffectParameter &other) + + Assigns the \a other effect parameter to this parameter and returns + a reference to this parameter. +*/ + +/*! + \enum Phonon::EffectParameter::Hint + + Only for backend developers: + + Flags to set the return values of isToggleControl(), + isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and + isBoundedAbove(). The values of the flags correspond to the values + used for LADSPA effects. + + \value ToggledHint + If this hint is set it means that + the the control has only two states: zero and non-zero + (see isToggleControl()). + + \value LogarithmicHint + LADSPA's SAMPLE_RATE hint needs to be translated by the backend + to normal bounds, as the backend knows the sample rate - and the + frontend doesn't (see isLogarithmicControl()). + + \value IntegerHint See isIntegerControl(). +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter(int parameterId, + const QString &name, EffectParameter::Hints hints, + const QVariant &defaultValue, const QVariant &min = QVariant(), + const QVariant &max = QVariant(), const QVariantList &values = QVariantList(), + const QString &description = QString()) + + Only to be used by backend implementations: + + Creates a new effect parameter. + + \a parameterId This is a number to uniquely identify the + parameter. The id is used for value() and setValue(). + + \a name is the name/label for this parameter. + + \a hints sets the hints for the type of parameter. + + \a defaultValue The value that should be used as a default. + + \a min is the minimum value allowed for this parameter. You only + need to set this if the BoundedBelowHint is set. + + \a max is the maximum value allowed for this parameter. You only + need to set this if the BoundedAboveHint is set. + + The \a values parameter is the values that the effect parameter + can take (only applies if non-continuous) + + \a description is a descriptive text for the parameter + (explaining what it controls) to be used as a tooltip or + WhatsThis help. +*/ + +/*! + \fn int Phonon::EffectParameter::id() const + + \internal + + Returns the parameter's identifier. +*/ + +/*! + \class Phonon::AudioOutputInterface40 + \inmodule Phonon + \since 4.4 + \internal + \brief Interface for AudioOutput objects + +*/ + +/*! + \fn virtual Phonon::AudioOutputInterface40::~AudioOutputInterface40() + \internal +*/ + +/*! + \fn virtual qreal Phonon::AudioOutputInterface40::volume() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::AudioOutputInterface40::setVolume(qreal) = 0 + \internal +*/ + +/*! + \fn virtual int Phonon::AudioOutputInterface40::outputDevice() const = 0 + \internal +*/ + +/*! + \fn virtual bool Phonon::AudioOutputInterface40::setOutputDevice(int) = 0 + \internal +*/ + +/*! + \class Phonon::Path + \inmodule Phonon + \inheaderfile Phonon/Path + \since 4.4 + \brief The Path class describes connections between media nodes. + + In a \l{Building Graphs}{media graph}, \l{Phonon::}{MediaNode}s + are connected by Paths. The multimedia travels in streams over + these paths. + + You create a path between two media nodes using the static + Phonon::createPath() function, which takes two nodes as arguments. + The first argument will send the media stream to the second. + Please refer to the class description of the individual media + nodes and the Phonon \l{Phonon Overview}{overview} to see which + nodes can be connected to each other. + + Paths are also used to insert audio \l{Phonon::}{Effect}s between + two media nodes. The effect will then alter the stream on the + path. Notice that \l{Phonon::}{Effect}s also are media nodes, but + that insertEffect() - instead of Phonon::createPath() - is used to + insert them into the media graph. + + The following code example shows how to create a path between two + media nodes and insert an effect on that path. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 20 + + \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput, + Phonon::VideoWidget, {Phonon Module} +*/ + +/*! + \fn Phonon::Path::~Path(); + + Destroys this reference to the Path. If the path was valid the connection is not broken + as both the source and the sink MediaNodes still keep a reference to the Path. + + \sa disconnect() +*/ + +/*! + \fn Phonon::Path::Path(); + + Creates an invalid path. + + You can still make it a valid path by calling reconnect. It is + recommended to use the Phonon::createPath() function to create + paths. + + \sa Phonon::createPath(), isValid() +*/ + +/*! + \fn Phonon::Path::Path(const Path &path); + + Constructs a copy of the other \a path specified. + + This constructor is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::Path::isValid() const; + + A path is considered valid if it is connected to two media nodes, + in which case this function returns true. If it is connected to + one or no media nodes, it is consider invalid, and this function + will then return false. +*/ + +/*! + \fn Effect *Phonon::Path::insertEffect(const EffectDescription &desc, Effect *insertBefore = 0); + + Creates and inserts an effect into the path. + + You may insert effects of the same class as often as you like, + but if you insert the same object, the call will fail. + + \a desc is the EffectDescription object for the effect to be inserted. + + If you already inserted an effect you can + tell with \a insertBefore in which order the data gets + processed. If this is \c 0 the effect is appended at the end of + the processing list. If the effect has not been inserted before + the method will do nothing and return \c false. + + Returns a pointer to the effect object if it could be inserted + at the specified position. If \c 0 is returned, the effect was not + inserted. + + Below is a code example for inserting an effect into a path: + + \snippet doc/src/snippets/audioeffects.cpp 0 + + \sa removeEffect(), effects() +*/ + +/*! + \fn bool Phonon::Path::insertEffect(Effect *effect, Effect *insertBefore = 0); + + Inserts the given \a effect into the path before the effect specified by \a insertBefore + and returns true if successful; otherwise returns false. + + If \a insertBefore is zero, the effect is appended to the processing list. + + You may insert effects of the same class as often as you like, but if you insert + the same object, the call will fail. + + \a effect will be inserted right before \a insertBefore. If + \a insertBefore is \c 0, the effect is appended at the end of the + processing list. If the effect has not been inserted before the + method will do nothing and return \c false. + + Returns whether the effect could be inserted at the specified + position. If \c false is returned the effect was not inserted. + + \sa removeEffect(), effects() +*/ + +/*! + \fn bool Phonon::Path::removeEffect(Effect *effect); + + Removes the given \a effect from the path and returns true; otherwise returns false. + + Removes an \a effect from the path. + + If the effect is deleted while it is still connected, the effect will be removed + automatically. + + \omit + \param effect The effect to be removed. + + \return Returns whether the call was successful. If it returns + \c false the effect could not be found in the path, meaning it + has not been inserted before. + \endomit + + \sa insertEffect(), effects() +*/ + +/*! + \fn QList<Effect *> Phonon::Path::effects() const; + + Returns a list of Effect objects that are currently + used as effects. The order in the list determines the order the + signal is sent through the effects. + + \return A list with all current effects. + + \sa insertEffect(), removeEffect() +*/ + +/*! + \fn bool Phonon::Path::reconnect(MediaNode *source, MediaNode *sink); + + Changes the media nodes the path is connected to by connecting the path + to the \a source and \a sink nodes specified. Returns true if successful; + otherwise returns false. + + If unsuccessful, the path remains connected to the same nodes as before. + + \sa Phonon::createPath(), {Phonon Overview} +*/ + +/*! + \fn bool Phonon::Path::disconnect(); + + Tries to disconnect the path from the MediaNodes it is connected to, returning + true if successful or false if unsuccessful. + + If successful, the path is invalidated: isValid() will returns false. +*/ + +/*! + \fn Path &Phonon::Path::operator=(const Path &p); + + Assigns \a p to this Path and returns a reference to this Path. + + This operation is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::Path::operator==(const Path &p) const; + + Returns true if this Path is equal to \a p; otherwise returns false; +*/ + +/*! + \fn bool Phonon::Path::operator!=(const Path &p) const; + + Returns true if this Path is not equal to \a p; otherwise returns false; +*/ + +/*! + \fn Path Phonon::createPath(MediaNode *source, MediaNode *sink); + + \relates Phonon::Path + Creates a new Path connecting the two MediaNodes \a source and \a sink. + + The implementation will automatically select the right format and media type. E.g. connecting a + MediaObject and AudioOutput will create a Path object connecting the audio. This might be + represented as PCM or perhaps even AC3 depending on the AudioOutput object. + + \param source The MediaNode to connect an output from + \param sink The MediaNode to connect to. +*/ + +/*! + \class Phonon::PathPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaObjectInterface + \inmodule Phonon + \since 4.4 + \internal + \brief Backend interface for media sources. + + The backend implementation has to provide two signals, that are not defined + in this interface: + \list + \o \target phonon_MediaObjectInterface_stateChanged + void stateChanged(Phonon::State newstate, Phonon::State oldstate) + + Emitted when the state of the MediaObject has changed. + In case you're not interested in the old state you can also + connect to a slot that only has one State argument. + + \param newstate The state the Player is in now. + \param oldstate The state the Player was in before. + + \o \target phonon_MediaObjectInterface_tick + void tick(qint64 time) + + This signal gets emitted every tickInterval milliseconds. + + \param time The position of the media file in milliseconds. + + \sa setTickInterval() + \sa tickInterval() + \endlist + + \sa MediaObject +*/ + +/*! + \fn virtual Phonon::MediaObjectInterface::~MediaObjectInterface() + \internal +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::remainingTime() const + \internal +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::prefinishMark() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setPrefinishMark(qint32) = 0 + \internal +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::transitionTime() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setTransitionTime(qint32) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::play() = 0 + \internal + + Requests the playback to start. + + This method is only called if the state transition to PlayingState is possible. + + The backend should react immediately + by either going into PlayingState or BufferingState if the + former is not possible. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::pause() = 0 + \internal + + Requests the playback to pause. + + This method is only called if the state transition to PausedState is possible. + + The backend should react as fast as possible. Go to PausedState + as soon as playback is paused. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::stop() = 0 + \internal + + Requests the playback to be stopped. + + This method is only called if the state transition to StoppedState is possible. + + The backend should react as fast as possible. Go to StoppedState + as soon as playback is stopped. + + A subsequent call to play() will start playback at the beginning of + the media. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::seek(qint64 milliseconds) = 0 + \internal + + Requests the playback to be seeked to the given time. + + The backend does not have to finish seeking while in this function + (i.e. the backend does not need to block the thread until the seek is + finished; even worse it might lead to deadlocks when using a + ByteStream which gets its data from the thread this function would + block). + + As soon as the seek is done the currentTime() function and + the tick() signal will report it. + + \param milliseconds The time where playback should seek to in + milliseconds. +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::tickInterval() const = 0 + \internal + + Return the time interval in milliseconds between two ticks. + + Returns the tick interval that it was set to (might not + be the same as you asked for). +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setTickInterval(qint32 interval) = 0 + \internal + + Change the interval the tick signal is emitted. Set \a interval to 0 to + disable the signal. + + \a interval tick interval in milliseconds + + Returns the tick interval that it was set to (might not be the same as you + asked for). + +*/ + +/*! + \fn virtual bool Phonon::MediaObjectInterface::hasVideo() const = 0 + \internal + + Check whether the media data includes a video stream. + + Returns true if the media contains video data. +*/ + +/*! + \fn virtual bool Phonon::MediaObjectInterface::isSeekable() const = 0 + \internal + + If the current media may be seeked this function returns true; + otherwise, false. + + Returns whether the current media may be seeked. +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::currentTime() const = 0 + \internal + + Get the current time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn virtual Phonon::State Phonon::MediaObjectInterface::state() const = 0 + \internal + + Get the current state. +*/ + +/*! + \fn virtual QString Phonon::MediaObjectInterface::errorString() const = 0 + \internal + + A translated string describing the error. +*/ + +/*! + \fn virtual Phonon::ErrorType Phonon::MediaObjectInterface::errorType() const = 0 + \internal + + Tells your program what to do about the error. + + \sa Phonon::ErrorType +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::totalTime() const = 0 + \internal + + Returns the total time of the media in milliseconds. + + If the total time is not know return -1. Do not block until it is + known, instead emit the totalTimeChanged signal as soon as the total + time is known or changes. +*/ + +/*! + \fn virtual MediaSource Phonon::MediaObjectInterface::source() const = 0 + \internal + + Returns the current source. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setSource(const MediaSource &) = 0 + \internal + + Sets the current source. When this function is called the MediaObject is + expected to stop all current activity and start loading the new + source (i.e. go into LoadingState). + + It is expected that the + backend now starts preloading the media data, filling the audio + and video buffers and making all media meta data available. It + will also trigger the totalTimeChanged signal. + + If the backend does not know how to handle the source it needs to + change state to Phonon::ErrorState. Don't bother about handling KIO + URLs. It is enough to handle AbstractMediaStream sources correctly. + + \warning Keep the MediaSource object around as long as the backend + uses the AbstractMediaStream returned by the MediaSource. In case + that no other reference to the MediaSource exists and it is set to + MediaSource::autoDelete, the AbstractMediaStream is deleted when the + last MediaSource ref is deleted. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setNextSource(const MediaSource &source) = 0 + \internal + + Sets the next source to be used for transitions. When a next source + is set playback should continue with the new source. In that case + finished and prefinishMarkReached are not emitted. + + \param source The source to transition to (crossfade/gapless/gap). If + \a source is an invalid MediaSource object then the queue is empty + and the playback should stop normally. + + \warning Keep the MediaSource object around as long as the backend + uses the AbstractMediaStream returned by the MediaSource. In case + that no other reference to the MediaSource exists and it is set to + MediaSource::autoDelete, the AbstractMediaStream is deleted when the + last MediaSource ref is deleted. +*/ + +/*! + \class Phonon::EffectWidget effectwidget.h Phonon/EffectWidget + \inmodule Phonon + \inheaderfile Phonon/EffectWidget + \since 4.4 + \brief The EffectWidget class provides a widget to control the parameters of an Effect. + + The EffectWidget class provides a widget, with which an effects + parameters can be controlled. The widget does not have an API, + and is constructed with the \l{Phonon::}{Effect}, of which + parameters should be controlled. + + \snippet doc/src/snippets/audioeffects.cpp 1 + + The following image shows an example of an effect widget. + + \image effectwidget.png + + Note that some audio effects do not have parameters, and the + widget will then not \l{QWidget::}{show()} at all. + + \sa Effect, BackendCapabilities, EffectDescription, {Phonon Module} +*/ + +/*! + \class Phonon::AbstractAudioOutput + \inmodule Phonon + \internal + \brief Provides a common base class for all audio outputs. + + \sa AudioOutput +*/ + +/*! + \fn Phonon::AbstractAudioOutput::~AbstractAudioOutput() + \internal +*/ + +/*! + \class Phonon::AbstractAudioOutputPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class AudioOutputAdaptor + \inmodule Phonon + \brief Provides an adaptor class for interface org.kde.Phonon.AudioOutput + \internal +*/ + +/*! + \class Phonon::VolumeSlider + \inmodule Phonon + \inheaderfile Phonon/VolumeSlider + \since 4.4 + \brief The VolumeSlider widget provides a slider that is used to control the volume of an audio output device. + + The slider also displays an icon indicating if the volume of the + \l{Phonon::}{AudioOutput} it is connected to is muted. The icon + can be removed with setMuteVisible(). + + It is possible to set the \l{maximumVolume}{maximum} value of the + slider. By default, the minimum and maximum values of the slider + are 0.0 (no sound) to 1.0 (the maximum volume the audio output can + produce). + + Here follows a code example: + + \snippet doc/src/snippets/volumeslider.cpp 0 + + \omit mention how to change the style of the slider. \endomit + + \sa {Phonon Module} +*/ + +/*! + \property Phonon::VolumeSlider::maximumVolume + + This property holds the maximum volume that can be set with this slider. + + By default the maximum value is 1.0 (100%). +*/ + +/*! + \property Phonon::VolumeSlider::orientation + This property holds the orientation of the slider. + + The orientation must be Qt::Vertical (the default) or Qt::Horizontal. +*/ + +/*! + \property Phonon::VolumeSlider::tracking + This property holds whether slider tracking is enabled. + + If tracking is enabled (the default), the volume changes + while the slider is being dragged. If tracking is + disabled, the volume changes only when the user + releases the slider. +*/ + +/*! + \property Phonon::VolumeSlider::pageStep + This property holds the page step. + + The larger of two natural steps that a slider provides and + typically corresponds to the user pressing PageUp or PageDown. + + Defaults to 5 (5% of the voltage). +*/ + +/*! + \property Phonon::VolumeSlider::singleStep + This property holds the single step. + + The smaller of two natural steps that a slider provides and + typically corresponds to the user pressing an arrow key. + + Defaults to 1 (1% of the voltage). +*/ + +/*! + \property Phonon::VolumeSlider::muteVisible + This property holds whether the mute button/icon next to the slider is visible. + + By default the mute button/icon is visible. +*/ + +/*! + \property Phonon::VolumeSlider::iconSize + \brief the icon size used for the mute button/icon. + + The default size is defined by the GUI style. +*/ + +/*! + \fn explicit Phonon::VolumeSlider::VolumeSlider(QWidget *parent = 0) + Constructs a new volume slider with the given \a parent. +*/ + +/*! + \fn explicit Phonon::VolumeSlider::VolumeSlider(AudioOutput *output, QWidget *parent = 0) + Constructs a new volume slider with the given \a output object and \a parent. +*/ + +/*! + \fn Phonon::VolumeSlider::~VolumeSlider() +*/ + +/*! + \fn AudioOutput *Phonon::VolumeSlider::audioOutput() const +*/ + +/*! + \fn void Phonon::VolumeSlider::setAudioOutput(Phonon::AudioOutput *output) + + Sets the audio output object to be controlled by this slider to the specified + \a output object. +*/ + +/*! + \class Phonon::VolumeSliderPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaController + \inmodule Phonon + \inheaderfile Phonon/MediaController + \since 4.4 + \brief The MediaController class controls optional features of a media file/device. + + Some media sources have content that the \l{Phonon::}{MediaObject} + does not provide control over, for instance, chapters in a DVD + file. The functionality the media controller offers is + dependent on the type of media source that is played back. + Commonly, the media controller allows you to: + + \list + \o Navigate between \bold chapters. + \o Navigate between \bold titles. + \o Select between \bold angles. + \endlist + + The \l{Phonon::MediaController::}{Feature} enum explains these + terms in more detail, and their context in playback of CD and DVD. + + The media controller keeps a \l{Phonon::}{MediaObject}, of which + \l{Phonon::MediaObject::currentSource()}{media source} is played + back. You can still call the media object's functions, e.g., + \l{Phonon::MediaObject::}{stop()}; this is all handled correctly + by the media controller. You have the option of letting the media + controller play all titles of a source in sequence by setting the + \l{autoplayTitles()}{autoplay titles} option. + + To start a playback using a media object, you call + \l{Phonon::MediaObject::}{play()} on the media object. To play a + specific title, use setCurrentTitle() and then call + \l{Phonon::MediaObject::}{play()}. + + \warning The Phonon::MediaController class is not yet supported by + Qt backends. + + \sa {Phonon Module} +*/ + +/*! + \fn int Phonon::MediaController::availableAudioChannels() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::availableAudioChannelsChanged() + \internal +*/ + +/*! + \fn QList<SubtitleDescription> Phonon::MediaController::availableSubtitles() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::availableSubtitlesChanged() + \internal +*/ + +/*! + \fn AudioChannelDescription Phonon::MediaController::currentAudioChannel() const + \internal +*/ + +/*! + \fn SubtitleDescription Phonon::MediaController::currentSubtitle() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream) + \internal +*/ + +/*! + \fn void Phonon::MediaController::setCurrentSubtitle(const Phonon::SubtitleDescription &stream) + \internal +*/ + +/*! + \fn Phonon::BackendCapabilities::availableAudioCaptureDevices() + \internal +*/ + +/*! + \fn Phonon::BackendCapabilities::Notifier::availableAudioCaptureDevicesChanged() + \internal +*/ + +/*! + \enum Phonon::MediaController::Feature + + The values of this enum are interpreted differently depending on + the type of media source, e.g., DVD or CD. We give examples for + these sources. + + \value Angles In the VOB (DVD) format, it is possible to to give + several video streams of the same scene, each of which displays + the scene from a different angle. The DVD viewer can then change + between these angles. + + \value Chapters In the VOB format, chapters are points in a + single video stream that can be played and seeked to + separately. + + \value Titles On a CD, a title is a separate sound track. On DVD, + a title is a separate VOB file. + +*/ + +/*! + \fn Phonon::MediaController::MediaController(MediaObject *parent) + + Constructs a new MediaController with the media object (\a parent) + to be used by the media controller. + + \sa MediaObject, Feature +*/ + +/*! + \fn Phonon::MediaController::~MediaController() +*/ + +/*! + \fn Features Phonon::MediaController::supportedFeatures() const +*/ + +/*! + \fn int Phonon::MediaController::availableAngles() const + + Returns the available angles that is available for the current + media source. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentAngle() const + + Returns the angle that is currently used. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::availableChapters() const + + Returns the number of chapters the current media source + contains. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentChapter() const + + Returns the chapter that is currently being played back. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::availableTitles() const + + Returns the number of titles that the current media source + contains. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentTitle() const + + Returns the title that is currently played back. + + The current title is 0 (the first) by default. + + \sa Feature +*/ + +/*! + \fn bool Phonon::MediaController::autoplayTitles() const + + Returns true if titles will automatically be played when the media + is played; otherwise returns false. + + The media controller will play the titles of the media source in + sequence when the media object's \l{Phonon::MediaObject::}{play()} + function is called. If the autoplay option is disabled, the media + object will play the + \l{Phonon::}{MediaController::currentTitle()}{current title} and then + finish the playback. + + \sa setAutoplayTitles(), currentTitle() +*/ + +/*! + \fn void Phonon::MediaController::setAutoplayTitles(bool enable) + + Sets the titles to play automatically when the media is played if + \a enable is true; otherwise disables this option. + + The media controller will play the titles of the media source in + sequence when the media object's \l{Phonon::MediaObject::}{play()} + function is called. If the autoplay option is disabled, the media + object will play the + \l{Phonon::}{MediaController::currentTitle()}{current title} and then + finish the playback. + + \sa autoplayTitles(), currentTitle() +*/ + +/*! + \fn void Phonon::MediaController::setCurrentAngle(int angleNumber) + + Sets the current angle to the given \a angleNumber if the media + file or device supports navigation by angle number. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::setCurrentChapter(int chapterNumber) + + Sets the current chapter to the given \a chapterNumber if the media + file or device supports navigation by chapter number. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::setCurrentTitle(int titleNumber) + + Skips to the given title \a titleNumber. + + If it was playing before the title change it will start playback on the new title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::nextTitle() + + Skips to the next title. + + If it was playing before the title change it will start playback on the next title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::previousTitle() + + Skips to the previous title. + + If it was playing before the title change it will start playback on the previous title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableAnglesChanged(int availableAngles) + + This signal is emitted whenever the number of available angles changes. + The new number of available angles is given by \a availableAngles. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::angleChanged(int angleNumber) + + This signal is emitted whenever the current angle changes. + The new angle number is given by \a angleNumber. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableChaptersChanged(int availableChapters) + + This signal is emitted whenever the number of available chapters changes. + The new number of available chapters is given by \a availableChapters. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::chapterChanged(int chapterNumber) + + This signal is emitted whenever the current chapter changes. + The new chapter number is given by \a chapterNumber. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableTitlesChanged(int availableTitles) + + This signal is emitted whenever the number of available titles changes. + The new number of available titles is given by \a availableTitles. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::titleChanged(int titleNumber) + + This signal is emitted whenever the current title changes. + The new title number is given by \a titleNumber. + + \sa Feature +*/ + +/*! + \class Phonon::VideoWidget + \inmodule Phonon + \inheaderfile Phonon/VideoWidget + \since 4.4 + \ingroup advanced + \ingroup multimedia + \brief The VideoWidget class provides a widget that is used to display video. + + The VideoWidget class renders the video of a media stream on a + QWidget. It is connected to the \l{Phonon::}{MediaObject}, of + which video stream it should render. You connect the two objects + using the Phonon::createPath() function. + + The widget has some possibilities to manipulate the video + stream. You can change the brightness(), hue(), saturation(), + and contrast(). + + Resizing of the video is handled automatically, but you can affect + the way the video is resized with the aspectRatio and scaleMode + properties. By default, the widget will use the aspect ratio of + the video stream itself. + + The video widget takes the size of the video when it receives a new video + stream (i.e., when a new MediaSource is set on the MediaObject to which it is + connected). If you need to know the size of the video, you can call + \l{QWidget::}{sizeHint()} after the video has been loaded (i.e., after the + MediaObject leaves the \l{Phonon::}{LoadingState}). + + It is also possible to go to \l{fullScreen}{full screen} mode. + + A typical example of usage follows below: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 21 + + \sa {Phonon Module} +*/ + +/*! + \fn Phonon::VideoWidget::VideoWidget(QWidget *parent = 0) + + Constructs a new video widget with the specified \a parent. +*/ + +/*! + \fn Phonon::VideoWidget::VideoWidget(VideoWidgetPrivate &d, QWidget *parent) + \internal + + Constructs a new video widget with the specified \a parent. +*/ + +/*! + \fn bool Phonon::VideoWidget::event(QEvent *) + \reimp +*/ + +/*! + \fn void Phonon::VideoWidget::mouseMoveEvent(QMouseEvent *) + \reimp +*/ + +/*! + \enum Phonon::VideoWidget::ScaleMode + + The ScaleMode enum describes how to treat aspect ratio during + resizing of video. + + \value FitInView The video will be fitted to fill the view + keeping aspect ratio. + \value ScaleAndCrop The video is scaled + + +*/ + +/*! + \property Phonon::VideoWidget::fullScreen + This property holds whether the video is shown using the complete + screen. + + The property differs from QWidget::fullScreen in that it is + writeable. + + By default the widget is not shown in fullScreen. + + \warning When switching to full screen mode using setFullScreen(), + the widget onto which the video is rendered is shown as a + top-level window. Key event forwarding is handled by VideoWidget, + but if you need to handle other events, e.g., mouse events, you + should handle fullscreen mode yourself. + +*/ + +/*! + \property Phonon::VideoWidget::aspectRatio + Defaults to AspectRatioAuto. + + \sa AspectRatio +*/ + +/*! + \property Phonon::VideoWidget::scaleMode + + If the size of the widget and the size of the video are not equal. + The video will be zoomed to fit the widget. The smaller zoom + (AddBarsScaleMode) adds black bars at the left/right or top/bottom to + make all of the image visible (default). The bigger zoom (ExpandMode) + fills the widget completely, keeping all information in one direction + and leaving parts of the image outside of the widget in the other + direction. +*/ + +/*! + \property Phonon::VideoWidget::brightness + + This property holds brightness of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::contrast + + This property holds the contrast of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::hue + + This property holds the hue of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::saturation + + This property holds saturation of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \enum Phonon::VideoWidget::AspectRatio + + Defines the width:height to be used for the video. + + \value AspectRatioAuto + Let the decoder find the aspect ratio automatically from the + media file (this is the default). + + \value AspectRatioWidget + Fits the video into the widget making the aspect ratio depend + solely on the size of the widget. This way the aspect ratio + is freely resizeable by the user. + + \value AspectRatio4_3 + Make width/height == 4/3, which is the old TV size and + monitor size (1024/768 == 4/3). (4:3) + + \value AspectRatio16_9 + Make width/height == 16/9, which is the size of most current + media. (16:9) +*/ + +/*! + \fn void Phonon::VideoWidget::exitFullScreen() + + Convenience slot, calling setFullScreen(false) +*/ + + +/*! + \fn void Phonon::VideoWidget::enterFullScreen() + + Convenience slot, calling setFullScreen(true) +*/ + +/*! + \class Phonon::VideoWidgetInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual Phonon::VideoWidgetInterface::~VideoWidgetInterface() +*/ + +/*! + \fn virtual Phonon::VideoWidget::AspectRatio Phonon::VideoWidgetInterface::aspectRatio() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setAspectRatio(Phonon::VideoWidget::AspectRatio ratio) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::brightness() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setBrightness(qreal) = 0 + \internal +*/ + +/*! + \fn virtual Phonon::VideoWidget::ScaleMode Phonon::VideoWidgetInterface::scaleMode() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setScaleMode(Phonon::VideoWidget::ScaleMode mode) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::contrast() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setContrast(qreal) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::hue() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setHue(qreal) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::saturation() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setSaturation(qreal) = 0 + \internal +*/ + +/*! + \fn virtual QWidget *Phonon::VideoWidgetInterface::widget() = 0 + \internal +*/ + +/*! + \class Phonon::PlatformPlugin + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual AbstractMediaStream *Phonon::PlatformPlugin::createMediaStream(const QUrl &url, QObject *parent) = 0 + + Creates a AbstractMediaStream object with the given \a parent that provides the data + for the given URL specified by \a url. + \omit + On KDE this uses KIO. + \endomit +*/ + +/*! + \fn virtual QIcon Phonon::PlatformPlugin::icon(const QString &name) const = 0 + + Returns the icon for the given icon name. +*/ + +/*! + \fn virtual void Phonon::PlatformPlugin::notification(const char *notificationName, const QString &text, + const QStringList &actions, QObject *receiver, const char *actionSlot) const = 0 + + Shows a notification pop-up with the given \a notificationName and \a text. + Each action in the associated list of \a actions is connected to the \a actionSlot + of the specified \a receiver object, which is expected to act on the actions as + they are triggered by the user. +*/ + +/*! + \fn virtual QString Phonon::PlatformPlugin::applicationName() const = 0 + + Returns the name of the application. For most Qt application this is + QCoreApplication::applicationName(), but for KDE this is overridden by KAboutData. +*/ + + +/*! + \fn virtual QObject *Phonon::PlatformPlugin::createBackend() = 0 + + Creates a backend object. This way the platform can decide the backend preference. +*/ + +/*! + \fn virtual QObject *Phonon::PlatformPlugin::createBackend(const QString &library, const QString &version) = 0 + + Using the library loader of the platform, loads a given backend provided the + specified \a library and \a version. +*/ + +/*! + \fn virtual bool Phonon::PlatformPlugin::isMimeTypeAvailable(const QString &mimeType) const = 0 + + Tries to check whether the default backend supports the MIME type specified by \a mimeType + without loading the actual backend library. + \omit + On KDE this reads the MIME type list from the .desktop file of + the backend. + \endomit +*/ + +/*! + \fn virtual void Phonon::PlatformPlugin::saveVolume(const QString &outputName, qreal volume) = 0 + + Saves the volume for the given output. +*/ + +/*! + \fn virtual qreal Phonon::PlatformPlugin::loadVolume(const QString &outputName) const = 0 + + Loads the volume for the given output. +*/ + +/*! + \class Phonon::MediaNode + \inmodule Phonon + \inheaderfile Phonon/MediaNode + \since 4.4 + \brief The MediaNode class is the base class for all nodes in a media graph. + + In all phonon applications, one builds a media graph consisting of + MediaNodes. The graph will take multimedia content, e.g., from a + file, as input. After its nodes have processed the multimedia, the + graph will output the media again, e.g., to a sound card. + + The multimedia content is streamed over \l{Phonon::}{Path}s + between the nodes in the graph. You can query the paths that are + connected to a media node with inputPaths() and outputPaths(). + + You can check whether the node is implemented by the current + backend by calling isValid(). This does not guarantee that an + instance of the class works as expected, but that the backend has + implemented functionality for the class. + + Currently, Phonon has four media nodes: \l{Phonon::}{MediaObject}, + \l{Phonon::}{AudioOutput}, \l{Phonon::}{VideoWidget}, and \l{Phonon::}{Effect}. + Please refer to their class descriptions for details about their usage, and to + find out which nodes can be connected to each other. See also \l{Building + Graphs} in Phonon's \l{Phonon Overview}{overview} document. + + Two nodes are connected to each other using the + Phonon::createPath() or \l{Phonon::}{Path::insertEffect()} + functions (only \l{Phonon::Effect}s use + \l{Phonon::Path::}{insertEffect()}). We show a code example below, + in which we build a media graph for video playback and then query + its media nodes for their \l{Phonon::}{Path}s: + + \snippet doc/src/snippets/medianodesnippet.cpp 0 + + When you create a Phonon application, you will likely build the + graph yourself. This makes isValid() the most useful function of + this class. The other two functions help navigate the graph, which + you do not need to do as you created the nodes yourself. + + \sa {Phonon Overview}, Phonon::MediaObject, + Phonon::AudioOutput, Phonon::VideoWidget, {Phonon Module} +*/ + +/*! + \fn virtual Phonon::MediaNode::~MediaNode() + + Destroys the media node and any paths connecting it to other + nodes. Any \l{Phonon::}{Effect}s connected to these paths will + also be deleted. +*/ + +/*! + \fn bool Phonon::MediaNode::isValid() const + + Returns true if the backend provides an implementation of this + class; otherwise returns false. + + This does not guarantee that instances of the class works as + expected, but that the backend has implemented the functionality + for this class. For instance, Qt's GStreamer backend will return + true for instances of the \l{Phonon::}{AudioOutput} class, even if + there is a problem with GStreamer and it could not play sound. + +*/ + +/*! + \fn QList<Path> Phonon::MediaNode::inputPaths() const + + Returns the paths that inputs multimedia to this media node. + + \sa outputPaths() +*/ + +/*! + \fn QList<Path> Phonon::MediaNode::outputPaths() const + + Returns the paths to which this media node outputs media. + + \sa inputPaths() +*/ + +/*! + \fn Phonon::MediaNode::MediaNode(MediaNodePrivate &dd) + \internal +*/ + +/*! + \class Phonon::GlobalConfig + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn Phonon::GlobalConfig::GlobalConfig() + \internal +*/ + +/*! + \fn Phonon::GlobalConfig::~GlobalConfig() + \internal +*/ + +/*! + \fn QList<int> Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, HideAdvancedDevicesOverride override = FromSettings) const + \internal +*/ + +/*! + \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category) const + \internal +*/ + +/*! + \class Phonon::ObjectDescriptionData + \inmodule Phonon + \since 4.4 + \internal + \brief Data class for objects describing devices or features of the backend. + + \sa Phonon::BackendCapabilities +*/ + +/*! + \fn bool Phonon::ObjectDescriptionData::operator==(const ObjectDescriptionData &otherDescription) const + + Returns \c true if this ObjectDescription describes the same + as \a otherDescription; otherwise returns \c false. +*/ + +/*! + \fn QString Phonon::ObjectDescriptionData::name() const + + Returns the name of the capture source. + + \return A string that should be presented to the user to + choose the capture source. +*/ + +/*! + \fn QString Phonon::ObjectDescriptionData::description() const + + Returns a description of the capture source. This text should + make clear what sound source this is, which is sometimes hard + to describe or understand from just the name. + + \return A string describing the capture source. +*/ + +/*! + \fn QVariant Phonon::ObjectDescriptionData::property(const char *name) const + + Returns a named property. + + If the property is not set an invalid value is returned. + + \sa propertyNames() +*/ + +/*! + \fn QList<QByteArray> Phonon::ObjectDescriptionData::propertyNames() const + + Returns all names that return valid data when property() is called. + + \sa property() +*/ + +/*! + \fn bool Phonon::ObjectDescriptionData::isValid() const + + Returns true if the Tuple is valid (index != -1); otherwise returns + false. +*/ + +/*! + \fn int Phonon::ObjectDescriptionData::index() const + + A unique identifier for this device/. Used internally + to distinguish between the devices/. + + \return An integer that uniquely identifies every device. +*/ + +/*! + \fn static ObjectDescriptionData *Phonon::ObjectDescriptionData::fromIndex(ObjectDescriptionType type, int index) + \internal +*/ + +/*! + \fn Phonon::ObjectDescriptionData::~ObjectDescriptionData() + \internal +*/ + +/*! + \fn Phonon::ObjectDescriptionData::ObjectDescriptionData(ObjectDescriptionPrivate * = 0) + \internal +*/ + +/*! + \class Phonon::AddonInterface + \inmodule Phonon + \since 4.4 + \internal + \brief Interface for Menu, Chapter, Angle and Title/Track control. +*/ + +/*! + \fn virtual Phonon::AddonInterface::~AddonInterface() + \internal +*/ + +/*! + \enum Phonon::AddonInterface::Interface + + This enum describes the type of interface represented by an AddonInterface object. + + \value NavigationInterface + \value ChapterInterface + \value AngleInterface + \value TitleInterface +*/ + +/*! + \enum Phonon::AddonInterface::NavigationCommand + \internal + \value Menu1Button +*/ + +/*! + \enum Phonon::AddonInterface::ChapterCommand + \internal + \value availableChapters + \value chapter + \value setChapter +*/ + +/*! + \enum Phonon::AddonInterface::AngleCommand + \internal + \value availableAngles + \value angle + \value setAngle +*/ + +/*! + \enum Phonon::AddonInterface::TitleCommand + \internal + \value availableTitles + \value title + \value setTitle + \value autoplayTitles + \value setAutoplayTitles +*/ + +/*! + \fn virtual bool Phonon::AddonInterface::hasInterface(Interface iface) const = 0 + \internal +*/ + +/*! + \fn virtual QVariant Phonon::AddonInterface::interfaceCall(Interface iface, int command, + const QList<QVariant> &arguments) = 0 + \internal +*/ + +/*! + \class Phonon::MediaNodePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \namespace Phonon::Factory + \inmodule Phonon + \internal +*/ + +/*! + \fn Sender *Phonon::Factory::sender() + + Returns a pointer to the object emitting the signals. + + \sa Sender::backendChanged() +*/ + +/*! + \fn QObject *Phonon::Factory::createMediaObject(QObject *parent = 0) + + Create a new backend object for a MediaObject. + + \return a pointer to the MediaObject the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createEffect(int effectId, QObject *parent = 0) + + Create a new backend object for a Effect. + + \return a pointer to the Effect the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createVolumeFaderEffect(QObject *parent = 0) + + Create a new backend object for a VolumeFaderEffect. + + \return a pointer to the VolumeFaderEffect the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createAudioOutput(QObject *parent = 0) + + Create a new backend object for a AudioOutput. + + \return a pointer to the AudioOutput the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createVideoWidget(QObject *parent = 0) + + Create a new backend object for a VideoWidget. + + \return a pointer to the VideoWidget the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::backend(bool createWhenNull = true) + + \return a pointer to the backend interface. +*/ + +/*! + \fn QString Phonon::Factory::identifier() + + Unique identifier for the Backend. Can be used in configuration files + for example. +*/ + + +/*! + \fn QString Phonon::Factory::backendName() + + Get the name of the Backend. + \omit + It's the name from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendComment() + + Get the comment of the Backend. + \omit + It's the comment from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendVersion() + + Get the version of the Backend. + \omit + It's the version from the .desktop file. + \endomit + + The version is especially interesting if there are several versions + available for binary incompatible versions of the backend's media + framework. +*/ + +/*! + \fn QString Phonon::Factory::backendIcon() + + Get the icon (name) of the Backend. + \omit + It's the icon from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendWebsite() + + Get the website of the Backend. + \omit + It's the website from the .desktop file. + \endomit +*/ + +/*! + \fn QObject *Phonon::Factory::registerQObject(QObject *object) + + Registers the given backend \a object with the factory. +*/ + +/*! + \fn bool Phonon::Factory::isMimeTypeAvailable(const QString &mimeType) +*/ + +/*! + \fn void Phonon::Factory::registerFrontendObject(MediaNodePrivate *) + \internal +*/ + +/*! + \fn void Phonon::Factory::deregisterFrontendObject(MediaNodePrivate *) + \internal +*/ + +/*! + \fn void Phonon::Factory::setBackend(QObject *) +*/ + +/*! + \fn PlatformPlugin *Phonon::Factory::platformPlugin() +*/ + +/*! +/*! + \class Phonon::AbstractMediaStreamPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::FrontendInterfacePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectWidgetPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::IODeviceStream + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn explicit Phonon::IODeviceStream::IODeviceStream(QIODevice *ioDevice, QObject *parent = 0) + \internal + + Creates a new IODeviceStream with the given \a ioDevice and \a + parent. + +*/ + +/*! + \fn Phonon::IODeviceStream::~IODeviceStream() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::reset() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::needData() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::seekStream(qint64) + \internal +*/ + +/*! + \namespace Phonon::Platform + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::EffectDescriptionModel + \inmodule Phonon + \brief provides a item view model containing available audio effects. + +*/ + +/*! + \typedef Phonon::SubtitleDescription + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::SubtitleDescriptionModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioChannelDescription + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioChannelDescriptionModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioCaptureDevice + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioCaptureDeviceModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef typedef void (*CleanUpFunction)() + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::QObjectPair + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \typedef Phonon::AudioOutputDeviceModel + \inmodule Phonon + \brief provides an item view model containing available audio output devices. + +*/ + +/*! + \fn uint Phonon::qHash(const Phonon::EffectParameter ¶m) + \internal + +*/ + +/*! + \fn Phonon::CleanUpGlobalStatic::~CleanUpGlobalStatic() + \internal +*/ + +/*! + \class Phonon::ConstIface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::CleanUpGlobalStatic + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectParameterPrivate + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::QSettingsGroup + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::MediaNodeDestructionHandler + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \fn Phonon::MediaNodeDestructionHandler::~MediaNodeDestructionHandler() + \internal + Called from Base::~Base if this object was registered + using BasePrivate::addDestructionHandler(). +*/ + +/*! + \fn Phonon::MediaNodeDestructionHandler::phononObjectDestroyed(MediaNodePrivate *) + \internal +*/ + +/*! + \fn explicit Phonon::EffectWidget::EffectWidget(Effect *effect, QWidget *parent = 0) + \internal + + Constructs a new EffectWidget for the specified \a effect and with + the specified \a parent. +*/ + +/*! + \fn Phonon::EffectWidget::~EffectWidget() + \internal +*/ + +/*! + \fn QDebug Phonon::operator<<(QDebug s, const ObjectDescription<T> &o) + \internal +*/ + +/*! + \class Phonon::ListModelHelper + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class AudioOutputInterface42 + \inmodule Phonon + \since 4.4 + \internal +*/ + |