ReadingSystemEngine is the entry point to the Colibrio Reading System API. It is used for loading publications, accessing the ReaderView, creating SyncMediaPlayers and more.

You get an engine instance from ColibrioReadingSystemView.readingSystemEngine.

Threading

Use the whole reading system API from the main thread - this engine, its ReaderView, the publications it loads and their timelines and SyncMediaPlayers. This includes the suspend overloads: call them from a coroutine on the main dispatcher rather than switching dispatchers first. The reading system drives an Android WebView, whose state is confined to the main thread.

Calls from another thread are not supported. The framework logs an error when it detects one, but the call may still lose its result or leave the reading system inconsistent.

That rule covers calls you make into the reading system. The reading system also calls into code you implement. Those calls arrive on the main thread, except for the resource interfaces: com.colibrio.core.io.ResourceProvider, com.colibrio.core.io.RandomAccessDataSource and com.colibrio.core.io.ResourceResponse. The reading system may call those from any thread, and from more than one at once, so they must be thread safe.

The callback-style overloads invoke their onSuccess and onError callbacks on the main thread.

Loading publications

Call loadEpub or loadPdf to load a publication into the ReadingSystemEngine. The returned ReaderPublication can be used with the readerView to render content.

Engine Events

The reading system lets you listen and react to events. This can for example be, the user clicking a link or an image, or a ReaderView navigating to the next page.

You can use the various add event listener methods on the framework classes such as the ReaderView.

Event listeners

Registering the same listener twice has no effect. Removing a listener that is not registered has no effect.

Each event goes to the listeners registered when its dispatch began. You may therefore add or remove listeners from inside a callback. A listener removed during a callback still receives the event being dispatched, and no event after it. A listener added during a callback first receives the next event.