Long live Qt 4.5!

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 &parameter) 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 &parameter, 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 &param)
+    \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
+*/
+