Class: ViewState

PSPDFKit.ViewState

new PSPDFKit.ViewState()

The current UI state of a document instance.

The ViewState holds information about the current UI representation of a specific document.

It is an Immutable.Record and thus can be updated using set(key, value), for example: viewState.set("showToolbar", false).

An initial ViewState can be set in PSPDFKit.Configuration.

Because the ViewState is an immutable data type, you must use PSPDFKit.Instance#setViewState on the PSPDFKit.Instance to update it.

To be notified when PSPDFKit updates the ViewState, you can use the dedicated PSPDFKit.Instance~ViewStateChangeEvent.

The following examples show you how to update the ViewState and how to get notified about ViewState changes:

Examples

Adding a listener for the view state changed event

instance.addEventListener("viewState.change", (viewState) => {
  console.log(viewState.toJS());
});

Update values for the immutable state object using PSPDFKit.Instance#setViewState

const state = instance.viewState;
const newState = state.set("currentPageIndex", 2);
instance.setViewState(newState);

Extends

  • Immutable.Record

Members

Methods



Members

allowExport: boolean

Control whether or not the export PDF button in the toolbar should be disabled. If the user has insufficient permissions, the feature will automatically be disabled.

This feature requires the download permission in the JWT.

It is possible to remove the export PDF button with the Toolbar API.

Type:
  • boolean
Default Value:
  • true

allowPrinting: boolean

Control whether or not the printing button in the toolbar should be disabled. If the user has insufficient permissions, the feature will automatically be disabled.

This feature requires the download permission in the JWT, because on some browsers we have to fall back to downloading the PDF in order to allow performant printing.

It is possible to remove the print button with the Toolbar API.

Type:
  • boolean
Default Value:
  • true

canScrollWhileDrawing: boolean

This flag controls whether to enable/disable finger scrolling during Ink Drawing using a pen (safari only)

  • When set to false, (default), scrolling with the finger in drawing mode is disabled.
  • When set to true, once a pen input has been detected, finger input will result in scrolling the document.
Type:
  • boolean
Default Value:
  • false
Example
instance.setViewState(viewState => (
   viewState.set("canScrollWhileDrawing", true)
 ));

currentPageIndex: number

The page index of the page that's currently visible. If there is more than one page visible this will return the page that is using the most space in the viewport. The pageIndex is zero-based and has a maximum value of totalPageCount - 1.

Type:
  • number
Default Value:
  • 0

disablePointSnapping: boolean

Snapping to the nearest point is enabled by default in ur SDK for measurement tools. It can be disabled by this API.

Type:
  • boolean
Default Value:
  • false
Example
instance.setViewState(viewState =>
  viewState.set("disablePointSnapping", true)
);

enableAlwaysScrollToZoom: boolean

When this is enabled, the document will always zoom to the mouse position when scrolling.

Type:
  • boolean
Default Value:
  • false
Example
instance.setViewState(viewState =>
 viewState.set("enableAlwaysScrollToZoom", true)
);

enableAnnotationToolbar: boolean

Set this to false if you want PSPDFKit to disable the annotation toolbar when an annotation is being created or modified.

Type:
  • boolean
Default Value:
  • true

formDesignMode: boolean

This flag controls what kind of UI interaction is active for widget annotations.

  • When set to false, (default), clicking on a widget annotation will allow to modify its value.
  • When set to true, clicking on a widget annotation will select it and allow moving, resizing and deleting it using the annotation toolbar.

This flag can only be set to true if the Form Creator component is included in the license and the current backend supports it.

Type:
  • boolean
Default Value:
  • false
Example
instance.setViewState(viewState => (
   viewState.set("formDesignMode", true)
 ));

(nullable) interactionMode: PSPDFKit.InteractionMode

Controls the current interaction mode in the viewer. When this value is changed, we will make sure that the state is properly transformed.

If, for example, the user is currently creating an ink annotation and you change this value to PSPDFKit.InteractionMode.TEXT, we will delete the current in-memory ink annotation.

For a list of all available mode, please refer to PSPDFKit.InteractionMode.

If this value is null, no interaction mode will be enabled. This corresponds to the default mode that allows text selection and scrolling using the mouse wheel or scrollbars (and panning on mobile devices).

Type:
Default Value:
  • null
Example
instance.setViewState(viewState => (
   viewState.set("interactionMode", PSPDFKit.InteractionMode.PAN)
 ));

