de.softpro.signware.SPAcquire Class Reference

Inheritance diagram for de.softpro.signware.SPAcquire:

Detailed Description

Acquire a signature / reference without GUI on the computer screen.

Signware also includes an object to capture signatures / references with native GUI, please read the chapter comparison of SPAcquire and SPGuiAcqu.

The java interfaces add one more object to capture signature / reference without GUI: SPAcquire2. SPAcquire2 extends SPAcquire and adds support for javax.swing.Action objects and dispatches virtual button clicks to the registered actions.

Operating Systems:: Windows (Win32)

Public Member Functions

void acquire () throws SPSignwareException

Start acquiry mode.

void acquireDone (int iResult) throws SPSignwareException

End acquiry mode.

void acquireProcessMessages () throws SPSignwareException

Process pending messages if in acquiry mode.

void acquireWait () throws SPSignwareException

Wait for termination of acquiry mode.

void addBackgroundDocument (String strDescription) throws SPSignwareException

Add one or more Documents in the background image.

void addBackgroundDocument (byte[] baDescription) throws SPSignwareException

Add one or more Documents in the background image.

void addBackgroundImage (String strDescription) throws SPSignwareException

Add one or more Images in the background image.

void addBackgroundImage (byte[] baDescription) throws SPSignwareException

Add one or more Images in the background image.

void addBackgroundObject (String strDescription) throws SPSignwareException

Add one or more image and text fields in the background image.

void addBackgroundObject (byte[] baDescription) throws SPSignwareException

Add one or more image and text fields in the background image.

void addBackgroundText (String strDescription) throws SPSignwareException

Add one or more text fields in the background image.

void addBackgroundText (byte[] baDescription) throws SPSignwareException

Add one or more text fields in the background image.

void buttonCallback (int iButtonId)

Callback function called when a hardware button is pressed.

void clearEntries (int iFlags) throws SPSignwareException

Clear all internal signature data of any acquiries within this object.

void connect (SPPropertyMap spDescriptor) throws SPSignwareException

Connect to the associated SPTablet object based on an enumeration.

void connect (String strTabletAlias) throws SPSignwareException

Connect to the associated SPTablet object based on an Alias.

void connect (String strTabletClass, String strConfig) throws SPSignwareException

Connect to the associated SPTablet object.

void connect (int iDriver) throws SPSignwareException

Connect to the associated SPTablet object.

void createTablet (SPPropertyMap spDescriptor) throws SPSignwareException

Create the associated SPTablet object based on an enumeration.

void createTablet (String strTabletAlias) throws SPSignwareException

Create the associated SPTablet object based on an Alias.

void createTablet (String strTabletClass, String strConfig) throws SPSignwareException

Create the associated SPTablet object.

void createTablet (int iDriver) throws SPSignwareException

Create the associated SPTablet object.

void disconnect () throws SPSignwareException

Disonnect from the associated SPTablet object.

void documentCallback (int iDocId, int iRectId)

Callback function called when a virtual button (rectangle), that is assigned o a document, is clicked.

SPImage getBackgroundImage () throws SPSignwareException

Query the background image as it is displayed on the tablet.

String getBackgroundText () throws SPSignwareException

Query the background text as it is displayed on the tablet.

boolean getBoolProperty (String strName) throws SPSignwareException

Query a property.

int getDrawMode () throws SPSignwareException

Get the draw mode.

int getIntProperty (String strName) throws SPSignwareException

Query a property.

SPReference getReference () throws SPSignwareException

Query the reference after a signature or reference signature acquiry.

SPSignature getSignature () throws SPSignwareException

Query the signature during acquiry mode.

SPTablet getTablet () throws SPSignwareException

Get the associated SPTablet object.

void rectCallback (int iId)

Callback function called when a virtual button (rectangle) is clicked.

void registerDocumentRect (int aId, byte[] baVirtualButtonDescription) throws SPSignwareException

Register a virtual button in a document.

void registerDocumentRect (int aId, String strVirtualButtonDescription) throws SPSignwareException

Register a virtual button in a document.

int registerRect (int iId, String strRectDescription) throws SPSignwareException

Register a virtual button in acquiry mode.

int registerRect (int iId, byte[] baRectDescription) throws SPSignwareException

Register a virtual button in acquiry mode.

void removeBackgroundObjects () throws SPSignwareException

Remove all text and image background objects.

void setActive (boolean bActive) throws SPSignwareException

Activate / deactivate the acquiry mode.

void setBackgroundImage (byte[] pucImage) throws SPSignwareException

Set the background image of a tablet that includes a LCD display.

void setBackgroundObjects (SPBackgroundObjects spBackgroundObjects) throws SPSignwareException

Set images, text fields or rectangles to the tablet LCD screen.

void setBoolProperty (String strName, boolean aValue) throws SPSignwareException

Set a property.

void setDocumentContent (int aId, byte[] baContent) throws SPSignwareException

