|
| 1 | +# Navigator |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +A navigator is a component of the [Readium architecture](https://readium.org/architecture/) used to render and navigate through the content of a publication. This is a core building block for adding a reader to your application. |
| 6 | + |
| 7 | +The Readium toolkit comes with several navigator implementations that work with different publication formats. Some are Android `Fragment`s, designed to be added to your view hierarchy (e.g. `EpubNavigatorFragment`). Others are chromeless and can be used in the background, such as `TtsNavigator` and `AudioNavigator`. |
| 8 | + |
| 9 | +| | EPUB | PDF | LCP PDF | WebPub | Audiobook | CBZ | Divina | |
| 10 | +|--------------------------|--------------------|--------------------|--------------------|--------------------|--------------------|--------------------|--------------------| |
| 11 | +| `EpubNavigatorFragment` | :heavy_check_mark: | | | :heavy_check_mark: | | | | |
| 12 | +| `PdfNavigatorFragment` | | :heavy_check_mark: | :heavy_check_mark: | | | | | |
| 13 | +| `ImageNavigatorFragment` | | | | | | :heavy_check_mark: | :heavy_check_mark: | |
| 14 | +| `AudioNavigator` | | | | | :heavy_check_mark: | | | |
| 15 | +| `TtsNavigator` | :heavy_check_mark: | | | | | | | |
| 16 | + |
| 17 | +### Navigator APIs |
| 18 | + |
| 19 | +The navigators implement a set of shared interfaces to help reuse the reading logic across publication formats. For example, use the `Navigator` interface instead of specific implementations (e.g. `EpubNavigatorFragment`) to create a location history manager that works with all types of navigators. |
| 20 | + |
| 21 | +You can write your own navigators and integrate them into your app with minimal changes by implementing the same interfaces. |
| 22 | + |
| 23 | +#### `Navigator` interface |
| 24 | + |
| 25 | +All navigators implement the `Navigator` interface, which provides the foundation for navigating resources in a `Publication`. Use it to traverse the content of the publication or observe the current location with `currentLocator`. |
| 26 | + |
| 27 | +It does not specify how the content is presented to the user. |
| 28 | + |
| 29 | +#### `VisualNavigator` interface |
| 30 | + |
| 31 | +Navigators rendering the content visually on the screen should implement the `VisualNavigator` interface. It provides information about the nature of the presentation (e.g. scrolled, right-to-left, etc.) and can be used to observe input events, such as taps or keyboard strokes. |
| 32 | + |
| 33 | +#### `MediaNavigator` interface |
| 34 | + |
| 35 | +The `MediaNavigator` interface is implemented by navigators rendering a publication as audio or video content. You can use it to control the playback or observe its status. |
| 36 | + |
| 37 | +[See the corresponding user guide for more information](media-navigator.md). |
| 38 | + |
| 39 | +##### `TimeBasedMediaNavigator` interface |
| 40 | + |
| 41 | +A time-based `MediaNavigator` renders an audio or video content with time locations. It is suited for audiobook or media overlay navigators. |
| 42 | + |
| 43 | +##### `TextAwareMediaNavigator` interface |
| 44 | + |
| 45 | +A text-aware `MediaNavigator` synchronizes utterances (e.g. sentences) with their corresponding audio or video clips. It can be used for text-to-speech, media overlays, and subtitled navigators. |
| 46 | + |
| 47 | +#### `SelectableNavigator` interface |
| 48 | + |
| 49 | +Navigators that enable users to select parts of the content, such as text or audio range selection, should implement `SelectableNavigator`. An app can use a selectable navigator to extract the `Locator` and content of the selected portion. |
| 50 | + |
| 51 | +#### `DecorableNavigator` interface |
| 52 | + |
| 53 | +A decorable navigator is able to render arbitrary decorations over a publication. It can be used to draw highlights over a publication. |
| 54 | + |
| 55 | +[See the corresponding proposal for more information](https://readium.org/architecture/proposals/008-decorator-api.html). |
| 56 | + |
| 57 | +## Instantiating a navigator |
| 58 | + |
| 59 | +### Visual navigators |
| 60 | + |
| 61 | +The Visual navigators are implemented as `Fragment` and must be added to your Android view hierarchy. |
| 62 | + |
| 63 | +#### `EpubNavigatorFragment` |
| 64 | + |
| 65 | +First, create an `EpubNavigatorFactory` from your `Publication` instance. You can optionally provide custom defaults for the user preferences. |
| 66 | + |
| 67 | +```kotlin |
| 68 | +val navigatorFactory = EpubNavigatorFactory( |
| 69 | + publication = publication, |
| 70 | + configuration = EpubNavigatorFactory.Configuration( |
| 71 | + defaults = EpubDefaults( |
| 72 | + pageMargins = 1.4 |
| 73 | + ) |
| 74 | + ) |
| 75 | +) |
| 76 | +``` |
| 77 | + |
| 78 | +Then, you need to setup the `FragmentFactory` in your custom parent `Fragment`. See `EpubReaderFragment` in the Test App for a complete example. |
| 79 | + |
| 80 | +:point_up: This is one way to set up the `EpubNavigatorFragment` in your view hierarchy. Choose what works best for your application. |
| 81 | + |
| 82 | +```kotlin |
| 83 | +class EpubReaderFragment : Fragment(), EpubNavigatorFragment.Listener { |
| 84 | + |
| 85 | + lateinit var navigator: EpubNavigatorFragment |
| 86 | + |
| 87 | + override fun onCreate(savedInstanceState: Bundle?) { |
| 88 | + // You are responsible for creating/restoring the `NavigatorFactory`, |
| 89 | + // for example from an in-memory repository. |
| 90 | + // See `ReaderRepository` in the Test App for an example. |
| 91 | + val navigatorFactory = ... |
| 92 | + |
| 93 | + // You should restore the initial location from your view model. |
| 94 | + childFragmentManager.fragmentFactory = |
| 95 | + navigatorFactory.createFragmentFactory( |
| 96 | + initialLocator = viewModel.initialLocator, |
| 97 | + listener = this |
| 98 | + ) |
| 99 | + |
| 100 | + // IMPORTANT: Set the `fragmentFactory` before calling `super`. |
| 101 | + super.onCreate(savedInstanceState) |
| 102 | + } |
| 103 | + |
| 104 | + override fun onCreateView( |
| 105 | + inflater: LayoutInflater, |
| 106 | + container: ViewGroup?, |
| 107 | + savedInstanceState: Bundle? |
| 108 | + ): View { |
| 109 | + val view = super.onCreateView(inflater, container, savedInstanceState) |
| 110 | + val tag = "EpubNavigatorFragment" |
| 111 | + |
| 112 | + if (savedInstanceState == null) { |
| 113 | + childFragmentManager.commitNow { |
| 114 | + add(R.id.navigator_container, EpubNavigatorFragment::class.java, Bundle(), tag) |
| 115 | + } |
| 116 | + } |
| 117 | + |
| 118 | + navigator = childFragmentManager.findFragmentByTag(tag) as EpubNavigatorFragment |
| 119 | + |
| 120 | + return view |
| 121 | + } |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +```xml |
| 126 | +<?xml version="1.0" encoding="utf-8"?> |
| 127 | +<FrameLayout |
| 128 | + xmlns:android="http://schemas.android.com/apk/res/android" |
| 129 | + android:layout_width="match_parent" |
| 130 | + android:layout_height="match_parent" |
| 131 | + > |
| 132 | + |
| 133 | + <androidx.fragment.app.FragmentContainerView |
| 134 | + android:id="@+id/navigator_container" |
| 135 | + android:layout_width="match_parent" |
| 136 | + android:layout_height="match_parent" |
| 137 | + /> |
| 138 | +</FrameLayout> |
| 139 | +``` |
| 140 | + |
| 141 | +#### `PdfNavigatorFragment` |
| 142 | + |
| 143 | +Use the same approach as described with the `EpubNavigatorFragment`, using a `PdfNavigatorFactory` instead. |
| 144 | + |
| 145 | +#### `ImageNavigatorFragment` |
| 146 | + |
| 147 | +Use the same approach as described with the `EpubNavigatorFragment`, except that there is no `ImageNavigatorFactory`. Instead, you can build the `FragmentFactory` directly with: |
| 148 | + |
| 149 | +```kotlin |
| 150 | +childFragmentManager.fragmentFactory = |
| 151 | + ImageNavigatorFragment.createFactory( |
| 152 | + publication = publication, |
| 153 | + initialLocator = viewModel.initialLocator, |
| 154 | + listener = this |
| 155 | + ) |
| 156 | +``` |
| 157 | + |
| 158 | +### `AudioNavigator` |
| 159 | + |
| 160 | +The audio navigator is chromeless and independent of the Android view hierarchy, making it much simpler to use than the visual navigators. |
| 161 | + |
| 162 | +First, create an instance of the `AudioNavigatorFactory`, with the audio engine provider you want to use. |
| 163 | + |
| 164 | +```kotlin |
| 165 | +val navigatorFactory = AudioNavigatorFactory( |
| 166 | + publication = publication, |
| 167 | + audioEngineProvider = ExoPlayerEngineProvider( |
| 168 | + application, |
| 169 | + defaults = ExoPlayerDefaults( |
| 170 | + pitch = 0.8 |
| 171 | + ) |
| 172 | + ) |
| 173 | +) |
| 174 | +``` |
| 175 | + |
| 176 | +Then, simply request an instance of the `AudioNavigator` at the given initial location. |
| 177 | + |
| 178 | +```kotlin |
| 179 | +val navigator = navigatorFactory.createNavigator(initialLocator) |
| 180 | +``` |
| 181 | + |
| 182 | +### `TtsNavigator` |
| 183 | + |
| 184 | +The text-to-speech navigator is very similar to the `AudioNavigator`. |
| 185 | + |
| 186 | +```kotlin |
| 187 | +val navigatorFactory = TtsNavigatorFactory( |
| 188 | + application, |
| 189 | + publication, |
| 190 | + defaults = AndroidTtsDefaults( |
| 191 | + pitch = 0.8 |
| 192 | + ) |
| 193 | +) |
| 194 | + |
| 195 | +val navigator = navigatorFactory.createNavigator(initialLocator) |
| 196 | +``` |
0 commit comments