@mescius/dsimageviewer
Version:
Document Solutions Image Viewer
638 lines (637 loc) • 22.8 kB
TypeScript
import { Color } from "@dt/core-ui";
import { EventFan, PluginModel } from "@dt/core-viewer";
import { PanelHandle } from "@dt/core-viewer/types/api/PluginModel";
import { DocumentViewer } from "@dt/core-viewer/types/components";
/// <reference path="../../vendor/i18next.d.ts" />
//@ts-ignore
import { i18n } from "i18next";
/// <reference path="../../vendor/react/react.d.ts" />
//@ts-ignore
import { Component } from "react";
import { EventBusAttachOptions, EventBusEventName } from "../Core/EventBus";
import { ConfirmButton } from "../Dialogs/Types";
import { IImageLayer } from "../Layers/types";
import { ImageToolbarLayout } from "../Toolbar/ImageToolbarLayout";
import { ColorEditorLocalization } from "../Tools/ColorEditor/types";
import { UndoCommandSupport } from "../Undo/Commands";
import { ViewerOptions } from "../ViewerOptions";
import { IViewerPlugin } from "./IViewerPlugin";
import { IViewerTransactionSupport } from "./IViewerTransactionSupport";
import { IGcSelectionBox, PointLocation, Size } from "./SelectionBoxTypes";
import { GlobalCursorType, ImageFormatCode, SaveOptions } from "./Types";
import { BeforeOpenEventArgs } from "./EventArgs";
/**
* Interface describing the ImageViewer API, primarily utilized for control/plugin development purposes.
**/
export interface IImageViewer {
/**
* Used by Images Filter plugin.
* @ignore exclude from docs.
**/
pluginPanels: {
[key: string]: {
handle: PluginModel.PanelHandle;
panel: Component<any> | null;
};
};
/**
* Closes the side panel.
* @ignore exclude from docs
* @param panelHandleOrId Optional. Panel handle or panel id to close.
* @example
* ```javascript
* viewer.closePanel();
* ```
*/
closePanel(panelHandleOrId?: PanelHandle | string): any;
/**
* Left sidebar API.
* @ignore exclude from docs
* @example
* ```javascript
* viewer.leftSidebar.hide();
* ```
**/
get leftSidebar(): any;
/**
* Occurs immediately before the image opens.
* @example
* ```javascript
* var viewer = new DsImageViewer('#root');
* viewer.onBeforeOpen.register(function(args) {
* alert("A new image will be opened,\n payload type(binary or URL): " + args.type +",\n payload(bytes or string): " + args.payload);
* });
* viewer.open('Test.png');
* ```
**/
get onBeforeOpen(): EventFan<BeforeOpenEventArgs>;
createPanel<TState>(component: any, binder: PluginModel.IStateBinder<TState>, key: string, { icon, description, visible, enabled, label, location }: Partial<PluginModel.PanelSettings>): PluginModel.PanelHandle;
/** Updates the panel visibility. */
showPanel(panelKey: PluginModel.PanelHandle, visible?: boolean): void;
/** Updates panel settings such as visibility, label or "enabled" status. */
updatePanel(panelKey: PluginModel.PanelHandle, settings: Partial<PluginModel.PanelSettings>): void;
/** Gets the current panel state. */
getPanelState(panelKey: PluginModel.PanelHandle): PluginModel.PanelSettings | null;
/** Orders and filters panel items. '*' indicates "the rest of panels". 'sep'/'separator' indicated menu separator. */
layoutPanels(layout: string[]): void;
expandPanel(panelKey: PluginModel.PanelHandle): void;
collapsePanel(panelKey: PluginModel.PanelHandle): void;
/**
* Saves the Image document loaded in the Viewer to the local disk.
* @param {string | SaveOptions} [options] - The save options, including the destination file name and other settings.
* @param {boolean} [original=false] - Flag indicating whether to use the initial version of the image for save. Defaults to `false`.
* @example
* ```javascript
* // Example: Save the modified image without using specific options.
* const viewer = DsImageViewer.findControl("#root");
* viewer.save();
* ```
* @example
* ```javascript
* // Example: Save the modified image as "image.png".
* const viewer = DsImageViewer.findControl("#root");
* viewer.save({ fileName: "image.png" });
* ```
* @example
* ```javascript
* // Example: Download the original version of the image as "original_image.jpg".
* const viewer = DsImageViewer.findControl("#root");
* viewer.save({ fileName: "original_image.jpg", original: true });
* ```
* @example
* ```javascript
* // Example: Save the modified image in PNG format.
* const viewer = DsImageViewer.findControl("#root");
* viewer.save({ convertToFormat: "image/png" });
* ```
* @example
* ```javascript
* // Example: Save the modified image with a custom file name and in JPEG format.
* const viewer = DsImageViewer.findControl("#root");
* viewer.save({ fileName: "custom_name", convertToFormat: "image/jpeg" });
* ```
**/
save(options?: string | SaveOptions, original?: boolean): void;
/**
* Gets a value indicating full screen mode.
**/
get isFullscreen(): boolean;
/**
* Toggle full screen mode.
* @param fullscreen
**/
toggleFullscreen(fullscreen?: boolean): void;
/**
* Gets a value indicating whether the toolbar is hidden.
**/
get isToolbarHidden(): boolean;
/**
* Toggle toolbar visibility.
* @param show
**/
toggleToolbar(show?: boolean): void;
/**
* Sets of toggles sidebar's panels visibility
**/
toggleSidebar: (show?: boolean | undefined) => void;
get imageFormatSupportsTransparency(): boolean;
maxImageSize: Size;
panSupport: IPanSupport | undefined;
plugin: any;
toolbar: any;
/**
* Defines the layout of the toolbar.
* @description
* The full list of the *viewer* specific toolbar items:
* ```javascript
* 'open', '$navigation', '$split', 'zoom', '$fullscreen', 'save', 'about'
* ```
* @example
* ```javascript
* // Customize the toolbar layout:
* viewer.toolbarLayout.viewer.default = ["open", "$zoom", "$fullscreen", "save", "print", "about"];
* viewer.applyToolbarLayout();
* ```
**/
toolbarLayout: ImageToolbarLayout;
altPressed: boolean;
ctrlPressed: boolean;
shiftPressed: boolean;
spacePressed: boolean;
/**
* Call this method in order to apply changes in @see:toolbarLayout.
* @example
* ```javascript
* viewer.toolbarLayout.viewer.default = ["open", "save"];
* viewer.applyToolbarLayout();
* ```
* @example
* ```javascript
* var viewer = new GcImageViewer(document.querySelector("#viewer"));
* var toolbar = viewer.toolbar;
* var toolbarLayout = viewer.toolbarLayout;
* toolbar.addItem({
* key: 'custom-action',
* icon: { type: "svg", content: '<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="24" height="24" viewBox="0 0 24 24"><path style="fill: #205F78;" d="M20.25 12l-2.25 2.25 2.25 2.25-3.75 3.75-2.25-2.25-2.25 2.25-2.25-2.25-2.25 2.25-3.75-3.75 2.25-2.25-2.25-2.25 2.25-2.25-2.25-2.25 3.75-3.75 2.25 2.25 2.25-2.25 2.25 2.25 2.25-2.25 3.75 3.75-2.25 2.25 2.25 2.25z"></path></svg>' },
* title: 'Custom action',
* checked: false, enabled: false,
* action: function () {
* alert("Implement your action here.");
* },
* onUpdate: function (args) {
* return {
* enabled: true,
* checked: false,
* title: 'Custom action title'
* }
* }
* });
* toolbarLayout.viewer.default.splice(0, 0, "custom-action");
* viewer.applyToolbarLayout();
* ```
**/
applyToolbarLayout(): any;
/**
* Add window keyboard listener.
* @param uniqueKey
* @param selectionBoxHandler
*/
addKeyboardListener(uniqueKey: string, handler: WindowKeyboardListener): any;
/**
* Remove window keyboard listener.
* @param uniqueKey
*/
removeKeyboardListener(uniqueKey: string): any;
canvasToDataURL(canvas: HTMLCanvasElement): string;
/**
* Used preliminarily by the plugin developers to configure the main toolbar layout.
*
* @param pos - The position where the buttons should be inserted. Use `false` or `-1` to skip insertion. Undefined means the position will be determined automatically.
* @param buttonsToInsert - An array of button keys to be inserted.
* @param pluginType - The type of the plugin. It can be one of the following: "PaintTools", "PageTools", or "ImageFilters".
*
* @example
* // Apply a custom layout to insert "zoomIn" and "zoomOut" buttons at position 2 for the "PaintTools" plugin.
* viewer.configurePluginMainToolbar(2, ["zoomIn", "zoomOut"]);
*
* @returns void
*/
configurePluginMainToolbar(pos: number | boolean | undefined, buttonsToInsert: string[]): any;
performTransparencyConversionCheck(message: string): Promise<boolean>;
/**
* Load image data using given data url.
**/
dataUrlToImageData(dataUrl: string, destinationSize?: {
width: number;
height: number;
}): Promise<ImageData>;
/**
* Create at least one image layer which will be used for painting.
**/
ensurePaintLayer(): IImageLayer;
/**
* Finds a viewer plugin by its id.
* @example
* ```javascript
* // find imageFilters plugin:
* var imageFilters = viewer.findPlugin("imageFilters");
* // find pageTools plugin:
* var pageTools = viewer.findPlugin("pageTools");
* ```
* @param pluginId
*/
findPlugin(pluginId: string): IViewerPlugin | null;
/**
* Retrieves the point location from the pointer event provided by the 'event' parameter.
* The returned point is relative to the active canvas element
* @param event DOM Pointer or Mouse event object.
**/
getEventCanvasPoint(event: PointerEvent | MouseEvent): PointLocation;
/**
* Get current image data url.
**/
getImageDataUrl(): string;
renderColorDropdown(colorValue: Color | null | undefined, onSelect: (color: Color) => void, localization: ColorEditorLocalization, refCallback: any, settings?: {
size?: 'small' | 'default' | 'large';
includeOpacity?: boolean;
disabled?: boolean;
}): JSX.Element;
/**
* Sets the cursor style for the image viewer
* @param {GlobalCursorType} cursorType - The cursor style to apply
* @returns {void}
* @example
* // Set rotate cursor during image rotation
* viewer.setCursor('rotate');
*
* @example
* // Set resize cursor when hovering over edges
* viewer.setCursor('nwse-resize');
*
* @see GlobalCursorType for all available cursor options
*/
setCursor(cursorType: GlobalCursorType): IImageViewer;
/**
* Resets the cursor to default style
* @returns {void}
* @example
* // Reset cursor when operation completes
* viewer.resetCursor();
*
* @example
* // Reset cursor on mouse leave
* viewerElement.addEventListener('mouseleave', () => {
* viewer.resetCursor();
* });
*/
resetCursor(): IImageViewer;
/**
* Toggles between specified cursor and default style
* @param {GlobalCursorType | false} cursorType - Cursor style to apply, or false to reset
* @returns {void}
* @example
* // Toggle grab cursor during drag operations
* viewer.toggleCursor(isDragging ? 'grab' : false);
*
* @example
* // Toggle zoom cursor based on modifier key
* document.addEventListener('keydown', (e) => {
* if (e.ctrlKey) {
* viewer.toggleCursor('zoom-in');
* }
* });
*
*/
toggleCursor(cursorType: GlobalCursorType | false): IImageViewer;
/**
* Modify current image data url.
**/
setImageDataUrl(dataUrl: any): Promise<void>;
/**
* Show activity spinner.
* @example
* ```javascript
* viewer.showActivitySpinner();
* ```
**/
showActivitySpinner(container?: HTMLElement): any;
/**
* Hide activity spinner.
* @example
* ```javascript
* viewer.hideActivitySpinner();
* ```
**/
hideActivitySpinner(): any;
/**
* Start transaction.
* @ignore exclude from docs
**/
setTransaction(transaction: IViewerTransactionSupport): any;
/**
* Commit active transaction.
* @ignore exclude from docs
**/
confirmChanges(): Promise<void>;
/**
* Cancel active transaction.
* @ignore exclude from docs
**/
cancelChanges(): Promise<void | boolean>;
/**
* Clear active transaction.
* @ignore exclude from docs
**/
clearTransaction(transaction: IViewerTransactionSupport): any;
/**
* Display confirmation dialog.
**/
confirm(confirmationText?: string | JSX.Element, level?: "info" | "warning" | "error", title?: string, buttons?: ConfirmButton[]): Promise<boolean | ConfirmButton>;
/**
* Get unmodified current image data url.
**/
getOriginalImageDataUrl(): string;
/**
* Get viewer type by type name.
* @ignore exclude from docs
* @param typeName
* @example
* ```javascript
* // Get image utilities:
* var ImageUtils = viewer.getType('ImageUtils');
* ```
*/
getType(typeName: string): any;
/**
* Hide second toolbar.
* @ignore exclude from docs
* @example
* ```javascript
* viewer.hideSecondToolbar();
* ```
* @ignore exclude from docs.
**/
hideSecondToolbar(toolbarKey?: SecondToolbarType): Promise<void>;
/**
* Ensures that all visual child elements of the viewer are properly updated for layout.
* Call this method to update the size of the inner content when the viewer is dynamically resized.
* @ignore exclude from docs
* @example
* ```javascript
* viewer.eventBus.on("viewersizechanged", function() {
* // Make viewer height equal to content height of inner pages, including the margins:
* document.querySelector("#root").style.height = viewer.pageCount * 50 + viewer.pageCount * viewer.getPageSize(0, true).height + "px";
* // Invalidate layout:
* viewer.invalidate();
* });
* ```
**/
invalidate(): any;
raiseStateChanged(): any;
/**
* Remove and dispose image layer given by argument layerOrIndex.
* @param layerOrIndex Image layer or image layer index or image layer name.
**/
removeLayer(layerOrIndex: IImageLayer | number): any;
/**
* Remove and dispose all image layers.
**/
removeLayers(): any;
/**
* Show a second toolbar specified by the toolbarKey argument.
* @param toolbarKey
* @example
* ```javascript
* // Show page tools bar.
* viewer.showSecondToolbar("page-tools");
* ```
**/
showSecondToolbar(toolbarKey: SecondToolbarType): Promise<void>;
/**
* Image viewer event bus.
* @example
* ```javascript
* viewer.eventBus.on("after-open", function(args) {
* console.log("Image opened.", args);
* });
* viewer.open('Test.png');
* ```
**/
get eventBus(): IEventBus;
/**
* Indicates whether the viewer has opened the image.
* @example
*```javascript
* var hasImageFlag = viewer.hasImage;
*```
**/
get hasImage(): boolean;
/**
* Gets a format type of the opened image.
**/
get imageFormat(): ImageFormatCode;
/**
* Sets a format type of the opened image.
**/
set imageFormat(format: ImageFormatCode);
/**
* i18next instance.
**/
readonly in17n: i18n;
/**
* The ID of the viewer instance.
* Used to get access to the public UI API.
* @example
* ```javascript
* API.of(viewer.instanceId).menu.collapse();
* ```
* @ignore exclude from docs.
**/
get instanceId(): string;
/**
* Image layers. Used for painting.
**/
get layers(): IImageLayer[];
/**
* Gets the active image natural size.
* The natural size is the image's width/height if drawn with nothing constraining its width/height,
* this is the number of CSS pixels wide the image will be.
**/
get naturalSize(): {
width: number;
height: number;
};
/**
* Second toolbar API.
* @ignore exclude from docs
**/
get secondToolbar(): any;
get selectionBox(): IGcSelectionBox;
/**
* Command based undo state storage.
* @example
* ```javascript
* const isUndoInProgress = viewer.undoStorage.undoInProgress;
* ```
**/
get undoStorage(): IUndoStorage;
/**
* Outermost viewer's host element containing the gc-viewer-host class.
**/
get hostElement(): Element;
/**
* Gets currently viewed document state.
* @ignore exclude from docs.
**/
get viewerState(): DocumentViewer.Model;
}
/**
* Command based undo state storage.
**/
export interface IUndoStorage {
/**
* Apply undo storage options.
* @param options
*/
applyOptions(options: ViewerOptions): any;
/**
* Dispose undo storage.
**/
dispose(): any;
/**
* Clear undo storage.
**/
clear(): any;
/**
* Gets a value indicating whether the command specified in the command parameter is supported.
* @param command
**/
isCommandSupported(command: UndoCommandSupport): boolean;
/**
* Execute a new command.
* @param {type} command Instance of a command.
* @returns {undefined}
**/
execute(command: UndoCommandSupport): Promise<void>;
/**
* Called after command action has been executed.
* @param command
*/
onCommandExecuted(command: UndoCommandSupport): any;
/**
* Undo last action.
**/
undo(): Promise<void>;
/**
* Redo next action.
**/
redo(): Promise<void>;
/**
* Gets a value indicating whether the undo storage can undo changes.
**/
get hasUndo(): boolean;
/**
* Gets a value indicating whether the undo storage can redo changes.
**/
get hasRedo(): boolean;
/**
* Gets current undo level index.
**/
get undoIndex(): number;
/**
* Gets total undo levels count.
**/
get undoCount(): number;
/**
* Gets a flag indicating whether an undo/redo or execute operation is in progress.
**/
get undoInProgress(): boolean;
/**
* Gets undo commands list. Used by FiltersPreviewPanel.
* @ignore exclude from docs.
**/
get commands(): UndoCommandSupport[];
}
/**
* The image viewer event bus.
* @description
* Use the event bus to listen and receive certain specific "events".
* Available events are: "before-open", "after-open", "before-close", "after-close", "zoom-changed", "frame-index-changed", "animation-started", "animation-stopped".
* @example
* ```javascript
* // Liisten frame index changes:
* viewer.eventBus.on("frame-index-changed", function(args) { console.log("Image frame changed", args); });
* ```
* @example
* ```javascript
* // Listen "after-open" event once:
* viewer.eventBus.on("after-open", function(args) { console.log("Image opened", args); }, { once: true });
* ```
**/
export interface IEventBus {
/**
* Use the dispatch method to raise an event.
* @param {string} eventName
* @param {Object} data
*/
dispatch(eventName: EventBusEventName, data: any): any;
/**
* Listen eventbus event.
* @param {string} eventName
* @param {function} listener
* @param {Object} [options]
*/
on(eventName: EventBusEventName, listener: any, options?: EventBusAttachOptions): any;
/**
* Internal listen implementation, takes priority over public "on" API.
* @ignore
*/
_on(eventName: EventBusEventName, listener: any, options?: EventBusAttachOptions): any;
/**
* Remove event listener specified by the listener argument for the event specified by the eventName argument.
* @param {string} eventName
* @param {function} listener
*/
off(eventName: EventBusEventName, listener: any): any;
/**
* Internal unlisten implementation.
* @ignore
**/
_off(eventName: EventBusEventName, listener: Function | false): any;
}
export declare type PaintToolType = "Selection" | "Pencil" | "Brush" | "Eraser" | "CloneStamp" | "Text" | "Rectangle" | "Line" | "Ellipse" | "Arrow" | "Brackets" | "Image" | "None";
/**
* Represents the types of items that can be used in the Paint, Text, and Effects toolbars.
*/
export declare type ToolbarItemType = "Selection" | "Pencil" | "Brush" | "Eraser" | "CloneStamp" | "Text" | "Pixelate" | "Blur" | "Brightness" | "Contrast" | "BrightnessContrast" | "Vibrance" | "Splitter" | "Size" | "Color" | "UseOriginalImage" | "Undo" | "Redo" | "Apply" | "Cancel" | "FontSize" | "FontName" | "FontBold" | "FontItalic" | "FontColor" | "Rectangle" | "Line" | "Ellipse" | "Arrow" | "Brackets" | "Image" | "BackupObjects" | "RestoreObjects";
/**
* Second toolbar type.
*/
export declare type SecondToolbarType = "page-tools" | "crop-image" | "resize-image" | "text-tools" | "paint-tools" | "effects" | "objects" | "image-filter-tools" | "image-filter-settings" | "none";
/**
* Window keyboard listener handler interface.
**/
export interface WindowKeyboardListener {
/**
* Called when key pressed.
**/
onKeyDown: (e: KeyboardEvent, params: {
alt: boolean;
ctrl: boolean;
shift: boolean;
space: boolean;
}) => any;
/**
* Called when key released.
**/
onKeyUp: (e: KeyboardEvent, params: {
alt: boolean;
ctrl: boolean;
shift: boolean;
space: boolean;
}) => any;
}
export interface IPanSupport {
suspend(): void;
resume(): void;
}