1 /****************************************************************************

     2 **

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

     4 ** All rights reserved.

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

     6 **

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

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

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

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

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

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

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

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

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

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

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

    23 **

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

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

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

    27 **

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

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

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example phonon/capabilities

    44     \title Capabilities Example

    45 

    46     The Backend Capabilities example shows how to check which MIME

    47     types, audio devices, and audio effects are available.

    48 

    49     \image capabilitiesexample.png

    50 

    51     Phonon does not implement the multimedia functionality itself, but

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

    53     hardware directly, but use intermediate technologies: QuickTime on

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

    55     on Windows. 

    56 

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

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

    59     support for multimedia MIME types, and audio effects in Phonon

    60     will therefore vary from system to system.

    61 

    62     Backends informs the programmer about current capabilities through

    63     an implementation of the Phonon::BackendCapabilities namespace.

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

    65     audio effects are available, and which sound devices are available

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

    67     emit the

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

    69     signal.

    70 

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

    72     capabilities information from the current backend used by Phonon.

    73 

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

    75     Phonon.

    76 

    77     \section1 Window Class Definition

    78 

    79     The \c Window class queries the Phonon backend for its

    80     capabilities. The results are presented in a GUI consisting of

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

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

    83     class.

    84 

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

    86 

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

    88 

    89     \c mimeListWidget and \c devicesListView lists MIME types and

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

    91     expands to show their parameters.

    92 

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

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

    95     functions while discussing the implementation because they do not

    96     contain Phonon relevant code.

    97 

    98     \section1 Window Class Implementation

    99 

   100     Our examination starts with a look at the constructor:

   101 

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

   103 

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

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

   106     backend. We then connect the slot to the

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

   108     and

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

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

   111     is running. The signal is emitted by a

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

   113     changes in the backend.

   114 

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

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

   117     of \c Window. We dissect it here:

   118 

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

   120 

   121     The

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

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

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

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

   126     USB headset.

   127 

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

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

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

   131 

   132     \omit

   133     ###

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

   135     model that displays the names of the devices. Their

   136     descriptions are shown as tooltips and disabled devices are

   137     shown in gray.

   138     \endomit

   139 

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

   141 

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

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

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

   145     MIME types.

   146 

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

   148 

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

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

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

   152     effect.

   153 

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

   155 

   156     The parameters are only accessible through an instance of the

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

   158     with the effect description.

   159 

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

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

   162     describe the parameter in the tree widget.

   163 

   164     \section1 The main() function

   165 

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

   167     application a name. You do this with

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

   169 

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

   171 */