Capture signatures. More...

Public Member Functions
	~SignDocCapture ()
	Destructor. More...

	!SignDocCapture ()
	Finalizer. More...

	SignDocCapture ()
	Constructor. More...

SignDocCaptureDevice	createDefaultDevice (SignDocCaptureFilters aFilters)
	Create a SignDocCaptureDevice object for the default capture device. More...

void	enumerateDevices (SignDocCaptureFilters aFilters)
	Enumerate capture devices. More...

int	getNumberOfDevices ()
	Get the number of devices found by enumerateDevices(). More...

SignDocCaptureDevice	takeDevice (int aIndex)
	Get a device found by enumerateDevices(), taking ownership. More...

SignDocCaptureDisplay	createDisplayForHwnd (long long aHwnd)
	Create a SignDocCaptureDisplay object for a Windows window handle. More...

void	startCapture (SignDocCaptureDevice aDevice, SignDocCaptureDisplay aDisplay, SignDocCaptureListener aListener, SignDocCaptureParameters aCaptureParameters, SignDocImageParameters aImageParameters)
	Capture a signature. More...

SignDocSignatureData	waitCapture (SignDocCaptureOutput aOutput)
	Wait until the capture started by startCapture() ends. More...

SignDocCaptureResult	waitCapture2 ()
	Wait until the capture started by startCapture() ends. More...

void	stopCapture (CaptureEvent aEvent, int aButtonId)
	Make waitCapture2() or waitCapture() return now. More...

void	restartCapture ()
	Restart capture. More...

SignDocSignatureData	getSignatureData ()
	Get the samples collected so far. More...

bool	isCapturing ()
	Check if this object is currently capturing. More...

SignDocImagePoint	mapCoordinates1 (CaptureCoordinateSystem aCoordinateSystem, int aX, int aY)
	Map the coordinates of a sample from the digitizer coordinate system (CaptureCoordinateSystem.Digitizer) to another coordinate system. More...

SignDocSignatureSample	mapCoordinates (CaptureCoordinateSystem aCoordinateSystem, SignDocSignatureSample aInput)
	Map the coordinates of a sample from the digitizer coordinate system (CaptureCoordinateSystem.Digitizer) to another coordinate system. More...

SignDocImagePoint	mapCoordinates (CaptureCoordinateSystem aInputCoordinateSystem, CaptureCoordinateSystem aOutputCoordinateSystem, int aX, int aY)
	Map between two coordinate systems. More...

SignDocSignatureSample	mapCoordinates (CaptureCoordinateSystem aInputCoordinateSystem, CaptureCoordinateSystem aOutputCoordinateSystem, SignDocSignatureSample aInput)
	Map between two coordinate systems. More...

string	getCaptureError ()
	Get the error message for CaptureEvent.Error. More...

string	getErrorMessage ()
	Get an error message for the last function call. More...

Detailed Description

Capture signatures.

Do this to capture a signature:

Create a SignDocCapture object.
Call SignDocCapture.createDefaultDevice() or SignDocCapture.enumerateDevices() to get a SignDocCaptureDevice object for the capture device. Alternatively, implement your own capture device by deriving from SignDocCaptureDevice.
Optionally call SignDocCaptureDevice.setDeviceInteger() and friends to configure the capture device.
Call SignDocCaptureDevice.connect().
Call SignDocCaptureDevice.getDeviceInteger("DisplayType") to find out what type of display the capture device has.
Create a SignDocCaptureParameters object and set any desired parameters such as the background image (for display type CaptureDisplayType.Dedicated).
Optionally create a SignDocImageParameters object to control how a color image is converted to monochrome for capture devices with monochrome display.
If the display type is CaptureDisplayType.Managed, you need to create a GUI window to be able to capture a signature (for other display types, you can capture without a GUI, the following step is optional for those).
Create a GUI window (a SignDocCaptureDisplayControl or using a class derived from it).
Call SignDocCapture.startCapture(), passing the objects created above.
If SignDocCapture.startCapture() succeeds, call SignDocCapture.waitCapture2(). waitCapture2() or waitCapture() must be called if startCapture() succeeds.
Examine the SignDocCaptureResult object.
Call SignDocCaptureDevice.disconnect().
If you are using the captured data for signing a PDF or TIFF document, call SignDocSignatureData.saveToMemory() on the object returned by SignDocCaptureResult.getSignatureData(). Pass SignatureDataFormat.iso_19794_7_2014 in aFormat and call SignDocSignatureParameters.setBlob() with the resulting blob to set blob parameter "BiometricData".

The process should be per monitor DPI aware.

Constructor & Destructor Documentation

~SignDocCapture ( )

Destructor.

!SignDocCapture ( )

