Replace a writable position() property with a seek() method.

Seeking is sometimes asynchronous, and more importantly nearly every
one using a slider for seeking ends up with a binding loop.

Change-Id: I45d92e19b0276c8b97c51c073754d1c9d3dc611e
Reviewed-by: Ling Hu <ling.hu@nokia.com>

examples/video/qmlvideo/qml/qmlvideo/VideoDummy.qml

@@ -71,4 +71,5 @@ Rectangle {
 
     function start() { }
     function stop() { }
+    function seek() { }
 }

examples/video/qmlvideo/qml/qmlvideo/VideoItem.qml

@@ -73,4 +73,5 @@ VideoOutput {
 
     function start() { mediaPlayer.play() }
     function stop() { mediaPlayer.stop() }
+    function seek(position) { mediaPlayer.seek(position); }
 }

examples/video/qmlvideo/qml/qmlvideo/VideoSeek.qml

@@ -65,7 +65,7 @@ Scene {
         }
         duration: content.contentItem() ? content.contentItem().duration : 0
         playPosition: content.contentItem() ? content.contentItem().position : 0
-        onSeekPositionChanged: { content.contentItem().position = seekPosition }
+        onSeekPositionChanged: { content.contentItem().seek(seekPosition); }
     }
 
     Component.onCompleted: root.content = content

src/imports/multimedia/qdeclarativeaudio.cpp

@@ -276,23 +276,6 @@ int QDeclarativeAudio::position() const
     return !m_complete ? m_position : m_player->position();
 }
 
-void QDeclarativeAudio::setPosition(int position)
-{
-    // QMediaPlayer clamps this to positive numbers
-    if (position < 0)
-        position = 0;
-
-    if (this->position() == position)
-        return;
-
-    m_position = position;
-
-    if (m_complete)
-        m_player->setPosition(m_position);
-    else
-        emit positionChanged();
-}
-
 qreal QDeclarativeAudio::volume() const
 {
     return !m_complete ? m_vol : qreal(m_player->volume()) / 100;
@@ -421,6 +404,34 @@ void QDeclarativeAudio::stop()
     setPlaybackState(QMediaPlayer::StoppedState);
 }
 
+/*!
+    \qmlmethod QtMultimedia5::Audio::seek(offset)
+
+    If the \l seekable property is true, seeks the current
+    playback position to \a offset.
+
+    Seeking may be asynchronous, so the \l position property
+    may not be updated immediately.
+
+    \sa seekable, position
+*/
+void QDeclarativeAudio::seek(int position)
+{
+    // QMediaPlayer clamps this to positive numbers
+    if (position < 0)
+        position = 0;
+
+    if (this->position() == position)
+        return;
+
+    m_position = position;
+
+    if (m_complete)
+        m_player->setPosition(m_position);
+    else
+        emit positionChanged();
+}
+
 /*!
     \qmlproperty url QtMultimedia5::Audio::source
 
@@ -522,7 +533,9 @@ QDeclarativeAudio::PlaybackState QDeclarativeAudio::playbackState() const
 
     This property holds the current playback position in milliseconds.
 
-    If the \l seekable property is true, this property can be set to seek to a new position.
+    To change this position, use the \l seek() method.
+
+    \sa seek()
 */
 
 /*!
@@ -575,7 +588,7 @@ bool QDeclarativeAudio::hasVideo() const
 
     This property holds whether position of the audio can be changed.
 
-    If true; setting a \l position value will cause playback to seek to the new position.
+    If true, calling the \l seek() method will cause playback to seek to the new position.
 */
 
 /*!
@@ -1321,7 +1334,9 @@ void QDeclarativeAudio::_q_statusChanged()
 
     This property holds the current playback position in milliseconds.
 
-    If the \l seekable property is true, this property can be set to seek to a new position.
+    To change this position, use the \l seek() method.
+
+    \sa seek()
 */
 
 /*!
@@ -1364,7 +1379,19 @@ void QDeclarativeAudio::_q_statusChanged()
 
     This property holds whether position of the audio can be changed.
 
-    If true; setting a \l position value will cause playback to seek to the new position.
+    If true, calling the \l seek() method will cause playback to seek to the new position.
+*/
+
+/*!
+    \qmlmethod QtMultimedia5::MediaPlayer::seek(offset)
+
+    If the \l seekable property is true, seeks the current
+    playback position to \a offset.
+
+    Seeking may be asynchronous, so the \l position property
+    may not be updated immediately.
+
+    \sa seekable, position
 */
 
 /*!

src/imports/multimedia/qdeclarativeaudio_p.h

@@ -82,7 +82,7 @@ class QDeclarativeAudio : public QObject, public QQmlParserStatus
     Q_PROPERTY(bool autoLoad READ isAutoLoad WRITE setAutoLoad NOTIFY autoLoadChanged)
     Q_PROPERTY(Status status READ status NOTIFY statusChanged)
     Q_PROPERTY(int duration READ duration NOTIFY durationChanged)
-    Q_PROPERTY(int position READ position WRITE setPosition NOTIFY positionChanged)
+    Q_PROPERTY(int position READ position NOTIFY positionChanged)
     Q_PROPERTY(qreal volume READ volume WRITE setVolume NOTIFY volumeChanged)
     Q_PROPERTY(bool muted READ isMuted WRITE setMuted NOTIFY mutedChanged)
     Q_PROPERTY(bool hasAudio READ hasAudio NOTIFY hasAudioChanged)
@@ -171,7 +171,6 @@ public:
     int duration() const;
 
     int position() const;
-    void setPosition(int position);
 
     qreal volume() const;
     void setVolume(qreal volume);
@@ -200,6 +199,7 @@ public Q_SLOTS:
     void play();
     void pause();
     void stop();
+    void seek(int position);
 
 Q_SIGNALS:
     void sourceChanged();

tests/auto/unit/qdeclarativeaudio/tst_qdeclarativeaudio.cpp

@@ -315,7 +315,7 @@ void tst_QDeclarativeAudio::nullPlayerControl()
     QCOMPARE(audio.duration(), 0);
 
     QCOMPARE(audio.position(), 0);
-    audio.setPosition(10000);
+    audio.seek(10000);
     QCOMPARE(audio.position(), 10000);
 
     QCOMPARE(audio.volume(), qreal(1.0));
@@ -369,7 +369,7 @@ void tst_QDeclarativeAudio::nullService()
     QCOMPARE(audio.duration(), 0);
 
     QCOMPARE(audio.position(), 0);
-    audio.setPosition(10000);
+    audio.seek(10000);
     QCOMPARE(audio.position(), 10000);
 
     QCOMPARE(audio.volume(), qreal(1.0));
@@ -611,17 +611,17 @@ void tst_QDeclarativeAudio::position()
     // QDeclarativeAudio won't bound set positions to the duration.  A media service may though.
     QCOMPARE(audio.duration(), 0);
 
-    audio.setPosition(450);
+    audio.seek(450);
     QCOMPARE(audio.position(), 450);
     QCOMPARE(provider.playerControl()->position(), qint64(450));
     QCOMPARE(spy.count(), 1);
 
-    audio.setPosition(-5403);
+    audio.seek(-5403);
     QCOMPARE(audio.position(), 0);
     QCOMPARE(provider.playerControl()->position(), qint64(0));
     QCOMPARE(spy.count(), 2);
 
-    audio.setPosition(-5403);
+    audio.seek(-5403);
     QCOMPARE(audio.position(), 0);
     QCOMPARE(provider.playerControl()->position(), qint64(0));
     QCOMPARE(spy.count(), 2);