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
44QT_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*/
88QMediaPlayerControl::~QMediaPlayerControl()
89{
90}
91
92/*!
93 Constructs a new media player control with the given \a parent.
94*/
95QMediaPlayerControl::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"
384QT_END_NAMESPACE
385
386