Skip to content
Permalink
Browse files

Dox and API naming improvements

  • Loading branch information
nyalldawson committed Mar 11, 2020
1 parent 9be31cc commit 92b257440d4a2ac6cc0f5790528c2d91978cdf9f
@@ -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

};
@@ -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();
@@ -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
};

/**
@@ -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 );

@@ -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;
}

0 comments on commit 92b2574

Please sign in to comment.
You can’t perform that action at this time.