Interface IReaderView

ReaderViews are used for displaying publication documents.

To get a ReaderView up and running you need to:

Add one or more renderers.
Set which reader documents to display.
Set the DOM Element where the ReaderView should render.
Go to a location in the content.

How the ReaderView selects a renderer

A newly created ReaderView is initially in responsive mode. In responsive mode, the ReaderView selects a renderer based on the ResponsiveViewRule (if any was assigned to the renderer) and how much area of the viewport element it can use.

It is important to note that the ReaderView will not automatically refresh and re-render on viewport resize. Clients need to call refresh() on the ReaderView when the element passed to renderTo() is resized. This can for example be done by adding a 'resize' listener on window The ReaderView does not handle this automatically because in certain circumstances, 'resize' events should not trigger refresh(). For example, clicking a search input field on mobile will popup the soft keyboard and trigger a 'resize' event which should probably not make the ReaderView refresh().

Example: Creating a ReaderView over the complete publication

let readerView = readingSystemEngine.createView();
readerView.addRenderer(new StackRenderer());
readerView.setReaderDocuments(readerPublication.getSpine());
readerView.renderTo(someElement)
readerView.goToStart();

interface IReaderView {
    addEngineEventListener<T extends keyof IEngineEventTypeMap>(
        type: T,
        listener: IEngineEventListener<IEngineEventTypeMap[T]>,
    ): void;
    addRenderer(
        renderer: IRenderer,
        rule?: string | IResponsiveViewRule | (() => boolean),
    ): void;
    canPerformGoTo(): boolean;
    canPerformNext(): boolean;
    canPerformPrevious(): boolean;
    clearContentSelection(): void;
    createAnnotationLayer<T = any>(name: string): IReaderViewAnnotationLayer<T>;
    destroyAnnotationLayer(layer: IReaderViewAnnotationLayer): void;
    focusOnReadingPosition(
        options: IFocusOnReadingPositionOptions,
    ): Promise<void>;
    getActiveGestureType(): ReaderViewGestureType;
    getActiveNavigationAction(): NavigationAction;
    getActiveRenderer(): IRenderer;
    getAllowedGestureTypes(): ReaderViewGestureType[];
    getAnnotationLayerByName(name: string): IReaderViewAnnotationLayer<any>;
    getAnnotationLayers(): IReaderViewAnnotationLayer<any>[];
    getElement(): HTMLElement;
    getEngineEventListeners<T extends keyof IEngineEventTypeMap>(
        type: T,
    ): IEngineEventListener<IEngineEventTypeMap[T]>[];
    getName(): string;
    getOptions(): DeepRequired<IReaderViewOptions>;
    getPageProgressionDirection(): ReaderViewPageProgressionDirection;
    getPageProgressionTimeline(): IPageProgressionTimeline;
    getReaderDocuments(): IReaderDocument[];
    getReaderDocumentsLoadedForRendering(): IReaderDocument[];
    getReaderPublications(): IReaderPublication[];
    getReadingAreaRange(): IContentLocation;
    getReadingPosition(): IContentLocation;
    getReadingSystemEngine(): IReadingSystemEngine;
    getRendererByName(name: string): IRenderer;
    getRenderers(): IRenderer[];
    getScrollState(): IReaderViewScrollStateData;
    getSyncMediaPlayer(): ISyncMediaPlayer;
    getTransformManager(): IReaderViewTransformManager;
    getVisiblePages(): IVisiblePage[];
    getVisibleRange(): IContentLocation;
    getVisibleReaderDocuments(): IReaderDocument[];
    goTo(
        location:
            | ILocator
            | ILocatorData
            | IContentLocation
            | IReaderPublicationNavigationItemData
            | IReaderPublicationNavigationItem
            | IUnresolvedContentLocation,
        options?: IReaderViewGotoOptions,
    ): Promise<void>;
    goToStart(): Promise<void>;
    hasActiveTransform(): boolean;
    isAtEnd(): boolean;
    isAtStart(): boolean;
    isContentSelectionEnabled(): boolean;
    isDestroyed(): boolean;
    isNavigating(): boolean;
    isOffscreenContentRendering(): boolean;
    isResponsiveRendererSelectionEnabled(): boolean;
    isScriptedContentDocumentEventHandlersEnabled(): boolean;
    isScrolling(): boolean;
    isVisibleContentRendering(): boolean;
    next(): Promise<void>;
    previous(): Promise<void>;
    refresh(force?: boolean): void;
    removeEngineEventListener<T extends keyof IEngineEventTypeMap>(
        type: T,
        listener: IEngineEventListener<IEngineEventTypeMap[T]>,
    ): void;
    removeRenderer(renderer: IRenderer): void;
    renderTo(viewElement: HTMLElement): void;
    scrollBy(
        length: ILength,
        options?: IReaderViewScrollByOptions,
    ): Promise<void>;
    setActiveRenderer(renderer: IRenderer): void;
    setAllowedGestureTypes(gestureTypes: ReaderViewGestureType[]): void;
    setContentOnActiveRendererMissing(
        customViewContent: string | ICustomReaderViewContent,
    ): void;
    setContentOnEmptyPage(
        customViewContent: string | ICustomReaderViewContent,
    ): void;
    setContentOnLicenseGracePeriodExpired(
        customViewContent: string | ICustomReaderViewContent,
    ): void;
    setContentOnLoadError(
        customViewContent: string | ICustomReaderViewContent,
    ): void;
    setContentOnLoading(
        customViewContent: string | ICustomReaderViewContent,
    ): void;
    setContentSelectionEnabled(enabled: boolean): void;
    setOptions(options: IReaderViewOptions): void;
    setReaderDocuments(readerDocuments: IReaderDocument[]): void;
    setResponsiveRendererSelectionEnabled(enabled: boolean): void;
    setScriptedContentDocumentEventHandlersEnabled(enabled: boolean): void;
    setSyncMediaPlayer(
        syncMediaPlayer: ISyncMediaPlayer,
        initialSyncMethod?: SyncMediaReaderViewSynchronizationMethod,
    ): void;
    toJSON(): IReaderViewStateData;
}