keepFirstSpreadAsSinglePage: boolean

When this is enabled, the first spread will always show a single page, even when PSPDFKit.LayoutMode.DOUBLE is enabled. This is useful for magazines that want to show a cover page before the regular content starts.

A spread is a container for either one or two pages, based on the configured PSPDFKit.ViewState#layoutMode.

Type:
  • boolean
Default Value:
  • false

keepSelectedTool: boolean

This flag controls whether a selected tool should maintain its selected state after an annotation is created

  • When set to false, (default), after an annotation has been created the tool is not selected anymore.
  • When set to true, the tool used to create the annotation will still be selected and so it'll be possible to keep adding annotations.

This feature is available for Note Annotation, Text Annotation, Redaction Annotation, Shape Annotation and Comments. Ink Annotation behaves like this by default, the ink tool stays selected until its deselected either programmatically or via the UI.

Type:
  • boolean
Default Value:
  • false
Example
instance.setViewState(viewState => (
   viewState.set("keepSelectedTool", true)
 ));

layoutMode: PSPDFKit.LayoutMode

Controls how pages inside a view are displayed.

Type:

pageSpacing: number

The spacing between pages in pixels. This value will adjust to the current zoom level, so when you zoom in, it does not appear fixed to the viewport. This spacing only applies for PSPDFKit.LayoutMode.DOUBLE.

Type:
  • number
Default Value:
  • 0

pagesRotation: number

The current rotation of all pages. The value is in degrees and describes a clockwise rotation.

Can either be 0°, 90°, 180°, or 270°. Negative values and values above 270 are normalized to one of the valid rotations.

When a page rotation is set, the values are not persisted in the PDF. This setting only affects how the PDF is viewed in the application.

Type:
  • number
Default Value:
  • 0
Example
instance.setViewState(viewState => viewState.set("pagesRotation", -450))
// ... later
instance.viewState.pagesRotation; // => 270

(nullable) prerenderedPageSpreads: number

Number of page spreads to prerender.

Apart from the current page, PSPDFKit for Web prerenders a specific number of page spreads before and after the current page to improve the user experience when scrolling through the document.

A page spread is a container for either one or two pages, based on the configured layout mode. The number of prerendered page spreads is set to 5 by default, which means that PSPDFKit for Web will prerender 5 page spreads before and after the current page.

If set to null, all the page spreads in the document will be prerendered. This setting is not recommended for large documents, as it may lead to performance issues.

Type:
  • number
Default Value:
  • 5
Example
// Prerender 10 page spreads
instance.setViewState(viewState =>
 viewState.set("prerenderedPageSpreads", 10)
);
// Prerender all page spreads
instance.setViewState(viewState =>
 viewState.set("prerenderedPageSpreads", null)
);

previewRedactionMode: boolean

This flag controls whether to show the marked state or redacted state for redaction annotations.

  • When set to false, (default), the marked state of redaction annotations will be shown.
  • When set to true, the redacted state of redaction annotations will be used.

This flag can only be set to true if the Redactions component is included in the license.

Type:
  • boolean
Default Value:
  • false
Example
instance.setViewState(viewState => (
   viewState.set("previewRedactionMode", true)
 ));

readOnly: boolean

When the read only mode is activated, the UI for creating, updating and deleting annotations will be completely hidden. In addition, the user will also no longer be able to select annotations or modify form field values.

However, it is still possible to add annotations programmatically.

If a read only mode is specified within the JWT itself or in the PDF document permissions, and PSPDFKit.Options.IGNORE_DOCUMENT_PERMISSIONS is not set, this option cannot be unset.

Type:
  • boolean
Default Value:
  • false

(readonly) resolvedLayoutMode: PSPDFKit.LayoutMode.SINGLE|PSPDFKit.LayoutMode.DOUBLE

When in PSPDFKit.LayoutMode.AUTO mode, this property is set to the actual rendered layout mode, which can either be PSPDFKit.LayoutMode.SINGLE or PSPDFKit.LayoutMode.DOUBLE. It can be used to be notified when the layout mode changes while still being in PSPDFKit.LayoutMode.AUTO mode: if the rendered layout mode changes while in PSPDFKit.LayoutMode.AUTO (because of user UI interactions, for example), the viewState.change event will be dispatched, and this property will hold the updated value.

