/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \example phonon/capabilities

    \title Capabilities Example

    The Backend Capabilities example shows how to check which MIME

    types, audio devices, and audio effects are available.

    \image capabilitiesexample.png

    Phonon does not implement the multimedia functionality itself, but

    relies on a backend to manage this. The backends do not manage the

    hardware directly, but use intermediate technologies: QuickTime on

    Mac, GStreamer on Linux, and DirectShow (which requires DirectX)

    on Windows. 

    The user may add support for new MIME types and effects to these

    systems, and the systems abilities may also be different. The

    support for multimedia MIME types, and audio effects in Phonon

    will therefore vary from system to system.

    Backends informs the programmer about current capabilities through

    an implementation of the Phonon::BackendCapabilities namespace.

    The backend reports which MIME types can be played back, which

    audio effects are available, and which sound devices are available

    on the system. When the capabilities of a backend changes, it will

    emit the

    \l{Phonon::BackendCapabilities::Notifier::}{capabilitiesChanged()}

    signal.

    The example consists of one class, \c Window, which displays

    capabilities information from the current backend used by Phonon.

    See the \l{Phonon Overview} for a high-level introduction to

    Phonon.

    \section1 Window Class Definition

    The \c Window class queries the Phonon backend for its

    capabilities. The results are presented in a GUI consisting of

    standard Qt widgets. We will now take a tour of the Phonon related

    parts of both the definition and implementation of the \c Window

    class.

    \snippet examples/phonon/capabilities/window.h windowMembers

    We need the slot to notice changes in the backends capabilities. 

    \c mimeListWidget and \c devicesListView lists MIME types and

    audio devices. The \c effectsTreeWidget lists audio effects, and

    expands to show their parameters.

    The \c setupUi() and \c setupBackendBox() private utility

    functions create the widgets and lays them out. We skip these

    functions while discussing the implementation because they do not

    contain Phonon relevant code.

    \section1 Window Class Implementation

    Our examination starts with a look at the constructor:

    \snippet examples/phonon/capabilities/window.cpp constructor

    After creating the user interface, we call \c updateWidgets(),

    which will fill the widgets with the information we get from the

    backend. We then connect the slot to the

    \l{Phonon::BackendCapabilities::Notifier::}{capabilitiesChanged()}

    and

    \l{Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged()}{availableAudioOutputDevicesChanged()}

    signals in case the backend's abilities changes while the example

    is running. The signal is emitted by a

    Phonon::BackendCapabilities::Notifier object, which listens for

    changes in the backend.

    In the \c updateWidgets() function, we query the backend for

    information it has about its abilities and present it in the GUI

    of \c Window. We dissect it here:

    \snippet examples/phonon/capabilities/window.cpp outputDevices

    The

    \l{Phonon::BackendCapabilities::Notifier::}{availableAudioOutputDevicesChanged()}

    function is a member of the Phonon::BackendCapabilities namespace.

    It returns a list of \l{Phonon::}{AudioOutputDevice}s, which gives

    us information about a particular device, e.g., a sound card or a

    USB headset.

    Note that \l{Phonon::}{AudioOutputDevice} and also

    \l{Phonon::}{EffectDescription}, which is described shortly, are

    typedefs of \l{Phonon::}{ObjectDescriptionType}.

    \omit

    ###

    The \l{Phonon::}{ObjectDescriptionModel} is a convenience

    model that displays the names of the devices. Their

    descriptions are shown as tooltips and disabled devices are

    shown in gray.

    \endomit

    \snippet examples/phonon/capabilities/window.cpp mimeTypes

    The MIME types supported are given as strings in a QStringList. We

    can therefore create a list widget item with the string, and

    append it to the \c mimeListWidget, which displays the available

    MIME types.

    \snippet examples/phonon/capabilities/window.cpp effects

    As before we add the description and name to our widget, which in

    this case is a QTreeWidget. A particular effect may also have

    parameters, which are inserted in the tree as child nodes of their

    effect.

    \snippet examples/phonon/capabilities/window.cpp effectsParameters

    The parameters are only accessible through an instance of the

    \l{Phonon::}{Effect} class. Notice that an effect is created

    with the effect description.

    The \l{Phonon::}{EffectParameter} contains information about one

    of an effects parameters. We pick out some of the information to

    describe the parameter in the tree widget.

    \section1 The main() function

    Because Phonon uses D-Bus on Linux, it is necessary to give the

    application a name. You do this with

    \l{QCoreApplication::}{setApplicationName()}.

    \snippet examples/phonon/capabilities/main.cpp everything

*/