Set the content of a document.

void setDocumentContent (int aId, String strContent) throws SPSignwareException

Set the content of a document.

void setDrawMode (int iDrawMode) throws SPSignwareException

Set the draw mode.

void setIntProperty (String strName, int iValue) throws SPSignwareException

Set a property.

void setTimeout (int iTimeout) throws SPSignwareException

Set an inactivity timeout.

SPAcquire () throws SPSignwareException

Constructor.

void statusChanged (int iMajor, int iDetail)

Callback function that is called on status changes, please read tablet status change notifications for more details.

void timeoutCallback ()

Callback function called after some time of inactivity.

void unregisterAllRects () throws SPSignwareException

Unregister all registered components.

void unregisterRect (int iId) throws SPSignwareException

Unregister a virtual button.

void vectorCallback (int iX, int iY, int iP, int iT)

Callback function that is called when the tablet sends a vector.

Static Public Attributes

static final int IDCANCEL = 2

Constant for acquireDone Result Cancel.

static final int IDOK = 1

Constant for acquireDone Result OK.

static final int SP_DRAW_MIRROR_TABLET = 0x400

Mirror the tablet contents.

static final int SP_VIRTUAL_BUTTON_CLICK = 0x200

Draw mode flag: virtual button click mode.

static final int SP_VIRTUAL_BUTTON_MODE = 0x80

Virtual button mode, do not display / process any vectors that do not refer to any virtual buttons.

Constructor & Destructor Documentation

de.softpro.signware.SPAcquire.SPAcquire ( ) throws SPSignwareException

Constructor.

Operating Systems:
Windows (Win32)

See also:
SPAcquireCreate SPAcquire comments

Member Function Documentation

void de.softpro.signware.SPAcquire.acquire ( ) throws SPSignwareException

Start acquiry mode.
This function enables acquiry mode and returns immediately. The actual state change of the tablet is signaled by callback functions, see statusChanged.
Call acquireWait() to wait for termination of acquiry mode, acquire mode is terminated with a call to acquireDone.

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
acquireDone(), acquireWait(), SPAcquireAcquire

void de.softpro.signware.SPAcquire.acquireDone ( int iResult ) throws SPSignwareException

End acquiry mode.
This function terminates acquiry mode, acquireWait() will return after terminating aquiry mode.
Call this function either from a different thread or from a callback function.

Parameters:

iResult [i] result of the signature capture,

SP_IDOK signature is be accepted
SP_IDCANCEL signature is not accepted and will be ignored

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
acquire(), acquireWait(), SPAcquireAcquireDone, SP_IDOK, SP_IDCANCEL

void de.softpro.signware.SPAcquire.acquireProcessMessages ( ) throws SPSignwareException

Process pending messages if in acquiry mode.
Acquiry mode is terminated by acquireDone() being called from a callback methods, see setTimeout() and registerRect().
acquireProccessMessages returns as soon as all pending messages have been processed, while acquireWait will not return until acquireDone was called.

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
acquire(), acquireDone(), SPAcquireAcquireProcessMessages, acquireWait

void de.softpro.signware.SPAcquire.acquireWait ( ) throws SPSignwareException

Wait for termination of acquiry mode.
Acquiry mode is terminated by acquireDone() being called from a callback methods, see setTimeout() and registerRect().
acquireProccessMessages returns as soon as all pending messages have been processed, while acquireWait returns after acquireDone was called.

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
acquire(), acquireDone(), SPAcquireAcquireWait, acquireProcessMessages

void de.softpro.signware.SPAcquire.addBackgroundDocument ( String strDescription ) throws SPSignwareException

Add one or more Documents in the background image.

Parameters:

strDescription [i] the document description, sec_XML_Data, sec_DocumentDescriptionDTD. The only supported encoding in the XML declaration is UTF-8

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireAddBackgroundDocument

void de.softpro.signware.SPAcquire.addBackgroundDocument ( byte[] baDescription ) throws SPSignwareException

Add one or more Documents in the background image.

Parameters:

baDescription [i] the document description, sec_XML_Data, sec_DocumentDescriptionDTD. Supported encodings in the XML declaration are ASCII, UTF-8, and ISO-8859-1

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireAddBackgroundDocument

void de.softpro.signware.SPAcquire.addBackgroundImage ( String strDescription ) throws SPSignwareException

Add one or more Images in the background image.

Parameters:

strDescription [i] the image description, sec_XML_Data, sec_ImageDescriptionDTD. The only supported encoding in the XML declaration is UTF-8

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireAddBackgroundImage

void de.softpro.signware.SPAcquire.addBackgroundImage ( byte[] baDescription ) throws SPSignwareException

Add one or more Images in the background image.

Parameters:

baDescription [i] the image description, sec_XML_Data, sec_ImageDescriptionDTD. Supported encodings in the XML declaration are ASCII, UTF-8, and ISO-8859-1

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireAddBackgroundImage

