@mescius/dspdfviewer
Version:
Document Solutions PDF Viewer
1,259 lines • 115 kB
TypeScript
import { WidgetAnnotation, GcProps, LineAnnotation, CircleAnnotation, SquareAnnotation, RedactAnnotation, TextAnnotation, InkAnnotation, PolyLineAnnotation, PolygonAnnotation, FreeTextAnnotation, FileAttachmentAnnotation, SoundAnnotation, ButtonWidget, ChoiceWidget, TextWidget, StampAnnotation, AnnotationBase, SignatureAnnotation, LinkAnnotation, PopupAnnotation, HighlightAnnotation, UnderlineAnnotation, SquigglyAnnotation, StrikeOutAnnotation, AnnotationTypeName } from "./Annotations/AnnotationTypes";
import { RichMediaAnnotation } from "./Annotations/RichMediaAnnotation";
import { ValidationCallerType } from "./FormFiller/types";
import { DocumentListItem, FieldAppearanceRenderingType, JsExecutionConfig, KeyboardShortcutDefinition, OpenParameters, OptionalContentConfig, SaveSettings, StampCategory, ViewerFeatureName } from "./Models/ViewerTypes";
import { LogLevel } from "./SharedDocuments/types";
import { ISupportApiBase } from "./SupportApi/ISupportApiBase";
import { TableDataExportFormat } from "./SupportApi/types";
import { ClientTableExtractOptions } from "./TableDataExtraction/types";
import { PageDisplayType, SaveAsOptions, SaveAsFormat } from "./Toolbar/controls/types";
import { UndoStorageOptions } from "./Undo/types";
/**
* Configuration options for the Page Navigation toolbar component
*/
export type NavigationControlOptions = {
/**
* Show/hide the 'First Page' navigation button
* @default false
*/
showFirstButton?: boolean;
/**
* Show/hide the 'Previous Page' navigation button
* @default true
*/
showPrevButton?: boolean;
/**
* Show/hide the page number input and counter display
* @default true
*/
showPageInput?: boolean;
/**
* Show/hide the 'Next Page' navigation button
* @default true
*/
showNextButton?: boolean;
/**
* Show/hide the 'Last Page' navigation button
* @default false
*/
showLastButton?: boolean;
/**
* Width of the page input container in pixels
* @default 70
* @minimum 50
*/
pageInputWidth?: number;
/**
* Custom format for the page counter text
* Available placeholders:
* - {{current}}: Current page number
* - {{total}}: Total page count
* @default "{{current}} / {{total}}"
*/
pageCounterFormat?: string;
/**
* Display text when no document is loaded
* @default "-- / --"
*/
emptyPageCounterFormat?: string;
/**
* Controls the sizing of navigation buttons
* - 'compact': 30px width
* - 'standard': 40px width
* - number: Custom width in pixels
* @default 'compact'
*/
buttonSizing?: 'compact' | 'standard' | number;
};
/**
* Settings for the Reply Tool.
**/
export type ReplyToolSettings = {
/**
* Enables read-only mode, preventing any modifications.
**/
readOnly?: boolean;
/**
* Allows adding notes.
**/
allowAddNote?: boolean;
/**
* Allows changing the user name.
**/
allowChangeUserName?: boolean;
/**
* Allows adding replies.
**/
allowAddReply?: boolean;
/**
* Allows deleting notes or replies.
**/
allowDelete?: boolean;
/**
* Allows setting a status on notes or replies.
**/
allowStatus?: boolean;
/**
* Allows modifying notes created by other users.
**/
allowChangeOtherUser?: boolean;
/**
* Allows deleting notes or replies created by other users.
**/
allowDeleteOtherUser?: boolean;
/**
* Allows setting a status on notes or replies created by other users.
**/
allowStatusOtherUser?: boolean;
/**
* Allows adding replies to notes created by other users.
**/
allowAddReplyOtherUser?: boolean;
/**
* Controls whether the Reply Tool automatically expands when a comment is added via the context menu.
*
* @property {boolean} [autoExpandOnCommentAdd=true] - Set to `true` to enable automatic expansion,
* or `false` to disable it.
*
* @example
* ```javascript
* // Disable automatic expansion of the Reply Tool.
* var viewer = new DsPdfViewer("#root", { replyTool: { autoExpandOnCommentAdd: false } });
* ```
**/
autoExpandOnCommentAdd?: boolean;
/**
* Defines the color used for temporarily highlighting an annotation on the PDF page
* when it is selected in the comments list within the Reply Tool.
*
* @property {string} [annotationFocusColor='#ff0000'] - The highlight color in hex format.
* This setting is also utilized in the `showAnnotationFocusOutline` method if the
* color parameter is not explicitly specified.
*
* @example
* ```javascript
* var viewer = new DsPdfViewer("#root", { replyTool: { annotationFocusColor: "blue" } });
* ```
*/
annotationFocusColor?: string;
/**
* If set to `true`, comment icons will be filled with the color used in the annotation.
**/
useColoredIcons?: boolean;
/**
* Enables the use of relative dates in comment headers.
*
* @property {boolean} [useRelativeDates=true] -
* - `true`: Displays relative dates (e.g., "5 minutes ago").
* - `false`: Displays absolute dates instead.
*
* @example
* ```javascript
* // Enable relative dates (default behavior).
* var viewer = new DsPdfViewer("#root", { replyTool: { useRelativeDates: true } });
*
* // Disable relative dates.
* var viewer = new DsPdfViewer("#root", { replyTool: { useRelativeDates: false } });
* ```
**/
useRelativeDates?: boolean;
/**
* Specifies the custom format for absolute dates in comment headers.
*
* @property {string} [dateFormat="yyyy-mm-dd HH:MM"] - The format to use when displaying absolute dates.
* Ignored if `useRelativeDates` is `true`.
*
* @example
* ```javascript
* // Use a custom format for absolute dates.
* var viewer = new DsPdfViewer("#root", { replyTool: { useRelativeDates: false, dateFormat: "dd.mm.yyyy HH:MM" } });
* ```
**/
dateFormat?: string;
/**
* Optional filter function to determine which annotations should be displayed in the Reply Tool.
* If the function returns `true`, the annotation is shown; if `false`, it is hidden.
* If not provided, the default behavior is used.
*
* @param {AnnotationBase} annotation - The annotation being evaluated.
* @param {number} index - The index of the annotation in the array.
* @param {AnnotationBase[]} array - The full list of annotations.
* @returns {boolean} `true` to display the annotation, `false` to hide it.
*
* @example
* ```javascript
* // Show only text annotations in the Reply Tool
* var viewer = new DsPdfViewer("#root", {
* replyTool: {
* annotationFilter: (annotation) => annotation.annotationType === 1 // AnnotationType.TEXT
* }
* });
* ```
*/
annotationFilter?: (annotation: AnnotationBase, index: number, array: AnnotationBase[]) => undefined | boolean;
};
/**
* Settings for configuring the Support API in the viewer.
**/
export type SupportApiSettings = {
/**
* URL to the Support API service that will be used to enable PDF editing features.
**/
apiUrl: string;
/**
* Specifies a custom implementation of the SupportApi for editing functions.
* When this property is set, the viewer will use the provided custom implementation instead of a separate service.
* All other properties (apiUrl, webSocketUrl, and token) will be ignored.
* @example
* ```javascript
* // Example
* var viewer = new DsPdfViewer("#root", {
* supportApi: {
* implementation: new CustomSupportApi()
* }
* });
* ```
**/
implementation: ISupportApiBase;
/**
* Authentication or antiforgery token. In each subsequent SupportApi request, the token is passed in the request for server-side validation.
* You can use ASP.NET Core Antiforgery to generate and verify security token, see {@link https://docs.microsoft.com/en-us/aspnet/core/security/anti-request-forgery?view=aspnetcore-6.0|Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core} for details.
* @example
* ```javascript
* // Specify antiforgery token on client side:
* const viewer = new DsPdfViewer("#viewer", {
* supportApi: {
* apiUrl: "192.168.0.1/support-api",
* token: "support-api-demo-net-core-token",
* webSocketUrl: false
* }
* });
* ```
* @example
* ```csharp
* // Here is an example of how to validate the token on the server side inside the SupportApi service project:
*
* // Startup.cs:
* GcPdfViewerController.Settings.VerifyToken += VerifyAuthToken;
*
* private void VerifyAuthToken(object sender, SupportApi.Models.VerifyTokenEventArgs e)
* {
* string token = e.Token;
* if (token != "support-api-demo-net-core-token")
* {
* e.Reject = true;
* }
* }
* ```
**/
token?: string;
/**
* Set this setting to true if you are using the Web Forms (WEB API 2) version of the SupportApi service.
* Note, in most cases, you do not need to set this setting, the server type is determined by the viewer automatically.
* @example
* ```javascript
* const viewer = new DsPdfViewer("#viewer", {
* supportApi: {
* apiUrl: "/api/pdf-viewer",
* webSocketUrl: "/signalr",
* legacyServer: true,
* token: "support-api-demo-net-core-token"
* }
* });
* ```
**/
legacyServer?: boolean;
/**
* The internal Support API client uses the fetch API to make requests to the server.
* Use the requestInit setting to configure fetch options (like authorization headers, etc),
* see https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch for details.
* @example
* ```javascript
* // Include Basic Authentication headers:
* const viewer = new DsPdfViewer("#viewer", {
* supportApi: {
* apiUrl: "192.168.0.1/support-api",
* requestInit: {
* headers: {
* "Authorization": "Basic " + btoa(unescape(encodeURIComponent("USERNAME:PASSWORD"))),
* "CustomHeader": "Custom header value"
* }
* }
* }
* });
* ```
**/
requestInit?: RequestInit;
/**
* Optional. SignalR socket URL for persistent connections.
* Persistent connections are required for collaboration mode.
* Set this setting to false to disable persistent connections.
* @default /signalr
**/
webSocketUrl?: string | false;
/**
* Automatically reconnect to the server at the specified interval in milliseconds.
* Used by persistent connections.
* @default 5000
**/
reconnectInterval?: number;
/**
* Suppress Support API informational messages (e.g. Support API reconnect messages).
* @example
* ```javascript
* // Suppress informational messages only:
* const viewer = new DsPdfViewer("#viewer", {
* supportApi: {
* apiUrl: "http://192.168.0.1/support-api",
* webSocketUrl: false,
* suppressInfoMessages: true
* }
* });
* ```
**/
suppressInfoMessages?: boolean;
/**
* Suppress Support API error messages (e.g. messages about the Support API availability / version mismatch).
* @example
* ```javascript
* // Suppress both error and informational messages:
* const viewer = new DsPdfViewer("#viewer", {
* supportApi: {
* apiUrl: "http://192.168.0.1/support-api",
* webSocketUrl: false,
* suppressInfoMessages: true,
* suppressErrorMessages: true
* }
* });
* ```
**/
suppressErrorMessages?: boolean;
/**
* Not used.
* @ignore
**/
docBaseUrl?: string;
};
/**
* Configuration options for the text markup context sub-menu.
*/
export type TextMarkupContextMenuSettings = {
/**
* Defines the available color options in the text markup context menu.
*
* - An array of colors applies the same color options to all markup types.
* - An object with specific markup types allows defining different color sets for each type.
* - Setting this to `false` disables the color selection in the text markup context menu.
*
* @example
* ```javascript
* // Customize available colors for all text markup types:
* textMarkupContextMenu: {
* colors: [
* { value: "#ff0000", displayName: "Red" },
* { value: "#000000", displayName: "Black" }
* ]
* }
* ```
*
* @example
* ```javascript
* // Hide all color options in the text markup sub-menu:
* textMarkupContextMenu: { colors: [] }
* ```
*
* @example
* ```javascript
* // Define specific colors for each text markup type:
* textMarkupContextMenu: {
* colors: {
* highlight: [
* { value: "#ff0000", displayName: "Red" },
* { value: "#000000", displayName: "Black" }
* ],
* underline: [
* { value: "#ff0000", displayName: "Red" }
* ],
* strikeout: [
* { value: "#000000", displayName: "Black" }
* ],
* squiggly: [
* { value: "#ff0000", displayName: "Red" }
* ]
* }
* }
* ```
*/
colors: {
value: string;
displayName: string;
}[] | {
highlight?: {
value: string;
displayName: string;
}[];
underline?: {
value: string;
displayName: string;
}[];
strikeout?: {
value: string;
displayName: string;
}[];
squiggly?: {
value: string;
displayName: string;
}[];
} | false;
};
/**
* GcDocs PDF Viewer options class.
**/
export declare class ViewerOptions {
/**
* ViewerOptions constructor
* @param options viewer options object.
* @ignore
* @example
* ```javascript
* // Create options object:
* var options = { snapAlignment: false, supportApi: 'api/pdf-viewer'};
* // Pass options object to the DsPdfViewer constructor:
* var viewer = new DsPdfViewer("#root", options);
* ```
*/
constructor(options?: Partial<ViewerOptions>);
/**
* Use this option to change the default SVG icons to custom ones.
* Available icon keys: 'undo2', 'font-bold', 'font-italic', 'checkbox-checked', 'checkbox-unchecked', 'close', 'aspect-ratio', 'search', 'chevron', 'chevron-accent',
* 'animated-spinner', 'drag-handle', 'download', 'keyboard', 'brush', 'image', 'image-list', 'save', 'theme-change', 'single-page', 'continuous-view', 'view-mode', 'show-view-tools',
* 'show-edit-tools', 'show-form-editor', 'toggle-annotation-properties', 'toggle-form-properties', 'edit-converted-to-content', 'edit-free-text', 'edit-ink', 'edit-text', 'edit-square',
* 'edit-line', 'edit-link', 'edit-circle', 'edit-stamp', 'add-stamp-accent', 'edit-sign-tool', 'edit-file-attachment', 'edit-sound', 'edit-polyline', 'edit-polygon', 'edit-popup',
* 'edit-redact', 'edit-redact-apply', 'edit-redact-applied', 'edit-unknown-type', 'edit-widget-signature', 'edit-widget-tx-field', 'edit-widget-tx-text-area', 'edit-widget-tx-comb',
* 'edit-widget-tx-password', 'edit-widget-btn-checkbox', 'edit-widget-btn-radio', 'edit-widget-btn-push', 'edit-widget-btn-submit', 'edit-widget-btn-reset', 'edit-widget-ch-combo',
* 'edit-widget-ch-list-box', 'edit-widget-unknown-type', 'edit-undo', 'edit-redo', 'remove-attachment', 'edit-select', 'edit-erase', 'form-filler', 'field-invalid', 'new-document',
* 'new-page', 'delete-page', 'print', 'rotate', 'confirm-ok', 'confirm-cancel', 'open', 'open-pdf', 'text-selection', 'hide-annotations', 'pan', 'bookmarks', 'structure-tree', 'layers', 'thumbnails', 'articles', 'attachments', 'documents-list', 'share', 'shared-documents-list', 'view-mode-on', 'view-mode-off', 'edit-mode-on', 'edit-mode-off', 'remove-user', 'doc-properties', 'about', 'pdf-doc-title', 'close-icon-sm', 'menu-dots', 'comments-status-accepted', 'comments-status-cancelled', 'comments-status-completed', 'comments-status-rejected', 'context-copy', 'context-paste', 'context-cut', 'context-delete', 'move-to-top-page', 'move-to-bottom-page', 'arrow-expand-horizontal', 'arrow-expand-all', 'magnify-minus-outline', 'magnify-plus-outline', 'magnify', 'text-tools', 'draw-tools', 'attachment-tools', 'form-tools', 'page-tools', 'resize-handle-h'.
* @example
* ```javascript
* var viewer = new DsPdfViewer(selector, {
* customIcons: {
* 'open': '<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="24" height="24" viewBox="0 0 24 24"><path d="M9.516 14.016q1.875 0 3.188-1.313t1.313-3.188-1.313-3.188-3.188-1.313-3.188 1.313-1.313 3.188 1.313 3.188 3.188 1.313zM15.516 14.016l4.969 4.969-1.5 1.5-4.969-4.969v-0.797l-0.281-0.281q-1.781 1.547-4.219 1.547-2.719 0-4.617-1.875t-1.898-4.594 1.898-4.617 4.617-1.898 4.594 1.898 1.875 4.617q0 0.984-0.469 2.227t-1.078 1.992l0.281 0.281h0.797z"></path></svg>',
* 'search': '<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="24" height="24" viewBox="0 0 24 24"><path d="M9.516 14.016q1.875 0 3.188-1.313t1.313-3.188-1.313-3.188-3.188-1.313-3.188 1.313-1.313 3.188 1.313 3.188 3.188 1.313zM15.516 14.016l4.969 4.969-1.5 1.5-4.969-4.969v-0.797l-0.281-0.281q-1.781 1.547-4.219 1.547-2.719 0-4.617-1.875t-1.898-4.594 1.898-4.617 4.617-1.898 4.594 1.898 1.875 4.617q0 0.984-0.469 2.227t-1.078 1.992l0.281 0.281h0.797z"></path></svg>'
* }
* });
* ```
**/
customIcons?: {
[iconKey: string]: Element | string;
};
/**
* If set to true, disables browser history during navigation inside PDF document.
*
* @example
* ```javascript
* var viewer = new DsPdfViewer(selector, {
* disableHistory: true
* });
* ```
*/
disableHistory: boolean;
/**
* Contains default values for a new annotations and fields.
* @example
* ```javascript
* // Change the default sticky note and text annotation color to Red:
* var viewer = new DsPdfViewer("#root", {
* editorDefaults: {
* stickyNote: { color: "#ff0000" },
* textAnnotation: {color: "#ff0000" }
* },
* supportApi: 'api/pdf-viewer'
* });
* ```
* @example
* ```javascript
* // Change the default square annotation appearance:
* var viewer = new DsPdfViewer("#root", {
* editorDefaults: {
* squareAnnotation: {
* annotationType: 5, // AnnotationTypeCode.SQUARE
* subtype: "Square",
* borderStyle: { width: 5, style: 1, horizontalCornerRadius: 0, verticalCornerRadius: 0 },
* color: [0, 0, 0],
* interiorColor: [255, 0, 0],
* }
* },
* supportApi: 'api/pdf-viewer'
* });
* ```
* */
editorDefaults: {
/**
* Array of the available font names.
* @default [
* { value: 'Helv', name: 'Helvetica' }, { value: 'HelveticaRegular', name: 'Helvetica-Oblique' }, { value: 'HelveticaBold', name: 'Helvetica-Bold' }, { value: 'HelveticaBoldItalic', name: 'Helvetica-BoldOblique' },
* { value: 'TimesRegular', name: 'Times-Roman' }, { value: 'TimesItalic', name: 'Times-Italic' }, { value: 'TimesBold', name: 'Times-Bold' }, { value: 'TimesBoldItalic', name: 'Times-BoldItalic' },
* { value: 'CourierRegular', name: 'Courier' }, { value: 'CourierItalic', name: 'Courier-Oblique' }, { value: 'CourierBold', name: 'Courier-Bold' }, { value: 'CourierBoldItalic', name: 'Courier-BoldOblique' },
* { value: 'Symbol', name: 'Symbol' }
* ]
* @example
* ```javascript
* var viewer = new DsPdfViewer("#root", {
* editorDefaults: { fontNames: [{value: 'Arial', name: 'Arial'}, {value: 'Verdana', name: 'Verdana'}] },
* supportApi: { apiUrl: 'support-api/gc-pdf-viewer', webSocketUrl: false }
* });
* ```
**/
fontNames?: {
value: string;
name: string;
}[];
/**
* Set this setting to true if you do not want to display an additional floating bar for editor mode.
*
* @example
* ```javascript
* var viewer = new DsPdfViewer("#root", {
* editorDefaults: { hideFloatingBar: true },
* supportApi: { apiUrl: 'support-api/gc-pdf-viewer', webSocketUrl: false }
* });
* ```
**/
hideFloatingBar?: boolean;
/**
* When the rememberLastValues setting is set to true (or undefined), the last used property values will be used as default values for new annotations.
* @default undefined
* @example
* ```javascript
* // Do not use the last used property values as defaults:
* var viewer = new DsPdfViewer("#root", { editorDefaults: { rememberLastValues: false } });
* ```
**/
rememberLastValues?: boolean;
/**
* Determines which annotation properties should persist during editing operations.
*
* @remarks
* When enabled, these property values will be remembered and automatically applied:
* - When creating new annotations of the same type
* - When adding form widgets
* - During subsequent editing sessions
*
* This creates a consistent editing experience by maintaining property values
* between annotation actions.
*
* @defaultValue
* ```typescript
* [
* "appearanceColor", "borderStyle", "color", "interiorColor",
* "backgroundColor", "borderColor", "opacity", "textAlignment",
* "printableFlag", "open", "lineStart", "lineEnd",
* "markBorderColor", "markFillColor", "overlayFillColor",
* "overlayText", "overlayTextJustification", "newWindow",
* "calloutLineEnd", "fontSize", "fontName", "name",
* "readOnly", "required", "hasEditFlag"
* ]
* ```
*
* @example
* Remember only the borderStyle property:
* ```javascript
* const viewer = new DsPdfViewer("#root", {
* editorDefaults: {
* rememberLastValues: true,
* lastValueKeys: ["borderStyle"]
* }
* });
* ```
*/
lastValueKeys?: string[];
/**
* The `printResolution` option specifies the resolution (in dots per inch - DPI) used for printing PDF documents.
* It determines the quality and detail of the rendered images during the printing process. Higher DPI values
* produce sharper and more detailed printed output but may also increase memory usage and rendering time.
*
* @type {number}
* @default 150 - If not specified, the default resolution is 150 DPI.
* @example
* ```javascript
* // Example: Set the print resolution to 300 DPI
* var viewer = new DsPdfViewer("#root", {
* printResolution: 300
* });
* ```
*/
printResolution?: number;
/**
* The `printSingleJobMode` option controls whether all pages are printed as a single print job,
* regardless of their individual orientation. When set to `true`, the viewer sends all pages as a single
* print task, which may cause pages with different orientations to be printed incorrectly. When set to `false`
* (the default), pages with different orientations are printed separately to preserve their intended layout.
*
* @type {boolean}
* @default false
* @example
* ```javascript
* // Example: Enable single print job mode to force all pages to be printed together
* var viewer = new DsPdfViewer("#root", {
* printSingleJobMode: true
* });
* ```
*/
printSingleJobMode?: boolean;
/**
* Resize handle size in pixels.
* @default 8
* @example
* ```javascript
* var viewer = new DsPdfViewer("#root", {
* editorDefaults: {
* resizeHandleSize: 20,
* moveHandleSize: 40
* },
* supportApi: { apiUrl: 'support-api/gc-pdf-viewer', webSocketUrl: false }
* });
* ```
**/
resizeHandleSize?: number;
/**
* Move handle size in pixels.
* @default 14
* @example
* ```javascript
* var viewer = new DsPdfViewer("#root", {
* editorDefaults: {
* moveHandleSize: 40
* },
* supportApi: { apiUrl: 'support-api/gc-pdf-viewer', webSocketUrl: false }
* });
* ```
**/
moveHandleSize?: number;
/**
* Dot handle size in pixels. Used for callout points.
* @default 8
* @example
* ```javascript
* var viewer = new DsPdfViewer("#root", {
* editorDefaults: {
* dotHandleSize: 20
* },
* supportApi: { apiUrl: 'support-api/gc-pdf-viewer', webSocketUrl: false }
* });
* ```
**/
dotHandleSize?: number;
/**
* The URL where the standard font files are located. Include the trailing slash.
* @example
* ```javascript
* // Example with relative URL:
* var viewer = new DsPdfViewer("#root", { standardFontDataUrl: "resources/standard_fonts/" });
*
* // Example with absolute URL:
* var viewer = new DsPdfViewer("#root", { standardFontDataUrl: "http://localhost:8080/resources/standard_fonts/" });
* ```
**/
standardFontDataUrl?: string;
/**
* Default properties for Sticky note.
**/
stickyNote?: {
color?: string;
contents?: string;
};
/**
* Default properties for Line annotation.
* */
lineAnnotation?: Partial<LineAnnotation>;
/**
* Default properties for Circle annotation.
* */
circleAnnotation?: Partial<CircleAnnotation>;
/**
* Default properties for Square annotation.
* */
squareAnnotation?: Partial<SquareAnnotation>;
/**
* Default properties for Link annotation.
* */
linkAnnotation?: Partial<LinkAnnotation>;
/**
* Default properties for Redact annotation.
* */
redactAnnotation?: Partial<RedactAnnotation>;
/**
* Default properties for Ink annotation.
* */
inkAnnotation?: Partial<InkAnnotation>;
/**
* Default properties for PolyLine annotation.
* */
polyLineAnnotation?: Partial<PolyLineAnnotation>;
/**
* Default properties for Polygon annotation.
* */
polygonAnnotation?: Partial<PolygonAnnotation>;
/**
* Default properties for Text annotation.
**/
textAnnotation?: Partial<TextAnnotation>;
/**
* Default properties for FreeText annotation.
* */
freeTextAnnotation?: Partial<FreeTextAnnotation>;
/**
* Default properties for FileAttachment annotation.
**/
fileAttachmentAnnotation?: Partial<FileAttachmentAnnotation>;
/**
* Default properties for Rich Media annotation.
**/
richMediaAnnotation?: Partial<RichMediaAnnotation>;
/**
* Default properties for Sound annotation.
**/
soundAnnotation?: Partial<SoundAnnotation>;
/**
* Default properties for Stamp annotation.
**/
stampAnnotation?: Partial<StampAnnotation>;
/**
* Default properties for Highlight annotation.
**/
highlightAnnotation?: Partial<HighlightAnnotation>;
/**
* Default properties for Underline annotation.
**/
underlineAnnotation?: Partial<UnderlineAnnotation>;
/**
* Default properties for Squiggly annotation.
**/
squigglyAnnotation?: Partial<SquigglyAnnotation>;
/**
* Default properties for StrikeOut annotation.
**/
strikeOutAnnotation?: Partial<StrikeOutAnnotation>;
/**
* Default properties for Popup annotation.
* */
popupAnnotation?: Partial<PopupAnnotation>;
/**
* Default properties for CheckBox button widget.
**/
checkBoxButton?: Partial<ButtonWidget>;
/**
* Default properties for Radio button widget.
**/
radioButton?: Partial<ButtonWidget>;
/**
* Default properties for Push button widget.
* */
pushButton?: Partial<ButtonWidget>;
/**
* Default properties for Reset button widget.
* */
resetButton?: Partial<ButtonWidget>;
/**
* Default properties for Submit button widget.
**/
submitButton?: Partial<ButtonWidget>;
/**
* Default properties for Combo choice widget.
**/
comboChoice?: Partial<ChoiceWidget>;
/**
* Default properties for ListBox choice widget.
**/
listBoxChoice?: Partial<ChoiceWidget>;
/**
* Default properties for Password field widget.
* */
passwordField?: Partial<TextWidget>;
/**
* Default properties for TextArea widget.
**/
textArea?: Partial<TextWidget>;
/**
* Default properties for Text field widget.
**/
textField?: Partial<TextWidget>;
/**
* Default properties for Signature field widget.
* */
signatureField?: Partial<SignatureAnnotation>;
/**
* Default properties for Comb Text field widget.
**/
combTextField?: Partial<TextWidget>;
};
/**
* Use this option to enable annotation tools from the form editor or field tools from the annotation editor.
* @default
* ```javascript
* {
* annotationEditor: 'annotations',
* formEditor: 'fields'
* }
* ```
* @example
* ```javascript
* viewer.options.allowedTools = { formEditor: 'all' };
* ```
**/
allowedTools: {
viewer?: 'all' | 'annotations' | 'fields' | string[];
annotationEditor?: 'all' | 'annotations' | 'fields' | string[];
formEditor?: 'all' | 'annotations' | 'fields' | string[];
};
/**
* Form fields appearance rendering settings.
* Use this option to customize a specific rendering type for the appearance of form fields.
* Available appearance rendering types:
* * "Custom" - Default. The custom appearance has some improvements over the web appearance,
* for example you can specify background / border colors.
* * "Web" - Standard form field appearance using platform-native styling. See https://developer.mozilla.org/en-US/docs/Web/CSS/appearance for details.
* * "Predefined" - Predefined appearance stream from PDF when available, if appearance stream is not available, custom appearance will be used.
* @example
* ```javascript
* // Use standard form field appearance using platform-native styling for radio and checkbox buttons.
* var viewer = new DsPdfViewer("#root", { fieldsAppearance: { radioButton: "Web", checkBoxButton: "Web" } });
* ```
* @example
* ```javascript
* // Use predefined appearance stream from PDF when available:
* var viewer = new DsPdfViewer("#root", { fieldsAppearance: { radioButton: "Predefined", checkBoxButton: "Predefined" } });
* ```
**/
fieldsAppearance: {
/**
* Radio button appearance rendering type.
**/
radioButton?: FieldAppearanceRenderingType;
/**
* Check-box button appearance rendering type.
**/
checkBoxButton?: FieldAppearanceRenderingType;
/**
* Push button appearance rendering type.
**/
pushButton?: FieldAppearanceRenderingType;
};
/**
* Lock open timeout period in milliseconds.
* The user will not be able to open another document using the "open" method during the period
* specified by the lockOpenTimeout option or until the previous document is loaded.
* @ignore exclude from docs
* @default 20000
* @example
* ```javascript
* // Change lock open timeout to 5 sec:
* var viewer = new DsPdfViewer("#root", { lockOpenTimeout: 5000 );
* viewer.open("doc1.pdf");
* // The next time the open method is called, the viewer will
* // wait a maximum of 5 seconds for the previous document to open.
* viewer.open("doc2.pdf");
* ```
**/
lockOpenTimeout: number;
/**
* Configuration options for the PDF viewer's navigation toolbar component.
*
* @remarks
* Provides fine-grained control over the navigation controls in the PDF viewer toolbar,
* allowing customization of which buttons appear and their behavior. The navigation controls
* include page navigation buttons and page number display/input.
*
* @example
* Basic usage showing only previous/next buttons:
* ```typescript
* var viewer = new DsPdfViewer("#root", {
* navigation: {
* showFirstButton: false,
* showLastButton: false,
* showPageInput: false
* }
* });
* ```
*
* @example
* Custom page input width and format:
* ```typescript
* var viewer = new DsPdfViewer("#root", {
* navigation: {
* pageInputWidth: 100,
* pageCounterFormat: "Page {{current}} of {{total}}",
* showFirstButton: true,
* showLastButton: true
* }
* });
* ```
*
* @example
* Complete configuration with all options:
* ```typescript
* var viewer = new DsPdfViewer("#root", {
* navigation: {
* showFirstButton: true, // Show first page button
* showPrevButton: true, // Show previous page button
* showPageInput: true, // Show page number input
* showNextButton: true, // Show next page button
* showLastButton: true, // Show last page button
* pageInputWidth: 90, // Width of page input in pixels
* pageCounterFormat: "{{current}}/{{total}}" // Custom page counter format
* }
* });
* ```
*
* @see {@link NavigationControlOptions} for the complete interface definition.
*/
navigation?: NavigationControlOptions;
/**
* Specifies the default file name to be used when creating a new document within the viewer.
* This option is different from `friendlyFileName` as it specifically sets the name for newly created documents,
* rather than naming an existing document.
*
* @type {string}
* @default "new-document.pdf"
*
* @example
* // Initialize the viewer with a custom file name for new documents
* var viewer = new DsPdfViewer("#root", { newDocumentFileName: "sample.pdf" });
*/
newDocumentFileName?: string;
/**
* Page display type.
* @example
* ```javascript
* // Example: Switch the page display mode to "TwoPage".
* var viewer = new DsPdfViewer("#root", {
* pageDisplay: "TwoPage"
* });
* ```
*/
pageDisplay?: PageDisplayType;
/**
* Default viewer's save settings, used when user clicks the Save button.
*
* @type {SaveSettings}
* @example
* ```javascript
* // Save the document in PDF format with a custom progress message.
* var viewer = new DsPdfViewer("#root", { saveSettings: { format: "PDF", progressMessage: "Saving PDF..." } });
*
* // Save only the first three pages of the document in PNG format.
* var viewer = new DsPdfViewer("#root", { saveSettings: { format: "PNG", pages: "0-2" } });
*
* // Save the document with a signature and reload it in the viewer.
* var viewer = new DsPdfViewer("#root", { saveSettings: { sign: { ...signatureDetails }, reload: true } });
*
* // Save the document with a zoom factor of 2.0 when saving as PNG.
* var viewer = new DsPdfViewer("#root", { saveSettings: { format: "PNG", zoomFactor: 2.0 } });
*
* // Save the document in linearized PDF format for fast web viewing.
* var viewer = new DsPdfViewer("#root", { saveSettings: { format: "PDF", saveMode: "Linearized" } });
* ```
*/
saveSettings: SaveSettings;
/**
* "Save As" dropdown button options.
* @type {SaveAsOptions | SaveAsFormat}
* @example
* ```javascript
* // Limit the save as options available in the dropdown menu to "PDF" and "PNG".
* var viewer = new DsPdfViewer("#root", { saveAsOptions: { availableFormats: ["PDF", "PNG"] } });
*
* // Show the "Save As" button dropdown with default available formats.
* var viewer = new DsPdfViewer("#root", { saveAsOptions: { showSaveAsButton: true } });
*
* // Hide the "Save As" dropdown button.
* var viewer = new DsPdfViewer("#root", { saveAsOptions: { showSaveAsButton: false } });
* ```
*/
saveAsOptions?: SaveAsOptions | SaveAsFormat;
/**
* The Snap Alignment feature customization settings.
* The *tolerance* setting is the distance between the edges of two objects within which the object that is being
* moved or resized snaps to the other object. Margin is the extra space before or after the edge of a field or page.
* The *margin* setting is the distance from the target object to which the edge of the object being moved or resized snaps.
* The *center* setting allows to snap objects to centers of other objects (in addition to edges).
* @default
* ```javascript
* { snapAlignment: true }
* By default, snap tolerance is 5pt,
* snap margin between objects and page edges is 10pt,
* snap to center is true.
* ```
* @example
* ```javascript
* // Enable vertical snap margin:
* var viewer = new DsPdfViewer("#root", { snapAlignment: { margin: { vertical: 10, horizontal: false} }, supportApi: 'api/pdf-viewer'});
* ```
* @example
* ```javascript
* // Change tolerance and snap margins:
* viewer.options.snapAlignment = { tolerance: 5, margin: 20 };
* ```
**/
snapAlignment: true | false | {
tolerance: number | {
horizontal: number | false;
vertical: number | false;
};
margin: false | true | number | {
horizontal: number | boolean;
vertical: number | boolean;
};
center: false | true | {
horizontal: boolean;
vertical: boolean;
};
};
/**
* By default, the viewer uses its own context menu.
* Set this option to true if you want to use the browser context menu.
* Please, note, if you set this option to true, some functions of the
* context menu will not be available (for example, actions of the Editor and Reply tool).
* @default false
* @example
* ```javascript
* // Enable native browser context menu:
* var viewer = new DsPdfViewer("#root", { useNativeContextMenu: true } );
* ```
* */
useNativeContextMenu: boolean;
/**
* This function will be called when context menu is about to be shown.
* You can use this function to customize context menu.
* Return false if you want to prevent open context menu action.
* @default undefined
* @example
* ```javascript
* // This code shows how to modify the context menu and
* // add search using Google and Bing search engines:
* viewer.options.onBeforeOpenContextMenu = function (items, mousePosition, viewer) {
* var selectedText = viewer.getSelectedText();
* if (selectedText) {
* // Remove existent items:
* items.splice(0, items.length);
* // Add own menu items:
* items.push({
* type: 'button',
* text: 'Search using Google',
* onClick: function () {
* window.open('http://www.google.com/search?q=' + encodeURI(selectedText), '_blank');
* }
* });
* items.push({
* type: 'button',
* text: 'Search using Bing',
* onClick: function () {
* window.open('https://www.bing.com/search?q=' + encodeURI(selectedText), '_blank');
* }
* });
* }
* return true;
* };
* ```
**/
onBeforeOpenContextMenu?: Function;
/**
* This function will be called when context menu is about to be hidden.
* Return false if you want to prevent close context menu action.
* @default undefined
* @example
* ```javascript
* viewer.options.onBeforeCloseContextMenu = function(e) {
* console.log("The context menu will be closed soon.");
* return true;
* };
* ```
* @default undefined
* @example
* ```javascript
* viewer.options.onBeforeCloseContextMenu = function(e) {
* if(!confirm("Do you want to close context menu?")) {
* console.log("The context menu will not be closed.");
* return false;
* }
* console.log("The context menu will be closed.");
* return true;
* };
* ```
* */
onBeforeCloseContextMenu?: Function;
/**
* Controls the display of the context menu when text is selected.
* - "Auto": Automatically determines whether to show the context menu based on the device type.
* - "On": Always show the context menu when text is selected.
* - "Off": Never show the context menu when text is selected.
* Default value is "Auto".
* On systems with mice, "Auto" behaves like "Off".
* On small devices (phones, tablets) without mice, "Auto" behaves like "On".
* @example
* // Configure the viewer to always show the context menu when text is selected
* var viewer = new DsPdfViewer(selector, {
* showContextMenuOnSelection: "On"
* });
* @example
* // Configure the viewer to never show the context menu when text is selected
* var viewer = new DsPdfViewer(selector, {
* showContextMenuOnSelection: "Off"
* });
*/
showContextMenuOnSelection?: "Auto" | "On" | "Off" | boolean;
/**
* Specifies whether the modification date of an annotation can be edited in the UI.
*
* @type {boolean}
* @default false
* @description If set to `true`, the modification date field in the property grid UI will be editable.
* By default, it is set to `false`, making the modification date read-only.
* @example
* // Configure the Viewer to allow editing of the Modification Date in the Annotation Editor UI
* var viewer = new DsPdfViewer(selector, {
* allowModificationDateEdit: true
* });
*/
allowModificationDateEdit?: boolean;
/**
* Configuration options for the text markup context sub-menu.
*
* @example
* ```javascript
* // Disable the text markup context sub-menu:
* var viewer = new DsPdfViewer(selector, {
* textMarkupContextMenu: false
* });
* ```
*
* @example
* ```javascript
* // Customize the available colors in the text markup context menu:
* var viewer = new DsPdfViewer(selector, {
* textMarkupContextMenu: {
* colors: [
* { value: "#ff0000", displayName: "Red" },
* { value: "#000000", displayName: "Black" }
* ]
* }
* });
* ```
*
* @example
* ```javascript
* // Define different colors for specific text markup types:
* var viewer = new DsPdfViewer(selector, {
* textMarkupContextMenu: {
* colors: {
* highlight: [
* { value: "#ff0000", displayName: "Red" },
* { value: "#000000", displayName: "Black" }
* ],
* underline: [
* { value: "#ff0000", displayName: "Red" }
* ]
* }
* }
* });
* ```
*
* @example
* ```javascript
* // Hide all color options in the text markup context menu:
* var viewer = new DsPdfViewer(selector, {
* textMarkupContextMenu: { colors: [] }
* });
* ```
*/
textMarkupContextMenu?: TextMarkupContextMenuSettings | false;
/**
* Undo state storage options.
* @example
* ```javascript
* // Disable undo storage:
* var viewer = new DsPdfViewer(selector, {
* undo: false
* });
* ```
* @example
* ```javascript
* // Do not track "Open" and "Close" commands:
* var viewer = new DsPdfViewer(selector, {
* undo: { skipCommands: "Open" }
* });
* ```
**/
undo?: UndoStorageOptions | false;
/**
* An optional content is a collection of graphics that can be made visible or invisible dynamically.
* Use the optionalContentConfig option to configure optional content visibility
* @ignore exclude from docs
**/
optionalContentConfig?: OptionalContentConfig;
/**
* The Reply Tool settings.
* @default
* Default settings are:
* * readOnly: false,
* * allowAddNote: true,
* * allowChangeUserName: true,
* * allowAddReply: true,
* * allowDelete: true,
* * allowStatus: true,
* * allowChangeOtherUser: true,
* * allowDeleteOtherUser: true,
* * allowStatusOtherUser: true,
* * allowAddReplyOtherUser: true
* ```javascript
* // Prevent changing or deleting another user's comments:
* var viewer = new DsPdfViewer('#root', { replyTool: { allowChangeOtherUser: false,
* allowDeleteOtherUser: false },
* userName: 'John', supportApi: 'api/pdf-viewer' });
* viewer.addReplyTool('expanded');
* ```
* @example
* ```javascript
* // Disallow change author name (allowChangeUserName is false)
* // and disallow add changes to comments of other users (allowChangeOtherUser is false):
* var viewer = new DsPdfViewer('#root', { replyTool: { allowChangeOtherUser: false,
* allowChangeUserName: false },
* userName: 'John', supportApi: 'api/pdf-viewer' });
* viewer.addReplyTool('expanded');
* ```
* @example
* ```javascript
* // Add read-only reply tool:
* var viewer = new DsPdfViewer('#root', {
* replyTool: { readOnly: true },
* userName: 'John',
* supportApi: 'api/pdf-viewer' });
* viewer.addReplyTool('expanded');
* ```
* @example
* ```javascript
* // Hide "Add Sticky Note" item from context menu:
* var viewer = new DsPdfViewer('#root', { replyTool: { allowAddNote: false },
* userName: 'John', supportApi: 'api/pdf-viewer' });
* viewer.addReplyTool();
* ```
**/
replyTool?: ReplyToolSettings;
/**
* Author's user name.
* This option is used by the Annotation Editor and Reply Tool as the default for the Author field.
* @example
* ```javascript
* var viewer = new DsPdfViewer('#root', { userName: 'John', supportApi: 'api/pdf-viewer' });
* ```
* */
userName?: string;
/**
* Used by form submission and for theme urls.
* @example
* ```javascript
* var viewer = new DsPdfViewer("#root", { baseUrl: "http://localhost/mysite/" });
* ```
* */
baseUrl?: string;
/**