Type:
  • PSPDFKit.LayoutMode.SINGLE | PSPDFKit.LayoutMode.DOUBLE
Example
instance.addEventListener("viewState.change", (viewState) => {
console.log(viewState.resolvedLayoutMode);
});

scrollMode: PSPDFKit.ScrollMode

Controls how pages can be scrolled.

Type:

showAIDocumentAssistant: boolean

When this is enabled, the document assistant chat dialog will be shown. If this is disabled, the chat dialog will not be shown.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({
  initialViewState: new PSPDFKit.ViewState({
    showAIDocumentAssistant: true,
  }),
});

showAnnotationNotes: boolean

When this is set to false, annotation notes will no longer be rendered.

Type:
  • boolean
Default Value:
  • true

showAnnotations: boolean

When this is set to false, annotations will no longer be rendered.

This option can also be set to false, when PSPDFKit.ViewState#readOnly mode is enabled.

Type:
  • boolean
Default Value:
  • true

showComments: boolean

When this is set to false, comments will no longer be rendered.

PSPDFKit ignores this value when you haven't purchased the comments component.

Type:
  • boolean
Default Value:
  • true

showSignatureValidationStatus: PSPDFKit.ShowSignatureValidationStatusMode

Controls when the digital signature validation UI will be shown.

Type:
Example
instance.setViewState(viewState => (
  viewState.set("showSignatureValidationStatus", PSPDFKit.ShowSignatureValidationStatusMode.IF_SIGNED)
));

showToolbar: boolean

Set this to true if you want a toolbar for navigation and annotation controls or false if you don't.

Type:
  • boolean
Default Value:
  • true

(nullable) sidebarMode: PSPDFKit.SidebarMode

Controls the current sidebar mode in the viewer.

For a list of all available mode, please refer to PSPDFKit.SidebarMode.

If this value is null, the sidebar is hidden. This corresponds to the default mode.

Type:
Default Value:
  • null
Example
instance.setViewState(viewState => (
  viewState.set("sidebarMode", PSPDFKit.SidebarMode.THUMBNAILS)
));

sidebarOptions: PSPDFKit.SidebarOptions

Defines specific options that affect each individual sidebar.

For a list of all available options, please refer to PSPDFKit.SidebarOptions.

Type:
  • PSPDFKit.SidebarOptions
Example
instance.setViewState(viewState => (
  viewState.set("sidebarOptions",  {
      [PSPDFKit.SidebarMode.ANNOTATIONS]: {
        includeContent: [PSPDFKit.Annotations.TextAnnotation, PSPDFKit.Annotations.HighlightAnnotation]
      }
    })
));

sidebarPlacement: PSPDFKit.SidebarPlacement

Controls the current sidebar placement in the viewer.

Type:
Default Value:
  • null
Example
instance.setViewState(viewState => (
  viewState.set("sidebarPlacement", PSPDFKit.SidebarPlacement.END)
));

sidebarWidth: number

Controls the width of the sidebar in client, pixel units. Changing the ViewState.sidebarMode does not affect this value.

The default value depends on the current viewport width: if the viewport width is less than 768px, the sidebar will take 100% of the viewport width by default. If the viewport width is greater, the sidebar will take 300px by default.

Type:
  • number
Example
instance.setViewState(viewState => (
  viewState.set("sidebarWidth", 400)
));

spreadSpacing: number

The spacing between spreads in pixels. This value will adjust to the current zoom level, so when you zoom in, it does not appear fixed to the viewport. This spacing only applies for PSPDFKit.ScrollMode.CONTINUOUS.

A spread is a container for either one or two pages, based on the configured PSPDFKit.ViewState#layoutMode.

Type:
  • number
Default Value:
  • 20

viewportPadding: object

The padding between the viewport and the document in pixels. This value will not increase, when you zoom in.

The horizontal value will be used as padding-left and padding-right and the vertical value for padding-top and padding-bottom. The same value for both sides will be used, this means that horizontal: 20 is equal to padding-left: 20px; padding-right: 20px;.

When you set those values to zero, there will be no space between the viewport and the document.

Type:
  • object
Properties:
Name Type Description
horizontal number

The horizontal padding for left and right in pixel.
vertical number

The vertical padding for top and bottom in pixel.
Default Value:
  • { horizontal: 20, vertical: 20 }

