From 5e6bdc3c394b3dc906365fd082242f65edb246fa Mon Sep 17 00:00:00 2001 From: Peng Liu Date: Wed, 26 Jan 2022 12:11:02 +0200 Subject: [PATCH] [viewport] Align public API surface with iOS. (#1079) --- plugin-viewport/README.md | 25 +++++++------- .../plugin/viewport/ViewportPluginImpl.kt | 3 +- .../state/FollowPuckViewportStateImpl.kt | 13 ++----- .../state/OverviewViewportStateImpl.kt | 8 +---- .../plugin/viewport/ViewportPluginImplTest.kt | 7 ++-- .../state/FollowPuckViewportStateImplTest.kt | 20 +++++------ .../state/OverviewViewportStateImplTest.kt | 4 +-- .../MapboxViewportTransitionFactoryTest.kt | 18 +++++----- .../plugin/viewport/CompletionListener.kt | 3 ++ .../maps/plugin/viewport/ViewportConstants.kt | 26 ++++---------- .../maps/plugin/viewport/ViewportStatus.kt | 4 +-- .../plugin/viewport/ViewportStatusObserver.kt | 6 ++-- .../data/DefaultViewportTransitionOptions.kt | 10 +++--- .../data/FollowPuckViewportStateBearing.kt | 10 +++--- .../data/FollowPuckViewportStateOptions.kt | 34 ++++++++++--------- .../data/OverviewViewportStateOptions.kt | 10 +++--- .../plugin/viewport/data/ViewportOptions.kt | 6 ++-- .../data/ViewportStatusChangeReason.kt | 6 ++-- .../viewport/state/FollowPuckViewportState.kt | 2 ++ .../viewport/state/OverviewViewportState.kt | 2 ++ .../plugin/viewport/state/ViewportState.kt | 6 ++-- .../state/ViewportStateDataObserver.kt | 2 ++ .../transition/DefaultViewportTransition.kt | 2 ++ .../viewport/transition/ViewportTransition.kt | 2 ++ 24 files changed, 114 insertions(+), 115 deletions(-) diff --git a/plugin-viewport/README.md b/plugin-viewport/README.md index 83422b06e8..97f558fc41 100644 --- a/plugin-viewport/README.md +++ b/plugin-viewport/README.md @@ -10,7 +10,7 @@ At any given time, the viewport is either: - transitioning (camera is being managed by a ViewportTransition) Two ViewportState are provided by default that user can create instance from the ViewportPlugin: - * `viewport.makeFollowingViewportState(options): FollowingViewportState` + * `viewport.makeFollowPuckViewportState(options): FollowPuckViewportState` This state allows to follow user's location, and syncs the viewport position with the location puck provided by the LocationComponent. * `viewport.makeOverviewViewportState(options): OverviewViewportState` This state sets the viewport to cover user provided geometry with configurations. @@ -50,7 +50,7 @@ allprojects { } // In the app build.gradle file dependencies { - implementation 'com.mapbox.plugin:maps-viewport:10.3.0-beta.1' + implementation 'com.mapbox.plugin:maps-viewport:10.3.0-rc.1' } ``` @@ -58,10 +58,10 @@ dependencies { ```kotlin val viewportPlugin = mapView.viewport - val followingViewportState: FollowingViewportState = viewportPlugin.makeFollowingViewportState( - FollowingViewportStateOptions.Builder() - .bearing(FollowingViewportStateBearing.Constant(0.0)) - .frameAnimationDurationMs(500) + val followPuckViewportState: FollowPuckViewportState = viewportPlugin.makeFollowPuckViewportState( + FollowPuckViewportStateOptions.Builder() + .bearing(FollowPuckViewportStateBearing.Constant(0.0)) + .animationDurationMs(500) .padding(EdgeInsets(200.0 * resources.displayMetrics.density, 0.0, 0.0, 0.0)) .build() ) @@ -73,15 +73,14 @@ dependencies { ) } val immediateTransition = viewportPlugin.makeImmediateViewportTransition() - viewportPlugin.setTransition(immediateTransition, from = followingViewportState, to = overviewViewportState) - // transition from idle(the default state) to the created followingViewportState - viewportPlugin.transitionTo(followingViewportState) { isFinished -> - // the transtion has been completed with flag to check the finished status + // transition from idle(the default state) to the created followPuckViewportState with default transition + viewportPlugin.transitionTo(followPuckViewportState) { isFinished -> + // the transition has been completed with flag to check the finished status } ... - // transition from followingViewportState to overviewViewportState with the customised immediate transiton - viewportPlugin.transitionTo(overviewViewportState) { isFinished -> - // the transtion has been completed with flag to check the finished status + // transition from followPuckViewportState to overviewViewportState with immediate transition + viewportPlugin.transitionTo(overviewViewportState, immediateTransition) { isFinished -> + // the transition has been completed with flag to check the finished status } ``` diff --git a/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/ViewportPluginImpl.kt b/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/ViewportPluginImpl.kt index d73122ed40..6939f7af64 100644 --- a/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/ViewportPluginImpl.kt +++ b/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/ViewportPluginImpl.kt @@ -153,7 +153,8 @@ class ViewportPluginImpl(private val handler: Handler = Handler(Looper.getMainLo completionBlockInvoked = true if (isFinished) { // transfer camera updating responsibility to targetState - currentCancelable = targetState.startUpdatingCamera() + targetState.startUpdatingCamera() + currentCancelable = Cancelable { targetState.stopUpdatingCamera() } updateStatus( ViewportStatus.State(targetState), ViewportStatusChangeReason.TRANSITION_SUCCEEDED diff --git a/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportStateImpl.kt b/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportStateImpl.kt index 7815a6dbb3..60d478598e 100644 --- a/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportStateImpl.kt +++ b/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportStateImpl.kt @@ -134,17 +134,15 @@ internal class FollowPuckViewportStateImpl( if (!locationComponent.enabled) { Logger.w( TAG, - "Location component is required to be enabled to use FollowingViewportState, otherwise there would be no FollowingViewportState updates or ViewportTransition updates towards the FollowingViewportState." + "Location component is required to be enabled to use FollowPuckViewportState, otherwise there would be no FollowPuckViewportState updates or ViewportTransition updates towards the FollowPuckViewportState." ) } } /** * Start updating the camera for the current [ViewportState]. - * - * @return a handle that cancels the camera updates. */ - override fun startUpdatingCamera(): Cancelable { + override fun startUpdatingCamera() { checkLocationComponentEnablement() addIndicatorListenerIfNeeded() updateFrame( @@ -154,11 +152,6 @@ internal class FollowPuckViewportStateImpl( isFollowingStateRunning = true } } - return Cancelable { - isFollowingStateRunning = false - cancelAnimation() - removeIndicatorListenerIfNeeded() - } } /** @@ -239,6 +232,6 @@ internal class FollowPuckViewportStateImpl( } private companion object { - const val TAG = "FollowingViewportStateImpl" + const val TAG = "FollowPuckViewportStateImpl" } } \ No newline at end of file diff --git a/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/state/OverviewViewportStateImpl.kt b/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/state/OverviewViewportStateImpl.kt index 656c4ffbee..8518596457 100644 --- a/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/state/OverviewViewportStateImpl.kt +++ b/plugin-viewport/src/main/kotlin/com/mapbox/maps/plugin/viewport/state/OverviewViewportStateImpl.kt @@ -80,15 +80,9 @@ internal class OverviewViewportStateImpl( /** * Start updating the camera for the current [ViewportState]. - * - * @return a handle that cancels the camera updates. */ - override fun startUpdatingCamera(): Cancelable { + override fun startUpdatingCamera() { isOverviewStateRunning = true - return Cancelable { - isOverviewStateRunning = false - cancelAnimation() - } } /** diff --git a/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/ViewportPluginImplTest.kt b/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/ViewportPluginImplTest.kt index 6387086417..ca83c1a32f 100644 --- a/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/ViewportPluginImplTest.kt +++ b/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/ViewportPluginImplTest.kt @@ -49,7 +49,6 @@ class ViewportPluginImplTest { private val targetState = mockk() private val transition = mockk() private val transitionToCompletionListener = mockk() - private val stateUpdatingCancelable = mockk() private val transitionUpdateCancelable = mockk() private lateinit var viewportPlugin: ViewportPluginImpl @@ -63,12 +62,12 @@ class ViewportPluginImplTest { every { mapPluginProviderDelegate.camera } returns cameraPlugin every { cameraPlugin.addCameraAnimationsLifecycleListener(any()) } just runs every { cameraPlugin.removeCameraAnimationsLifecycleListener(any()) } just runs - every { targetState.startUpdatingCamera() } returns stateUpdatingCancelable + every { targetState.startUpdatingCamera() } just runs + every { targetState.stopUpdatingCamera() } just runs every { transition.run(any(), any()) } returns transitionUpdateCancelable every { transitionToCompletionListener.onComplete(any()) } just runs every { handler.post(any()) } returns true every { statusObserver.onViewportStatusChanged(any(), any(), any()) } just runs - every { stateUpdatingCancelable.cancel() } just runs every { transitionUpdateCancelable.cancel() } just runs viewportPlugin = ViewportPluginImpl(handler) viewportPlugin.onDelegateProvider(delegateProvider) @@ -331,7 +330,7 @@ class ViewportPluginImplTest { } } verifyOrder { - stateUpdatingCancelable.cancel() + targetState.stopUpdatingCamera() transition.run(newState, any()) } } diff --git a/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportStateImplTest.kt b/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportStateImplTest.kt index 3e2b545477..b5ff61978c 100644 --- a/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportStateImplTest.kt +++ b/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportStateImplTest.kt @@ -15,8 +15,8 @@ import com.mapbox.maps.plugin.locationcomponent.OnIndicatorBearingChangedListene import com.mapbox.maps.plugin.locationcomponent.OnIndicatorPositionChangedListener import com.mapbox.maps.plugin.locationcomponent.location import com.mapbox.maps.plugin.viewport.CAMERA_ANIMATIONS_UTILS -import com.mapbox.maps.plugin.viewport.DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH -import com.mapbox.maps.plugin.viewport.DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM +import com.mapbox.maps.plugin.viewport.DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH +import com.mapbox.maps.plugin.viewport.DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM import com.mapbox.maps.plugin.viewport.LOCATION_COMPONENT_UTILS import com.mapbox.maps.plugin.viewport.data.FollowPuckViewportStateBearing import com.mapbox.maps.plugin.viewport.data.FollowPuckViewportStateOptions @@ -109,8 +109,8 @@ class FollowPuckViewportStateImplTest { cameraOptions { bearing(testBearing) center(testCenter) - pitch(DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH) - zoom(DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM) + pitch(DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH) + zoom(DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM) padding(EdgeInsets(0.0, 0.0, 0.0, 0.0)) } ) @@ -162,8 +162,8 @@ class FollowPuckViewportStateImplTest { cameraOptions { center(testCenter) bearing(constantBearing) - zoom(DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM) - pitch(DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH) + zoom(DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM) + pitch(DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH) padding(EdgeInsets(0.0, 0.0, 0.0, 0.0)) } ) @@ -213,8 +213,8 @@ class FollowPuckViewportStateImplTest { cameraOptions { bearing(testBearing) center(testCenter) - pitch(DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH) - zoom(DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM) + pitch(DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH) + zoom(DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM) padding(EdgeInsets(0.0, 0.0, 0.0, 0.0)) } ) @@ -228,8 +228,8 @@ class FollowPuckViewportStateImplTest { cameraOptions { bearing(testBearing) center(testCenter) - pitch(DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH) - zoom(DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM) + pitch(DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH) + zoom(DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM) padding(EdgeInsets(0.0, 0.0, 0.0, 0.0)) } ) diff --git a/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/state/OverviewViewportStateImplTest.kt b/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/state/OverviewViewportStateImplTest.kt index 33017b3f01..d88850eb6a 100644 --- a/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/state/OverviewViewportStateImplTest.kt +++ b/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/state/OverviewViewportStateImplTest.kt @@ -166,7 +166,7 @@ class OverviewViewportStateImplTest { every { animatorSet.cancel() } just runs // test start updating camera - val cancelable = overviewState.startUpdatingCamera() + overviewState.startUpdatingCamera() assertTrue(overviewState.isOverviewStateRunning) // test updating overview state option to trigger an animation @@ -181,7 +181,7 @@ class OverviewViewportStateImplTest { } // test stop updating camera - cancelable.cancel() + overviewState.stopUpdatingCamera() assertFalse(overviewState.isOverviewStateRunning) verify { animatorSet.cancel() } verify { cameraPlugin.unregisterAnimators(animator) } diff --git a/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/transition/MapboxViewportTransitionFactoryTest.kt b/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/transition/MapboxViewportTransitionFactoryTest.kt index cc06a48ef2..1c310df261 100644 --- a/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/transition/MapboxViewportTransitionFactoryTest.kt +++ b/plugin-viewport/src/test/kotlin/com/mapbox/maps/plugin/viewport/transition/MapboxViewportTransitionFactoryTest.kt @@ -11,8 +11,8 @@ import com.mapbox.maps.plugin.delegates.MapCameraManagerDelegate import com.mapbox.maps.plugin.delegates.MapDelegateProvider import com.mapbox.maps.plugin.delegates.MapPluginProviderDelegate import com.mapbox.maps.plugin.viewport.CAMERA_ANIMATIONS_UTILS -import com.mapbox.maps.plugin.viewport.DEFAULT_FRAME_ANIMATION_DURATION_MS -import com.mapbox.maps.plugin.viewport.DEFAULT_STATE_TRANSITION_MAX_DURATION_MS +import com.mapbox.maps.plugin.viewport.DEFAULT_STATE_ANIMATION_DURATION_MS +import com.mapbox.maps.plugin.viewport.DEFAULT_TRANSITION_MAX_DURATION_MS import com.mapbox.maps.plugin.viewport.TRANSITION_UTILS import io.mockk.every import io.mockk.mockk @@ -70,7 +70,7 @@ class MapboxViewportTransitionFactoryTest { } returns mockk() transitionsFactory.transitionFromLowZoomToHighZoom( cameraOptions, - DEFAULT_STATE_TRANSITION_MAX_DURATION_MS + DEFAULT_TRANSITION_MAX_DURATION_MS ) assertEquals(-10.0, valueSlot.captured.targets.last(), EPS) @@ -93,7 +93,7 @@ class MapboxViewportTransitionFactoryTest { } returns mockk() transitionsFactory.transitionFromHighZoomToLowZoom( cameraOptions, - DEFAULT_STATE_TRANSITION_MAX_DURATION_MS + DEFAULT_TRANSITION_MAX_DURATION_MS ) assertEquals(-10.0, valueSlot.captured.targets.last(), EPS) @@ -113,7 +113,7 @@ class MapboxViewportTransitionFactoryTest { every { cameraPlugin.createBearingAnimator(capture(valueSlot), any(), any()) } returns mockk() - transitionsFactory.transitionLinear(cameraOptions, DEFAULT_FRAME_ANIMATION_DURATION_MS) + transitionsFactory.transitionLinear(cameraOptions, DEFAULT_STATE_ANIMATION_DURATION_MS) assertEquals(-10.0, valueSlot.captured.targets.last(), EPS) verify { normalizeBearing(10.0, 350.0) } @@ -130,10 +130,10 @@ class MapboxViewportTransitionFactoryTest { val animator = transitionsFactory.transitionFromLowZoomToHighZoom( TEST_CAMERA_OPTIONS, - DEFAULT_STATE_TRANSITION_MAX_DURATION_MS + DEFAULT_TRANSITION_MAX_DURATION_MS ) - verify { animatorSet.constrainDurationTo(DEFAULT_STATE_TRANSITION_MAX_DURATION_MS) } + verify { animatorSet.constrainDurationTo(DEFAULT_TRANSITION_MAX_DURATION_MS) } assertEquals(constrainedSet, animator) } @@ -148,10 +148,10 @@ class MapboxViewportTransitionFactoryTest { val animator = transitionsFactory.transitionFromHighZoomToLowZoom( TEST_CAMERA_OPTIONS, - DEFAULT_STATE_TRANSITION_MAX_DURATION_MS + DEFAULT_TRANSITION_MAX_DURATION_MS ) - verify { animatorSet.constrainDurationTo(DEFAULT_STATE_TRANSITION_MAX_DURATION_MS) } + verify { animatorSet.constrainDurationTo(DEFAULT_TRANSITION_MAX_DURATION_MS) } assertEquals(constrainedSet, animator) } diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/CompletionListener.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/CompletionListener.kt index bdfc858fd9..d5ea7c8e40 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/CompletionListener.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/CompletionListener.kt @@ -1,8 +1,11 @@ package com.mapbox.maps.plugin.viewport +import com.mapbox.maps.MapboxExperimental + /** * A listener that's notified when the action is completed. */ +@MapboxExperimental fun interface CompletionListener { /** * Notifies the action is completed. diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportConstants.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportConstants.kt index 612e7877c9..a97718244e 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportConstants.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportConstants.kt @@ -4,33 +4,19 @@ package com.mapbox.maps.plugin.viewport * The default maximum duration of the generated transitions set for the state transition options, * including delays between animators and their respective durations. */ -const val DEFAULT_STATE_TRANSITION_MAX_DURATION_MS = 3500L +const val DEFAULT_TRANSITION_MAX_DURATION_MS = 3500L /** * The default duration of the generated transitions set for the frame transition options. */ -const val DEFAULT_FRAME_ANIMATION_DURATION_MS = 1000L +const val DEFAULT_STATE_ANIMATION_DURATION_MS = 1000L /** - * The default pitch value for the follow viewport state. + * The default pitch value for the follow puck viewport state. */ -const val DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH = 45.0 +const val DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH = 45.0 /** - * The default zoom value for the follow viewport state. + * The default zoom value for the follow puck viewport state. */ -const val DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM = 16.35 - -/** - * Indicates that the [ViewportStatus] is changed due to programmatic reason. - * - * Used in the reason field of [ViewportStatusObserver] - */ -const val VIEWPORT_STATUS_OBSERVER_REASON_PROGRAMMATIC = "PROGRAMMATIC" - -/** - * Indicates that the [ViewportStatus] is changed due to user interaction reason. - * - * Used in the reason field of [ViewportStatusObserver] - */ -const val VIEWPORT_STATUS_OBSERVER_REASON_USER_INTERACTION = "USER_INTERACTION" \ No newline at end of file +const val DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM = 16.35 \ No newline at end of file diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatus.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatus.kt index ea29988dc7..7d0980dcbd 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatus.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatus.kt @@ -1,5 +1,6 @@ package com.mapbox.maps.plugin.viewport +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.viewport.state.ViewportState import com.mapbox.maps.plugin.viewport.transition.ViewportTransition import java.util.* @@ -9,11 +10,10 @@ import java.util.* * * It could be either a [ViewportState] or [ViewportTransition]. */ +@MapboxExperimental sealed class ViewportStatus { /** * Represents the current status is a [ViewportState]. - * - * The state is null if current status is IDLE. */ class State( /** diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatusObserver.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatusObserver.kt index 01054db171..b96b0867dd 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatusObserver.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/ViewportStatusObserver.kt @@ -1,16 +1,18 @@ package com.mapbox.maps.plugin.viewport +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.viewport.data.ViewportStatusChangeReason /** * Observer that gets notified whenever [ViewportStatus] changes. */ +@MapboxExperimental fun interface ViewportStatusObserver { /** * Called whenever [ViewportStatus] changes. * - * @param from The previous [ViewportStatus], null if the previous [ViewportStatus] is IDLE. - * @param to The current [ViewportStatus], null if the current [ViewportStatus] is IDLE. + * @param from The previous [ViewportStatus] + * @param to The current [ViewportStatus]. * @param reason The reason that the [ViewportStatus] has been changed. */ fun onViewportStatusChanged(from: ViewportStatus, to: ViewportStatus, reason: ViewportStatusChangeReason) diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/DefaultViewportTransitionOptions.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/DefaultViewportTransitionOptions.kt index 05d26b4800..0da0b89b20 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/DefaultViewportTransitionOptions.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/DefaultViewportTransitionOptions.kt @@ -1,16 +1,18 @@ package com.mapbox.maps.plugin.viewport.data -import com.mapbox.maps.plugin.viewport.DEFAULT_STATE_TRANSITION_MAX_DURATION_MS +import com.mapbox.maps.MapboxExperimental +import com.mapbox.maps.plugin.viewport.DEFAULT_TRANSITION_MAX_DURATION_MS /** * Options that impact the [DefaultViewportTransition]. */ +@MapboxExperimental class DefaultViewportTransitionOptions private constructor( /** * The maximum duration of the transitions in milliseconds, * including delays between animators and their respective durations. * - * Defaults to [DEFAULT_STATE_TRANSITION_MAX_DURATION_MS] milliseconds. + * Defaults to [DEFAULT_TRANSITION_MAX_DURATION_MS] milliseconds. */ val maxDurationMs: Long ) { @@ -40,13 +42,13 @@ class DefaultViewportTransitionOptions private constructor( * Builder for [DefaultViewportTransitionOptions] */ class Builder { - private var maxDurationMs: Long = DEFAULT_STATE_TRANSITION_MAX_DURATION_MS + private var maxDurationMs: Long = DEFAULT_TRANSITION_MAX_DURATION_MS /** * Sets maximum duration of the generated transitions set in milliseconds, * including delays between animators and their respective durations. * - * Defaults to [DEFAULT_STATE_TRANSITION_MAX_DURATION_MS] milliseconds. + * Defaults to [DEFAULT_TRANSITION_MAX_DURATION_MS] milliseconds. */ fun maxDurationMs(maxDurationMs: Long) = apply { this.maxDurationMs = maxDurationMs diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateBearing.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateBearing.kt index 062bbe66e4..d4faaec95c 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateBearing.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateBearing.kt @@ -1,15 +1,17 @@ package com.mapbox.maps.plugin.viewport.data +import com.mapbox.maps.MapboxExperimental import java.util.Objects /** - * Describes the camera bearing options for the [FollowingViewportState]. + * Describes the camera bearing options for the [FollowPuckViewportState]. */ +@MapboxExperimental sealed class FollowPuckViewportStateBearing { /** * The viewport's bearing is fixed to the given bearing. * - * @param bearing The bearing that the [FollowingViewportState] uses to generate camera updates. + * @param bearing The bearing that the [FollowPuckViewportState] uses to generate camera updates. */ class Constant(val bearing: Double) : FollowPuckViewportStateBearing() { /** @@ -25,7 +27,7 @@ sealed class FollowPuckViewportStateBearing { /** * Returns a String for the object. */ - override fun toString() = "FollowingViewportStateBearing#Constant(bearing=$bearing)" + override fun toString() = "FollowPuckViewportStateBearing#Constant(bearing=$bearing)" } /** @@ -48,6 +50,6 @@ sealed class FollowPuckViewportStateBearing { /** * Returns a String for the object. */ - override fun toString() = "FollowingViewportStateBearing#SyncWithLocationPuck" + override fun toString() = "FollowPuckViewportStateBearing#SyncWithLocationPuck" } } \ No newline at end of file diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateOptions.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateOptions.kt index 573b31c6df..091f21d030 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateOptions.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/FollowPuckViewportStateOptions.kt @@ -1,14 +1,16 @@ package com.mapbox.maps.plugin.viewport.data import com.mapbox.maps.EdgeInsets -import com.mapbox.maps.plugin.viewport.DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH -import com.mapbox.maps.plugin.viewport.DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM -import com.mapbox.maps.plugin.viewport.DEFAULT_FRAME_ANIMATION_DURATION_MS +import com.mapbox.maps.MapboxExperimental +import com.mapbox.maps.plugin.viewport.DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH +import com.mapbox.maps.plugin.viewport.DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM +import com.mapbox.maps.plugin.viewport.DEFAULT_STATE_ANIMATION_DURATION_MS import java.util.Objects /** - * Options that impact the [FollowingViewportState]. + * Options that impact the [FollowPuckViewportState]. */ +@MapboxExperimental class FollowPuckViewportStateOptions private constructor( /** * The edge padding of the map. @@ -17,11 +19,11 @@ class FollowPuckViewportStateOptions private constructor( /** * The default zoom that will be generated for camera following frames. * - * Defaults to [DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM]. + * Defaults to [DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM]. */ val zoom: Double?, /** - * The camera bearing configuration of the [FollowingViewportState]. + * The camera bearing configuration of the [FollowPuckViewportState]. * * Defaults to [FollowPuckViewportStateBearing.SyncWithLocationPuck] */ @@ -29,13 +31,13 @@ class FollowPuckViewportStateOptions private constructor( /** * The default pitch that will be generated for following camera frames. * - * Defaults to [DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH] degrees. + * Defaults to [DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH] degrees. */ val pitch: Double?, /** * The maximum duration between frames in milliseconds. * - * Defaults to [DEFAULT_FRAME_ANIMATION_DURATION_MS] milliseconds + * Defaults to [DEFAULT_STATE_ANIMATION_DURATION_MS] milliseconds */ val animationDurationMs: Long ) { @@ -65,18 +67,18 @@ class FollowPuckViewportStateOptions private constructor( * Returns a String for the object. */ override fun toString() = - "FollowingViewportStateOptions(padding=$padding, zoom=$zoom, bearing=$bearing, pitch=$pitch, animationDurationMs=$animationDurationMs)" + "FollowPuckViewportStateOptions(padding=$padding, zoom=$zoom, bearing=$bearing, pitch=$pitch, animationDurationMs=$animationDurationMs)" /** * Builder for [FollowPuckViewportStateOptions] */ class Builder { private var padding: EdgeInsets? = EdgeInsets(0.0, 0.0, 0.0, 0.0) - private var zoom: Double? = DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM + private var zoom: Double? = DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM private var bearing: FollowPuckViewportStateBearing? = FollowPuckViewportStateBearing.SyncWithLocationPuck - private var pitch: Double? = DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH - private var animationDurationMs: Long = DEFAULT_FRAME_ANIMATION_DURATION_MS + private var pitch: Double? = DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH + private var animationDurationMs: Long = DEFAULT_STATE_ANIMATION_DURATION_MS /** * The edge padding of the map. @@ -88,14 +90,14 @@ class FollowPuckViewportStateOptions private constructor( /** * The default zoom that will be generated for camera following frames. * - * Defaults to [DEFAULT_FOLLOW_VIEWPORT_STATE_ZOOM]. + * Defaults to [DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_ZOOM]. */ fun zoom(zoom: Double?) = apply { this.zoom = zoom } /** - * The camera bearing configuration of the [FollowingViewportState]. + * The camera bearing configuration of the [FollowPuckViewportState]. * * Defaults to [FollowPuckViewportStateBearing.SyncWithLocationPuck] */ @@ -106,7 +108,7 @@ class FollowPuckViewportStateOptions private constructor( /** * The default pitch that will be generated for following camera frames. * - * Defaults to [DEFAULT_FOLLOW_VIEWPORT_STATE_PITCH] degrees. + * Defaults to [DEFAULT_FOLLOW_PUCK_VIEWPORT_STATE_PITCH] degrees. */ fun pitch(pitch: Double?) = apply { this.pitch = pitch @@ -115,7 +117,7 @@ class FollowPuckViewportStateOptions private constructor( /** * The maximum duration between frames in milliseconds. * - * Defaults to [DEFAULT_FRAME_ANIMATION_DURATION_MS] milliseconds + * Defaults to [DEFAULT_STATE_ANIMATION_DURATION_MS] milliseconds */ fun animationDurationMs(duration: Long) = apply { this.animationDurationMs = duration diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/OverviewViewportStateOptions.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/OverviewViewportStateOptions.kt index 4724231c9b..53ebcbd69d 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/OverviewViewportStateOptions.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/OverviewViewportStateOptions.kt @@ -2,13 +2,15 @@ package com.mapbox.maps.plugin.viewport.data import com.mapbox.geojson.Geometry import com.mapbox.maps.EdgeInsets -import com.mapbox.maps.plugin.viewport.DEFAULT_FRAME_ANIMATION_DURATION_MS +import com.mapbox.maps.MapboxExperimental +import com.mapbox.maps.plugin.viewport.DEFAULT_STATE_ANIMATION_DURATION_MS import java.lang.IllegalArgumentException import java.util.* /** * Options that impact the [OverviewViewportState]. */ +@MapboxExperimental class OverviewViewportStateOptions private constructor( /** * The geometry that the OverviewState should cover. @@ -29,7 +31,7 @@ class OverviewViewportStateOptions private constructor( /** * The duration between frames in milliseconds. * - * Defaults to [DEFAULT_FRAME_ANIMATION_DURATION_MS] milliseconds + * Defaults to [DEFAULT_STATE_ANIMATION_DURATION_MS] milliseconds */ val animationDurationMs: Long ) { @@ -69,7 +71,7 @@ class OverviewViewportStateOptions private constructor( private var padding: EdgeInsets = EdgeInsets(0.0, 0.0, 0.0, 0.0) private var bearing: Double? = 0.0 private var pitch: Double? = 0.0 - private var animationDurationMs: Long = DEFAULT_FRAME_ANIMATION_DURATION_MS + private var animationDurationMs: Long = DEFAULT_STATE_ANIMATION_DURATION_MS /** * The geometry that the OverviewState should cover. @@ -102,7 +104,7 @@ class OverviewViewportStateOptions private constructor( /** * The duration between frames in milliseconds. * - * Defaults to [DEFAULT_FRAME_ANIMATION_DURATION_MS] milliseconds + * Defaults to [DEFAULT_STATE_ANIMATION_DURATION_MS] milliseconds */ fun animationDurationMs(duration: Long) = apply { this.animationDurationMs = duration diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/ViewportOptions.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/ViewportOptions.kt index 8322a17c9f..5073fcc944 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/ViewportOptions.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/ViewportOptions.kt @@ -1,13 +1,15 @@ package com.mapbox.maps.plugin.viewport.data +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.viewport.state.ViewportState /** * Options that impact the [ViewportPlugin]. */ +@MapboxExperimental class ViewportOptions private constructor( /** - * Indicates whether to transition [ViewportState] to IDLE (null) when user interact with the map + * Indicates whether to transition [ViewportState] to IDLE when user interact with the map * using gestures. * * Defaults to true. @@ -43,7 +45,7 @@ class ViewportOptions private constructor( private var transitionsToIdleUponUserInteraction: Boolean = true /** - * Indicates whether to transition [ViewportState] to IDLE (null) when user interact with the map + * Indicates whether to transition [ViewportState] to IDLE when user interact with the map * using gestures. * * Defaults to true. diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/ViewportStatusChangeReason.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/ViewportStatusChangeReason.kt index 76cba16e4a..491d090187 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/ViewportStatusChangeReason.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/data/ViewportStatusChangeReason.kt @@ -1,15 +1,17 @@ package com.mapbox.maps.plugin.viewport.data +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.viewport.ViewportStatus /** * The reason why the [ViewportStatus] has been changed. */ -class ViewportStatusChangeReason( +@MapboxExperimental +class ViewportStatusChangeReason private constructor( /** * The string describing the change reason. */ - val reason: String + private val reason: String ) { /** * Indicates whether some other object is "equal to" this one. diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportState.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportState.kt index d13defb90e..0cc766e1a5 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportState.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/FollowPuckViewportState.kt @@ -1,5 +1,6 @@ package com.mapbox.maps.plugin.viewport.state +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.locationcomponent.LocationComponentPlugin import com.mapbox.maps.plugin.viewport.data.FollowPuckViewportStateOptions @@ -11,6 +12,7 @@ import com.mapbox.maps.plugin.viewport.data.FollowPuckViewportStateOptions * Users are responsible to create the viewport states and keep a reference to these states for * future operations. */ +@MapboxExperimental interface FollowPuckViewportState : ViewportState { /** * Describes the configuration options of the state. diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/OverviewViewportState.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/OverviewViewportState.kt index f224fdeb24..8f34c132bb 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/OverviewViewportState.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/OverviewViewportState.kt @@ -1,5 +1,6 @@ package com.mapbox.maps.plugin.viewport.state +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.viewport.data.OverviewViewportStateOptions /** @@ -8,6 +9,7 @@ import com.mapbox.maps.plugin.viewport.data.OverviewViewportStateOptions * Users are responsible to create the viewport states and keep a reference to these states for * future operations. */ +@MapboxExperimental interface OverviewViewportState : ViewportState { /** * Describes the configuration options of the state. diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/ViewportState.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/ViewportState.kt index b38eb9b2ca..09f6ac73fe 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/ViewportState.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/ViewportState.kt @@ -1,5 +1,6 @@ package com.mapbox.maps.plugin.viewport.state +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.animation.Cancelable import com.mapbox.maps.plugin.viewport.ViewportPlugin @@ -12,6 +13,7 @@ import com.mapbox.maps.plugin.viewport.ViewportPlugin * Users are responsible to create the viewport states and keep a reference to these states for * future operations. */ +@MapboxExperimental interface ViewportState { /** * Observe the new camera options produced by the [ViewportState], it can be used to get the @@ -24,10 +26,8 @@ interface ViewportState { /** * Start updating the camera for the current [ViewportState]. - * - * @return a handle that cancels the camera updates. */ - fun startUpdatingCamera(): Cancelable + fun startUpdatingCamera() /** * Stop updating the camera for the current [ViewportState]. diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/ViewportStateDataObserver.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/ViewportStateDataObserver.kt index aa40b65a50..a889ed08ae 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/ViewportStateDataObserver.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/state/ViewportStateDataObserver.kt @@ -1,10 +1,12 @@ package com.mapbox.maps.plugin.viewport.state import com.mapbox.maps.CameraOptions +import com.mapbox.maps.MapboxExperimental /** * Observer that gets notified whenever new data is available. */ +@MapboxExperimental fun interface ViewportStateDataObserver { /** * Notifies that new data is available. diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/transition/DefaultViewportTransition.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/transition/DefaultViewportTransition.kt index 7068aa4e4c..b8c160d635 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/transition/DefaultViewportTransition.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/transition/DefaultViewportTransition.kt @@ -1,10 +1,12 @@ package com.mapbox.maps.plugin.viewport.transition +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.viewport.data.DefaultViewportTransitionOptions /** * The default [ViewportTransition] that transitions Viewport to the target [ViewportState]. */ +@MapboxExperimental interface DefaultViewportTransition : ViewportTransition { /** * Describes the configuration options for the [DefaultViewportTransition]. diff --git a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/transition/ViewportTransition.kt b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/transition/ViewportTransition.kt index a1ac45f6bf..643be5d223 100644 --- a/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/transition/ViewportTransition.kt +++ b/sdk-base/src/main/java/com/mapbox/maps/plugin/viewport/transition/ViewportTransition.kt @@ -1,5 +1,6 @@ package com.mapbox.maps.plugin.viewport.transition +import com.mapbox.maps.MapboxExperimental import com.mapbox.maps.plugin.animation.Cancelable import com.mapbox.maps.plugin.viewport.CompletionListener import com.mapbox.maps.plugin.viewport.state.ViewportState @@ -7,6 +8,7 @@ import com.mapbox.maps.plugin.viewport.state.ViewportState /** * Defines how to transition to another [ViewportState]. */ +@MapboxExperimental fun interface ViewportTransition { /** * Run the [ViewportTransition] from current viewport to the target [ViewportState].