--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/capabilitiesexample.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,171 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 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
+*/