void de.softpro.signware.SPAcquire.addBackgroundObject ( String strDescription ) throws SPSignwareException

Add one or more image and text fields in the background image.

Parameters:

strDescription [i] the text field(s) description, see sec_XML_Data, sec_ObjectDescriptionDTD. The only supported encoding in the XML declaration is UTF-8

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireAddBackgroundObject

void de.softpro.signware.SPAcquire.addBackgroundObject ( byte[] baDescription ) throws SPSignwareException

Add one or more image and text fields in the background image.

Parameters:

baDescription [i] the text field(s) description, see sec_XML_Data, sec_ObjectDescriptionDTD. Supported encodings in the XML declaration are ASCII, UTF-8, and ISO-8859-1

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireAddBackgroundObject

void de.softpro.signware.SPAcquire.addBackgroundText ( String strDescription ) throws SPSignwareException

Add one or more text fields in the background image.

Parameters:

strDescription [i] the text field(s) description, see sec_XML_Data, sec_TextDescriptionDTD. The only supported encoding in the XML declaration is UTF-8

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireAddBackgroundText

void de.softpro.signware.SPAcquire.addBackgroundText ( byte[] baDescription ) throws SPSignwareException

Add one or more text fields in the background image.

Parameters:

baDescription [i] the text field(s) description, see sec_XML_Data, sec_TextDescriptionDTD. Supported encodings in the XML declaration are ASCII, UTF-8, and ISO-8859-1

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireAddBackgroundText

void de.softpro.signware.SPAcquire.buttonCallback ( int iButtonId )

Callback function called when a hardware button is pressed.
Override this method to do any action when a hardware button is pressed. Call acquireDone() to end acquiry mode.

Parameters:

iButtonId [i] a value identifying the button that was pressed. The value depends on the tablet, see Tablet Hardware button Assignment

See also:
acquireDone(), rectCallback()

Reimplemented in de.softpro.signware.SPAcquire2.

void de.softpro.signware.SPAcquire.clearEntries ( int iFlags ) throws SPSignwareException

Clear all internal signature data of any acquiries within this object.

Parameters:

iFlags [i] reserved parameter, pass 0

This function may be required to reenter a signature / reference when the prior entry was not accepted e.g. because the reference did not satisfy the quality criterias.

Operating Systems:
Windows (Win32)

See also:
SPAcquireClearEntries

void de.softpro.signware.SPAcquire.connect ( SPPropertyMap spDescriptor ) throws SPSignwareException

Connect to the associated SPTablet object based on an enumeration.
Please read Tablet creation options for enumerating tablets

Note:
This function connects with the default tablet if spDescriptor is null

Parameters:

spDescriptor [i] descriptor of the desired tablet

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireConnectByAlias

void de.softpro.signware.SPAcquire.connect ( String strTabletAlias ) throws SPSignwareException

Connect to the associated SPTablet object based on an Alias.
Please read Tablet creation options for resolving the alias

Parameters:

strTabletAlias [i] alias name of the desired tablet

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireConnectByAlias

void de.softpro.signware.SPAcquire.connect ( String strTabletClass,

String strConfig

) throws SPSignwareException

Connect to the associated SPTablet object.
Please read Tablet creation options for a list of supported options

Parameters:

strTabletClass [i] class name of Kofax tablet access module.

strConfig [i] pass optional configuration data. Configuration data depends on the detected hardware driver, see Installation and configuration of various pads

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireConnectEx

void de.softpro.signware.SPAcquire.connect ( int iDriver ) throws SPSignwareException

Connect to the associated SPTablet object.
Please read Tablet creation options

Parameters:

iDriver [i] Driver number, use SPTablet.SP_UNKNOWN_DRV to use any driver

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireConnect

void de.softpro.signware.SPAcquire.createTablet ( SPPropertyMap spDescriptor ) throws SPSignwareException

Create the associated SPTablet object based on an enumeration.
This is a convenience function provided for applications that might need to access the tablet driver before it is connected. The tablet driver object will be created when it is internally required, the application does not have to call this function.
A typical sample could be to select an image per tablet device. Create the tablet driver object, query the device id, pass the device specific image and then connect to the tablet.
Please read Tablet creation options for enumerating tablets

Note:
This function creates a default tablet if spDescriptor is null

Parameters:

spDescriptor [i] descriptor of the desired tablet

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireCreateTabletByAlias

void de.softpro.signware.SPAcquire.createTablet ( String strTabletAlias ) throws SPSignwareException

Create the associated SPTablet object based on an Alias.
This is a convenience function provided for applications that might need to access the tablet driver before it is connected. The tablet driver object will be created when it is internally required, the application does not have to call this function.
A typical sample could be to select an image per tablet device. Create the tablet driver object, query the device id, pass the device specific image and then connect to the tablet.
Please read Tablet creation options for resolving the Alias

Parameters:

strTabletAlias [i] alias name of the desired tablet

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireCreateTabletByAlias

void de.softpro.signware.SPAcquire.createTablet ( String strTabletClass,

String strConfig

) throws SPSignwareException

Create the associated SPTablet object.
This is a convenience function provided for applications that might need to access the tablet driver before it is connected. The tablet driver object will be created when it is internally required, the application does not have to call this function.
A typical sample could be to select an image per tablet device. Create the tablet driver object, query the device id, pass the device specific image and then connect to the tablet.
Please read Tablet creation options for a list of supported options

Parameters:

strTabletClass [i] class name of Kofax tablet access module.

strConfig [i] pass optional configuration data. Configuration data depends on the detected hardware driver, see Installation and configuration of various pads

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireCreateTabletEx

void de.softpro.signware.SPAcquire.createTablet ( int iDriver ) throws SPSignwareException

Create the associated SPTablet object.
This is a convenience function provided for applications that might need to access the tablet driver before it is connected. The tablet driver object will be created when it is internally required, the application does not have to call this function.
A typical sample could be to select an image per tablet device. Create the tablet driver object, query the device id, pass the device specific image and then connect to the tablet.
Please read Tablet creation options

Parameters:

iDriver [i] Driver number, use SPTablet.SP_UNKNOWN_DRV to use any driver

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireCreateTablet

void de.softpro.signware.SPAcquire.disconnect ( ) throws SPSignwareException

Disonnect from the associated SPTablet object.

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireDisconnect

void de.softpro.signware.SPAcquire.documentCallback ( int iDocId,

int iRectId

)

Callback function called when a virtual button (rectangle), that is assigned o a document, is clicked.

Parameters:

iDocId [i] Identifier of the associated document

iRectId [i] Identifier of the clicked Rectangle

Override this method to do any action when a virtual button (rectangle) is clicked. Call acquireDone() to end acquiry mode.

See also:
acquireDone(), registerDocumentRect()

SPImage de.softpro.signware.SPAcquire.getBackgroundImage ( ) throws SPSignwareException

Query the background image as it is displayed on the tablet.
The image will NOT contain any partial or fully entered signature strokes.

Returns:
the resulting image as a SPImage object

Exceptions:

SPSignwareException on error

SP_MEMERR out of memory
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireGetBackgroundImage

String de.softpro.signware.SPAcquire.getBackgroundText ( ) throws SPSignwareException

Query the background text as it is displayed on the tablet.

Returns:
the resulting text

Exceptions:

SPSignwareException on error

SP_MEMERR out of memory
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireGetBackgroundText

boolean de.softpro.signware.SPAcquire.getBoolProperty ( String strName ) throws SPSignwareException

Query a property.

Parameters:

strName [i] Name of the property, see SPAcquire Properties

Returns:
boolean, the value of the property

Exceptions:

SPSignwareException on errors

See also:
SPAcquireGetBoolProperty, setBoolProperty

Operating Systems:
Windows (Win32)

Since:
SPSignware Version 3.2

int de.softpro.signware.SPAcquire.getDrawMode ( ) throws SPSignwareException

Get the draw mode.

Returns:
int the draw mode, a ccombination of these flags:

SP_VIRTUAL_BUTTON_MODE equals getBoolProperty("NoStrokeEcho", true)
SP_DRAW_MIRROR_TABLET equals getBoolProperty("MirrorTablet", true)
SP_VIRTUAL_BUTTON_CLICK equals getBoolProperty("ButtonClickMode", true)

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireGetDrawMode

int de.softpro.signware.SPAcquire.getIntProperty ( String strName ) throws SPSignwareException

Query a property.

Parameters:

strName [i] Name of the property, see SPAcquire Properties

Returns:
int, the value of the property

Exceptions:

SPSignwareException on errors

See also:
SPAcquireGetIntProperty, setIntProperty

Operating Systems:
Windows (Win32)

SPReference de.softpro.signware.SPAcquire.getReference ( ) throws SPSignwareException

Query the reference after a signature or reference signature acquiry.
This is a convenience function which behaves exactly like SPReference(SPAcquire).
The returned Reference may contain a single signature, in this case a signature was captured, or multiple signatures when a true reference was captured. It is the responsability of the application to convert the reference to a signature, if the returned object includes a single signature.

Returns:
the actual acquired refence or signature returned as a reference

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireGetReference

SPSignature de.softpro.signware.SPAcquire.getSignature ( ) throws SPSignwareException

Query the signature during acquiry mode.
This is a convenience function which behaves exactly like SPSignature(SPAcquire). An error will be thrown when not in acquiry mode.
The returned signature need not contain all captured vectors. This function is provided to check for empty signatures BEFORE accepting the signature (see acquireDone).

Returns:
SPSignature: the actual acquired signature

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireGetSignature

SPTablet de.softpro.signware.SPAcquire.getTablet ( ) throws SPSignwareException

