[JAVA] About the camera change event of Google Maps Android API

The Google Maps library for Android has an event GoogleMap.OnCameraChangeListener that occurs when the camera is changed (= change to position, rotation, tilt).

However, with the August 2016 release, `ʻOnCameraChangeListener`` has been deprecated and four new events have been added instead.

• Release Notes - August 1, 2016 ｜  Google Maps Android API

This release introduces a set of new camera change listeners for camera motion start, ongoing, and end events. You can also see why the camera is moving, whether it's caused by user gestures, built-in API animations or developer-controlled movements. Below is a summary of the new listeners. For details, see the guide to camera change events. (Issue 4636)

• The onCameraMoveStarted() callback of the OnCameraMoveStartedListener is invoked when the camera starts moving. The callback method receives a reason for the camera motion.
• The onCameraMove() callback of the OnCameraMoveListener is invoked multiple times while the camera is moving or the user is interacting with the touch screen.
• The OnCameraIdle() callback of the OnCameraIdleListener is invoked when the camera stops moving and the user has stopped interacting with the map.
• The OnCameraMoveCanceled() callback of the OnCameraMoveCanceledListener is invoked when the current camera movement has been interrupted.

onCameraMoveStarted-When the camera starts moving

Occurs once immediately after the camera starts moving. The same applies to moving the camera by methods such as ʻupdateCamera`` and ʻanimateCamera``, and by gestures such as dragging and pinching.

onCameraMoveIdle-When the camera has finished moving

Occurs once immediately after the camera movement is complete. This means that whenever any view change occurs, ʻonCameraMoveIdle`` is always called once at the end. The ʻonCameraMoveIdle is still called when the animation is cancelled. It is similar in position to the deprecated `ʻonCameraChange. By the way, after ʻonCameraChange`` is called, ʻonCameraMoveIdle`` is called.

If ʻonCameraMoveStarted`` and ʻonCameraMoveIdle are always paired, there are ** cases where they are not **. This is the case when the map is moved by dragging the map while the map is being moved by `ʻanimateCamera. This will be discussed later.

onCameraMove-when the camera moves

Occurs when the camera moves. For direct camera position movements with moveCamera, this event ** may or may not occur **. Animated moves with `ʻanimateCamera`` raise this event during the animation. It also occurs with gesture operations such as dragging and pinching.

onCameraMoveCanceled-When the animation is canceled

Occurs when an animated camera move, such as `ʻanimateCamera``, is canceled by some operation. "Some operation" is

• Called by stopAnimation during animation
• Tap or drag the screen during the animation

is.

[Bonus] Callback of `ʻanimateCamera``

`ʻanimateCamera`` can specify a callback that can receive the completion / cancellation of the animation.

public final void animateCamera (
    CameraUpdate update, 
    GoogleMap.CancelableCallback callback)

Event occurrence for each case

I made a sample application and tried to find out what kind of event would occur in the actual operation.

Execution of updateCamera method

1. onCameraMoveStarted
2. onCameraMove ← May not occur
3. ~~onCameraChange~~
4. onCameraIdle

** It seems that ʻonCameraMove`` may or may not occur **, I was not sure about the condition (it seems that ʻonCameraMove does not occur because the position changes. ). Since `ʻonCameraChange is deprecated, it has a strikethrough.

Execution of animateCamera method (without interruption)

1. onCameraMoveStarted
2. onCameraMove
3. onCameraMove
4. ・ ・ ・
5. animateCamera_onFinish
6. ~~onCameraChange~~
7. onCameraIdle

```onCameraMove is called multiple times during the move. The number of times depends on the speed of the animation. When the move is complete, the `ʻanimateCamera method callback will be notified ofʻonFinish`` and thenʻonCameraIdle`` will be called.

Execution of animateCamera method → Execution of stopAnimation

1. onCameraMoveStarted
2. onCameraMove
3. ・ ・ ・
4. onCameraMove
5. Call stopAnimation
6. onCameraMoveCanceled
7. animateCamera_onCancel
8. ~~onCameraChange~~
9. onCameraIdle

If you call stopAnimation during animation, the camera will stop moving and you will be notified of the stop in the order of ʻonCameraMoveCanceled`` → ʻanimateCamera_onCancel. After that, `ʻonCameraIdle is called just as it was when it was completed.

Execution of animateCamera method → Drag while moving to move the map

1. onCameraMoveStarted ← Start moving by animateCamera
2. onCameraMove
3. ・ ・ ・
4. onCameraMove
5. Drag to move the map
6. onCameraMoveCanceled
7. onCameraMoveStarted ← Start moving by dragging
8. animateCamera_onCancel
9. onCameraMove
10. onCameraMove
11. ・ ・ ・
12. Stop dragging
13. ~~ onCameraChange ~~ ← End of movement by animateCamera?
14. onCameraMove
15. onCameraMove
16. ~~ onCameraChange ~~ ← End of movement by dragging?
17. onCameraIdle

If you drag while moving the map, ʻonCameraMoveCanceled`` will notify you of the interruption and immediately notify you of ʻonCameraMoveStarted as a new camera move. It is after that that `ʻanimateCamera is notified of the animation cancellation` ʻanimateCamera_onCancel``.

After that, ʻonCameraMove`` by dragging occurred continuously, and when dragging was stopped, ~~ ʻonCameraChange ~~ was called twice, and `ʻonCameraIdle was called once at the end.

The following is a summary of points to note in this case.

• Before ʻonCancel`` is notified to ʻanimateCamera, `ʻonCameraMoveStarted is notified by dragging.
• ʻonCameraMoveStarted`` is notified twice (when calling ʻanimateCamera and when dragging starts), but` ʻonCameraIdle is notified only once at the end.

When streaming multiple events with RxJava etc., you have to be aware of the order and number of events that occur, but I feel that it may be a problem at that time.

Call stopAnimation when non-animated

1. ~~onCameraChange~~
2. onCameraIdle

Just calling stopAnimation will call ~~ ʻonCameraChange`` ~~, ʻonCameraIdle``. It feels bad.

Summary

• You can use ʻonCameraIdle`` as an alternative to the deprecated ʻonCameraChange``, but be aware that the timing of occurrence may be different for Bimyo!
• The newly added ʻonCameraMoveStarted`` can start moving the camera, and ʻonCameraMove`` can receive the moving camera.
• ʻonCameraXXXX`` will notify you not only when the camera is moved by the method, but also when the camera is moved by the gesture. The end / interruption of the animation of ʻanimateCamera`` is received by the argument callback.

[Bonus] Google Maps SDK for iOS

In the Google Maps SDK for iOS, our sister library, camera-related events

• Protocol Reference  ｜  Google Maps SDK for iOS

It is in. according to this,

• willMove
• didChangeCameraPosition
• idleAtCameraPosition

there is. It's annoying because it's for Android. .. ..