Dev Center
Table of contents

Thanks for Downloading Dynamic Web TWAIN 30-Day Trial!

Your download will start shortly. If your download does not begin, click here to retry.

Global

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

Methods

       
CreateDWTObject() CreateDWTobjectEx() DeleteDWTObject() GetWebTwain()
Load() RegisterEvent() Unload()  

Properties

       
Autoload Containers CustomizableDisplayInfo DeviceFriendlyName
Host IfAddMD5InUploadHeader IfConfineMaskWithinTheViewer IfUseActiveXForIE10Plus
JSVersion ProductKey ResourcesPath ServiceInstallerLocation
UseDefaultViewer IfCheckCORS    

Events

       
OnWebTwainReady OnWebTwainError OnWebTwainPostExecute OnWebTwainPreExecute

CreateDWTObject()

Creates a new WebTwain instance that listens to the specified host & ports. An UI element specified by the parameter ContainerId which is typically a <div> is required. The library will generate UI and bind it to this element.

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v12.0+ v12.0+ v12.0+ v12.1+

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.

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v16.0+ v16.0+ v16.0+ v16.0+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v12.0+ v12.0+ v12.0+ v12.1+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.1+ v10.1+ v11.0+ v11.0+ v12.1+

Example

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

Usage Note

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

Load()

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

Syntax

Load(): Promise<void>;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.2+ v10.2+ v11.0+ v11.0+ v12.1+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v1.0+ v10.0+ v11.0+ v11.0+ v12.1+

Example

Dynamsoft.DWT.RegisterEvent('OnWebTwainReady',
 Dynamsoft_OnReady //The typical function for initalizing the environment once the resources have loaded
);
 
function Dynamsoft_OnReady() {
DWTObject = Dynamsoft.DWT.GetWebTwain('dwtcontrolContainer'); // Get the Dynamic Web TWAIN object that is embeded 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 Dynamsoft Service.

Syntax

Unload(): void;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.2+ v10.2+ v11.0+ v11.0+ v12.1+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.2+ v10.2+ v11.0+ v11.0+ v12.1+

Usage Notes

Default value: true.


Containers

Defines the Id and UI of the WebTwain instances.

Syntax

Containers: Container[];

Please refer to Container.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.1+ v10.1+ v11.0+ v11.0+ v12.1+

CustomizableDisplayInfo

Define the display info.

Syntax

CustomizableDisplayInfo: DisplayInfo;

Please refer to DisplayInfo.

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v16.2+ v16.2+ v16.2+ v16.2+ v16.2+

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-tracable UID will be generated.

Syntax

DeviceFriendlyName: string;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.0+ v18.0+ v18.0+ v18.0+ v18.0+

Host

Specify the target address for the local Dynamsoft Service.

Syntax

Host: string;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v16.2+ v16.2+ v16.2+ v16.2+ v16.2+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v14.0+ v14.0+ v14.0+ v14.0+ v14.0+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v14.0+ v14.0+ v14.0+ v14.0+ v14.0+

Usage Notes

Default Value: false.


IfUseActiveXforIE10Plus

This property specifies whether Dynamic Web TWAIN will be loaded using HTML5 or ActiveX when loaded in Internet Explorer 10+.

Syntax

IfUseActiveXForIE10Plus: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.3+ v10.3+ v11.0+ v11.0+ v12.1+

Usage Notes

  • Default value: false.
  • If set to true, ActiveX will be used, else HTML5 will be used.
  • This property needs to be set before Dynamic Web TWAIN loads.

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v13.1+ v13.1+ v13.1+ v13.1+ v13.1+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.1+ v10.1+ v11.0+ v11.0+ v12.1+

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 where the path to the Dynamic Web TWAIN resource files are hosted.

Syntax

ResourcesPath: string;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.1+ v10.1+ v11.0+ v11.0+ v12.1+

ServiceInstallerLocation

Sets or returns where the path to the Dynamsoft Service installers are hosted.

Syntax

ServiceInstallerLocation: string;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.4+ v18.4+ v18.4+ v18.4+ v18.4+

UseDefaultViewer

Whether to use the built-in viewer.

Syntax

UseDefaultViewer: boolean;

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v16.2+ v16.2+ v16.2+ v16.2+ v16.2+

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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v18.5+ v18.5+ v18.5+ v18.5+

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 Dynamsoft Service is not connected and prompt a service installation window.

OnWebTwainReady

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

Syntax

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v10.1+ v10.1+ v11.0+ v11.0+ v12.1+

Example

Dynamsoft.DWT.RegisterEvent('OnWebTwainReady', 
  Dynamsoft_OnReady //The typical function for initalizing 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 embeded 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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
v18.2+ v18.2+ v18.2+ v18.2+ v18.2+

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 behaviour is to hide the mask and loading spinner triggered by OnWebTwainPreExecute.

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

Syntax

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

Availability

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v10.3+ v11.0+ v11.0+ v12.1+

OnWebTwainPreExecute

This event triggers at the beginning of an asynchronous API.

The default behaviour 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

ActiveX H5(Windows) H5(macOS/TWAIN) H5(macOS/ICA) H5(Linux)
not supported v10.3+ v11.0+ v11.0+ v12.1+

Is this page helpful?

YesYes NoNo

In this article:

latest version

    • Latest Version (18.5.1)
    • Version 18.4
    • Version 18.3
    • Version 18.1
    • Version 18.0
    • Version 17.3
    • Version 17.2.1
    • Version 17.1.1
    • Version 17.0
    • Version 16.2
    • Version 16.1.1
    Change +