zoom: PSPDFKit.ZoomMode|number

Controls the current zoom factor. This could either be a number multiplier or a distinct zoom mode.

If a number value is used, it must be between PSPDFKit.Instance#minimumZoomLevel and PSPDFKit.Instance#maximumZoomLevel.

Note: Using a PSPDFKit.ZoomMode will override the padding set using PSPDFKit.ViewState#viewportPadding

Type:
Default Value:

zoomStep: number

Controls the zoom step when zooming in or out using the toolbar buttons.

Type:
  • number
Default Value:
  • 1.25
Example
instance.setViewState(viewState => (
  viewState.set("zoomStep", 1.1)
));

Methods

goToNextPage() → {PSPDFKit.ViewState}

Creates a new PSPDFKit.ViewState with a currentPageIndex increased by one.

This method cannot be called on an instance of PSPDFKit.ViewState without an PSPDFKit.Instance assigned. You can use this method on all view states returned by PSPDFKit.Instance#viewState and PSPDFKit.Instance#setViewState.

When you hit PSPDFKit.Instance#totalPageCount - 1, it will not update the state.

Throws:

When this method is called on a self-constructed instance of PSPDFKit.ViewState.

Type
PSPDFKit.Error
Returns:

New PSPDFKit.ViewState with an updated zoom property.

Type
PSPDFKit.ViewState
Example
instance.setViewState(viewState => viewState.goToNextPage());

goToPreviousPage() → {PSPDFKit.ViewState}

Creates a new PSPDFKit.ViewState with a currentPageIndex decreased by one.

When you hit 0, it will not update the state.

Throws:

When this method is called on a self-constructed instance of PSPDFKit.ViewState.

Type
PSPDFKit.Error
Returns:

New PSPDFKit.ViewState with an updated zoom property.

Type
PSPDFKit.ViewState
Example
instance.setViewState(viewState => viewState.goToPreviousPage());

rotateLeft() → {PSPDFKit.ViewState}

Creates a new PSPDFKit.ViewState where all pages are rotated by 90° counterclockwise.

Returns:

New PSPDFKit.ViewState with an updated pagesRotation property.

Type
PSPDFKit.ViewState
Example
instance.setViewState(viewState => viewState.rotateLeft())

rotateRight() → {PSPDFKit.ViewState}

Creates a new PSPDFKit.ViewState where all pages are rotated by 90° clockwise.

Returns:

New PSPDFKit.ViewState with an updated pagesRotation property.

Type
PSPDFKit.ViewState
Example
instance.setViewState(viewState => viewState.rotateRight())

zoomIn() → {PSPDFKit.ViewState}

Creates a new PSPDFKit.ViewState with a specific zoom level that is 25% greater than the current zoom level.

If a PSPDFKit.ZoomMode is set, it will overwrite it with a number value (which will no longer adopt when you resize the window).

This method cannot be called on an instance of PSPDFKit.ViewState without an PSPDFKit.Instance assigned. You can use this method on all view states returned by PSPDFKit.Instance#viewState and PSPDFKit.Instance#setViewState.

When the new zoom level would exceed the maximum zoom level, it will be capped at the maximum value.

Throws:

When this method is called on a self-constructed instance of PSPDFKit.ViewState.

Type
PSPDFKit.Error
Returns:

New PSPDFKit.ViewState with an updated zoom property.

Type
PSPDFKit.ViewState
Example
instance.setViewState(viewState => viewState.zoomIn())

zoomOut() → {PSPDFKit.ViewState}

Creates a new PSPDFKit.ViewState with a specific zoom level that is 25% lower than the current zoom level.

If a PSPDFKit.ZoomMode is set, it will overwrite it with a number value (which will no longer adopt when you resize the window).

This method cannot be called on an instance of PSPDFKit.ViewState without an PSPDFKit.Instance assigned. You can use this method on all view states returned by PSPDFKit.Instance#viewState and PSPDFKit.Instance#setViewState.

When the new zoom level would undercut the minimum zoom level, it will be capped at the minimum value.

Throws:

When this method is called on a self-constructed instance of PSPDFKit.ViewState.

Type
PSPDFKit.Error
Returns:

New PSPDFKit.ViewState with an updated zoom property.

Type
PSPDFKit.ViewState
Example
instance.setViewState(viewState => viewState.zoomOut())

See also