ContentPositionTimeline

A ContentPositionTimeline is used for describing positions within ReaderPublication content as integers. The timeline starts at position 0 and its length can be retrieved using the length property.

ContentPositionTimelines can be created with different units of measurements, like CHARACTERS, WORDS or PAGES. For example, consider a timeline created for an EPUB Publication with WORDS as the unit of measurement. Then each position in the timeline represents a word:

• Calling timeline.length will return the total number of words in the publication.

• The timeline position 3 describes the position of the fourth word in the publication.

There is no limit to the number of ContentPositionTimeline instances you can create. Thus, you can for example create one timeline with CHARACTERS as unit of measurement, and another timeline using WORDS as a unit of measurement.

Unit of measurement

The unit of measurement used for a ContentPositionTimeline instance must be configured when creating the timeline. It cannot be changed after the timeline instance has been created.

Which units of measurement that are available differs from publication to publication and can be retrieved using ReaderPublication.availableContentPositionTimelineUnits.

Generally, PAGES as unit of measurement is only available for fixed-layout publications.

For example:

• EPUB publications can construct ContentPositionTimelines with CHARACTERS as the unit of measurement. A position is the character offset from the start of the publication.

• PDF publications can construct ContentPositionTimelines with PAGES as the unit of measurement A position is the page index from the start of the publication.

See EpubReaderPublication.createContentPositionTimeline, PdfReaderPublication.createContentPositionTimeline for how to create a ContentPositionTimeline.

Converting between timeline positions and locators

The ContentPositionTimeline object provides an API for converting integer positions to locators, and vice versa.

The methods fetchTimelinePosition and fetchTimelineRange allows you to convert locators like for example ReaderView.getReadingPosition or ReaderView.visibleRange to a position or range on the timeline.

You can also navigate the ReaderView to a position on the timeline by converting a timeline position to a locator using fetchLocator and pass the result to ReaderView.goTo.

As another example, you can highlight the first 20 words in the publication in a ReaderViewAnnotationLayer by calling fetchLocatorAsRange(0, 20) and pass the result to ReaderViewAnnotationLayer.createAnnotation.

Timeline positions are unaffected by content reflow

As the timeline is constructed from the source publication content, a position in the timeline will always map to the same locator in the publication content regardless of how the content is reflowed into pages. Thus, it is useful for implementing progress bars, reporting reading progression, numbers of words read, etc.

Avoid saving positions across reading sessions for bookmarking purposes

While it is possible to save position from the ContentPositionTimeline for bookmarking and annotation purposes, it is important to note that the timeline positions are highly dependant on how the ContentPositionTimeline was created, for example which options that were used when creating it.

Changing a single option when creating the timeline might cause old timeline positions to point to different locations in the publication content. For example, if you change a CHARACTER based timeline from collapsing whitespace to skipping whitespace, the timeline length will change and timeline positions will point to different content than before.

This could also happen if a bug is found in any of the algorithm causing the calculations to change in a bugfix release.

Thus, for bookmarking and annotations, we highly recommend to use locators to ensure correctness.

Differences between ContentPositionTimeline and PageProgressionTimeline

A ContentPositionTimeline is static. Once it has been created, it is never recalculated. Thus, converting between timeline positions and locators are always deterministic regardless of device size or if device orientation changes.

A PageProgressionTimeline is dynamic. Since it is based on the number of pages rendered by a ReaderView, it is recalculated every time the ReaderView dimensions or ReaderView options changes when rendering reflowable content.

Furthermore, a ContentPositionTimeline may have higher precision as unit of measurements such as CHARACTERS can be used.