Dox and API naming improvements

qgis · Mar 12, 2020 · 92b2574 · 92b2574
1 parent 9be31cc
commit 92b2574
Show file tree

Hide file tree

Showing 8 changed files with 182 additions and 112 deletions.
diff --git a/python/core/auto_generated/qgstemporalcontroller.sip.in b/python/core/auto_generated/qgstemporalcontroller.sip.in
@@ -24,17 +24,17 @@ updates of the objects temporal range.
 %End
   public:
 
-    QgsTemporalController( QObject *parent = 0 );
+    QgsTemporalController( QObject *parent /TransferThis/ = 0 );
 %Docstring
-Constructor for QgsTemporalController.
+Constructor for QgsTemporalController, with the specified ``parent`` object.
 %End
 
   signals:
 
     void updateTemporalRange( const QgsDateTimeRange &range );
 %Docstring
-Signals that a temporal ``range`` has changed and need to be updated to
-the related objects.
+Signals that a temporal ``range`` has changed and needs to be updated in
+all connected objects.
 %End
 
 };

diff --git a/python/core/auto_generated/qgstemporalnavigationobject.sip.in b/python/core/auto_generated/qgstemporalnavigationobject.sip.in
@@ -15,7 +15,7 @@
 class QgsTemporalNavigationObject : QgsTemporalController
 {
 %Docstring
-The QgsTemporalNavigationObject class
+Implements a temporal controller based on a frame by frame navigation and animation.
 
 .. versionadded:: 3.14
 %End
@@ -25,91 +25,111 @@ The QgsTemporalNavigationObject class
 %End
   public:
 
-    QgsTemporalNavigationObject( QObject *parent = 0 );
+    QgsTemporalNavigationObject( QObject *parent /TransferThis/ = 0 );
 %Docstring
-Constructor for QgsTemporalNavigationObject
+Constructor for QgsTemporalNavigationObject, with the specified ``parent`` object.
 %End
 
-    enum PlaybackMode
+    enum AnimationState
     {
       Forward,
       Reverse,
       Idle,
     };
 
-    void setPlayBackMode( PlaybackMode mode );
+    void setAnimationState( AnimationState state );
 %Docstring
-Sets the current playback mode.
+Sets the current animation ``state``.
 
-.. seealso:: :py:func:`playBackMode`
+.. seealso:: :py:func:`animationState`
 %End
 
-    PlaybackMode playBackMode() const;
+    AnimationState animationState() const;
 %Docstring
-Returns the current playback mode.
+Returns the current animation state.
 
-.. seealso:: :py:func:`setPlayBackMode`
+.. seealso:: :py:func:`setAnimationState`
 %End
 
-    void setTemporalExtents( QgsDateTimeRange temporalExtents );
+    void setTemporalExtents( const QgsDateTimeRange &extents );
 %Docstring
-Sets the navigation temporal extents.
+Sets the navigation temporal ``extents``, which dictate the earliest
+and latest date time possible in the animation.
+
+.. note::
+
+   Calling this will reset the currentFrameNumber() to the first frame.
 
 .. seealso:: :py:func:`temporalExtents`
 %End
 
     QgsDateTimeRange temporalExtents() const;
 %Docstring
-Returns the navigation temporal extent.
+Returns the navigation temporal extents, which dictate the earliest
+and latest date time possible in the animation.
 
 .. seealso:: :py:func:`setTemporalExtents`
 %End
 
-    void setCurrentFrameNumber( long long frameNumber );
+    void setCurrentFrameNumber( long long frame );
 %Docstring
-Sets the current frame value.
+Sets the current animation ``frame`` number.
+
+Caling this method will change the controllers current datetime range to match, based on the
+temporalExtents() and frameDuration() values.
 
 .. seealso:: :py:func:`currentFrameNumber`
 %End
 
     long long currentFrameNumber() const;
 %Docstring
-Returns the current set frame value.
+Returns the current frame number.
 
 .. seealso:: :py:func:`setCurrentFrameNumber`
 %End
 
-    void setFrameDuration( QgsInterval frameDuration );
+    void setFrameDuration( QgsInterval duration );
 %Docstring
-Sets the frame duration
+Sets the frame ``duration``, which dictates the temporal length of each frame in the animation.
+
+.. note::
+
+   Calling this will reset the currentFrameNumber() to the first frame.
 
 .. seealso:: :py:func:`frameDuration`
 %End
 
     QgsInterval frameDuration() const;
 %Docstring
-Returns the current set frame value.
+Returns the current set frame duration, which dictates the temporal length of each frame in the animation.
 
 .. seealso:: :py:func:`setFrameDuration`
 %End
 
     QgsDateTimeRange dateTimeRangeForFrameNumber( long long frame ) const;
 %Docstring
-Calculate the temporal range from the navigation start time, using
-current frame number and the frame duration.
+Calculates the temporal range associated with a particular animation ``frame``.
+
+This is calculated from the navigation start time (taken from temporalExtents()),
+the specified ``frame`` number, and the frame duration (see frameDuration()).
 %End
 
-    void setFramesPerSeconds( double framesPerSeconds );
+    void setFramesPerSeconds( double rate );
 %Docstring
-Sets the frames per seconds value. This is used to define
-the navigation frame rate.
+Sets the animation frame ``rate``, in frames per second.
+
+This setting controls the overall playback speed of the animation, i.e. how quickly
+a playing animation will advance to the next frame.
 
 .. seealso:: :py:func:`framesPerSeconds`
 %End
 
     double framesPerSeconds() const;
 %Docstring
-Returns the set frames per seconds value.
+Returns the animation frame rate, in frames per second.
+
+This setting controls the overall playback speed of the animation, i.e. how quickly
+a playing animation will advance to the next frame.
 
 .. seealso:: :py:func:`setFramesPerSeconds`
 %End
@@ -124,37 +144,53 @@ Returns the total number of frames for the navigation.
     void play();
 %Docstring
 Starts playing the temporal navigation from its current frame,
-using the direction specified by playBackMode()
+using the direction specified by animationState()
 %End
 
     void pause();
 %Docstring
-Stops the temporal navigation.
+Pauses the temporal navigation.
+
+Calling this slot changes the animation state to idle, preventing
+automatic advancement of frames.
+
+It does not affect the current animation frame number or the current
+temporal range of the controller.
 %End
 
-    void forward();
+    void playForward();
 %Docstring
-Starts the animation playing in a forward direction up till the end of frames.
+Starts the animation playing in a forward direction up till the end of all frames.
 %End
 
-    void backward();
+    void playBackward();
 %Docstring
 Starts the animation playing in a reverse direction until the beginning of the time range.
 %End
 
     void next();
 %Docstring
-Forward the temporal navigation by one frame.
+Advances to the next frame.
+
+.. note::
+
+   Calling this slot does not change the current animation state, i.e. a paused animation
+   will remain paused.
 %End
 
     void previous();
 %Docstring
-Decrement the temporal navigation by one frame.
+Jumps back to the previous frame.
+
+.. note::
+
+   Calling this slot does not change the current animation state, i.e. a paused animation
+   will remain paused.
 %End
 
     void rewindToStart();
 %Docstring
-Rewind the temporal navigation to start of the temporal extent.
+Rewinds the temporal navigation to start of the temporal extent.
 %End
 
     void skipToEnd();

diff --git a/src/core/qgsmaplayertemporalproperties.h b/src/core/qgsmaplayertemporalproperties.h
@@ -68,8 +68,8 @@ class CORE_EXPORT QgsMapLayerTemporalProperties : public QgsTemporalProperty
      */
     enum TemporalSource
     {
-      Layer = 0, //! Defined from layer .
-      Project = 1//! Defined from project time settings;
+      Layer = 0, //!< Layer's temporal range has been manually defined
+      Project = 1 //!< Layer should inherit its temporal range from the project's time settings
     };
 
     /**

diff --git a/src/core/qgstemporalcontroller.h b/src/core/qgstemporalcontroller.h
@@ -39,16 +39,16 @@ class CORE_EXPORT QgsTemporalController : public QObject
   public:
 
     /**
-     * Constructor for QgsTemporalController.
+     * Constructor for QgsTemporalController, with the specified \a parent object.
      *
     */
-    QgsTemporalController( QObject *parent = nullptr );
+    QgsTemporalController( QObject *parent SIP_TRANSFERTHIS = nullptr );
 
   signals:
 
     /**
-     * Signals that a temporal \a range has changed and need to be updated to
-     * the related objects.
+     * Signals that a temporal \a range has changed and needs to be updated in
+     * all connected objects.
      */
     void updateTemporalRange( const QgsDateTimeRange &range );
 

diff --git a/src/core/qgstemporalnavigationobject.cpp b/src/core/qgstemporalnavigationobject.cpp
@@ -63,7 +63,7 @@ QgsDateTimeRange QgsTemporalNavigationObject::dateTimeRangeForFrameNumber( long
   return QgsDateTimeRange( begin, mTemporalExtents.end() );
 }
 
-void QgsTemporalNavigationObject::setTemporalExtents( QgsDateTimeRange temporalExtents )
+void QgsTemporalNavigationObject::setTemporalExtents( const QgsDateTimeRange &temporalExtents )
 {
   mTemporalExtents = temporalExtents;
   setCurrentFrameNumber( 0 );
@@ -126,61 +126,56 @@ void QgsTemporalNavigationObject::play()
 void QgsTemporalNavigationObject::pause()
 {
   mNewFrameTimer->stop();
-  setPlayBackMode( PlaybackMode::Idle );
+  setAnimationState( AnimationState::Idle );
 }
 
-void QgsTemporalNavigationObject::forward()
+void QgsTemporalNavigationObject::playForward()
 {
-  setPlayBackMode( PlaybackMode::Forward );
+  setAnimationState( AnimationState::Forward );
   play();
   next();
 }
 
-void QgsTemporalNavigationObject::backward()
+void QgsTemporalNavigationObject::playBackward()
 {
-  setPlayBackMode( PlaybackMode::Reverse );
+  setAnimationState( AnimationState::Reverse );
   play();
   previous();
 }
 
 void QgsTemporalNavigationObject::next()
 {
-  long long frame = mCurrentFrameNumber + 1;
-  setCurrentFrameNumber( frame );
+  setCurrentFrameNumber( mCurrentFrameNumber + 1 );
 }
 
 void QgsTemporalNavigationObject::previous()
 {
-  long long frame = mCurrentFrameNumber - 1;
-  setCurrentFrameNumber( frame );
+  setCurrentFrameNumber( mCurrentFrameNumber - 1 );
 }
 
 void QgsTemporalNavigationObject::rewindToStart()
 {
-  long long frame = 0;
-  setCurrentFrameNumber( frame );
+  setCurrentFrameNumber( 0 );
 }
 
 void QgsTemporalNavigationObject::skipToEnd()
 {
-  long long frame = totalFrameCount();
+  const long long frame = totalFrameCount();
   setCurrentFrameNumber( frame );
 }
 
 long long QgsTemporalNavigationObject::totalFrameCount()
 {
   QgsInterval totalAnimationLength = mTemporalExtents.end() - mTemporalExtents.begin();
-  long long totalFrameCount = std::ceil( totalAnimationLength.seconds() / mFrameDuration.seconds() ) + 1;
-
-  return totalFrameCount;
+  return std::ceil( totalAnimationLength.seconds() / mFrameDuration.seconds() ) + 1;
 }
 
-void QgsTemporalNavigationObject::setPlayBackMode( PlaybackMode mode )
+void QgsTemporalNavigationObject::setAnimationState( AnimationState mode )
 {
   mPlayBackMode = mode;
 }
 
-QgsTemporalNavigationObject::PlaybackMode QgsTemporalNavigationObject::playBackMode() const
+QgsTemporalNavigationObject::AnimationState QgsTemporalNavigationObject::animationState() const
 {
   return mPlayBackMode;
 }