1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2016 The Qt Company Ltd. |
4 | ** Contact: https://www.qt.io/licensing/ |
5 | ** |
6 | ** This file is part of the Qt Toolkit. |
7 | ** |
8 | ** $QT_BEGIN_LICENSE:LGPL$ |
9 | ** Commercial License Usage |
10 | ** Licensees holding valid commercial Qt licenses may use this file in |
11 | ** accordance with the commercial license agreement provided with the |
12 | ** Software or, alternatively, in accordance with the terms contained in |
13 | ** a written agreement between you and The Qt Company. For licensing terms |
14 | ** and conditions see https://www.qt.io/terms-conditions. For further |
15 | ** information use the contact form at https://www.qt.io/contact-us. |
16 | ** |
17 | ** GNU Lesser General Public License Usage |
18 | ** Alternatively, this file may be used under the terms of the GNU Lesser |
19 | ** General Public License version 3 as published by the Free Software |
20 | ** Foundation and appearing in the file LICENSE.LGPL3 included in the |
21 | ** packaging of this file. Please review the following information to |
22 | ** ensure the GNU Lesser General Public License version 3 requirements |
23 | ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. |
24 | ** |
25 | ** GNU General Public License Usage |
26 | ** Alternatively, this file may be used under the terms of the GNU |
27 | ** General Public License version 2.0 or (at your option) the GNU General |
28 | ** Public license version 3 or any later version approved by the KDE Free |
29 | ** Qt Foundation. The licenses are as published by the Free Software |
30 | ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 |
31 | ** included in the packaging of this file. Please review the following |
32 | ** information to ensure the GNU General Public License requirements will |
33 | ** be met: https://www.gnu.org/licenses/gpl-2.0.html and |
34 | ** https://www.gnu.org/licenses/gpl-3.0.html. |
35 | ** |
36 | ** $QT_END_LICENSE$ |
37 | ** |
38 | ****************************************************************************/ |
39 | |
40 | #include "qmediaplayercontrol.h" |
41 | #include "qmediacontrol_p.h" |
42 | #include "qmediaplayer.h" |
43 | |
44 | QT_BEGIN_NAMESPACE |
45 | |
46 | |
47 | /*! |
48 | \class QMediaPlayerControl |
49 | \inmodule QtMultimedia |
50 | |
51 | |
52 | \ingroup multimedia_control |
53 | |
54 | |
55 | \brief The QMediaPlayerControl class provides access to the media playing |
56 | functionality of a QMediaService. |
57 | |
58 | If a QMediaService can play media is will implement QMediaPlayerControl. |
59 | This control provides a means to set the \l {setMedia()}{media} to play, |
60 | \l {play()}{start}, \l {pause()} {pause} and \l {stop()}{stop} playback, |
61 | \l {setPosition()}{seek}, and control the \l {setVolume()}{volume}. |
62 | It also provides feedback on the \l {duration()}{duration} of the media, |
63 | the current \l {position()}{position}, and \l {bufferStatus()}{buffering} |
64 | progress. |
65 | |
66 | The functionality provided by this control is exposed to application |
67 | code through the QMediaPlayer class. |
68 | |
69 | The interface name of QMediaPlayerControl is \c org.qt-project.qt.mediaplayercontrol/5.0 as |
70 | defined in QMediaPlayerControl_iid. |
71 | |
72 | \sa QMediaService::requestControl(), QMediaPlayer |
73 | */ |
74 | |
75 | /*! |
76 | \macro QMediaPlayerControl_iid |
77 | |
78 | \c org.qt-project.qt.mediaplayercontrol/5.0 |
79 | |
80 | Defines the interface name of the QMediaPlayerControl class. |
81 | |
82 | \relates QMediaPlayerControl |
83 | */ |
84 | |
85 | /*! |
86 | Destroys a media player control. |
87 | */ |
88 | QMediaPlayerControl::~QMediaPlayerControl() |
89 | { |
90 | } |
91 | |
92 | /*! |
93 | Constructs a new media player control with the given \a parent. |
94 | */ |
95 | QMediaPlayerControl::QMediaPlayerControl(QObject *parent): |
96 | QMediaControl(*new QMediaControlPrivate, parent) |
97 | { |
98 | } |
99 | |
100 | /*! |
101 | \fn QMediaPlayerControl::state() const |
102 | |
103 | Returns the state of a player control. |
104 | */ |
105 | |
106 | /*! |
107 | \fn QMediaPlayerControl::stateChanged(QMediaPlayer::State newState) |
108 | |
109 | Signals that the state of a player control has changed to \a newState. |
110 | |
111 | \sa state() |
112 | */ |
113 | |
114 | /*! |
115 | \fn QMediaPlayerControl::mediaStatus() const |
116 | |
117 | Returns the status of the current media. |
118 | */ |
119 | |
120 | |
121 | /*! |
122 | \fn QMediaPlayerControl::mediaStatusChanged(QMediaPlayer::MediaStatus status) |
123 | |
124 | Signals that the \a status of the current media has changed. |
125 | |
126 | \sa mediaStatus() |
127 | */ |
128 | |
129 | |
130 | /*! |
131 | \fn QMediaPlayerControl::duration() const |
132 | |
133 | Returns the duration of the current media in milliseconds. |
134 | */ |
135 | |
136 | /*! |
137 | \fn QMediaPlayerControl::durationChanged(qint64 duration) |
138 | |
139 | Signals that the \a duration of the current media has changed. |
140 | |
141 | \sa duration() |
142 | */ |
143 | |
144 | /*! |
145 | \fn QMediaPlayerControl::position() const |
146 | |
147 | Returns the current playback position in milliseconds. |
148 | */ |
149 | |
150 | /*! |
151 | \fn QMediaPlayerControl::setPosition(qint64 position) |
152 | |
153 | Sets the playback \a position of the current media. This will initiate a seek and it may take |
154 | some time for playback to reach the position set. |
155 | */ |
156 | |
157 | /*! |
158 | \fn QMediaPlayerControl::positionChanged(qint64 position) |
159 | |
160 | Signals the playback \a position has changed. |
161 | |
162 | This is only emitted in when there has been a discontinous change in the playback postion, such |
163 | as a seek or the position being reset. |
164 | |
165 | \sa position() |
166 | */ |
167 | |
168 | /*! |
169 | \fn QMediaPlayerControl::volume() const |
170 | |
171 | Returns the audio volume of a player control. |
172 | */ |
173 | |
174 | /*! |
175 | \fn QMediaPlayerControl::setVolume(int volume) |
176 | |
177 | Sets the audio \a volume of a player control. |
178 | |
179 | The volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume). |
180 | */ |
181 | |
182 | /*! |
183 | \fn QMediaPlayerControl::volumeChanged(int volume) |
184 | |
185 | Signals the audio \a volume of a player control has changed. |
186 | |
187 | \sa volume() |
188 | */ |
189 | |
190 | /*! |
191 | \fn QMediaPlayerControl::isMuted() const |
192 | |
193 | Returns the mute state of a player control. |
194 | */ |
195 | |
196 | /*! |
197 | \fn QMediaPlayerControl::setMuted(bool mute) |
198 | |
199 | Sets the \a mute state of a player control. |
200 | */ |
201 | |
202 | /*! |
203 | \fn QMediaPlayerControl::mutedChanged(bool mute) |
204 | |
205 | Signals a change in the \a mute status of a player control. |
206 | |
207 | \sa isMuted() |
208 | */ |
209 | |
210 | /*! |
211 | \fn QMediaPlayerControl::bufferStatus() const |
212 | |
213 | Returns the buffering progress of the current media. Progress is measured in the percentage |
214 | of the buffer filled. |
215 | */ |
216 | |
217 | /*! |
218 | \fn QMediaPlayerControl::bufferStatusChanged(int percentFilled) |
219 | |
220 | Signal the amount of the local buffer filled as a percentage by \a percentFilled. |
221 | |
222 | \sa bufferStatus() |
223 | */ |
224 | |
225 | /*! |
226 | \fn QMediaPlayerControl::isAudioAvailable() const |
227 | |
228 | Identifies if there is audio output available for the current media. |
229 | |
230 | Returns true if audio output is available and false otherwise. |
231 | */ |
232 | |
233 | /*! |
234 | \fn QMediaPlayerControl::audioAvailableChanged(bool audioAvailable) |
235 | |
236 | Signals that there has been a change in the availability of audio output \a audioAvailable. |
237 | |
238 | \sa isAudioAvailable() |
239 | */ |
240 | |
241 | /*! |
242 | \fn QMediaPlayerControl::isVideoAvailable() const |
243 | |
244 | Identifies if there is video output available for the current media. |
245 | |
246 | Returns true if video output is available and false otherwise. |
247 | */ |
248 | |
249 | /*! |
250 | \fn QMediaPlayerControl::videoAvailableChanged(bool videoAvailable) |
251 | |
252 | Signal that the availability of visual content has changed to \a videoAvailable. |
253 | |
254 | \sa isVideoAvailable() |
255 | */ |
256 | |
257 | /*! |
258 | \fn QMediaPlayerControl::isSeekable() const |
259 | |
260 | Identifies if the current media is seekable. |
261 | |
262 | Returns true if it possible to seek within the current media, and false otherwise. |
263 | */ |
264 | |
265 | /*! |
266 | \fn QMediaPlayerControl::seekableChanged(bool seekable) |
267 | |
268 | Signals that the \a seekable state of a player control has changed. |
269 | |
270 | \sa isSeekable() |
271 | */ |
272 | |
273 | /*! |
274 | \fn QMediaPlayerControl::availablePlaybackRanges() const |
275 | |
276 | Returns a range of times in milliseconds that can be played back. |
277 | |
278 | Usually for local files this is a continuous interval equal to [0..duration()] |
279 | or an empty time range if seeking is not supported, but for network sources |
280 | it refers to the buffered parts of the media. |
281 | */ |
282 | |
283 | /*! |
284 | \fn QMediaPlayerControl::availablePlaybackRangesChanged(const QMediaTimeRange &ranges) |
285 | |
286 | Signals that the available media playback \a ranges have changed. |
287 | |
288 | \sa QMediaPlayerControl::availablePlaybackRanges() |
289 | */ |
290 | |
291 | /*! |
292 | \fn qreal QMediaPlayerControl::playbackRate() const |
293 | |
294 | Returns the rate of playback. |
295 | */ |
296 | |
297 | /*! |
298 | \fn QMediaPlayerControl::setPlaybackRate(qreal rate) |
299 | |
300 | Sets the \a rate of playback. |
301 | */ |
302 | |
303 | /*! |
304 | \fn QMediaPlayerControl::media() const |
305 | |
306 | Returns the current media source. |
307 | */ |
308 | |
309 | /*! |
310 | \fn QMediaPlayerControl::mediaStream() const |
311 | |
312 | Returns the current media stream. This is only a valid if a stream was passed to setMedia(). |
313 | |
314 | \sa setMedia() |
315 | */ |
316 | |
317 | /*! |
318 | \fn QMediaPlayerControl::setMedia(const QMediaContent &media, QIODevice *stream) |
319 | |
320 | Sets the current \a media source. If a \a stream is supplied; data will be read from that |
321 | instead of attempting to resolve the media source. The media source may still be used to |
322 | supply media information such as mime type. |
323 | |
324 | Setting the media to a null QMediaContent will cause the control to discard all |
325 | information relating to the current media source and to cease all I/O operations related |
326 | to that media. |
327 | |
328 | Qt resource files are never passed as is. If the service supports |
329 | QMediaServiceProviderHint::StreamPlayback, a \a stream is supplied, pointing to an opened |
330 | QFile. Otherwise, the resource is copied into a temporary file and \a media contains the |
331 | url to that file. |
332 | */ |
333 | |
334 | /*! |
335 | \fn QMediaPlayerControl::mediaChanged(const QMediaContent& content) |
336 | |
337 | Signals that the current media \a content has changed. |
338 | */ |
339 | |
340 | /*! |
341 | \fn QMediaPlayerControl::play() |
342 | |
343 | Starts playback of the current media. |
344 | |
345 | If successful the player control will immediately enter the \l {QMediaPlayer::PlayingState} |
346 | {playing} state. |
347 | |
348 | \sa state() |
349 | */ |
350 | |
351 | /*! |
352 | \fn QMediaPlayerControl::pause() |
353 | |
354 | Pauses playback of the current media. |
355 | |
356 | If successful the player control will immediately enter the \l {QMediaPlayer::PausedState} |
357 | {paused} state. |
358 | |
359 | \sa state(), play(), stop() |
360 | */ |
361 | |
362 | /*! |
363 | \fn QMediaPlayerControl::stop() |
364 | |
365 | Stops playback of the current media. |
366 | |
367 | If successful the player control will immediately enter the \l {QMediaPlayer::StoppedState} |
368 | {stopped} state. |
369 | */ |
370 | |
371 | /*! |
372 | \fn QMediaPlayerControl::error(int error, const QString &errorString) |
373 | |
374 | Signals that an \a error has occurred. The \a errorString provides a more detailed explanation. |
375 | */ |
376 | |
377 | /*! |
378 | \fn QMediaPlayerControl::playbackRateChanged(qreal rate) |
379 | |
380 | Signal emitted when playback rate changes to \a rate. |
381 | */ |
382 | |
383 | #include "moc_qmediaplayercontrol.cpp" |
384 | QT_END_NAMESPACE |
385 | |
386 | |