Get the associated SPTablet object.
The returned tablet object is intended to query additional information such as sample rate etc, but you cannot use it to set listeners or to start acquiry mode directly.

Returns:
SPTablet the tablet object

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireGetTablet

void de.softpro.signware.SPAcquire.rectCallback ( int iId )

Callback function called when a virtual button (rectangle) is clicked.

Parameters:

iId [i] Identifier of the clicked Rectangle

Override this method to do any action when a virtual button (rectangle) is clicked. Call acquireDone() to end acquiry mode.

See also:
acquireDone(), registerRect()

Reimplemented in de.softpro.signware.SPAcquire2.

void de.softpro.signware.SPAcquire.registerDocumentRect ( int aId,

byte[] baVirtualButtonDescription

) throws SPSignwareException

Register a virtual button in a document.

Note:
The virtual button description includes an id which may not be 0. The button id should be a unique id for each button. Subsequent registrations of virtual buttons with the same id will modify the already registered virtual button, e. g. set an icon, or move the button.

Parameters:

aId [i] the unique identifyer of the document

baVirtualButtonDescription [i] description of the rectangle position, size, text, font etc. Please see element SPSWVirtualButton in sec_VirtualButtonDescriptionDTD for details.

Returns:
SP_NOERR on success, else error code:

SP_PARAMERR invalid parameter

See also:
setDocumentContent, addBackgroundDocument, SPAcquireRegisterDocumentRect
sec_DocumentDescriptionDTD

void de.softpro.signware.SPAcquire.registerDocumentRect ( int aId,

String strVirtualButtonDescription

) throws SPSignwareException

Register a virtual button in a document.

Note:
The virtual button description includes an id which may not be 0. The button id should be a unique id for each button. Subsequent registrations of virtual buttons with the same id will modify the already registered virtual button, e. g. set an icon, or move the button.

Parameters:

aId [i] the unique identifyer of the document

strVirtualButtonDescription [i] description of the rectangle position, size, text, font etc. Please see element SPSWVirtualButton in sec_VirtualButtonDescriptionDTD for details. The only supported encoding in the XML declaration is UTF-8

Returns:
SP_NOERR on success, else error code:

SP_PARAMERR invalid parameter

See also:
setDocumentContent, addBackgroundDocument, SPAcquireRegisterDocumentRect
sec_DocumentDescriptionDTD

int de.softpro.signware.SPAcquire.registerRect ( int iId,

String strRectDescription

) throws SPSignwareException

Register a virtual button in acquiry mode.
Any registered virtual buttons will be notified in acquiry mode when the pen is pressed on a rectangle.
Registering a virtual button with an ID that has already been registered will be interpreted as an update on the rectangle coordinates.
Rectangles can only be drawn to an optional LCD screen on the tablet if they are registered before the tablet enters acquiry mode.
TextFields will be positioned within the rectangle (centered, excluding optional image space) if no valid coordinate is specified. Images will be positioned within the rectangle (left aligned) if no valid coordinate is specified.
SignWare will call the method rectCallback() when a button is clicked.

Parameters:

iId [i] the identifier for the virtual button to be registered or 0 to let this function create (and return) the ID.

If iId is 0 then a new virtual button will be created. registerRect will return the actual Id that was assigned to the button.
If iId is not 0 and a virtual button with the same Id is already registered then the existing virtual button will be updated with the passed descriptor
If iId is not 0 and a virtual button with the same Id is not yet registered then a new virtual button will be created. The Id of the new virtual button will be returned.

strRectDescription [i] description of the rectangle position, size, text, font etc. Please see element SPSWVirtualButton in sec_VirtualButtonDescriptionDTD for details.

Returns:
The identifier of the rectangle

Operating Systems:
Windows (Win32)

See also:
acquire, rectCallback(), SPAcquireRecgisterRect2 SPAcquire comments

int de.softpro.signware.SPAcquire.registerRect ( int iId,

byte[] baRectDescription

) throws SPSignwareException

Register a virtual button in acquiry mode.
Any registered virtual buttons will be notified in acquiry mode when the pen is pressed on a rectangle.
Registering a rectangle with an ID that has already been registered will be interpreted as an update on the rectangle coordinates.
Rectangles can only be drawn to an optional LCD screen on the tablet if they are registered before the tablet enters acquiry mode.
TextFields will be positioned within the rectangle (centered, excluding optional image space) if no valid coordinate is specified. Images will be positioned within the rectangle (left aligned) if no valid coordinate is specified.
SignWare will call the method rectCallback() when a button is clicked.

Parameters:

iId [i] the identifier for the virtual button to be registered or 0 to let this function create (and return) the ID.

If iId is 0 then a new virtual button will be created. registerRect will return the actual Id that was assigned to the button.
If iId is not 0 and a virtual button with the same Id is already registered then the existing virtual button will be updated with the passed descriptor
If iId is not 0 and a virtual button with the same Id is not yet registered then a new virtual button will be created. The Id of the new virtual button will be returned.

