Revisit navigator interfaces (#408)

Author: qnga

docs/migration-guide.md

@@ -166,16 +166,26 @@ navigator.addInputListener(object : InputListener {
 })
 ```
 
+### New navigator interfaces
+
+An important part of `VisualNavigator` was moved to `DirectionalNavigator`. A new `HyperlinkNavigator`
+interface implemented by the `EpubFragmentNavigator` provides the ability to intercept clicks on
+links to both internal and external URLs. Opening external URLs is no longer handled by the navigator,
+that's something you should do by yourself in the way you like.
+
 ### Edge tap and keyboard navigation
 
 Version 3.0.0 ships with a new `DirectionalNavigationAdapter` component replacing `EdgeTapNavigation`. This helper allows users to turn pages with arrow and space keys on their keyboard or by tapping the edge of the screen.
 
-It's easy to set it up with an implementation of `VisualNavigator`, as it implements `InputListener`.
+It's easy to set it up with an implementation of `DirectionalNavigator`, as it implements `InputListener`.
 
 ```kotlin
-navigator.addInputListener(DirectionalNavigationAdapter(
-    animatedTransition = true
-))
+navigator.addInputListener(
+    DirectionalNavigationAdapter(
+        navigator,
+        animatedTransition = true
+    )
+)
 ```
 
 `DirectionalNavigationAdapter` offers a lot of customization options. Take a look at its API.

readium/adapters/exoplayer/audio/src/main/java/org/readium/adapter/exoplayer/audio/ExoPlayerEngine.kt

@@ -205,19 +205,19 @@ public class ExoPlayerEngine private constructor(
         exoPlayer.pause()
     }
 
-    override fun seek(index: Int, position: Duration) {
-        exoPlayer.seekTo(index, position.inWholeMilliseconds)
+    override fun skipTo(index: Int, offset: Duration) {
+        exoPlayer.seekTo(index, offset.inWholeMilliseconds)
     }
 
-    override fun seekBy(offset: Duration) {
-        exoPlayer.seekBy(offset)
+    override fun skip(duration: Duration) {
+        exoPlayer.seekBy(duration)
     }
 
-    override fun seekForward() {
+    override fun skipForward() {
         exoPlayer.seekForward()
     }
 
-    override fun seekBackward() {
+    override fun skipBackward() {
         exoPlayer.seekBack()
     }
 

readium/adapters/pdfium/navigator/src/main/java/org/readium/adapter/pdfium/navigator/PdfiumEngineProvider.kt

@@ -8,8 +8,8 @@ package org.readium.adapter.pdfium.navigator
 
 import android.graphics.PointF
 import com.github.barteksc.pdfviewer.PDFView
+import org.readium.r2.navigator.OverflowNavigator
 import org.readium.r2.navigator.SimplePresentation
-import org.readium.r2.navigator.VisualNavigator
 import org.readium.r2.navigator.input.TapEvent
 import org.readium.r2.navigator.pdf.PdfDocumentFragmentInput
 import org.readium.r2.navigator.pdf.PdfEngineProvider
@@ -68,7 +68,7 @@ public class PdfiumEngineProvider(
         return settingsPolicy.settings(preferences)
     }
 
-    override fun computePresentation(settings: PdfiumSettings): VisualNavigator.Presentation =
+    override fun computePresentation(settings: PdfiumSettings): OverflowNavigator.Presentation =
         SimplePresentation(
             readingProgression = settings.readingProgression,
             scroll = true,

readium/adapters/pspdfkit/navigator/src/main/java/org/readium/adapter/pspdfkit/navigator/PsPdfKitEngineProvider.kt

@@ -8,8 +8,8 @@ package org.readium.adapter.pspdfkit.navigator
 
 import android.graphics.PointF
 import com.pspdfkit.configuration.PdfConfiguration
+import org.readium.r2.navigator.OverflowNavigator
 import org.readium.r2.navigator.SimplePresentation
-import org.readium.r2.navigator.VisualNavigator
 import org.readium.r2.navigator.input.TapEvent
 import org.readium.r2.navigator.pdf.PdfDocumentFragmentInput
 import org.readium.r2.navigator.pdf.PdfEngineProvider
@@ -68,7 +68,7 @@ public class PsPdfKitEngineProvider(
         return settingsPolicy.settings(preferences)
     }
 
-    override fun computePresentation(settings: PsPdfKitSettings): VisualNavigator.Presentation =
+    override fun computePresentation(settings: PsPdfKitSettings): OverflowNavigator.Presentation =
         SimplePresentation(
             readingProgression = settings.readingProgression,
             scroll = settings.scroll,

readium/navigator-media2/src/main/java/org/readium/navigator/media2/MediaMetadataFactory.kt

@@ -7,7 +7,7 @@ import androidx.media2.common.MediaMetadata
  *
  * The metadata are used for example in the media-style Android notification.
  */
-@ExperimentalMedia2
+@Deprecated("Use the new MediaMetadataFactory from the readium-navigator-media-common module.")
 public interface MediaMetadataFactory {
 
     /**

readium/navigator-media2/src/main/java/org/readium/navigator/media2/MediaNavigator.kt

@@ -55,7 +55,7 @@ import timber.log.Timber
  * providing [create] with it. If you don't, ExoPlayer will be used, without cache.
  * You can build your own [SessionPlayer] based on [ExoPlayer] using [ExoPlayerDataSource].
  */
-@ExperimentalMedia2
+@Deprecated("Use the new AudioNavigator from the readium-navigator-media-audio module.")
 @OptIn(ExperimentalTime::class)
 public class MediaNavigator private constructor(
     override val publication: Publication,
@@ -383,12 +383,12 @@ public class MediaNavigator private constructor(
         return true
     }
 
-    override fun goForward(animated: Boolean, completion: () -> Unit): Boolean {
+    public fun goForward(animated: Boolean, completion: () -> Unit): Boolean {
         launchAndRun({ goForward() }, completion)
         return true
     }
 
-    override fun goBackward(animated: Boolean, completion: () -> Unit): Boolean {
+    public fun goBackward(animated: Boolean, completion: () -> Unit): Boolean {
         launchAndRun({ goBackward() }, completion)
         return true
     }

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

@@ -9,8 +9,95 @@
 
 package org.readium.r2.navigator
 
+import kotlin.time.Duration
+import kotlinx.coroutines.flow.Flow
+import org.readium.r2.navigator.media.MediaPlayback
+
 @Deprecated("Use navigator fragments.", level = DeprecationLevel.ERROR)
 public interface IR2Activity
 
 @Deprecated("Use TtsNavigator.", level = DeprecationLevel.ERROR)
 public interface IR2TTS
+
+/**
+ * A navigator rendering an audio or video publication.
+ */
+@Deprecated("Use the new readium-navigator-media modules.")
+@OptIn(ExperimentalAudiobook::class)
+public interface MediaNavigator : Navigator {
+
+    /**
+     * Current playback information.
+     */
+    public val playback: Flow<MediaPlayback>
+
+    /**
+     * Indicates whether the navigator is currently playing.
+     */
+    public val isPlaying: Boolean
+
+    /**
+     * Sets the speed of the media playback.
+     *
+     * Normal speed is 1.0 and 0.0 is incorrect.
+     */
+    public fun setPlaybackRate(rate: Double)
+
+    /**
+     * Resumes or start the playback at the current location.
+     */
+    public fun play()
+
+    /**
+     * Pauses the playback.
+     */
+    public fun pause()
+
+    /**
+     * Toggles the playback.
+     * Can be useful as a handler for play/pause button.
+     */
+    public fun playPause()
+
+    /**
+     * Stops the playback.
+     *
+     * Compared to [pause], the navigator may clear its state in whatever way is appropriate. For
+     * example, recovering a player's resources.
+     */
+    public fun stop()
+
+    /**
+     * Seeks to the given time in the current resource.
+     */
+    public fun seekTo(position: Duration)
+
+    /**
+     * Seeks relatively from the current position in the current resource.
+     */
+    public fun seekRelative(offset: Duration)
+
+    public interface Listener : Navigator.Listener
+}
+
+/**
+ * Moves to the left content portion (eg. page) relative to the reading progression direction.
+ */
+@Deprecated(
+    "Use a DirectionalNavigationAdapter or goFoward and goBackward.",
+    level = DeprecationLevel.ERROR
+)
+public fun VisualNavigator.goLeft(animated: Boolean = false, completion: () -> Unit = {}): Boolean {
+    throw NotImplementedError()
+}
+
+/**
+ * Moves to the right content portion (eg. page) relative to the reading progression direction.
+ */
+@Deprecated(
+    "Use a DirectionalNavigationAdapter or goFoward and goBackward.",
+    level = DeprecationLevel.ERROR
+)
+public fun VisualNavigator.goRight(animated: Boolean = false, completion: () -> Unit = {}): Boolean {
+    throw NotImplementedError()
+}

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

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2023 Readium Foundation. All rights reserved.
+ * Use of this source code is governed by the BSD-style license
+ * available in the top-level LICENSE file of the project.
+ */
+
+package org.readium.r2.navigator
+
+import org.readium.r2.shared.ExperimentalReadiumApi
+import org.readium.r2.shared.publication.Link
+import org.readium.r2.shared.util.AbsoluteUrl
+
+/**
+ * A navigator supporting hyperlinks.
+ */
+@ExperimentalReadiumApi
+public interface HyperlinkNavigator : Navigator {
+
+    @ExperimentalReadiumApi
+    public interface Listener : Navigator.Listener {
+
+        /**
+         * Called when a link to an internal resource was clicked in the navigator.
+         *
+         * You can use this callback to perform custom navigation like opening a new window
+         * or other operations.
+         *
+         * By returning false the navigator wont try to open the link itself and it is up
+         * to the calling app to decide how to display the link.
+         */
+        @ExperimentalReadiumApi
+        public fun shouldFollowInternalLink(link: Link): Boolean { return true }
+
+        /**
+         * Called when a link to an external URL was activated in the navigator.
+         */
+        @ExperimentalReadiumApi
+        public fun onExternalLinkActivated(url: AbsoluteUrl)
+    }
+}