1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
/****************************************************************************
**
** Copyright (C) 2011 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:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $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
*/
|
