source: trunk/doc/src/examples/musicplayerexample.qdoc@ 651

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

trunk: Merged in qt 4.6.2 sources.

File size: 10.4 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2010 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:LGPL$
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
14** a written agreement between you and Nokia.
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** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example phonon/qmusicplayer
44 \title Music Player Example
45
46 The Music Player Example shows how to use Phonon - the multimedia
47 framework that comes with Qt - to create a simple music player.
48 The player can play music files, and provides simple playback
49 control, such as pausing, stopping, and resuming the music.
50
51 \image musicplayer.png
52
53 The player has a button group with the play, pause, and stop
54 buttons familiar from most music players. The top-most slider
55 controls the position in the media stream, and the bottom slider
56 allows adjusting the sound volume.
57
58 The user can use a file dialog to add music files to a table,
59 which displays meta information about the music - such as the
60 title, album, and artist. Each row contains information about a
61 single music file; to play it, the user selects that row and
62 presses the play button. Also, when a row is selected, the files
63 in the table are queued for playback.
64
65 Phonon offers playback of sound using an available audio device,
66 e.g., a sound card or an USB headset. For the implementation, we
67 use two objects: a \l{Phonon::}{MediaObject}, which controls the
68 playback, and an \l{Phonon::}{AudioOutput}, which can output the
69 audio to a sound device. We will explain how they cooperate when
70 we encounter them in the code. For a high-level introduction to
71 Phonon, see its \l{Phonon Overview}{overview}.
72
73 The API of Phonon is implemented through an intermediate
74 technology on each supported platform: DirectShow, QuickTime, and
75 GStreamer. The sound formats supported may therefore vary from
76 system to system. We do not in this example try to determine which
77 formats are supported, but let Phonon report an error if the user
78 tries to play an unsupported sound file.
79
80 Our player consists of one class, \c MainWindow, which both
81 constructs the GUI and handles the playback. We will now go
82 through the parts of its definition and implementation that
83 concerns Phonon.
84
85 \section1 MainWindow Class Definition
86
87 Most of the API in \c MainWindow is private, as is often the case
88 for classes that represent self-contained windows. We list Phonon
89 objects and slots we connect to their signals; we take a closer
90 look at them when we walk through the \c MainWindow
91 implementation.
92
93 \snippet examples/phonon/qmusicplayer/mainwindow.h 2
94
95 We use the \l{Phonon::}{SeekSlider} to move the current playback
96 position in the media stream, and the \l{Phonon::}{VolumeSlider}
97 controls the sound volume. Both of these widgets come ready made
98 with Phonon. We use another \l{Phonon::}{MediaObject},
99 metaInformationProvider, to get the meta information from the
100 music files. More on this later.
101
102 \snippet examples/phonon/qmusicplayer/mainwindow.h 1
103
104 The \l{Phonon::}{MediaObject} informs us of the state of the playback and
105 properties of the media it is playing back through a series of
106 signals. We connect the signals we need to slots in \c MainWindow.
107 The \c tableClicked() slot is connected to the table, so that we
108 know when the user requests playback of a new music file, by
109 clicking on the table.
110
111 \section1 MainWindow Class Implementation
112
113 The \c MainWindow class handles both the user interface and
114 Phonon. We will now take a look at the code relevant for Phonon.
115 The code required for setting up the GUI is explained elsewhere.
116
117 We start with the constructor:
118
119 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 0
120
121 We start by instantiating our media and audio output objects.
122 As mentioned, the media object knows how to playback
123 multimedia (in our case sound files) while the audio output
124 can send it to a sound device.
125
126 For the playback to work, the media and audio output objects need
127 to get in contact with each other, so that the media object can
128 send the sound to the audio output. Phonon is a graph based
129 framework, i.e., its objects are nodes that can be connected by
130 paths. Objects are connected using the \c createPath() function,
131 which is part of the Phonon namespace.
132
133 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 1
134
135 We also connect signals of the media object to slots in our \c
136 MainWindow. We will examine them shortly.
137
138 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 2
139
140 Finally, we call private helper functions to set up the GUI.
141 The \c setupUi() function contains code for setting up the seek
142 , and volume slider. We move on to \c setupUi():
143
144 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 3
145 \dots
146 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 4
147
148 After creating the widgets, they must be supplied with the
149 \l{Phonon::}{MediaObject} and \l{Phonon::}{AudioOutput} objects
150 they should control.
151
152 In the \c setupActions(), we connect the actions for the play,
153 pause, and stop tool buttons, to slots of the media object.
154
155 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 5
156
157 We move on to the slots of \c MainWindow, starting with \c
158 addFiles():
159
160 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 6
161
162 In the \c addFiles() slot, we add files selected by the user to
163 the \c sources list. We then set the first source selected on the
164 \c metaInformationProvider \l{Phonon::}{MediaObject}, which will
165 send a state changed signal when the meta information is resolved;
166 we have this signal connected to the \c metaStateChanged() slot.
167
168 The media object informs us of state changes by sending the \c
169 stateChanged() signal. The \c stateChanged() slot is connected
170 to this signal.
171
172 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 9
173
174 The \l{Phonon::MediaObject::}{errorString()} function gives a
175 description of the error that is suitable for users of a Phonon
176 application. The two values of the \l{Phonon::}{ErrorState} enum
177 helps us determine whether it is possible to try to play the same
178 file again.
179
180 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 10
181
182 We update the GUI when the playback state changes, i.e., when it
183 starts, pauses, stops, or resumes.
184
185 The media object will report other state changes, as defined by the
186 \l{Phonon::}{State} enum.
187
188 The \c tick() slot is connected to a \l{Phonon::}{MediaObject} signal which is
189 emitted when the playback position changes:
190
191 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 11
192
193 The \c time is given in milliseconds.
194
195 When the table is clicked on with the mouse, \c tableClick()
196 is invoked:
197
198 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 12
199
200 Since we stop the media object, we first check whether it is
201 currently playing. \c row contains the row in the table that was
202 clicked upon; the indices of \c sources follows the table, so we
203 can simply use \c row to find the new source.
204
205 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 13
206
207 When the media source changes, we simply need to select the
208 corresponding row in the table.
209
210 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 14
211
212 When \c metaStateChanged() is invoked, \c
213 metaInformationProvider has resolved the meta data for its current
214 source. A \l{Phonon::}{MediaObject} will do this before
215 entering \l{Phonon::}{StoppedState}. Note that we could also
216 have used the \l{Phonon::MediaObject::}{metaDataChanged()} signal for
217 this purpose.
218
219 Some of the meta data is then chosen to be displayed in the
220 music table. A file might not contain the meta data requested,
221 in which case an empty string is returned.
222
223 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 15
224
225 If we have media sources in \c sources of which meta information
226 is not resolved, we set a new source on the \c
227 metaInformationProvider, which will invoke \c metaStateChanged()
228 again.
229
230 We move on to the \c aboutToFinish() slot:
231
232 \snippet examples/phonon/qmusicplayer/mainwindow.cpp 16
233
234 When a file is finished playing, the Music Player will move on and
235 play the next file in the table. This slot is connected to the
236 \l{Phonon::}{MediaObject}'s
237 \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is
238 guaranteed to be emitted while there is still time to enqueue
239 another file for playback.
240
241 \section1 The main() function.
242
243 Phonon requires that the application has a name; it is set with
244 \l{QCoreApplication::}{setApplicationName()}. This is because
245 D-Bus, which is used by Phonon on Linux systems, demands this.
246
247 \snippet examples/phonon/qmusicplayer/main.cpp 1
248*/
Note: See TracBrowser for help on using the repository browser.