Fetches a ContentLocation that most closely matches the specified timelinePosition.
By passing 0, you fetch the ContentLocation matching the start of the timeline.
By passing the value returned by IContentPositionTimeline.getLength(), you fetch the ContentLocation matching
the end of the timeline.
For example, if the timeline has WORDS as unit of measurement, calling fetchContentLocation(20) will fetch the
ContentLocation to the start of the 21st word in the publication.
An integer value that will be clamped between 0 and the timeline length.
Fetches a ContentLocation as a range that most closely matches the given start and end timeline positions.
The returned ContentLocation will contain the content up-to but not including the end timeline position.
For example, if the timeline has WORDS as unit of measurement, calling fetchContentLocation(0, 20) will fetch a
ContentLocation starting at the beginning of word 0 up to the end of word 19.
If end is omitted, it will be set to start + 1, thus calling fetchingContentLocationAsRange(2) is the same
as calling fetchContentLocationAsRange(2, 3)
An integer value that will be clamped between 0 and the timeline length.
An integer value that will be clamped between start and timeline length.
Fetches a timeline position that most closely matches the specified ContentLocation or Locator.
If location is a range, the start of the range will be used.
When fetching a timeline position for a location that is before the timeline, 0 will be returned. When fetching a timeline position for a location that is after the timeline, timeline.getLength() will be returned.
If the location does not target the same ReaderPublication as was used to create the timeline, the returned
Promise will be rejected.
If the ReaderDocument targeted by the location is not part of the timeline, the closest timeline position after
that ReaderDocument will be used based on its index in the ReaderPublication spine.
For example:
A ReaderPublication defines the spine of ReaderDocuments as [d0, d1, d2].
A ContentPositionTimeline is created with [d0, d2].
Fetching a timeline position for any location targeting ReaderDocument d1 will return the timeline position
for the start of ReaderDocument d2.
In text-based unit of measurements, like for example WORDS, a location pointing to in-between words will return the timeline position for the word closest after that location. For example, a ContentLocation pointing to the whitespace between the words "Great book" will return the timeline position for the word "book".
Fetches an integer range containing a start and end position that most closely contains
the specified ContentLocation or Locator.
The returns range is defined as starting from the start property and up-to but not including the end property.
For example, if using WORDS as unit of measurement in a timeline of length 3 containing "The red fox" A ContentLocation pointing to the character 'x' in "fox" will return a the range 2-3 (i.e. matching one word "fox"). A ContentLocation range pointing to the content "ed fox" will return the range 1-3 (i.e. matching two words "red" "fox"). A ContentLocation pointing to the whitespace content " " between "red fox" will return the range 2-2 (i.e. matching no word, it starts at "fox" but ends before "fox").
If the location does not target the ReaderPublication this timeline was created with, the returned Promise will be rejected.
If any of the ReaderDocuments targeted by the location is not part of this timeline, the closest timeline position after
that ReaderDocument will be used based on its index in the ReaderPublication spine.
See fetchTimelinePosition() for an example.
Get the length of the timeline.
Get the list of ReaderDocuments this timeline was created with.
Get the unit of measurement this timeline uses for its integer positions.
Return true if the specified content location intersects with this timeline.
Creating ContentPositionTimeline instances can take a significant amount of time for some publications.
You can now work around this by calling toSerializedData() and saving the result.
The next time you create a ContentPositionTimeline, you can pass that data when calling
readerPublication.createContentPositionTimeline() to create the ContentPositionTimeline almost instantly.
The data returned by this method is a base64 encoded string and is usually just a few hundred bytes large. It is unique to one publication and can safely be shared among clients.
For timelines using ContentPositionTimelineUnit.PAGES or ContentPositionTimelineUnit.DOCUMENTS, this method
returns an empty string. This is because those timelines can be created quickly without any additional data.
When you pass serializedData to readerPublication.createContentPositionTimeline(), it will be validated to
ensure it has the correct format and that it was created for the same publication.
If validation fails, the serializedData is discarded and recalculated again.
See IEpubContentPositionTimelineOptions.serializedData.
Generated using TypeDoc
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 getLength().
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:
There is no limit to the number of ContentLocationTimeline 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.
It is important to note that the ContentPositionTimeline is stateless and has no connection to the ReaderView. Because of this it does not automatically keep track of readingPosition.
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
IReaderPublication.getAvailableContentPositionTimelineUnits().Generally, PAGES as unit of measurement is only available for fixed-layout publications.
For example:
See EpubReaderPublication.createContentPositionTimeline(), PdfReaderPublication.createContentPositionTimeline() for how to create a ContentPositionTimeline.
Converting between timeline positions and ContentLocations
The ContentPositionTimeline provides an API for converting integer positions to ContentLocations, and vice versa.
The methods
fetchTimelinePosition(contentLocation)andfetchTimelineRange(contentLocation)allows you to convert ContentLocations like for example ReaderView.getReadingPosition() or ReaderView.getVisibleRange() 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 ContentLocation using
fetchContentLocation(timelinePosition)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
fetchContentLocationAsRange(0, 20)and pass the result toReaderViewAnnotationLayer.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 ContentLocation in the publication content regardless of how the content has been 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, always use ContentLocations/Locators to ensure correctness, like for example
ReaderView.getReadingPosition().Differences between IContentPositionTimeline and IPageProgressionTimeline
A ContentPositionTimeline is static. Once it has been created, it is never recalculated. Thus, converting between timeline positions and ContentLocations is always deterministic regardless of device size or 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.