baRectDescription [i] description of the rectangle position, size, text, font etc. Please see element SPSWVirtualButton in sec_VirtualButtonDescriptionDTD for details.

Returns:
The identifier of the rectangle

Operating Systems:
Windows (Win32)

See also:
acquire, rectCallback(), SPAcquireRegisterRect2 SPAcquire comments

void de.softpro.signware.SPAcquire.removeBackgroundObjects ( ) throws SPSignwareException

Remove all text and image background objects.

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireRemoveBackgroundObjects

void de.softpro.signware.SPAcquire.setActive ( boolean bActive ) throws SPSignwareException

Activate / deactivate the acquiry mode.

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireSetActive

void de.softpro.signware.SPAcquire.setBackgroundImage ( byte[] pucImage ) throws SPSignwareException

Set the background image of a tablet that includes a LCD display.

Parameters:

pucImage [i] the image data, most standard image formats such as BMP, TIF, JPG, GIF CCITT4 etc are supported

Exceptions:

SPSignwareException on error

SP_UNSUPPORTEDERR the tablet does not support images
SP_PARAMERR any parameter was was wrong, or the image could not be read
SP_LINKLIBRARYERR external modules could not be loaded

Operating Systems:
Windows (Win32)

See also:
SPAcquireSetBackgroundImage

void de.softpro.signware.SPAcquire.setBackgroundObjects ( SPBackgroundObjects spBackgroundObjects ) throws SPSignwareException

Set images, text fields or rectangles to the tablet LCD screen.
Use SPBackgroundObjects.readFile or SPBackgroundObjects.readXML to create the background objects container. The proper objects will be selected based on the created tablet type, and all elements of the selected objects will be copied to the background

Note:
The element attribute screen is ignored in SPAcquire objects. Elements with the attribute tablet=on will be drawn on the tablet LCD, if appplicable
This object must have a vald tablet object, see createTablet, connect and must not be in aquiry state.
All existing background objects will be deleted and the new objects will be added, see removeBackgroundObjects

Parameters:

spBackgroundObjects [i] a SPBackgroundObjects object.

Exceptions:

SPSignwareException on error

SP_PARAMERR invalid parameter
SP_APPLERR cannot change background in acquiry mode or no tablet instantiated

Operating Systems:
Windows (Win32)

void de.softpro.signware.SPAcquire.setBoolProperty ( String strName,

boolean aValue

) throws SPSignwareException

Set a property.

Parameters:

strName [i] Name of the property, see SPAcquire Properties

aValue [i] the value of the property

Exceptions:

SPSignwareException on errors

See also:
SPAcquireSetBoolProperty, getBoolProperty

Operating Systems:
Windows (Win32)

Since:
SPSignware Version 3.2

void de.softpro.signware.SPAcquire.setDocumentContent ( int aId,

byte[] baContent

) throws SPSignwareException

Set the content of a document.
Use addBackgroundDocument or addBackgroundObject or setBackgroundObjects to define the layout of a document view. setDocumentContent may the be used to dynamically set the document content.

Parameters:

aId [i] the unique identifyer of the document

baContent [i] document contents as a byte array

Returns:
SP_NOERR on success, else error code:

SP_PARAMERR invalid parameter
SP_MEMERR out of memory
SP_APPLERR cannot change background in acquiry mode

Operating Systems:
Windows (Win32)

See also:
addBackgroundObject, addBackgroundDocument, removeBackgroundObjects
SPAcquireSetDocumentContent

void de.softpro.signware.SPAcquire.setDocumentContent ( int aId,

String strContent

) throws SPSignwareException

Set the content of a document.
Use addBackgroundDocument or addBackgroundObject or setBackgroundObjects to define the layout of a document view. setDocumentContent may the be used to dynamically set the document content.

Parameters:

aId [i] the unique identifyer of the document

strContent [i] fully qualified file name of the document

Returns:
SP_NOERR on success, else error code:

SP_PARAMERR invalid parameter
SP_MEMERR out of memory
SP_APPLERR cannot change background in acquiry mode

Operating Systems:
Windows (Win32)

See also:
addBackgroundObject, addBackgroundDocument, removeBackgroundObjects
SPAcquireSetDocumentContent

void de.softpro.signware.SPAcquire.setDrawMode ( int iDrawMode ) throws SPSignwareException

Set the draw mode.

Parameters:

iDrawMode [i] the draw mode, a combination of the flags:

SP_VIRTUAL_BUTTON_MODE equals setBoolProperty("NoStrokeEcho", true)
SP_DRAW_MIRROR_TABLET equals setBoolProperty("MirrorTablet", true)
SP_VIRTUAL_BUTTON_CLICK equals setBoolProperty("ButtonClickMode", true)

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireGetDrawMode

void de.softpro.signware.SPAcquire.setIntProperty ( String strName,

int iValue

) throws SPSignwareException

Set a property.