Finalizer.

SignDocCapture ( )

Constructor.

Member Function Documentation

SignDocCaptureDevice createDefaultDevice ( SignDocCaptureFilters aFilters )

Create a SignDocCaptureDevice object for the default capture device.

If aFilters is null, default filters will be used, see SignDocCaptureFilters.clear().

The license must allow capturing signatures.

Parameters

[in] aFilters Search for capture devices according to this filter specification. Default filters will be used if null is passed, see above.

Returns: The new SignDocCaptureDevice object.

See also: enumerateDevices()

SignDocCaptureDisplay createDisplayForHwnd ( long long aHwnd )

Create a SignDocCaptureDisplay object for a Windows window handle.

If you use the SignDocCaptureDisplay object created by this function with startCapture(), waitCapture2() or waitCapture() will run a message loop.

Parameters

[in] aHwnd The window handle. That window must not be destroyed before the new SignDocCaptureDisplay object.

Returns: The new SignDocCaptureDisplay object.

void enumerateDevices ( SignDocCaptureFilters aFilters )

Enumerate capture devices.

If aFilters is null, default filters will be used, see SignDocCaptureFilters.clear().

The license must allow capturing signatures.

This function fails if no capture devices can be found.

Parameters

[in] aFilters Search for capture devices according to this filter specification. Default filters will be used if null is passed, see above.

See also: createDefaultDevice(), getNumberOfDevices(), takeDevice()

string getCaptureError ( )

Get the error message for CaptureEvent.Error.

Returns: A string containing the error message for CaptureEvent.Error. The string is empty if SignDocCaptureResult.getEvent() (or SignDocCaptureOutput.getEvent()) does not return CaptureEvent.Error.

See also: getErrorMessage(), SignDocCaptureResult.getCaptureError()

string getErrorMessage ( )

Get an error message for the last function call.

Returns: A string describing the reason for the failure of the last function call. The string is empty if the last call succeeded.

See also: getCaptureError()

int getNumberOfDevices ( )

Get the number of devices found by enumerateDevices().

Returns: The number of devices found by enumerateDevices().

See also: enumerateDevices(), takeDevice()

SignDocSignatureData getSignatureData ( )

Get the samples collected so far.

Returns: The SignDocSignatureData object used for collecting samples, ie, the object that will be returned by waitCapture() or SignDocCaptureResult.getSignatureData(). Do not use the returned reference for destroying that object. null if not capturing.

bool isCapturing ( )

Check if this object is currently capturing.

A SignDocCapture object is capturing between a successful call to startCapture() and the return of waitCapture2() or waitCapture().

Returns: true iff this object is currently capturing.

SignDocSignatureSample mapCoordinates	(	CaptureCoordinateSystem	aCoordinateSystem,
		SignDocSignatureSample	aInput
	)

Map the coordinates of a sample from the digitizer coordinate system (CaptureCoordinateSystem.Digitizer) to another coordinate system.

Parameters

[in]	aCoordinateSystem	The new coordinate system, see CaptureCoordinateSystem.
[in]	aInput	The sample to be converted.

Returns: The sample with mapped coordinates.

See also: mapCoordinates1()

SignDocImagePoint mapCoordinates	(	CaptureCoordinateSystem	aInputCoordinateSystem,
		CaptureCoordinateSystem	aOutputCoordinateSystem,
		int	aX,
		int	aY
	)

Map between two coordinate systems.

Parameters

[in]	aInputCoordinateSystem	The coordinate system of aX and aY, see CaptureCoordinateSystem.
[in]	aOutputCoordinateSystem	The coordinate system of the return value, see CaptureCoordinateSystem.
[in]	aX	The X coordinate.
[in]	aY	The Y coordinate.

Returns: The mapped coordinates.

See also: mapCoordinates1()

SignDocSignatureSample mapCoordinates	(	CaptureCoordinateSystem	aInputCoordinateSystem,
		CaptureCoordinateSystem	aOutputCoordinateSystem,
		SignDocSignatureSample	aInput
	)

Map between two coordinate systems.

Parameters

[in]	aInputCoordinateSystem	The coordinate system of aInput, see CaptureCoordinateSystem.
[in]	aOutputCoordinateSystem	The coordinate system of the return value, see CaptureCoordinateSystem.
[in]	aInput	The sample to be converted.

Returns: The sample with mapped coordinates.

See also: mapCoordinates1()

SignDocImagePoint mapCoordinates1	(	CaptureCoordinateSystem	aCoordinateSystem,
		int	aX,
		int	aY
	)

Map the coordinates of a sample from the digitizer coordinate system (CaptureCoordinateSystem.Digitizer) to another coordinate system.

Parameters

