colibrio-reader-framework/com.colibrio.readingsystem.base/EpubReaderPublication/createContentPositionTimeline

createContentPositionTimeline

abstract fun createContentPositionTimeline(readerDocuments: List<ReaderDocument>, options: EpubContentPositionTimelineOptions = EpubContentPositionTimelineOptions.Characters(), onSuccess: (ContentPositionTimeline) -> Unit, onError: (ColibrioException) -> Unit, progressCallback: (Double) -> Unit = {})

Creates a new ContentPositionTimeline using the specified readerDocuments. A ContentPositionTimeline is used for describing positions in ReaderPublication content as integers.

See ContentPositionTimeline for more information and examples.

Choosing unit of measure

The ContentPositionTimeline can be configured with different unit of measure. See availableContentPositionTimelineUnits for which units of measure that are available in with this publication instance. By default, CHARACTERS will be used as unit of measure if no unit is specified.

CHARACTERS

The timeline is created by counting all the characters in the provided list of ReaderDocuments. Each position in the timeline can be resolved to a specific character in the publication content. This is generally the most high-resolution unit of measure available.

In publications with lots of media, it might be desirable to count media elements (or other replaced elements) as X number of characters to get a better estimation of the "length" of the rendered publication. By default each replaced element is counted as 50 characters.

Many HTML documents may contain lots of whitespace that is not visible in the rendered publication. By default, multiple adjacent whitespaces are collapsed and counter as a single whitespace.

You can change those behaviours by configuring and passing an options object.

WORDS

The timeline is created by counting all words in the provided list of ReaderDocuments. Each position in the timeline can be resolved to a specific word in the publication content.

NOTE: The current implementation uses whitespace as word boundary and is thus not suitable for all languages.

PAGES

The timeline is created by counting all pre-paginated pages in the provided list of ReaderDocuments. Each position in the timeline points to the start of a pre-paginated page. This unit of measure is not available in reflowable EPUBs. Use availableContentPositionTimelineUnits to see if this unit of measure is supported.

DOCUMENTS

The timeline is created by counting all provided ReaderDocuments.

Specifying the list of ReaderDocuments

The passed list of ReaderDocuments is validated according to the following rules:

The list must not be empty
All ReaderDocuments must belong to this publication.
All ReaderDocuments must be ordered as in the publication spine.

If the passed list of readerDocuments fails validation, the returned Promise will be rejected with an error.

Some examples:

const spine = readerPublication.getSpine();
readerPublication.createContentPositionTimeline(spine); // OK!
readerPublication.createContentPositionTimeline(spine.slice(1, 4)) // OK!
readerPublication.createContentPositionTimeline(spine.filter(item => item.isReflowable()); // OK!
readerPublication.createContentPositionTimeline(spine.reverse()); // ERROR!

Parameters

readerDocuments

The reader documents that should be part of the timeline.

options

Options to use for the timeline.

onSuccess

Called with the new ContentPositionTimeline object if the operation is successful.

onError

Called if an error occurred while creating the timeline.

progressCallback

A function called several times indicating the create progress as a value between 0 and 1.

abstract suspend fun createContentPositionTimeline(readerDocuments: List<ReaderDocument>, options: EpubContentPositionTimelineOptions = EpubContentPositionTimelineOptions.Characters(), progressCallback: (Double) -> Unit = {}): ColibrioResult<ContentPositionTimeline>