source: trunk/doc/src/examples/capabilitiesexample.qdoc@ 892

Last change on this file since 892 was 846, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 6.2 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 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: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 qt-info@nokia.com.
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*/
Note: See TracBrowser for help on using the repository browser.