Global

The Global Web TWAIN properties and methods on this page live in the namespace {Dynamsoft.DWT},

Methods

Properties

Events

CreateDWTObject()

Creates a new WebTwain instance that listens to the specified host and ports. This instance requires a UI element specified by the ContainerId attribute, typically a <div>. The DWT library will generate UI and bind it to this element.

Disable auto-loading a WebTwain instance when creating a WebTwain instance with CreateDWTObject by setting Dynamsoft.DWT.AutoLoad = false and Dynamsoft.DWT.Containers = [] in the dynamsoft.webtwain.config.js file.

Syntax

CreateDWTObject(
    ContainerId: string,
    successCallBack: (DWTObject: WebTwain) => void,
    failureCallBack: ({code: number, message: string}) => void
): void;

CreateDWTObject(
    ContainerId: string,
    host: string,
    port: string | number,
    portSSL: string | number,
    successCallBack: (DWTObject: WebTwain) => void,
    failureCallBack: ({code: number, message: string}) => void
): void;

Parameters

ContainerId: Specify the id of HTML element (typically of the type HTMLDivElement) to hold the UI.

host: Specify the host. Default value: "127.0.0.1"

port: Specify the port. Default value: 18622

portSSL: Specify the SSL port. Default value: 18623

successCallback: A callback function that is executed if the request succeeds.

• DWTObject: The WebTwain instance.

failureCallback: A callback function that is executed if the request fails.

• errorString: The error string.

Availability

Example

var DWTObject;
Dynamsoft.DWT.CreateDWTObject(
    "dwtcontrolContainer",
    "127.0.0.1",
    18622,
    18623,
    function (DWTObject) {
        DWTObject = DWTObject;
        DWTObject.SelectSourceAsync()
            .then(function () {
                DWTObject.AcquireImageAsync({
                    IfCloseSourceAfterAcquire: true,
                });
            })
            .catch(function (exp) {
                alert(exp.message);
            });
    },
    function (error) {
        console.log(error);
    },
);

OR

var DWTObject;
Dynamsoft.DWT.CreateDWTObject(
    "dwtcontrolContainer",
    function (DWTObject) {
        DWTObject = DWTObject;
        DWTObject.SelectSourceAsync()
            .then(function () {
                DWTObject.AcquireImageAsync({
                    IfCloseSourceAfterAcquire: true,
                });
            })
            .catch(function (exp) {
                alert(exp.message);
            });
    },
    function (error) {
        console.log(error);
    },
);

CreateDWTObjectEx()

Creates a new UI-less WebTwain instance. This instance will be uniquely identified by the parameter WebTwainId.

Disable auto-loading a WebTwain instance when creating a WebTwain instance with CreateDWTObject by setting Dynamsoft.DWT.AutoLoad = false and Dynamsoft.DWT.Containers = [] in the dynamsoft.webtwain.config.js file.

Syntax

CreateDWTObjectEx(
  dwtInitialConfig: DWTInitialConfig,
  successCallBack: (DWTObject: WebTwain) => void,
  failureCallBack: ({code: number, message: string}) => void
): void;

Parameters

dwtInitialConfig: Specify the initial configuration of the instance. Please refer to DWTInitialConfig.

successCallback: A callback function that is executed if the request succeeds.

• DWTObject: The WebTwain instance.

failureCallback: A callback function that is executed if the request fails.

• code: The error code.
• message: The error string.

Availability

Example

var DWTObject;
Dynamsoft.DWT.CreateDWTObjectEx(
    {
        WebTwainId: "dwtId",
    },
    function (DWTObject) {
        DWTObject = DWTObject;
        DWTObject.Viewer.bind("dwtcontrolContainer");
        DWTObject.Viewer.show();
        DWTObject.SelectSourceAsync()
            .then(function () {
                DWTObject.AcquireImageAsync({
                    IfCloseSourceAfterAcquire: true,
                });
            })
            .catch(function (exp) {
                alert(exp.message);
            });
    },
    function (error) {
        console.log(error);
    },
);

