/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** All rights reserved.
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $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
*/