Parameters:

strName [i] Name of the property, see SPAcquire Properties

iValue [i] the value of the property

Exceptions:

SPSignwareException on errors

See also:
SPAcquireSetIntProperty, getIntProperty

Operating Systems:
Windows (Win32)

void de.softpro.signware.SPAcquire.setTimeout ( int iTimeout ) throws SPSignwareException

Set an inactivity timeout.
SignWare will call the method timeoutCallback() when the specified time has passed without any tablet action (stroke).

Parameters:

iTimeout [i] timeout in milliseconds

Operating Systems:
Windows (Win32)

See also:
timeoutCallback()

void de.softpro.signware.SPAcquire.statusChanged ( int iMajor,

int iDetail

)

Callback function that is called on status changes, please read tablet status change notifications for more details.
Override this method to do any action on status changes

Parameters:

iMajor [i] major event identifyer

iDetail [i] detailed event identifyer

void de.softpro.signware.SPAcquire.timeoutCallback ( )

Callback function called after some time of inactivity.
Override this method to do any action on timeout. Call acquireDone() to end acquiry mode.

See also:
acquireDone(), setTimeout()

void de.softpro.signware.SPAcquire.unregisterAllRects ( ) throws SPSignwareException

Unregister all registered components.

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireUnregisterAllRects
registerRect, unregisterRect

void de.softpro.signware.SPAcquire.unregisterRect ( int iId ) throws SPSignwareException

Unregister a virtual button.

Note:
The identification of a component is returned in the registerRect call.

Parameters:

iId [i] the id of the virtual button / rectangle to be unregistered as returned by registerRect

Exceptions:

SPSignwareException on error

Operating Systems:
Windows (Win32)

See also:
SPAcquireUnregisterComponent
registerRect, unregisterAllRects

void de.softpro.signware.SPAcquire.vectorCallback ( int iX,

int iY,

int iP,

int iT

)

Callback function that is called when the tablet sends a vector.
Override this method to do any action on vector events

Note:
Vectors are handled internally, typically the application does not need to process tablet vectors

Parameters:

iX [i] x-coordinate

iY [i] y-coordinate

iP [i] pressure level

iT [i] timestamp, may be -1 if not measured

Member Data Documentation

final int de.softpro.signware.SPAcquire.IDCANCEL = 2 [static]

Constant for acquireDone Result Cancel.

final int de.softpro.signware.SPAcquire.IDOK = 1 [static]

Constant for acquireDone Result OK.

final int de.softpro.signware.SPAcquire.SP_DRAW_MIRROR_TABLET = 0x400 [static]

Mirror the tablet contents.
This flag will be ignored on full screen devices (such as TabletPC). It will mirror (exactly rotate by 180 degrees) the contents of LCD screen on the pad (if applicable) and mirror all vectors from the pad.
With this flag you may use the pad 'upside down'.

See also:
setDrawMode

final int de.softpro.signware.SPAcquire.SP_VIRTUAL_BUTTON_CLICK = 0x200 [static]

Draw mode flag: virtual button click mode.
if this flag is set then virtual buttons are clicked when the pen is pressed and released in the virtual button region.
if this flag is not set then virtual buttons are clicked when the pen is pressed in the virtual button region

See also:
setDrawMode

final int de.softpro.signware.SPAcquire.SP_VIRTUAL_BUTTON_MODE = 0x80 [static]

Virtual button mode, do not display / process any vectors that do not refer to any virtual buttons.
You may define virtual buttons, and they will send events when clicked, but no strokes will be displayed.

Note:
Some tablets with LCD screen will echo strokes to the integrated LCD even when this flag is set. Kofax is in contact with the tablet manufacturers to add supporting this feature in future versions.

See also:
setDrawMode

The documentation for this class was generated from the following file:

SPAcquire.java


Public Member Functions
void	acquire () throws SPSignwareException
	Start acquiry mode.
void	acquireDone (int iResult) throws SPSignwareException
	End acquiry mode.
void	acquireProcessMessages () throws SPSignwareException
	Process pending messages if in acquiry mode.
void	acquireWait () throws SPSignwareException
	Wait for termination of acquiry mode.
void	addBackgroundDocument (String strDescription) throws SPSignwareException
	Add one or more Documents in the background image.
void	addBackgroundDocument (byte[] baDescription) throws SPSignwareException
	Add one or more Documents in the background image.
void	addBackgroundImage (String strDescription) throws SPSignwareException
	Add one or more Images in the background image.
void	addBackgroundImage (byte[] baDescription) throws SPSignwareException
	Add one or more Images in the background image.
void	addBackgroundObject (String strDescription) throws SPSignwareException
	Add one or more image and text fields in the background image.
void	addBackgroundObject (byte[] baDescription) throws SPSignwareException
	Add one or more image and text fields in the background image.
void	addBackgroundText (String strDescription) throws SPSignwareException
	Add one or more text fields in the background image.
