Add NavigationCamera#update for MapboxMap animations

[danesfeder]

Description

The NavigationCamera currently has a few tracking modes that make it simple for developers to engage or disengage camera tracking behavior. Although when tracking is engaged and, simultaneously, a normal MapboxMap animation such as MapboxMap#animateCamera conflict can occur as the animation fights our current tracking state.

What's the goal?

The goal is to better organize this experience for developers. We should have explicit options that clearly determine / state the behavior for these two APIs interacting.

How is it being implemented?

New APIs:

NavigationCamera#update(NavigationCameraUpdate)
NavigationCamera#update(NavigationCameraUpdate, int durationMs)
NavigationCamera#update(NavigationCameraUpdate, int durationMs, Callback)

new NavigationCameraUpdate(CameraUpdate)

• #setMode(CameraUpdateMode) - determines behavior with tracking

enum CameraUpdateMode

• DEFAULT - if tracking or resetting, provided animation will be ignored
• OVERRIDE - if tracking or retting, LocationComponent will be set to tracking NONE and animation will fire

Example usage:

NavigationCamera camera = ...;
camera.updateCameraTrackingMode(NAVIGATION_TRACKING_MODE_GPS);

CameraUpdate cameraUpdate = ...;
NavigationCameraUpdate navCameraUpdate = new NavigationCameraUpdate(cameraUpdate);
navCameraUpdate.setMode(CameraUpdateMode.DEFAULT);

camera.update(navCameraUpdate); // Ignored
camera.updateCameraTrackingMode(NAVIGATION_TRACKING_MODE_NONE);
camera.update(navCameraUpdate); // Fires animation

camera.updateCameraTrackingMode(NAVIGATION_TRACKING_MODE_GPS);
navCameraUpdate.setMode(CameraUpdateMode.OVERRIDE);
camera.update(navCameraUpdate); // Fires animation

Screenshots or Gifs

Code driving this .gif (DEFAULT behavior):

navigationMap.resetCameraPositionWith(NavigationCamera.NAVIGATION_TRACKING_MODE_GPS);
CameraUpdate cameraUpdate = cameraOverheadUpdate();
if (cameraUpdate != null) {
  NavigationCameraUpdate navUpdate = new NavigationCameraUpdate(cameraUpdate);
  navigationMap.retrieveCamera().update(navUpdate);
}

Code driving this .gif (OVERRIDE behavior):

navigationMap.resetCameraPositionWith(NavigationCamera.NAVIGATION_TRACKING_MODE_GPS);
CameraUpdate cameraUpdate = cameraOverheadUpdate();
if (cameraUpdate != null) {
  NavigationCameraUpdate navUpdate = new NavigationCameraUpdate(cameraUpdate).setMode(CameraUpdateMode.OVERRIDE);
  navigationMap.retrieveCamera().update(navUpdate);
}

How has this been tested?

• Tested in ComponentNavigationActivity
• Unit testing

Checklist

• I have made corresponding changes to the documentation (JavaDoc)
• I have tested locally / staging (including SNAPSHOT upstream dependencies if needed)
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have added an Activity example in the test app showing the new feature implemented

[LukasPaczos]

🚀 One minor comment + missing javadoc and should be ready to go.

[LukasPaczos]

This should only check if cameraMode != CameraMode.NONE.

[LukasPaczos]

NIT: this method is not called from anywhere else, it can just be cut and pasted into render.

[LukasPaczos]

Would it make sense to add something along the lines of

... that evokes powered flight. If the camera is in a tracking mode, this animation is going to be ignored, or break the tracking, based on the CameraUpdateMode.

to each javadoc entry?

[LukasPaczos]

🚢

[codecov-io]

Codecov Report

Merging #1849 into master will increase coverage by 0.28%.
The diff coverage is 72.54%.

@@             Coverage Diff              @@
##             master    #1849      +/-   ##
============================================
+ Coverage     31.86%   32.14%   +0.28%     
- Complexity      949      964      +15     
============================================
  Files           244      248       +4     
  Lines          8537     8577      +40     
  Branches        647      651       +4     
============================================
+ Hits           2720     2757      +37     
- Misses         5570     5572       +2     
- Partials        247      248       +1