From f66d159d0a7fae0bd12398440528d85b72507820 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mickae=CC=88l=20Menu?= Date: Wed, 24 Nov 2021 10:45:31 +0100 Subject: [PATCH 1/2] Add API `Navigator.Listener.onJumpToLocator()` --- CHANGELOG.md | 3 +++ .../main/java/org/readium/r2/navigator/Navigator.kt | 13 ++++++++++++- .../r2/navigator/epub/EpubNavigatorFragment.kt | 2 ++ .../r2/navigator/image/ImageNavigatorFragment.kt | 1 + .../r2/navigator/media/MediaSessionNavigator.kt | 9 ++++++--- .../r2/navigator/pdf/PdfNavigatorFragment.kt | 3 ++- 6 files changed, 26 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d2a3ed33e..9095945f10 100644 --- a/CHANGELOG.md +++ b/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 will jump to a discontinuous location. + * 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 diff --git a/readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt b/readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt index 6ae10ad752..8d38e63827 100644 --- a/readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt +++ b/readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt @@ -72,7 +72,16 @@ interface Navigator { */ fun goBackward(animated: Boolean = false, completion: () -> Unit = {}): Boolean - interface Listener + interface Listener { + + /** + * Called when the navigator will interrupt the linear reading progression to jump to the + * given locator. + * + * This occurs for example when clicking on internal links or calling [go] programmatically. + */ + fun onJumpToLocator(locator: Locator) {} + } @Deprecated("Use [currentLocator.value] instead", ReplaceWith("currentLocator.value")) val currentLocation: Locator? get() = currentLocator.value @@ -194,4 +203,6 @@ interface MediaNavigator : Navigator { * Seeks relatively from the current position in the current resource. */ fun seekRelative(offset: Duration) + + interface Listener : Navigator.Listener } diff --git a/readium/navigator/src/main/java/org/readium/r2/navigator/epub/EpubNavigatorFragment.kt b/readium/navigator/src/main/java/org/readium/r2/navigator/epub/EpubNavigatorFragment.kt index 29cc9b2bf0..7d3ffaa0ab 100644 --- a/readium/navigator/src/main/java/org/readium/r2/navigator/epub/EpubNavigatorFragment.kt +++ b/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("#") diff --git a/readium/navigator/src/main/java/org/readium/r2/navigator/image/ImageNavigatorFragment.kt b/readium/navigator/src/main/java/org/readium/r2/navigator/image/ImageNavigatorFragment.kt index 50780e5708..8b20d87bf3 100644 --- a/readium/navigator/src/main/java/org/readium/r2/navigator/image/ImageNavigatorFragment.kt +++ b/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 diff --git a/readium/navigator/src/main/java/org/readium/r2/navigator/media/MediaSessionNavigator.kt b/readium/navigator/src/main/java/org/readium/r2/navigator/media/MediaSessionNavigator.kt index ec265bfdfe..87428da673 100644 --- a/readium/navigator/src/main/java/org/readium/r2/navigator/media/MediaSessionNavigator.kt +++ b/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) }) diff --git a/readium/navigator/src/main/java/org/readium/r2/navigator/pdf/PdfNavigatorFragment.kt b/readium/navigator/src/main/java/org/readium/r2/navigator/pdf/PdfNavigatorFragment.kt index 0055590298..5ecb930585 100644 --- a/readium/navigator/src/main/java/org/readium/r2/navigator/pdf/PdfNavigatorFragment.kt +++ b/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) From 12d18840b07c5c8bcedbc60f5ffc8f109670df36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mickae=CC=88l=20Menu?= Date: Fri, 26 Nov 2021 10:26:05 +0100 Subject: [PATCH 2/2] Improve documentation --- CHANGELOG.md | 2 +- .../main/java/org/readium/r2/navigator/Navigator.kt | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9095945f10..cd77898213 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,7 +24,7 @@ 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 will jump to a discontinuous location. +* 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. diff --git a/readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt b/readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt index 8d38e63827..62d9276105 100644 --- a/readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt +++ b/readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt @@ -75,10 +75,14 @@ interface Navigator { interface Listener { /** - * Called when the navigator will interrupt the linear reading progression to jump to the - * given locator. + * Called when the navigator jumps to an explicit location, which might break the linear + * reading progression. * - * This occurs for example when clicking on internal links or calling [go] programmatically. + * 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) {} }