Skip to content

Commit 3e6b366

Browse files
committedJul 20, 2023
Add the Navigator user guide
1 parent 6a489f7 commit 3e6b366

File tree

5 files changed

+204
-7
lines changed

5 files changed

+204
-7
lines changed
 

‎docs/guides/index.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
* [Extracting the content of a publication](content.md)
44
* [Supporting PDF documents](pdf.md)
5-
* [Configuring the Navigator](navigator-preferences.md)
6-
* [Font families in the EPUB navigator](epub-fonts.md)
7-
* [Media Navigator](media-navigator.md)
8-
* [Text-to-speech](tts.md)
5+
* [Text-to-speech](tts.md)
6+
* [Navigator](navigator/navigator.md)
7+
* [Configuring the Navigator](navigator/preferences.md)
8+
* [Font families in the EPUB navigator](navigator/epub-fonts.md)
9+
* [Media Navigator](navigator/media-navigator.md)

‎docs/guides/epub-fonts.md renamed to ‎docs/guides/navigator/epub-fonts.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Font families in the EPUB navigator
22

3-
Readium allows users to customize the font family used to render a reflowable EPUB, by changing the [EPUB navigator preferences](navigator-preferences.md).
3+
Readium allows users to customize the font family used to render a reflowable EPUB, by changing the [EPUB navigator preferences](preferences.md).
44

55
:warning: You cannot change the default font family of a fixed-layout EPUB (with zoomable pages), as it is similar to a PDF or a comic book.
66

‎docs/guides/navigator/navigator.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
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+
```

‎docs/guides/navigator-preferences.md renamed to ‎docs/guides/navigator/preferences.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
:warning: The Navigator Setting API is still experimental and currently only available with `EpubNavigatorFragment` and `PdfNavigatorFragment`.
44

5-
Take a look at the [migration guide](../migration-guide.md) if you are already using the legacy EPUB settings.
5+
Take a look at the [migration guide](../../migration-guide.md) if you are already using the legacy EPUB settings.
66

77
## Overview
88

@@ -12,7 +12,7 @@ You cannot directly overwrite the Navigator settings. Instead, you submit a set
1212

1313
For instance: "font size" is a **setting**, and the application can submit the font size value `150%` as a **preference**.
1414

15-
<img src="assets/settings-flow.svg">
15+
<img src="../assets/settings-flow.svg">
1616

1717
```kotlin
1818
// 1. Create a set of preferences.

0 commit comments

Comments
 (0)