Hierarchy (View Summary)

IEngineEventListenerTarget
- IReaderView

Methods

addEngineEventListener

addEngineEventListener<T extends keyof IEngineEventTypeMap>(
type: T,
listener: IEngineEventListener<IEngineEventTypeMap[T]>,
): void
Adds an EngineEvent listener to this instance.
Type Parameters
- T extends keyof IEngineEventTypeMap
Parameters
- type: T
  The EngineEvent type to listen to.
- listener: IEngineEventListener<IEngineEventTypeMap[T]>
  The object or callback function that should receive events.
Returns void
Inherited from IEngineEventListenerTarget.addEngineEventListener

addRenderer

addRenderer(
renderer: IRenderer,
rule?: string | IResponsiveViewRule | (() => boolean),
): void
Adds a renderer to this ReaderView and optionally a ResponsiveViewRule.

When responsive renderer selections is enabled, the ResponsiveViewRule associated with the renderer is used to evaluate if the renderer can be used or not. The rule can be defined as a CSS media query or a custom callback. The rule is evaluated each time refresh(), or renderTo() is called, but may also be evaluated on other occasions. Omitting the rule will still allow the renderer to be picked, but the ReaderView will prioritize renderers where the rule has explicitly been set.

If multiple renderers are added and more than one rule evaluates to true, the renderer that can use as much as possible of the area of the element set by ReaderView.renderTo() is chosen. If there are several renderers that can use an equal amount of the rendering area, the first one added will be chosen.
Parameters
- renderer: IRenderer
  The renderer to add to this ReaderView.
- Optionalrule: string | IResponsiveViewRule | (() => boolean)
  An IResponsiveViewRule instance, a media query string, or a callback. Omitting the rule is the same as passing: new ResponsiveViewRule(() => true)
Returns void
Example
```
readerView.addRenderer(new StackRenderer())
readerView.addRenderer(new FlipBookRenderer(), '(orientation: landscape) and (min-width: 500px)')
```

canPerformGoTo

canPerformGoTo(): boolean
Check if it is possible to call goTo() or goToStart() at this moment.

You can typically always perform a goTo() or goToStart() given that there is an activeRenderer and setReaderDocuments() has been called with a non-empty list.