DeleteDWTObject()

Delete and destroy the specified WebTwain instance.

Syntax

DeleteDWTObject(Id: string): boolean;

Parameters

Id: Specify the instance with its ContainerId or WebTwainId.

Return Value

true: Successfully.

false: Failed.

Availability

GetWebTwain()

Return the WebTwain instance by its ContainerId or WebTwainId.

Syntax

GetWebTwain(ContainerIdOrWebTwainId?: string): WebTwain;

Parameters

ContainerIdOrWebTwainId: Specify the instance with its ContainerId or WebTwainId.

Availability

Example

var DWTObject;
function Dynamsoft_OnReady() {
    DWTObject = Dynamsoft.DWT.GetWebTwain("dwtcontrolContainer"); // Get the Dynamic Web TWAIN object that is embedded in the div with id 'dwtcontrolContainer'
}

Usage Note

• If no parameter is provided, the first valid WebTwain instance is returned.

Load()

Initiates the library. If there are predefined Containers, one WebTwain instance will be created for each Container.

Syntax

Load(): Promise<void>;

Availability

Example

Dynamsoft.DWT.Load();

Usage Note

• Only used if AutoLoad is set to false.

RegisterEvent()

Registers an environmental event.

Syntax

Dynamsoft.DWT.RegisterEvent(eventName: string, listener: (...arguments: any[])=>any): boolean;

Parameters

eventName: Specify the event. Supported events: OnWebTwainReady, OnWebTwainError, OnWebTwainPostExecute, OnWebTwainPreExecute

listener: Specify the callback.

Availability

Example

Dynamsoft.DWT.RegisterEvent(
    "OnWebTwainReady",
    Dynamsoft_OnReady, //The typical function for initializing the environment once the resources have loaded
);

function Dynamsoft_OnReady() {
    DWTObject = Dynamsoft.DWT.GetWebTwain("dwtcontrolContainer"); // Get the Dynamic Web TWAIN object that is embedded in the div with id 'dwtcontrolContainer'
}

Dynamsoft.DWT.RegisterEvent("OnWebTwainError", function (error) {});

Dynamsoft.DWT.RegisterEvent("OnWebTwainPostExecute", function () {});

Dynamsoft.DWT.RegisterEvent("OnWebTwainPreExecute", function () {});

Unload()

Destroys all WebTwain instances and cuts off the connection to the Dynamic Web TWAIN Service.

Syntax

Unload(): void;

Availability

AutoLoad

Specifies whether or not to load the Web TWAIN environment when the Dynamic Web TWAIN scripts are loaded into memory.

Syntax

AutoLoad: boolean;

Availability

Usage Notes

Default value: true.

Containers

Defines the Id and UI of the WebTwain instances.

Syntax

Containers: Container[];

Please refer to Container.

Availability

CustomizableDisplayInfo

Define the display info.

Syntax

CustomizableDisplayInfo: DisplayInfo;

Please refer to DisplayInfo.

Availability

DeviceFriendlyName

This property allows you to specify a specified name to the client machine that will be used to identify the client machine when using Dynamsoft License Server. If this is not set, a randomly generated non-traceable UID will be generated.

Syntax

DeviceFriendlyName: string;

Availability

Host

Specify the target address for the local Dynamic Web TWAIN Service.

Syntax

Host: string;

Availability

Usage Notes

Default value: 127.0.0.1.

IfAddMD5InUploadHeader

Whether or not an md5 header dwt-md5 should be included in HTTP upload requests. Note that this header is not a standard header and may be deemed invalid on some web servers.

Syntax

IfAddMD5InUploadHeader: boolean;

Availability

Usage Notes

Default value: false.

IfConfineMaskWithinTheViewer

This property defines whether any Dynamic Web TWAIN generated masks will apply to the entire window or just the Viewer object. Setting this property to true will confine the mask to the Viewer object.

