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 | */
|
---|