Listen on "canPerformGoToChanged" to detect when this value changes.

Returns boolean

canPerformNext

canPerformNext(): boolean
Check if it is possible to call next() at this moment.

This will return false if isAtEnd() return true or if a next(), previous(), goTo() or goToStart() is currently being performed.

Listen on "canPerformNextChanged" to detect when this value changes.

Returns boolean

canPerformPrevious

canPerformPrevious(): boolean
Check if it is possible to call previous() at this moment.

This will return false if at last page or if a next(), previous(), goTo() or goToStart() is currently being performed.

Listen on "canPerformPreviousChanged" to detect when this value changes.

Returns boolean

clearContentSelection

clearContentSelection(): void
Clears any selection made in content documents.

Returns void

createAnnotationLayer

createAnnotationLayer<T = any>(name: string): IReaderViewAnnotationLayer<T>
Create a new ReaderViewAnnotationLayer and adds it to this ReaderView.
Type Parameters
- T = any
Parameters
- name: string
  A name identifying this annotation layer
Returns IReaderViewAnnotationLayer<T>

destroyAnnotationLayer

destroyAnnotationLayer(layer: IReaderViewAnnotationLayer): void
Removes and destroys an annotation layer. Throws an error if the layer was not created with this ReaderView instance. Does nothing if the layer is already destroyed.
Parameters
- layer: IReaderViewAnnotationLayer
Returns void

focusOnReadingPosition

focusOnReadingPosition(options: IFocusOnReadingPositionOptions): Promise<void>
Focus on the page and/or element best matching the reading position.

By focusing on publication content, your app give accessibility technologies such as screen readers an intent where to start reading. Depending on what browser, platform and accessibility technology you are targeting, you might need to experiment with the options you pass to this method in order to get the desired behavior.

The focus action will be applied after any ongoing navigation has completed and visible content has finished rendering. Thus, this method is safe to call immediately after a call to any navigation method such as goTo(), next() or previous().

NOTE: Calling focusOnReadingPosition() MAY remove user selection in some browsers. At the time of writing (2023-06-29), this has only been observed in Firefox on Windows.
Parameters
- options: IFocusOnReadingPositionOptions
Returns Promise<void>
A Promise that is resolved when the focus() action has been applied, rejected if the focus could not be applied due to an error.

getActiveGestureType

getActiveGestureType(): ReaderViewGestureType
Get the current active gesture type being performed by the user if any.

Listen on "activeGestureTypeChanged" to detect when this value changes.

Returns ReaderViewGestureType

getActiveNavigationAction

getActiveNavigationAction(): NavigationAction
Get the current ongoing navigation action if any.

Listen on "navigationStarted" and "navigationEnded" to detect when this value changes.

Returns NavigationAction

getActiveRenderer

getActiveRenderer(): IRenderer
Get the current active Renderer. Note that calling this method immediately after setting up the ReaderView will in most cases return null if the ReaderView.isResponsiveRendererSelectionEnabled() returns true, as it performs several async operations before selecting an active renderer.

You can also detect when the active renderer changes by adding an 'activeRendererChanged' event listener.

Returns IRenderer

getAllowedGestureTypes

getAllowedGestureTypes(): ReaderViewGestureType[]
Get the currently allowed gesture types.

Returns ReaderViewGestureType[]

getAnnotationLayerByName

getAnnotationLayerByName(name: string): IReaderViewAnnotationLayer<any>
Get an annotation layer by name.
Parameters
- name: string
Returns IReaderViewAnnotationLayer<any>

getAnnotationLayers

getAnnotationLayers(): IReaderViewAnnotationLayer<any>[]
Get all annotation layers created with this ReaderView.

Returns IReaderViewAnnotationLayer<any>[]

getElement

getElement(): HTMLElement
Get the Element this ReaderView is rendering to.

Returns HTMLElement

getEngineEventListeners

getEngineEventListeners<T extends keyof IEngineEventTypeMap>(
type: T,
): IEngineEventListener<IEngineEventTypeMap[T]>[]
Get all EngineEvent listeners for the specified type that has been added to this instance.
Type Parameters
- T extends keyof IEngineEventTypeMap
Parameters
- type: T
Returns IEngineEventListener<IEngineEventTypeMap[T]>[]
Inherited from IEngineEventListenerTarget.getEngineEventListeners

