1 | /****************************************************************************
|
---|
2 | **
|
---|
3 | ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
|
---|
4 | ** All rights reserved.
|
---|
5 | ** Contact: Nokia Corporation ([email protected])
|
---|
6 | **
|
---|
7 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
8 | **
|
---|
9 | ** $QT_BEGIN_LICENSE:FDL$
|
---|
10 | ** Commercial Usage
|
---|
11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
13 | ** Software or, alternatively, in accordance with the terms contained in a
|
---|
14 | ** written agreement between you and Nokia.
|
---|
15 | **
|
---|
16 | ** GNU Free Documentation License
|
---|
17 | ** Alternatively, this file may be used under the terms of the GNU Free
|
---|
18 | ** Documentation License version 1.3 as published by the Free Software
|
---|
19 | ** Foundation and appearing in the file included in the packaging of this
|
---|
20 | ** file.
|
---|
21 | **
|
---|
22 | ** If you have questions regarding the use of this file, please contact
|
---|
23 | ** Nokia at [email protected].
|
---|
24 | ** $QT_END_LICENSE$
|
---|
25 | **
|
---|
26 | ****************************************************************************/
|
---|
27 |
|
---|
28 | /*!
|
---|
29 | \example phonon/capabilities
|
---|
30 | \title Capabilities Example
|
---|
31 |
|
---|
32 | The Backend Capabilities example shows how to check which MIME
|
---|
33 | types, audio devices, and audio effects are available.
|
---|
34 |
|
---|
35 | \image capabilitiesexample.png
|
---|
36 |
|
---|
37 | Phonon does not implement the multimedia functionality itself, but
|
---|
38 | relies on a backend to manage this. The backends do not manage the
|
---|
39 | hardware directly, but use intermediate technologies: QuickTime on
|
---|
40 | Mac, GStreamer on Linux, and DirectShow (which requires DirectX)
|
---|
41 | on Windows.
|
---|
42 |
|
---|
43 | The user may add support for new MIME types and effects to these
|
---|
44 | systems, and the systems abilities may also be different. The
|
---|
45 | support for multimedia MIME types, and audio effects in Phonon
|
---|
46 | will therefore vary from system to system.
|
---|
47 |
|
---|
48 | Backends informs the programmer about current capabilities through
|
---|
49 | an implementation of the Phonon::BackendCapabilities namespace.
|
---|
50 | The backend reports which MIME types can be played back, which
|
---|
51 | audio effects are available, and which sound devices are available
|
---|
52 | on the system. When the capabilities of a backend changes, it will
|
---|
53 | emit the
|
---|
54 | \l{Phonon::BackendCapabilities::Notifier::}{capabilitiesChanged()}
|
---|
55 | signal.
|
---|
56 |
|
---|
57 | The example consists of one class, \c Window, which displays
|
---|
58 | capabilities information from the current backend used by Phonon.
|
---|
59 |
|
---|
60 | See the \l{Phonon Overview} for a high-level introduction to
|
---|
61 | Phonon.
|
---|
62 |
|
---|
63 | \section1 Window Class Definition
|
---|
64 |
|
---|
65 | The \c Window class queries the Phonon backend for its
|
---|
66 | capabilities. The results are presented in a GUI consisting of
|
---|
67 | standard Qt widgets. We will now take a tour of the Phonon related
|
---|
68 | parts of both the definition and implementation of the \c Window
|
---|
69 | class.
|
---|
70 |
|
---|
71 | \snippet examples/phonon/capabilities/window.h windowMembers
|
---|
72 |
|
---|
73 | We need the slot to notice changes in the backends capabilities.
|
---|
74 |
|
---|
75 | \c mimeListWidget and \c devicesListView lists MIME types and
|
---|
76 | audio devices. The \c effectsTreeWidget lists audio effects, and
|
---|
77 | expands to show their parameters.
|
---|
78 |
|
---|
79 | The \c setupUi() and \c setupBackendBox() private utility
|
---|
80 | functions create the widgets and lays them out. We skip these
|
---|
81 | functions while discussing the implementation because they do not
|
---|
82 | contain Phonon relevant code.
|
---|
83 |
|
---|
84 | \section1 Window Class Implementation
|
---|
85 |
|
---|
86 | Our examination starts with a look at the constructor:
|
---|
87 |
|
---|
88 | \snippet examples/phonon/capabilities/window.cpp constructor
|
---|
89 |
|
---|
90 | After creating the user interface, we call \c updateWidgets(),
|
---|
91 | which will fill the widgets with the information we get from the
|
---|
92 | backend. We then connect the slot to the
|
---|
93 | \l{Phonon::BackendCapabilities::Notifier::}{capabilitiesChanged()}
|
---|
94 | and
|
---|
95 | \l{Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged()}{availableAudioOutputDevicesChanged()}
|
---|
96 | signals in case the backend's abilities changes while the example
|
---|
97 | is running. The signal is emitted by a
|
---|
98 | Phonon::BackendCapabilities::Notifier object, which listens for
|
---|
99 | changes in the backend.
|
---|
100 |
|
---|
101 | In the \c updateWidgets() function, we query the backend for
|
---|
102 | information it has about its abilities and present it in the GUI
|
---|
103 | of \c Window. We dissect it here:
|
---|
104 |
|
---|
105 | \snippet examples/phonon/capabilities/window.cpp outputDevices
|
---|
106 |
|
---|
107 | The
|
---|
108 | \l{Phonon::BackendCapabilities::Notifier::}{availableAudioOutputDevicesChanged()}
|
---|
109 | function is a member of the Phonon::BackendCapabilities namespace.
|
---|
110 | It returns a list of \l{Phonon::}{AudioOutputDevice}s, which gives
|
---|
111 | us information about a particular device, e.g., a sound card or a
|
---|
112 | USB headset.
|
---|
113 |
|
---|
114 | Note that \l{Phonon::}{AudioOutputDevice} and also
|
---|
115 | \l{Phonon::}{EffectDescription}, which is described shortly, are
|
---|
116 | typedefs of \l{Phonon::}{ObjectDescriptionType}.
|
---|
117 |
|
---|
118 | \omit
|
---|
119 | ###
|
---|
120 | The \l{Phonon::}{ObjectDescriptionModel} is a convenience
|
---|
121 | model that displays the names of the devices. Their
|
---|
122 | descriptions are shown as tooltips and disabled devices are
|
---|
123 | shown in gray.
|
---|
124 | \endomit
|
---|
125 |
|
---|
126 | \snippet examples/phonon/capabilities/window.cpp mimeTypes
|
---|
127 |
|
---|
128 | The MIME types supported are given as strings in a QStringList. We
|
---|
129 | can therefore create a list widget item with the string, and
|
---|
130 | append it to the \c mimeListWidget, which displays the available
|
---|
131 | MIME types.
|
---|
132 |
|
---|
133 | \snippet examples/phonon/capabilities/window.cpp effects
|
---|
134 |
|
---|
135 | As before we add the description and name to our widget, which in
|
---|
136 | this case is a QTreeWidget. A particular effect may also have
|
---|
137 | parameters, which are inserted in the tree as child nodes of their
|
---|
138 | effect.
|
---|
139 |
|
---|
140 | \snippet examples/phonon/capabilities/window.cpp effectsParameters
|
---|
141 |
|
---|
142 | The parameters are only accessible through an instance of the
|
---|
143 | \l{Phonon::}{Effect} class. Notice that an effect is created
|
---|
144 | with the effect description.
|
---|
145 |
|
---|
146 | The \l{Phonon::}{EffectParameter} contains information about one
|
---|
147 | of an effects parameters. We pick out some of the information to
|
---|
148 | describe the parameter in the tree widget.
|
---|
149 |
|
---|
150 | \section1 The main() function
|
---|
151 |
|
---|
152 | Because Phonon uses D-Bus on Linux, it is necessary to give the
|
---|
153 | application a name. You do this with
|
---|
154 | \l{QCoreApplication::}{setApplicationName()}.
|
---|
155 |
|
---|
156 | \snippet examples/phonon/capabilities/main.cpp everything
|
---|
157 | */
|
---|