1 files changed, 171 insertions, 0 deletions
diff --git a/doc/src/examples/capabilitiesexample.qdoc b/doc/src/examples/capabilitiesexample.qdoc
new file mode 100644
index 0000000..9d62c71
--- /dev/null
+++ b/doc/src/examples/capabilitiesexample.qdoc
@@ -0,0 +1,171 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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
+*/