void	addBackgroundText (byte[] baDescription) throws SPSignwareException
	Add one or more text fields in the background image.
void	buttonCallback (int iButtonId)
	Callback function called when a hardware button is pressed.
void	clearEntries (int iFlags) throws SPSignwareException
	Clear all internal signature data of any acquiries within this object.
void	connect (SPPropertyMap spDescriptor) throws SPSignwareException
	Connect to the associated SPTablet object based on an enumeration.
void	connect (String strTabletAlias) throws SPSignwareException
	Connect to the associated SPTablet object based on an Alias.
void	connect (String strTabletClass, String strConfig) throws SPSignwareException
	Connect to the associated SPTablet object.
void	connect (int iDriver) throws SPSignwareException
	Connect to the associated SPTablet object.
void	createTablet (SPPropertyMap spDescriptor) throws SPSignwareException
	Create the associated SPTablet object based on an enumeration.
void	createTablet (String strTabletAlias) throws SPSignwareException
	Create the associated SPTablet object based on an Alias.
void	createTablet (String strTabletClass, String strConfig) throws SPSignwareException
	Create the associated SPTablet object.
void	createTablet (int iDriver) throws SPSignwareException
	Create the associated SPTablet object.
void	disconnect () throws SPSignwareException
	Disonnect from the associated SPTablet object.
void	documentCallback (int iDocId, int iRectId)
	Callback function called when a virtual button (rectangle), that is assigned o a document, is clicked.
SPImage	getBackgroundImage () throws SPSignwareException
	Query the background image as it is displayed on the tablet.
String	getBackgroundText () throws SPSignwareException
	Query the background text as it is displayed on the tablet.
boolean	getBoolProperty (String strName) throws SPSignwareException
	Query a property.
int	getDrawMode () throws SPSignwareException
	Get the draw mode.
int	getIntProperty (String strName) throws SPSignwareException
	Query a property.
SPReference	getReference () throws SPSignwareException
	Query the reference after a signature or reference signature acquiry.
SPSignature	getSignature () throws SPSignwareException
	Query the signature during acquiry mode.
SPTablet	getTablet () throws SPSignwareException
	Get the associated SPTablet object.
void	rectCallback (int iId)
	Callback function called when a virtual button (rectangle) is clicked.
void	registerDocumentRect (int aId, byte[] baVirtualButtonDescription) throws SPSignwareException
	Register a virtual button in a document.
void	registerDocumentRect (int aId, String strVirtualButtonDescription) throws SPSignwareException
	Register a virtual button in a document.
int	registerRect (int iId, String strRectDescription) throws SPSignwareException
	Register a virtual button in acquiry mode.
int	registerRect (int iId, byte[] baRectDescription) throws SPSignwareException
	Register a virtual button in acquiry mode.
void	removeBackgroundObjects () throws SPSignwareException
	Remove all text and image background objects.
void	setActive (boolean bActive) throws SPSignwareException
	Activate / deactivate the acquiry mode.
void	setBackgroundImage (byte[] pucImage) throws SPSignwareException
	Set the background image of a tablet that includes a LCD display.
void	setBackgroundObjects (SPBackgroundObjects spBackgroundObjects) throws SPSignwareException
	Set images, text fields or rectangles to the tablet LCD screen.
void	setBoolProperty (String strName, boolean aValue) throws SPSignwareException
	Set a property.
void	setDocumentContent (int aId, byte[] baContent) throws SPSignwareException
	Set the content of a document.
void	setDocumentContent (int aId, String strContent) throws SPSignwareException
	Set the content of a document.
void	setDrawMode (int iDrawMode) throws SPSignwareException
	Set the draw mode.
void	setIntProperty (String strName, int iValue) throws SPSignwareException
	Set a property.
void	setTimeout (int iTimeout) throws SPSignwareException
	Set an inactivity timeout.
	SPAcquire () throws SPSignwareException
	Constructor.
void	statusChanged (int iMajor, int iDetail)
	Callback function that is called on status changes, please read tablet status change notifications for more details.
void	timeoutCallback ()
	Callback function called after some time of inactivity.
void	unregisterAllRects () throws SPSignwareException
	Unregister all registered components.
void	unregisterRect (int iId) throws SPSignwareException
	Unregister a virtual button.
void	vectorCallback (int iX, int iY, int iP, int iT)
	Callback function that is called when the tablet sends a vector.
Static Public Attributes
static final int	IDCANCEL = 2
	Constant for acquireDone Result Cancel.
static final int	IDOK = 1
	Constant for acquireDone Result OK.
static final int	SP_DRAW_MIRROR_TABLET = 0x400
	Mirror the tablet contents.
static final int	SP_VIRTUAL_BUTTON_CLICK = 0x200
	Draw mode flag: virtual button click mode.
static final int	SP_VIRTUAL_BUTTON_MODE = 0x80
	Virtual button mode, do not display / process any vectors that do not refer to any virtual buttons.