Adds an EngineEvent listener to this instance.
The EngineEvent type to listen to.
The object or callback function that should receive events.
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.
The renderer to add to this ReaderView.
An IResponsiveViewRule instance, a media query string, or a callback. Omitting the rule is the same as passing: new ResponsiveViewRule(() => true)
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.
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.
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.
Clears any selection made in content documents.
Create a new ReaderViewAnnotationLayer and adds it to this ReaderView.
A name identifying this annotation layer
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.
Fetch rectangles and content locations for line boxes and replaced elements such as
<img> elements from the specified visible page. If a contentLocation is specified, it will be used
to filter the result.
The rectangle coordinates are in application viewport coordinate space. This means that any subsequent transform applied to the ReaderView, such as the user pinch-zooming, will make those rectangles out of date.
The rects are ordered in document order.
If the passed visiblePage is not currently part of the array returned by getVisiblePages(), the returned Promise
is rejected with an error object with the error type set to VISIBLE_PAGE_OUTDATED.
If the passed visiblePage is destroyed before the result could be calculated, the returned Promise
is rejected with an error object with the error type set to ABORTED.
If the passed contentLocation is not intersecting with the visiblePage, the returned Promise
is rejected with an error object with the error type set to CONTENT_LOCATION_OUTSIDE_VISIBLE_PAGE.
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.
A Promise that is resolved when the focus() action has been applied, rejected if the focus could not be applied due to an error.
Get the current active gesture type being performed by the user if any.
Listen on "activeGestureTypeChanged" to detect when this value changes.
Get the current ongoing navigation action if any.
Listen on "navigationStarted" and "navigationEnded" to detect when this value changes.
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.
Get the currently allowed gesture types.
Get an annotation layer by name.
Get all annotation layers created with this ReaderView.
Get the Element this ReaderView is rendering to.
Get all EngineEvent listeners for the specified type that has been added to this instance.
Get the name of this ReaderView.
Get a copy of the options used for this instance.
Get the page progression direction used by this ReaderView. Will return the actual runtime value after setReaderDocuments() has been called.
Get the page progression timeline of this ReaderView if available. Listen on the "pageProgressionTimelineRecalculated" EngineEvent to detect when a new instance is available.
Get the reader documents used by this ReaderView, previously set with setReaderDocuments().
Get the reader documents currently loaded for rendering visible content and offscreen content.
Get the reader publications used by this ReaderView. Calculated from the reader documents previously set with setReaderDocuments().
Get the current reading position, or null if this ReaderView is not rendering any publication content.
Get the ReadingSystemEngine instance that was used to create this ReaderView.
Get a renderer by name that was previously added with addRenderer().
Get all renderers that have been added with addRenderer().
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.
Get the sync media player that has been attached to this ReaderView using setSyncMediaPlayer().
Returns the ReaderViewTransformManager used for applying transformations such as scaling and translations.
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.
Get a ResolvedContentLocation describing the range of the visible content.
Get the reader documents currently visible in the ReaderView.
Go to a specific location in a reader document that has been added to this ReaderView.
The location can be specified as:
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().
The new location to navigate to.
Additional options configuring how the goTo() should behave.
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.
Go to the start of the first ReaderDocument in this ReaderView.
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.
If there is an active transform applied on the ReaderView. Use getTransformManager() to get/set the active transform.
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.
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.
If the user is able to select content in content documents.
Check if this ReaderView has been destroyed.
Returns true if any navigation action such as next/previous/goTo is currently being processed.
If offscreen content is currently rendering.
If the ReaderView will choose the activeRenderer based on the ResponsiveViewRules associated with each added renderer. See addRenderer() for more details.
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.
If active renderer is currently scrolling. This method always return false for paginated renderers.
If visible content is currently rendering.
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 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.
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 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.
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.
If true, re-render contents regardless if the view element dimensions changed. Defaults to false.
Removes an EngineEvent listener that was previously added to this instance.
The EngineEvent type to remove.
The object or callback function to remove.
Remove a renderer previously added with addRenderer().
The renderer to remove.
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"
Scrolls a scrolling renderer's content by the specified amount. Relative values such as PERCENTAGE will be based on the renderer element's clientHeight.
If the active renderer is not a scrolling renderer, this method does nothing.
Returns true if the renderer started scrolling, false otherwise.
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.
The renderer to use as active renderer. Passing null will force no renderer to be used.
Sets which gesture types the user is allowed to perform on the ReaderView.
Set custom content to show when no active renderer could be found.
An implementation of ICustomReaderViewContent or a HTML string. If null is passed, no content will be shown.
Set custom content to use for empty pages. This can typically happen in spread renderers when pages have a preferred PageSpreadSlot.
An implementation of ICustomReaderViewContent or a HTML string. If null is passed, a blank page is shown.
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."
An implementation of ICustomViewContent or a HTML string. If null is passed, a blank page is shown.
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)
An implementation of ICustomReaderViewContent or a HTML string. If null is passed, a blank page is shown.
Set custom content to show when loading publication content. Use this method to change the default loading animation.
An implementation of ICustomReaderViewContent or a HTML string. If null is passed, the default Colibrio loader animation is used.
Sets if the user should be able to select content in content documents.
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.
Set which ReaderDocuments this ReaderView should render.
The passed list of ReaderDocuments is validated according to the following rules:
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()
A list of reader documents in reading order that should be rendered by this ReaderView.
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.
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.
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.
The SyncMediaPlayer to attach, or null to detach any already attached SyncMediaPlayer.
Get the state of this ReaderView as a plain JSON object.
Generated using TypeDoc
ReaderViews are used for displaying publication documents.
To get a ReaderView up and running you need to:
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
windowThe 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().Creating a ReaderView over the complete publication let readerView = readingSystemEngine.createView(); readerView.addRenderer(new StackRenderer()); readerView.setReaderDocuments(readerPublication.getSpine()); readerView.renderTo(someElement) readerView.goToStart();