getName

getName(): string
Get the name of this ReaderView.

Returns string

getOptions

getOptions(): DeepRequired<IReaderViewOptions>
Get a copy of the options used for this instance.

Returns DeepRequired<IReaderViewOptions>

getPageProgressionDirection

getPageProgressionDirection(): ReaderViewPageProgressionDirection
Get the page progression direction used by this ReaderView. Will return the actual runtime value after setReaderDocuments() has been called.

Returns ReaderViewPageProgressionDirection

getPageProgressionTimeline

getPageProgressionTimeline(): IPageProgressionTimeline
Get the page progression timeline of this ReaderView if available. Listen on the "pageProgressionTimelineRecalculated" EngineEvent to detect when a new instance is available.

Returns IPageProgressionTimeline

getReaderDocuments

getReaderDocuments(): IReaderDocument[]
Get the reader documents used by this ReaderView, previously set with setReaderDocuments().

Returns IReaderDocument[]

getReaderDocumentsLoadedForRendering

getReaderDocumentsLoadedForRendering(): IReaderDocument[]
Get the reader documents currently loaded for rendering visible content and offscreen content.

Returns IReaderDocument[]

getReaderPublications

getReaderPublications(): IReaderPublication[]
Get the reader publications used by this ReaderView. Calculated from the reader documents previously set with setReaderDocuments().

Returns IReaderPublication[]

getReadingAreaRange

getReadingAreaRange(): IContentLocation
Experimental
Returns a content location range that describes the Reading Area as closely as possible.

The Reading Area is a subset of the visible content that the renderer uses as the reference point for reading position calculations.

Key behaviors:
- After any navigation or scrolling that moves the old reading position out of visible range, the new reading position will align with the top of the Reading Area.
- For scrolling renderers, the Reading Area typically is a portion of the visible viewport. You can configure the Reading Area using the scroll renderer options readingAreaOffsetTop and readingAreaOffsetBottom.
- For non-scrolling (paginated) renderers, the Reading Area always equals the entire visible range.
Sync Media integration: If a SyncMediaPlayer is attached with managed synchronization enabled, scroll renderers will try to scroll the contents to keep the active reading position within the Reading Area range. Paginated renderers will automatically navigate to keep the reading position inside the Reading Area range.

Use the readingAreaRangeChanged engine event to detect when this value changes.
Returns IContentLocation
The content location range describing the Reading Area. This API is experimental and might be subject to changes in future releases.

getReadingPosition

getReadingPosition(): IContentLocation
Get the current reading position, or null if this ReaderView is not rendering any publication content.

Returns IContentLocation

getReadingSystemEngine

getReadingSystemEngine(): IReadingSystemEngine
Get the ReadingSystemEngine instance that was used to create this ReaderView.

Returns IReadingSystemEngine

getRendererByName

getRendererByName(name: string): IRenderer
Get a renderer by name that was previously added with addRenderer().
Parameters
- name: string
Returns IRenderer

getRenderers

getRenderers(): IRenderer[]
Get all renderers that have been added with addRenderer().

Returns IRenderer[]

getScrollState

getScrollState(): IReaderViewScrollStateData
Get information about the active renderer's current scroll state, if the renderer is a scrolling renderer. Note that the scrollTop value is not up-to-date while scrolling is true.

Returns IReaderViewScrollStateData

getSyncMediaPlayer

getSyncMediaPlayer(): ISyncMediaPlayer
Get the sync media player that has been attached to this ReaderView using setSyncMediaPlayer().

Returns ISyncMediaPlayer

getTransformManager

getTransformManager(): IReaderViewTransformManager
Returns the ReaderViewTransformManager used for applying transformations such as scaling and translations.

Returns IReaderViewTransformManager

getVisiblePages

getVisiblePages(): IVisiblePage[]
Get a list of the current visible pages.

The number of visible pages depend on the renderer used.

For example: If the active renderer is rendering single pages, one IVisiblePage will be returned. If the active renderer is rendering spreads, up to two IVisiblePages will be returned.

Returns IVisiblePage[]

getVisibleRange

getVisibleRange(): IContentLocation
Get a ResolvedContentLocation describing the range of the visible content.

Returns IContentLocation

getVisibleReaderDocuments

getVisibleReaderDocuments(): IReaderDocument[]
Get the reader documents currently visible in the ReaderView.

Returns IReaderDocument[]

goTo

goTo(
    location:
        | ILocator
        | ILocatorData
        | IContentLocation
        | IReaderPublicationNavigationItemData
        | IReaderPublicationNavigationItem
        | IUnresolvedContentLocation,
    options?: IReaderViewGotoOptions,
): Promise<void>
Go to a specific location in a reader document that has been added to this ReaderView.

The location can be specified as:
- An IContentLocation or IUnresolvedContentLocation object retrieved from a ReaderPublication, EngineEvent, etc.
- A Locator object or a serialized Locator (see the type ILocatorData for alternatives)
- A relative or absolute URL to the location in the publication content. These URLs can for example be retreived using Locator.toString(). You can also specify a selector string compatible with the publication format, like '#page=3' to go to Page 3 in a PDF publication.
See IReaderViewGotoOptions for additional options to use with goTo().
Parameters
- location:
      | ILocator
      | ILocatorData
      | IContentLocation
      | IReaderPublicationNavigationItemData
      | IReaderPublicationNavigationItem
      | IUnresolvedContentLocation
  The new location to navigate to.
- Optionaloptions: IReaderViewGotoOptions
  Additional options configuring how the goTo() should behave.
Returns Promise<void>
A Promise that is resolved when the active renderer has navigated to the new location. Rejected if the locator was invalid, or the locator could not be resolved to a readerDocument in this ReaderView. Rejected with errorType ABORTED if goTo() or goToStart() is called again before this call to goTo() had completed successfully.

goToStart

goToStart(): Promise<void>
Go to the start of the first ReaderDocument in this ReaderView.

Returns Promise<void>
A Promise that is resolved when the active renderer has navigated to the new location. Rejected with errorType ABORTED if goTo() or goToStart() is called again before this call to goTo() had completed successfully.

hasActiveTransform

hasActiveTransform(): boolean
If there is an active transform applied on the ReaderView. Use getTransformManager() to get/set the active transform.

Returns boolean

isAtEnd

isAtEnd(): boolean
Check if this ReaderView is currently showing the last content in the last reader document added to the ReaderView. Call this method after receiving the 'visiblePagesChanged' event to detect when this value is changed.

Returns boolean

isAtStart

isAtStart(): boolean
Check if this ReaderView is currently showing the first content in the first reader document added to the ReaderView. Call this method after receiving the 'visiblePagesChanged' event to detect when this value is changed.

Returns boolean

isContentSelectionEnabled

isContentSelectionEnabled(): boolean
If the user is able to select content in content documents.

Returns boolean

isDestroyed

isDestroyed(): boolean
Check if this ReaderView has been destroyed.

Returns boolean

isNavigating

isNavigating(): boolean
Returns true if any navigation action such as next/previous/goTo is currently being processed.

Returns boolean

isOffscreenContentRendering

isOffscreenContentRendering(): boolean
If offscreen content is currently rendering.

Returns boolean

isResponsiveRendererSelectionEnabled

isResponsiveRendererSelectionEnabled(): boolean
If the ReaderView will choose the activeRenderer based on the ResponsiveViewRules associated with each added renderer. See addRenderer() for more details.

Returns boolean

isScriptedContentDocumentEventHandlersEnabled

isScriptedContentDocumentEventHandlersEnabled(): boolean
If the scripted content document event handlers are allowed to receive events. Note that regardless if true or false is returned, you will still receive EngineEvents.

Returns boolean

isScrolling

isScrolling(): boolean
If active renderer is currently scrolling. This method always return false for paginated renderers.

Returns boolean

isVisibleContentRendering

isVisibleContentRendering(): boolean
If visible content is currently rendering.

Returns boolean

next(): Promise<void>
Tell the activeRenderer to navigate to and display next content fragment (i.e. page, spread, or content-document, depending on the renderer implementation). The navigation will be ignored if there is an ongoing navigation started with next(), previous(), goTo() or goToStart().

Scrolling renderers will always navigate to the next content-document when this method is called. See scrollBy() for programmatically scrolling the renderer.

Returns Promise<void>
Returns a Promise that is resolved when the navigation has completed successfully. Rejected if the navigation is canceled because another action forced a view change before the navigation completed. Rejected if the navigation cannot be done at all, for example if the ReaderView.isAtEnd() returns true or another navigation is being performed.

previous(): Promise<void>
Tell the activeRenderer to navigate to and display previous content fragment (i.e. page, spread, or content-document, depending on the renderer implementation). The navigation will be ignored if there is an ongoing navigation started with next(), previous(), goTo() or goToStart().

Scrolling renderers will always navigate to the previous content-document when this method is called. See scrollBy() for programmatically scrolling the renderer.

Returns Promise<void>
Returns a Promise that is resolved when the navigation has completed successfully. Rejected if the navigation is canceled because another action forced a view change before the navigation completed. Rejected if the navigation cannot be done at all, for example if the ReaderView.isAtStart() returns true or another navigation is being performed.

refresh

refresh(force?: boolean): void
Re-render contents if view element dimensions have changed. If the "force" parameter is set to true, the content is re-rendered regardless if the view element dimensions changed.

If responsive renderer selection is enabled, this method may switch active renderer.

The current reading position, if any, is kept. This method should be called when the view element has been resized in order for the renderer to use the new dimensions.

Note that calls to refresh() are quite expensive. Therefore, there is a built-in delay such that multiple calls to refresh() within a short time-span will internally be merged into a single refresh() call. You can configure the length of this delay using the refreshDelayMs option.

This method does nothing if there is no renderer assigned to this ReaderView, renderTo() has not been called yet, or if the list of reader documents is empty.
Parameters
- Optionalforce: boolean
  If true, re-render contents regardless if the view element dimensions changed. Defaults to false.
Returns void

removeEngineEventListener

removeEngineEventListener<T extends keyof IEngineEventTypeMap>(
type: T,
listener: IEngineEventListener<IEngineEventTypeMap[T]>,
): void
Removes an EngineEvent listener that was previously added to this instance.
Type Parameters
- T extends keyof IEngineEventTypeMap
Parameters
- type: T
  The EngineEvent type to remove.
- listener: IEngineEventListener<IEngineEventTypeMap[T]>
  The object or callback function to remove.
Returns void
Inherited from IEngineEventListenerTarget.removeEngineEventListener

removeRenderer

removeRenderer(renderer: IRenderer): void
Remove a renderer previously added with addRenderer().
Parameters
- renderer: IRenderer
  The renderer to remove.
Returns void

renderTo

renderTo(viewElement: HTMLElement): void
Render to the specified viewElement. The viewElement MUST be added to the DOM and have a width and height. The ReaderView will use the dimensions of the viewElement and will not expand the viewElement.

If the passed element has the position style set to "static", it will be changed to "relative" to ensure that is is an "offsetParent"
Parameters
- viewElement: HTMLElement
Returns void
Throws
EngineError with errorType set to INVALID_VIEW_OPERATION if the viewElement has no dimensions or is a non-displayed element.

scrollBy

scrollBy(length: ILength, options?: IReaderViewScrollByOptions): Promise<void>
Scrolls a scrolling renderer's content by the specified amount. Relative values such as PERCENTAGE will be based on the ReaderView's height.
Parameters
- length: ILength
- Optionaloptions: IReaderViewScrollByOptions
Returns Promise<void>
A promise that resolves after the scrolling animation has finished, or immediately if animations are disabled.

Throws
With errorType INVALID_RENDERER if the active renderer is not a scrolling renderer.

Throws
With errorType ABORTED if any other view operation or user scroll cancels the animation.

setActiveRenderer

setActiveRenderer(renderer: IRenderer): void
Sets the active renderer. The renderer must have previously been added with addRenderer(). This will set responsiveRendererSelectionEnabled to false meaning that calls to refresh() will no longer change the active renderer.

Call setResponsiveRendererSelectionEnabled(true) to allow refresh() to switch active renderer again.
Parameters
- renderer: IRenderer
  The renderer to use as active renderer. Passing null will force no renderer to be used.
Returns void

setAllowedGestureTypes