Syntax

IfConfineMaskWithinTheViewer: boolean;

Availability

Usage Notes

Default Value: false.

JSVersion

This is a readonly property that specifies what version the server side Dynamic Web TWAIN resources are being used with the web application.

Syntax

readonly JSVersion: string;

Availability

ProductKey

Sets or returns the product key for the library. A valid product key is required for each module of Dynamic Web TWAIN.

Syntax

ProductKey: string;

Availability

Example

Dynamsoft.DWT.ProductKey = "t0076lQAAAGNcO61He******";

If you have multiple license keys, separate them with semicolons like below:

Dynamsoft.DWT.ProductKey = "t0076lQAAAGNcO61He******;t0076lQAAAGNcO61He******";

ResourcesPath

Sets or returns the path to the directory containing Dynamic Web TWAIN resource files are hosted.

Syntax

ResourcesPath: string;

Availability

ServiceInstallerLocation

Sets or returns where the path to the Dynamic Web TWAIN Service installers are hosted.

Syntax

ServiceInstallerLocation: string;

Availability

UseDefaultViewer

Whether to use the built-in viewer.

Syntax

UseDefaultViewer: boolean;

Availability

Usage Notes

• If it is set to false, the file dynamsoft.webtwain.viewer.js is not loaded at all and there is no way to add it back later. Therefore, only set it to false when you absolutely won’t need the viewer or will be building your own viewer.

IfCheckCORS

Whether to check CORS issue in detail.

Syntax

IfCheckCORS: boolean;

Availability

Usage Notes

• Default value: false.
• When set to true, if encountering a CORS issue, it will detect the issue more specifically and return the corresponding CORS error.
• When set to false, if encountering a CORS issue, it will solely detect that the Dynamic Web TWAIN Service is not connected and prompt a service installation window.

IfAlwaysFocusOnPopupWindow

Control whether the scanner-related UI and load/save UI are always displayed in the foreground.

Syntax

IfAlwaysFocusOnPopupWindow: boolean;

Availability

Usage Notes

• Default value: true.

• When set to true, the scanner-related UI and load/save UI will always be displayed in the foreground.

• When set to false, the scanner-related UI and load/save UI will initially be displayed in the foreground, but by switching focus, they can be moved to the background behind the browser page.

OnWebTwainReady

A built-in callback triggered when the Web TWAIN resources have completed loading

Syntax

RegisterEvent("OnWebTwainReady", function () {});

Availability

Example

Dynamsoft.DWT.RegisterEvent(
    "OnWebTwainReady",
    Dynamsoft_OnReady, //The typical function for initializing the environment once the resources have loaded
);

var DWTObject;

function Dynamsoft_OnReady() {
    DWTObject = Dynamsoft.DWT.GetWebTwain("dwtcontrolContainer"); // Get the Dynamic Web TWAIN object that is embedded in the div with id 'dwtcontrolContainer'
}

OnWebTwainError

A built-in callback triggered when an error is detected when loading the Web TWAIN environment.

Syntax

RegisterEvent("OnWebTwainError", function () {});

Availability

Example

Dynamsoft.DWT.RegisterEvent("OnWebTwainError", Dynamsoft_OnError);

function Dynamsoft_OnError(error) {
    // error handling
    console.error(error.message);
}

OnWebTwainPostExecute

This event triggers at the resolution of an asynchronous API.

The default behavior is to hide the mask and loading spinner triggered by OnWebTwainPreExecute.

You may override this function to implement your own post-execute scenario. Please refer to this article.

Syntax

RegisterEvent("OnWebTwainPostExecute", function () {});

Availability

OnWebTwainPreExecute

This event triggers at the beginning of an asynchronous API.

The default behavior is to display a mask and a loading spinner.

You may override this function to either hide the default loading spinner, or define your own. Please refer to this article.

Syntax

RegisterEvent("OnWebTwainPreExecute", function () {});

Availability