Add API Navigator.Listener.onJumpToLocator() (#60)

Author: mickael-menu

CHANGELOG.md

@@ -24,6 +24,9 @@ All notable changes to this project will be documented in this file. Take a look
         return true
     }
     ```
+* The new `Navigator.Listener.onJumpToLocator()` API is called every time the navigator jumps to an explicit location, which might break the linear reading progression.
+    * For example, it is called when clicking on internal links or programmatically calling `Navigator.go()`, but not when turning pages.
+    * You can use this callback to implement a navigation history by differentiating between continuous and discontinuous moves.
 
 ### Fixed
 

readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt

@@ -72,7 +72,20 @@ interface Navigator {
      */
     fun goBackward(animated: Boolean = false, completion: () -> Unit = {}): Boolean
 
-    interface Listener
+    interface Listener {
+
+        /**
+         * Called when the navigator jumps to an explicit location, which might break the linear
+         * reading progression.
+         *
+         * For example, it is called when clicking on internal links or programmatically calling
+         * [go], but not when turning pages.
+         *
+         * You can use this callback to implement a navigation history by differentiating between
+         * continuous and discontinuous moves.
+         */
+        fun onJumpToLocator(locator: Locator) {}
+    }
 
     @Deprecated("Use [currentLocator.value] instead", ReplaceWith("currentLocator.value"))
     val currentLocation: Locator? get() = currentLocator.value
@@ -194,4 +207,6 @@ interface MediaNavigator : Navigator {
      * Seeks relatively from the current position in the current resource.
      */
     fun seekRelative(offset: Duration)
+
+    interface Listener : Navigator.Listener
 }

readium/navigator/src/main/java/org/readium/r2/navigator/epub/EpubNavigatorFragment.kt

@@ -274,6 +274,8 @@ class EpubNavigatorFragment private constructor(
     internal var pendingLocator: Locator? = null
 
     override fun go(locator: Locator, animated: Boolean, completion: () -> Unit): Boolean {
+        listener?.onJumpToLocator(locator)
+
         val href = locator.href
             // Remove anchor
             .substringBefore("#")

readium/navigator/src/main/java/org/readium/r2/navigator/image/ImageNavigatorFragment.kt

@@ -157,6 +157,7 @@ class ImageNavigatorFragment private constructor(
         val resourceIndex = publication.readingOrder.indexOfFirstWithHref(locator.href)
                 ?: return false
 
+        listener?.onJumpToLocator(locator)
         currentPagerPosition = resourceIndex
         resourcePager.currentItem = currentPagerPosition
 

readium/navigator/src/main/java/org/readium/r2/navigator/media/MediaSessionNavigator.kt

@@ -8,8 +8,6 @@ package org.readium.r2.navigator.media
 
 import android.media.session.PlaybackState
 import android.os.Bundle
-import android.os.Handler
-import android.os.Looper
 import android.support.v4.media.MediaMetadataCompat
 import android.support.v4.media.session.MediaControllerCompat
 import android.support.v4.media.session.MediaControllerCompat.TransportControls
@@ -43,9 +41,12 @@ private val skipBackwardInterval: Duration = Duration.seconds(30)
 class MediaSessionNavigator(
     override val publication: Publication,
     val publicationId: PublicationId,
-    val controller: MediaControllerCompat
+    val controller: MediaControllerCompat,
+    var listener: Listener? = null
 ) : MediaNavigator, CoroutineScope by MainScope() {
 
+    interface Listener: MediaNavigator.Listener
+
     /**
      * Indicates whether the media session is loaded with a resource from this [publication]. This
      * is necessary because a single media session could be used to play multiple publications.
@@ -176,6 +177,8 @@ class MediaSessionNavigator(
     override fun go(locator: Locator, animated: Boolean, completion: () -> Unit): Boolean {
         if (!isActive) return false
 
+        listener?.onJumpToLocator(locator)
+
         transportControls.playFromMediaId("$publicationId#${locator.href}", Bundle().apply {
             putParcelable("locator", locator)
         })

readium/navigator/src/main/java/org/readium/r2/navigator/pdf/PdfNavigatorFragment.kt

@@ -183,13 +183,14 @@ class PdfNavigatorFragment internal constructor(
     private val _currentLocator = MutableStateFlow(initialLocator ?: publication.readingOrder.first().toLocator())
 
     override fun go(locator: Locator, animated: Boolean, completion: () -> Unit): Boolean {
+        listener?.onJumpToLocator(locator)
         // FIXME: `position` is relative to the full publication, which would cause an issue for a publication containing several PDFs resources. Only publications with a single PDF resource are supported at the moment, so we're fine.
         val pageNumber = locator.locations.page ?: locator.locations.position ?: 1
         return goToHref(locator.href, pageNumberToIndex(pageNumber), animated, completion)
     }
 
     override fun go(link: Link, animated: Boolean, completion: () -> Unit): Boolean =
-        goToHref(link.href, pageNumberToIndex(1), animated, completion)
+        go(link.toLocator(), animated = animated, completion = completion)
 
     override fun goForward(animated: Boolean, completion: () -> Unit): Boolean {
         val page = pageIndexToNumber(pdfView.currentPage)