setAllowedGestureTypes(gestureTypes: ReaderViewGestureType[]): void
Sets which gesture types the user is allowed to perform on the ReaderView.
Parameters
- gestureTypes: ReaderViewGestureType[]
Returns void

setContentOnActiveRendererMissing

setContentOnActiveRendererMissing(
customViewContent: string | ICustomReaderViewContent,
): void
Set custom content to show when no active renderer could be found.
Parameters
- customViewContent: string | ICustomReaderViewContent
  An implementation of ICustomReaderViewContent or a HTML string. If null is passed, no content will be shown.
Returns void

setContentOnEmptyPage

setContentOnEmptyPage(
customViewContent: string | ICustomReaderViewContent,
): void
Set custom content to use for empty pages. This can typically happen in spread renderers when pages have a preferred PageSpreadSlot.
Parameters
- customViewContent: string | ICustomReaderViewContent
  An implementation of ICustomReaderViewContent or a HTML string. If null is passed, a blank page is shown.
Returns void

setContentOnLicenseGracePeriodExpired

setContentOnLicenseGracePeriodExpired(
customViewContent: string | ICustomReaderViewContent,
): void
Set custom content to use when no license has been validated on the device for the duration of the grace period (defaults to 30 days). See Engine Event 'licenseReadingSessionBlocked' for more information.

The default content is "Reading session expired. Please check your internet connection."
Parameters
- customViewContent: string | ICustomReaderViewContent
  An implementation of ICustomViewContent or a HTML string. If null is passed, a blank page is shown.
Returns void

setContentOnLoadError

setContentOnLoadError(
customViewContent: string | ICustomReaderViewContent,
): void
Set custom content to show for pages that could not be loaded due to an error.

It is recommended to show a "retry" button in this custom page content which is bound to ReaderView.refresh(true)
Parameters
- customViewContent: string | ICustomReaderViewContent
  An implementation of ICustomReaderViewContent or a HTML string. If null is passed, a blank page is shown.
Returns void

setContentOnLoading

setContentOnLoading(customViewContent: string | ICustomReaderViewContent): void
Set custom content to show when loading publication content. Use this method to change the default loading animation.
Parameters
- customViewContent: string | ICustomReaderViewContent
  An implementation of ICustomReaderViewContent or a HTML string. If null is passed, the default Colibrio loader animation is used.
Returns void

setContentSelectionEnabled

setContentSelectionEnabled(enabled: boolean): void
Sets if the user should be able to select content in content documents.
Parameters
- enabled: boolean
Returns void

setOptions

setOptions(options: IReaderViewOptions): void
Set new ReaderView options. Existing properties are preserved if they are not present in the passed options object. Properties explicitly set to the value undefined will be restored to their default values.
Parameters
- options: IReaderViewOptions
Returns void

setReaderDocuments

setReaderDocuments(readerDocuments: IReaderDocument[]): void
Set which ReaderDocuments this ReaderView should render.

The passed list of ReaderDocuments is validated according to the following rules:
- All ReaderDocuments must belong to one publication.
- All ReaderDocuments must be ordered as in the publication spine.
If the passed list of readerDocuments fails validation, this method will throw an EngineError.

ReaderDocuments where ReaderDocument.isRenderable() returns false (eg. Audiobook documents) will be filtered out and will not added to the ReaderView. If this happens, an error will be logged.

Some examples:
```
const spine = readerPublication.getSpine();
readerView.setReaderDocuments(spine); // OK!
readerView.setReaderDocuments(spine.slice(1, 4)) // OK!
readerView.setReaderDocuments(spine.filter(item => item.isReflowable()); // OK!
readerView.setReaderDocuments(spine.reverse()); // ERROR, items are not ordered correctly!
```
You need to call goTo() or goToStart() after calling this method to start rendering the new content. There is one exception where you don't need to call goTo() or goToStart() and that is when using this method to add additional ReaderDocuments from the same publication:
```
readerView.setReaderDocuments(spine.slice(0, 4)): // Initially, only render first 4 documents.
readerView.goToStart(); // We need goTo() or goToStart() so ReaderView knows what to render initially.
...

// Later:
readerView.setReaderDocuments(spine.slice(0, 6)); // Add 2 more ReaderDocuments,
// No need to call goTo() or goToStart()
```
Parameters
- readerDocuments: IReaderDocument[]
  A list of reader documents in reading order that should be rendered by this ReaderView.
Returns void

setResponsiveRendererSelectionEnabled

setResponsiveRendererSelectionEnabled(enabled: boolean): void
Sets if the ReaderView will choose the activeRenderer based on the ResponsiveViewRules associated with each added renderer. See addRenderer() for more details.

When this mode is enabled, active renderer may change when calling refresh() or renderTo().

When setting this to enabled, the active renderer will change immediately and re-render contents.
Parameters
- enabled: boolean
Returns void

setScriptedContentDocumentEventHandlersEnabled

setScriptedContentDocumentEventHandlersEnabled(enabled: boolean): void
Sets if the scripted content document event handlers are allowed to receive events. This is the only way to prevent scripted content document from receiving user generated events. Note that regardless if this is set to true or false, you will still receive EngineEvents.
Parameters
- enabled: boolean
Returns void

setSyncMediaPlayer

setSyncMediaPlayer(
syncMediaPlayer: ISyncMediaPlayer,
initialSyncMethod?: SyncMediaReaderViewSynchronizationMethod,
): void
Attach a SyncMediaPlayer to the ReaderView. This allows the SyncMediaPlayer and ReaderView to synchronize. See SyncMediaPlayer for more details.

If another SyncMediaPlayer is attached to this ReaderView, it will be detached.
Parameters
- syncMediaPlayer: ISyncMediaPlayer
  The SyncMediaPlayer to attach, or null to detach any already attached SyncMediaPlayer.
- OptionalinitialSyncMethod: SyncMediaReaderViewSynchronizationMethod
  How the ReaderView and SyncMediaPlayer should initially synchronize. Specifying READER_VIEW_NEXT or READER_VIEW_PREVIOUS will instead have the same effect as READER_VIEW_GOTO. If not specified, it defaults to SYNC_MEDIA_SEEK.
Returns void

toJSON

toJSON(): IReaderViewStateData
Get the state of this ReaderView as a plain JSON object.

Returns IReaderViewStateData

Interface IReaderView

How the ReaderView selects a renderer

Example: Creating a ReaderView over the complete publication

Hierarchy (View Summary)

Methods

addEngineEventListener

Type Parameters

Parameters

Returns void

addRenderer

Parameters

Returns void

Example

canPerformGoTo

Returns boolean

canPerformNext

Returns boolean

canPerformPrevious

Returns boolean

clearContentSelection

Returns void

createAnnotationLayer

Type Parameters

Parameters

Returns IReaderViewAnnotationLayer<T>

destroyAnnotationLayer

Parameters

Returns void

focusOnReadingPosition

Parameters

Returns Promise<void>

getActiveGestureType

Returns ReaderViewGestureType

getActiveNavigationAction

Returns NavigationAction

getActiveRenderer

Returns IRenderer

getAllowedGestureTypes

Returns ReaderViewGestureType[]

getAnnotationLayerByName

Parameters

Returns IReaderViewAnnotationLayer<any>

getAnnotationLayers

Returns IReaderViewAnnotationLayer<any>[]

getElement

Returns HTMLElement

getEngineEventListeners

Type Parameters

Parameters

Returns IEngineEventListener<IEngineEventTypeMap[T]>[]

getName

Returns string

getOptions

Returns DeepRequired<IReaderViewOptions>

getPageProgressionDirection

Returns ReaderViewPageProgressionDirection

getPageProgressionTimeline

Returns IPageProgressionTimeline

getReaderDocuments

Returns IReaderDocument[]

getReaderDocumentsLoadedForRendering

Returns IReaderDocument[]

getReaderPublications

Returns IReaderPublication[]

getReadingAreaRange

Returns IContentLocation

getReadingPosition

Returns IContentLocation

getReadingSystemEngine

Returns IReadingSystemEngine

getRendererByName

Parameters

Returns IRenderer

getRenderers

Returns IRenderer[]

getScrollState

Returns IReaderViewScrollStateData

getSyncMediaPlayer

Returns ISyncMediaPlayer

getTransformManager