[in]	aCoordinateSystem	The new coordinate system, see CaptureCoordinateSystem.
[in]	aX	The X coordinate.
[in]	aY	The Y coordinate.

Returns: The mapped coordinates.

See also: mapCoordinates()

void restartCapture ( )

Restart capture.

This function is used for letting the signer try again after making a mistake. It performs these steps:

temporarily suspend processing of incoming samples
throw the samples captured so far
clear the display of the capture device or redisplay the background image if one was set in the capture parameters
call clearDisplay() for aDisplay of startCapture()
reenable processing of incoming samples

On error, capture will be terminated and waitCapture2() or waitCapture() will report the error.

See also: stopCapture()

void startCapture	(	SignDocCaptureDevice	aDevice,
		SignDocCaptureDisplay	aDisplay,
		SignDocCaptureListener	aListener,
		SignDocCaptureParameters	aCaptureParameters,
		SignDocImageParameters	aImageParameters
	)

Capture a signature.

Use enumerateDevices() or createDefaultDevice() for getting a SignDocCaptureDevice object.

The objects passed to aDevice, aDisplay, and aListener must remain alive at least until waitCapture2() or waitCapture() returns (unless startCapture() reports an error).

If startCapture() succeeds, waitCapture2() or waitCapture() must be called.

The license must allow capturing signatures.

Parameters

[in]	aDevice	The capture device. Must not be null. The device must be in state CaptureDeviceState.Connected.
[in]	aDisplay	An object to be used for displaying the background image as well as samples as they are received. Can be null. If null is passed, the display of the capture device will be used (unless that display is managed by the operating system). If this argument is not null, aDisplay will be used in addition to the display of the capture device. For some capture devices (such as Tablet PC), aDisplay also defines the capture area. aDisplay must not have been created by SignDocCaptureDevice.createDisplay(). aDisplay must have been created by createDisplayForHwnd() for Tablet PC (Windows). Displaying samples on the capture device can be disabled by setting boolean parameter "PaintStrokes" of aCaptureParameters to false, see SignDocCaptureParameters.setBoolean().
[in]	aListener	A listener receiving samples and events, can be null.
[in]	aCaptureParameters	Capture parameters, can be null. If this argument is null, the default values of SignDocCaptureParameters will be used.
[in]	aImageParameters	Image parameters, used for showing the background image and for painting strokes on aDisplay, can be null. If this argument is null, the default values of SignDocImageParameters for startCapture() will be used.

See also: waitCapture(), waitCapture2()

void stopCapture	(	CaptureEvent	aEvent,
		int	aButtonId
	)

Make waitCapture2() or waitCapture() return now.

This function succeeds if waitCapture2() or waitCapture() already returned.

Parameters

[in]	aEvent	The event to be returned by SignDocCaptureResult.getEvent() or SignDocCaptureOutput.getEvent().
[in]	aButtonId	The button identifier to be returned by SignDocCaptureResult.getButtonId() or SignDocCaptureOutput.getButtonId().

See also: restartCapture(), SignDocCaptureListener.gotError(), SignDocCaptureListener.gotEvent()

SignDocCaptureDevice takeDevice ( int aIndex )

Get a device found by enumerateDevices(), taking ownership.

You can take ownership of each SignDocCaptureDevice object only once. When calling this function twice with the same index (without intervening call to enumerateDevices()), the second call will fail.

Parameters

[in] aIndex The zero-based index of the device.

Returns: The SignDocCaptureDevice object.

See also: enumerateDevices(), getNumberOfDevices()

SignDocSignatureData waitCapture ( SignDocCaptureOutput aOutput )

Wait until the capture started by startCapture() ends.

Please use waitCapture2() instead of waitCapture().

There are situations where blocking in waitCapture() or waitCapture2() is undesirable. In those cases, SignDocCaptureDevice.runDeviceLoop() should just return and SignDocCaptureDevice.stopCapture() should trigger the call to waitCapture() or waitCapture2().

Parameters

[in,out] aOutput An object that will be updated with the event that terminated capture. Can be null, but then you'll have to use a SignDocCaptureListener that records events.

Returns: An object containing the captured signature, null on error.

See also: stopCapture(), waitCapture2()

SignDocCaptureResult waitCapture2 ( )

Wait until the capture started by startCapture() ends.

This is a newer version of waitCapture().

There are situations where blocking in waitCapture2() or waitCapture() is undesirable. In those cases, SignDocCaptureDevice.runDeviceLoop() should just return and SignDocCaptureDevice.stopCapture() should trigger the call to waitCapture2() or waitCapture().

Returns: A new SignDocCaptureResult. That object will contain the captured data and other information. null on error.

See also: stopCapture(), waitCapture()

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation