visit Kofax web site

SPAcquire.h File Reference


Detailed Description

SignWare Dynamic Development toolkit, acquire signatures.

Author:
uko
This header includes an object for capturing signatures on a tablet without having a GUI on the computer screen.

Signware also includes an object to capture signatures / references with native GUI, please read Comparison SPAcquire versus SPGuiAcqu for a comparison of SPAcquire and SPGuiAcqu.

SPAcquire

The SPAcquire object captures one or more signatures from a tablet. There is no visual feedback on the pc screen, however displays integrated into the tablet will be updated.

SPAcquire adds capabilities to define special regions. These regions will be interpreted as clickable areas. When the user clicks these regions then a callback function will be called.

The acquiry object creates a signature and a reference object. The signature object will be filled during acquiry (as long as acquire mode is active). The signature object will be appended to the reference object if SPAcquireAcquireDone is called with SP_IDOK. In any case, the signature object will not be accessable after calling SPAcquireAcquireDone. The typical usage of the signature object is to check for empty signatures and to deny accepting empty signatures. Always use the created reference object as the result of an acquire operation.

The application must differentiate different types of tablet hardware:

You may define buttons that are clickable with the tablet.
These buttons are supported: Please see the provided samples for correct use of the acquiry object.

Note:
Some low-level tablet drivers use window messages to communicate with the application.
  • Wintab uses message ID's in the range WM_USER + 0x7BF0 (0x7FF0) through WM_USER + 0xFBFF (0x7FFF),
  • Kofax drivers use message ID's in the range WM_USER + 0x7BD0 (0x7FD0) through WM_USER + 0x7BDF (0x7FDF).
  • SPAcquire uses message ID's in the range WM_USER + 0x7BB0 (0x7FB0) through WM_USER + 0x7BBF (0x7FBF).
Please assure that these message ID's do not conflict with message ID's in your application.

Description of parameters passed as XML strings

Please see sections Virtual Buttons for more information on virtual button descriptors and background object descriptors.

Note:
SPAcquire will ignore elements that are designated to the PC screen (screen=on) and will draw elements designated to the tablet lcd (tablet=on).

Any coordinates with origin window or absscreen may result in undefined behaviour.

Comparison SPAcquire versus SPGuiAcqu

Signware offers two objects to capture signatures or references from a tablet, SPAcquire and SPGuiAcqu.
The obvious difference is that SPGuiAcqu includes handling of a native window to render the entered signature in real time.

However more limitations apply to SPAcquire due to the missing GUI:

Most applications will thus use a SPGuiAcqu object to capture a signature / reference. SPGuiAcqu can control all tablets which are supported by SignWare, and SPGuiAcqu gives visual feedback on the PC screen, if the tablet has a LCD panel or not.
A Tablet-Service application or an application that controls many Tablets, or an application that may want to run independent, not synchronized dialogs on tablet and screen may prefer to use a SPAcquire object.

Supported properties

The table below lists all supported Properties.

Name Default Range Description
"BackgroundColor" 0xFFFFFF Background color, format 0xrrggbb, rr: red, gg: green, bb: blue
"ForegroundColor" 0x000000 Foreground color, format 0xrrggbb, rr: red, gg: green, bb: blue
"PenThickness" 127 1 ... 255 Pen thickness, see @ref SPTabletSetTabletOption for details
"MirrorTablet" false SPBOOL Mirror tablet, see @ref SP_DRAW_MIRROR_TABLET for details
"NoStrokeEcho" false SPBOOL set stroke echo, see @ref SP_VIRTUAL_BUTTON_MODE for details
"ButtonClickMode" true SPBOOL set button click mode, see @ref SP_VIRTUAL_BUTTON_CLICK for details


Typedefs

typedef int(_cdecl * pSPACQUIREBUTTON_T )(pSPACQUIRE_T pSpAcquire, SPINT32 iButtonId, SPINT32 iPress)
 Callback function that is called when a hardware button on the tablet is pressed.
typedef int(_cdecl * pSPACQUIREDOCRECTLISTENER_T )(pSPACQUIRE_T pSpAcquire, SPUINT32 uDocId, SPUINT32 uRectId)
 Callback function that is called when a registered rectangle in a document is 'clicked'.
typedef int(_cdecl * pSPACQUIRELINETO_T )(pSPACQUIRE_T pSpAcquire, SPINT32 iX, SPINT32 iY, SPINT32 iPress, SPINT32 iTime)
 Callback function that is called for each vector.
typedef int(_cdecl * pSPACQUIRERECTLISTENER_T )(pSPACQUIRE_T pSpAcquire, SPUINT32 uId)
 Callback function that is called when a registered rectangle is 'clicked'.
typedef int(_cdecl * pSPACQUIRESTATUS_T )(pSPACQUIRE_T pSpAcquire, int iMajor, int iDetail)
 Callback function that is called when the tablet hardware status changes, please read tablet status change notifications for more details.
typedef int(_cdecl * pSPACQUIRETIMEOUT_T )(SPVPTR ulOptParameter)
 Callback function that is called when a timeout occurs.

Functions

SPINT32 __cdecl SPAcquireAcquire (pSPACQUIRE_T pSPAcquire)
 Start tablet acquiry mode.
SPINT32 __cdecl SPAcquireAcquireDone (pSPACQUIRE_T pSPAcquire, SPINT32 iResult)
 Terminate tablet acquiry mode.
SPINT32 __cdecl SPAcquireAcquireProcessMessages (pSPACQUIRE_T pSPAcquire)
 Process pending messages if the tablet is in acquiry mode.
SPINT32 __cdecl SPAcquireAcquireWait (pSPACQUIRE_T pSPAcquire)
 Wait until tablet acquiry mode is terminated.
SPINT32 __cdecl SPAcquireAddBackgroundDocument (pSPACQUIRE_T pSpAcquire, const SPCHAR *pszXMLDocumentDescription)
 Add documents to the tablet LCD screen.
SPINT32 __cdecl SPAcquireAddBackgroundImage (pSPACQUIRE_T pSpAcquire, const SPCHAR *pszXMLImageDescription)
 Add images to the tablet LCD screen.
SPINT32 __cdecl SPAcquireAddBackgroundObject (pSPACQUIRE_T pSpAcquire, const SPCHAR *pszXMLDescription)
 Add images, text fields or rectangles to the tablet LCD screen.
SPINT32 __cdecl SPAcquireAddBackgroundText (pSPACQUIRE_T pSpAcquire, const SPCHAR *pszXMLTextDescription)
 Add some text to the tablet LCD screen.
SPINT32 __cdecl SPAcquireClearEntries (pSPACQUIRE_T pSpAcquire, int iFlags)
 Clear all internal signature data of any acquiries of an SPAcquire object.
SPINT32 __cdecl SPAcquireConnect (pSPACQUIRE_T pSPAcquire, SPINT32 iDriver)
 Connect to a tablet specified by driver number.
SPINT32 __cdecl SPAcquireConnectByAlias (pSPACQUIRE_T pSPAcquire, const char *pszTabletAlias)
 Connect to a tablet specified by an alias name.
SPINT32 __cdecl SPAcquireConnectByEnum (pSPACQUIRE_T pSPAcquire, pSPPROPERTYMAP_T spDescriptor)
 Connect to a tablet specified by a descriptor.
SPINT32 __cdecl SPAcquireConnectEx (pSPACQUIRE_T pSPAcquire, const char *pszTabletClass, const char *pszConfig)
 Connect to a tablet specified by class name.
SPINT32 __cdecl SPAcquireCreate (pSPACQUIRE_T *ppSPAcquire, SPINT32 iFlags)
 Create an SPAcquire object.
SPINT32 __cdecl SPAcquireCreateTablet (pSPACQUIRE_T pSPAcquire, SPINT32 iDriver)
 Create the native tablet object that is required to connect to or acquire from the tablet hardware.
SPINT32 __cdecl SPAcquireCreateTabletByAlias (pSPACQUIRE_T pSPAcquire, const char *pszAlias)
 Create a new SPTablet object based on an Alias.
SPINT32 __cdecl SPAcquireCreateTabletByEnum (pSPACQUIRE_T pSPAcquire, pSPPROPERTYMAP_T spDescriptor)
 Create a new SPTablet object based on an enumeration.
SPINT32 __cdecl SPAcquireCreateTabletEx (pSPACQUIRE_T pSPAcquire, const char *pszTabletClass, const char *pszConfig)
 Create a native tablet object specified by class name.
SPINT32 __cdecl SPAcquireDisconnect (pSPACQUIRE_T pSPAcquire)
 Disconnect from a tablet.
SPINT32 __cdecl SPAcquireFree (pSPACQUIRE_T *ppSPAcquire)
 Free all resources used by an SPAcquire object.
SPINT32 SPAcquireGetBackgroundColor (pSPACQUIRE_T pSPAcquire, SPINT32 *piBackgroundColor)
 Get the background color.
SPINT32 __cdecl SPAcquireGetBackgroundImage (pSPACQUIRE_T pSPAcquire, SPINT32 iSource, pSPIMAGE_T *ppImage)
 Get the background image as it is displayed on the tablet.
SPINT32 __cdecl SPAcquireGetBackgroundText (pSPACQUIRE_T pSPAcquire, SPINT32 iSource, SPCHAR **ppszText)
 Get the background text as it is displayed on the tablet.
SPINT32 __cdecl SPAcquireGetBoolProperty (pSPACQUIRE_T pSPAcquire, const SPCHAR *pszName, SPBOOL *pbValue)
 Set a property.
SPINT32 __cdecl SPAcquireGetDrawMode (pSPACQUIRE_T pSpAcquire, SPINT32 *piDrawMode)
 Get the draw mode of an SPAcquire object.
SPINT32 SPAcquireGetForegroundColor (pSPACQUIRE_T pSPAcquire, SPINT32 *piForegroundColor)
 Get the foreground color.
SPINT32 __cdecl SPAcquireGetHwnd (pSPACQUIRE_T pSPAcquire, SPHWND *pHwnd)
 Get the window handle of the message window associated with an SPAcquire object.
SPINT32 __cdecl SPAcquireGetIntProperty (pSPACQUIRE_T pSPAcquire, const SPCHAR *pszName, SPINT32 *piValue)
 Set a property.
SPINT32 __cdecl SPAcquireGetReference (pSPACQUIRE_T pSPAcquire, pSPREFERENCE_T *ppReference)
 Get the reference after a signature or reference acquiry.
SPINT32 __cdecl SPAcquireGetSignature (pSPACQUIRE_T pSPAcquire, pSPSIGNATURE_T *ppSignature)
 Get the signature during acquiry mode.
SPINT32 __cdecl SPAcquireGetTablet (pSPACQUIRE_T pSPAcquire, pSPTABLET_T *ppTablet)
 Get the associated SPTablet object.
SPINT32 __cdecl SPAcquireGetUserLong (pSPACQUIRE_T pSPAcquire, SPVPTR *plUser)
 Get the optional user parameter of an SPAcquire object.
SPINT32 __cdecl SPAcquireRegisterDocumentRect (pSPACQUIRE_T pSpAcquire, SPUINT32 aId, const SPCHAR *pszVirtualButtonDescription)
 Register a virtual button in a document.
SPINT32 __cdecl SPAcquireRegisterRect (pSPACQUIRE_T pSPAcquire, SPUINT32 *pId, pSPRECT_T rcl, SPINT32 iFlags, const SPCHAR *pszName, pSPACQUIRERECTLISTENER_T pRectListener)
 Register a rectangle (virtual button) in acquiry mode.
SPINT32 __cdecl SPAcquireRegisterRect2 (pSPACQUIRE_T pSPAcquire, SPUINT32 *pId, const SPCHAR *pszVirtualButtonDescription, pSPACQUIRERECTLISTENER_T pRectListener)
 Register a rectangle (virtual button) in acquiry mode.
SPINT32 __cdecl SPAcquireRemoveBackgroundObjects (pSPACQUIRE_T pSpAcquire)
 Remove images, text and rectangle fields from the tablet LCD screen.
SPINT32 __cdecl SPAcquireSetActive (pSPACQUIRE_T pSpAcquire, SPBOOL bActive)
 Activate / deactivate the acquire window.
SPINT32 SPAcquireSetBackgroundColor (pSPACQUIRE_T pSPAcquire, SPINT32 iBackgroundColor)
 Set the background color.
SPINT32 __cdecl SPAcquireSetBackgroundImage (pSPACQUIRE_T pSPAcquire, const SPUCHAR *pbImage, SPINT32 iImageLen)
 Set the background image of a tablet that includes an LCD display.
SPINT32 __cdecl SPAcquireSetBackgroundObjects (pSPACQUIRE_T pSpAcquire, pSPBACKGROUNDOBJECTS_T pSpBackgroundObjects)
 Set images, text fields or rectangles to the tablet LCD screen.
SPINT32 __cdecl SPAcquireSetBoolProperty (pSPACQUIRE_T pSPAcquire, const SPCHAR *pszName, SPBOOL bValue)
 Set a property.
SPINT32 __cdecl SPAcquireSetButtonListener (pSPACQUIRE_T pSPAcquire, pSPACQUIRERECTLISTENER_T pRectListener, pSPACQUIREBUTTON_T pButtonListener)
 Set the tablet button listener.
SPINT32 __cdecl SPAcquireSetDocumentContent (pSPACQUIRE_T pSpAcquire, SPINT32 aId, const SPCHAR *pContent, SPINT32 iContent, SPINT32 aFormat)
 Set the content of a document.
SPINT32 __cdecl SPAcquireSetDocumentListener (pSPACQUIRE_T pSpAcquire, pSPACQUIREDOCRECTLISTENER_T pListener)
 Register a virtual button listener for buttons which are assigned to a specific document.
SPINT32 __cdecl SPAcquireSetDrawMode (pSPACQUIRE_T pSpAcquire, SPINT32 iDrawMode)
 Set the mode of an SPAcquire object.
SPINT32 SPAcquireSetForegroundColor (pSPACQUIRE_T pSPAcquire, SPINT32 iForegroundColor)
 Set the foreground color.
SPINT32 __cdecl SPAcquireSetIntProperty (pSPACQUIRE_T pSPAcquire, const SPCHAR *pszName, SPINT32 iValue)
 Set a property.
SPINT32 __cdecl SPAcquireSetStatusListener (pSPACQUIRE_T pSpAcquire, pSPACQUIRESTATUS_T pNotifyStatus)
 Set a status listener of an SPAcquire object.
SPINT32 __cdecl SPAcquireSetTimeout (pSPACQUIRE_T pSpAcquire, pSPACQUIRETIMEOUT_T pTimeoutListener, SPVPTR ulOptParameter, SPINT32 iTimeout)
 Set the timeout of an acquiry of an SPAcquire object.
SPINT32 __cdecl SPAcquireSetUserLong (pSPACQUIRE_T pSPAcquire, SPVPTR lUser)
 Set the optional user parameter of an SPAcquire object.
SPINT32 __cdecl SPAcquireSetVectorListener (pSPACQUIRE_T pSpAcquire, pSPACQUIRELINETO_T pNotifyVector)
 Set a vector listener of an SPAcquire object.
SPINT32 __cdecl SPAcquireUnregisterAllRects (pSPACQUIRE_T pSPAcquire)
 Unregister all rectangles (virtual buttons) in acquiry mode.
SPINT32 __cdecl SPAcquireUnregisterRect (pSPACQUIRE_T pSPAcquire, SPUINT32 uId)
 Unregister a rectangle (virtual button) in acquiry mode.


Typedef Documentation

typedef int( _cdecl * pSPACQUIREBUTTON_T)(pSPACQUIRE_T pSpAcquire, SPINT32 iButtonId, SPINT32 iPress)
 

Callback function that is called when a hardware button on the tablet is pressed.

A pointer to a function that is called to notify the application about a hardware button being pressed during acquiry mode.

Parameters:
pSpAcquire [i] pointer to the SPAcquire object for which the callback function has been registered.
iButtonId [i] a value identifying the button that was pressed. The value depends on the tablet, see Tablet Hardware button Assignment
iPress [i] the value depends on the tablet, see Tablet Hardware button Assignment
See also:
SPAcquireSetButtonListener
Returns:
0 on success, else error code, error codes are not evaluated

typedef int( _cdecl * pSPACQUIREDOCRECTLISTENER_T)(pSPACQUIRE_T pSpAcquire, SPUINT32 uDocId, SPUINT32 uRectId)
 

Callback function that is called when a registered rectangle in a document is 'clicked'.

Parameters:
pSpAcquire [i] pointer to the associated pSPACQUIRE_T object
uIdDoc [i] the identifier of the document that was clicked.
uIdRect [i] the identifier of the rectangle that was clicked.
Returns:
0 on success, else error code, error codes are not evaluated
See also:
SPAcquireRegisterRect

typedef int( _cdecl * pSPACQUIRELINETO_T)(pSPACQUIRE_T pSpAcquire, SPINT32 iX, SPINT32 iY, SPINT32 iPress, SPINT32 iTime)
 

Callback function that is called for each vector.

A pointer to a function that is called for every significant vector (sample) received from the tablet in acquiry mode.

Note:
SPAcquire handles all vectors internally, typically an application does not handle vectors.
Parameters:
pSpAcquire [i] pointer to the SPAcquire object that generated the event.
iX [i] the X coordinate (in tablet coordinates) of the vector.
iY [i] the Y coordinate (in tablet coordinates) of the vector.
iPress [i] the pressure value of the vector, normalized to 0 through 1023.
iTime [i] the time value of the vector, may be -1 if the time is not measured.
Returns:
always SP_NOERR, currently ignored.

typedef int( _cdecl * pSPACQUIRERECTLISTENER_T)(pSPACQUIRE_T pSpAcquire, SPUINT32 uId)
 

Callback function that is called when a registered rectangle is 'clicked'.

Parameters:
pSpAcquire [i] pointer to the associated pSPACQUIRE_T object
uId [i] the identifier of the rectangle that was clicked.
Returns:
0 on success, else error code, error codes are not evaluated
See also:
SPAcquireRegisterRect

typedef int( _cdecl * pSPACQUIRESTATUS_T)(pSPACQUIRE_T pSpAcquire, int iMajor, int iDetail)
 

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

A pointer to a function that is called to notify the application about tablet hardware status changes.

Parameters:
pSpAcquire [i] pointer to the associated SPAcquire object
iMajor [i] major event description
iDetail detail event description
Returns:
0 on success, else error code, error codes are not evaluated
See also:
SPAcquireSetStatusListener

typedef int( _cdecl * pSPACQUIRETIMEOUT_T)(SPVPTR ulOptParameter)
 

Callback function that is called when a timeout occurs.

A pointer to a function that is called to notify the application about a timeout condition during acquiry mode.

Parameters:
ulOptParameter [i] the user-defined parameter that was passed when the callback function was registered.
Returns:
0 on success, else error code, error codes are not evaluated
See also:
SPAcquireAcquire, SPAcquireSetTimeout


Function Documentation

SPINT32 __cdecl SPAcquireAcquire pSPACQUIRE_T  pSPAcquire  ) 
 

Start tablet acquiry mode.

Switch the tablet into acquiry mode.

SPTablet switches the tablet from pointer mode to pen entry mode during acquiry. Any registered rectangles will be notified in pen entry mode when the pen is pressed on a rectangle.

Pen entry mode is exclusive and will not send any pointer move notifications to any application.

This function enables aquiry mode and returns immediately. The actual state change of the tablet is signaled by callback functions, see SPAcquireSetStatusListener.

Further callbacks are called during aquiry mode, see SPAcquireSetTimeout, SPAcquireRegisterRect, SPAcquireRegisterRect2, SPAcquireSetButtonListener.

Events resulting in callbacks being called are stored in a queue. If SP_GAWW_EVENTS was set in iFlags of SPAcquireCreate, the system's queue will be used, that is, either the Windows message queue (for Windows) or the X11 event queue (for X11, not yet implemented). If SP_GAWW_EVENTS was not set in iFlags of SPAcquireCreate, an event queue internal to SignWare will be used.

In all cases, the queue must be read. This is done by

  • using a message loop under Windows (SP_GAWW_EVENTS was set)
  • or using an X11 event loop under Linux (SP_GAWW_EVENTS was set, not yet implemented)
  • or calling SPAcquireAcquireWait
  • or calling SPAcquireAcquireProcessMessages in a loop.
SPAcquireAcquireWait processes events and waits until SPAcquireAcquireDone is called, e. g. in response to a virtual button click notification.

Note:
Acquire mode will not be activated directly but may be delayed due to limitations caused by some drivers. This means that errors that occur while processing the state switch may not be passed to the application.
The application may set a timer to check the state of the tablet object, the state will be SP_TABLET_STATE_ACQUIRE on success. Some drivers notify the application if errors are detected while switching to acquiry mode by calling the registered status callback, see SPAcquireSetStatusListener.
Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAcquireWait, SPTabletAcquire, SPTabletAcquireDone

SPINT32 __cdecl SPAcquireAcquireDone pSPACQUIRE_T  pSPAcquire,
SPINT32  iResult
 

Terminate tablet acquiry mode.

Turn off tablet aquiry mode.

This function makes SPAcquireAcquireWait return.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
iResult [i] command; either SP_IDOK (add signature to reference) or SP_IDCANCEL (ignore signature)
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireGetReference, SPAcquireAcquireWait, SPAcquireGetSignature, SPTabletAcquire, SPTabletAcquireDone

SP_IDOK, SP_IDCANCEL

SPINT32 __cdecl SPAcquireAcquireProcessMessages pSPACQUIRE_T  pSPAcquire  ) 
 

Process pending messages if the tablet is in acquiry mode.

This function processes messages (or events) while in acquiry mode. SPAcquireAcquireProcessMessages returns as soon as all pending messages (or events) for this object have been processed whereas SPAcquireAcquireWait does not return until SPAcquireAcquireDone is called.

This function runs a message loop under Windows.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPAcquireAcquire, SPAcquireAcquireDone, SPAcquireCreate

SPINT32 __cdecl SPAcquireAcquireWait pSPACQUIRE_T  pSPAcquire  ) 
 

Wait until tablet acquiry mode is terminated.

This function processes messages (or events) and waits until SPAcquireAcquireDone is called in acquiry mode.

Applications that do not run a message loop must call either SPAcquireAcquireWait or periodically call SPAcquireAcquireProcessMessages to dispatch the messages for this object.

This function runs a message loop under Windows. Under Linux it waits for signature capture completion. Signature capture completion is signalled by SPAcquireAcquireDone.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAcquire, SPAcquireAcquireDone, SPAcquireCreate

SPINT32 __cdecl SPAcquireAddBackgroundDocument pSPACQUIRE_T  pSpAcquire,
const SPCHAR pszXMLDocumentDescription
 

Add documents to the tablet LCD screen.

The XML string is described in Image fields, element SPSWDocumentFields must be used.

The Objects will be displayed on an (optional) LCD screen when the application calls SPAcquireAcquire

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

Any coordinates with origin window or absscreen may result in undefined behaviour.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pszXMLDocumentDescription [i] string containing the XML description of the documents.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPAcquireAddBackgroundObject, SPAcquireAddBackgroundText, SPAcquireAddBackgroundImage, SPAcquireRemoveBackgroundObjects

SPINT32 __cdecl SPAcquireAddBackgroundImage pSPACQUIRE_T  pSpAcquire,
const SPCHAR pszXMLImageDescription
 

Add images to the tablet LCD screen.

The XML string is described in Image fields, element SPSWImageFields must be used.

The Objects will be displayed on an (optional) LCD screen when the application calls SPAcquireAcquire

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

Any coordinates with origin window or absscreen may result in undefined behaviour.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pszXMLImageDescription [i] string containing the XML description of the images.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAddBackgroundObject, SPAcquireAddBackgroundText, SPAcquireRemoveBackgroundObjects

SPINT32 __cdecl SPAcquireAddBackgroundObject pSPACQUIRE_T  pSpAcquire,
const SPCHAR pszXMLDescription
 

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

The XML string is described in Mixed image, document and text fields. Element SPSWObjects must be the root element, SPSWImageFileds, SPSWImage, SPSWRect, SPSWRectFields, SPSWTextFields and SPSWText elements will be displayed.

Note:
SPSWRect and SPSWRectFields will be displayed but cannot be clicked, use SPAcquireRegisterRect or SPAcquireRegisterRect2 to define virtual buttons.
The Objects will be displayed on an (optional) LCD screen when the application calls SPAcquireAcquire

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

Any coordinates with origin window or absscreen may result in undefined behaviour.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pszXMLDescription [i] string containing the XML description of the images and texts.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAddBackgroundText, SPAcquireAddBackgroundImage, SPAcquireRemoveBackgroundObjects

SPINT32 __cdecl SPAcquireAddBackgroundText pSPACQUIRE_T  pSpAcquire,
const SPCHAR pszXMLTextDescription
 

Add some text to the tablet LCD screen.

The XML string is described in Text fields, element SPSWTextFields must be used.

The Objects will be displayed on an (optional) LCD screen when the application calls SPAcquireAcquire

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

Any coordinates with origin window or absscreen may result in undefined behaviour.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pszXMLTextDescription [i] a description of the text, position and font to be included.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAddBackgroundObject, SPAcquireAddBackgroundImage, SPAcquireRemoveBackgroundObjects

SPINT32 __cdecl SPAcquireClearEntries pSPACQUIRE_T  pSpAcquire,
int  iFlags
 

Clear all internal signature data of any acquiries of an SPAcquire object.

This function will clear the SPReference object that is embedded in this object; this means that all signatures that were entered so far will be deleted. 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 criteria.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
iFlags [i] reserved parameter, should be 0.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireConnect pSPACQUIRE_T  pSPAcquire,
SPINT32  iDriver
 

Connect to a tablet specified by driver number.

The creation of a tablet object will fail if the connected tablet is a full screen device such as TabletPC or Wacom Cintiqu. Full screen devices are not supported with SPAcquire objects. Please read Comparison SPAcquire versus SPGuiAcqu for more details.

Please read Tablet creation options for a list of supported drivers

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
iDriver [i] the driver number, pass SP_UNKNOWN_DRV to use any driver.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireCreate, SPAcquireFree

SP_UNKNOWN_DRV, SP_WINTAB_DRV, SP_PADCOM_DRV, SP_NATIVE_DRV, SP_TCP_DRV

SPAcquireConnectEx, SPAcquireCreateTablet, SPTabletConnect, SPTabletDisconnect

SPINT32 __cdecl SPAcquireConnectByAlias pSPACQUIRE_T  pSPAcquire,
const char *  pszTabletAlias
 

Connect to a tablet specified by an alias name.

Please read Tablet creation options for resolving the Alias

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pszTabletAlias [i] the alias name of the tablet
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreateByAlias, SPAcquireConnect, SPAcquireConnectEx, SPAcquireCreateTabletByAlias

SPINT32 __cdecl SPAcquireConnectByEnum pSPACQUIRE_T  pSPAcquire,
pSPPROPERTYMAP_T  spDescriptor
 

Connect to a tablet specified by a descriptor.

Please read Tablet creation options for tablet enumeration

Note:
This function connects with the default tablet if spDescriptor is NULL
Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
spDescriptor [i] the descriptor of the enumerated tablet
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreateByEnum, SPAcquireConnect, SPAcquireConnectEx, SPAcquireCreateTabletByEnum

SPINT32 __cdecl SPAcquireConnectEx pSPACQUIRE_T  pSPAcquire,
const char *  pszTabletClass,
const char *  pszConfig
 

Connect to a tablet specified by class name.

The creation of a tablet object will fail if the connected tablet is a full screen device such as TabletPC or Wacom Cintiqu. Full screen devices are not supported with SPAcquire objects. Please read Comparison SPAcquire versus SPGuiAcqu for more details.

Please read Tablet creation options for a list of supported options

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pszTabletClass [i] the class name of Kofax tablet access module.
pszConfig [i] pass optional configuration data. Configuration data depends on the detected hardware driver (see Installation and configuration of various pads):
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireConnect, SPAcquireCreate, SPAcquireFree

SP_UNKNOWN_DRV, SP_WINTAB_DRV, SP_PADCOM_DRV, SP_NATIVE_DRV, SP_TCP_DRV

SPAcquireCreateTabletEx, SPTabletConnect, SPTabletDisconnect, SPTabletCreateEx

SPINT32 __cdecl SPAcquireCreate pSPACQUIRE_T ppSPAcquire,
SPINT32  iFlags
 

Create an SPAcquire object.

Under Windows an invisible message window will be created. You can query the handle of that window by calling SPAcquireGetHwnd. If SP_GAWW_EVENTS is set in iFlags, SPAcquire sends messages with ID's starting at WM_USER + 1000 to that message window.

The creation of a tablet object will fail if the connected tablet is a full screen device such as TabletPC or Wacom Cintiqu.

Under Windows most tablets, especially tablet using a Wintab driver, send vector notifications through as message events, which reqire message loop. Therefore, SP_GAWW_EVENTS must be set under Windows.

Please see section SPAcquire for more information about message event IDs.

Parameters:
ppSPAcquire [o] pointer to a variable that will be filled with a pointer to a new SPAcquire object. The caller is responsible for deallocating the new object by calling SPAcquireFree.
iFlags [i], a combination of:
  • SP_GAWW_EVENTS Use Windows messages (or X11 events).
    If this flag is set,then a message loop (or event loop) is required during acquiry (see SPAcquireAcquireWait and SPAcquireAcquireProcessMessages).
    If this flag is not set, an internal event queue will be used (see SPAcquireAcquireWait and SPAcquireAcquireProcessMessages).
    This flag must be set under Windows.
    Currently, this flag must not be set under Linux as X11 is not yet supported.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireFree, SPAcquireGetHwnd, SPAcquireAcquireProcessMessages, SPAcquireAcquireWait
Todo:
Implement SP_GAWW_EVENTS for Linux

SPINT32 __cdecl SPAcquireCreateTablet pSPACQUIRE_T  pSPAcquire,
SPINT32  iDriver
 

Create the native tablet object that is required to connect to or acquire from the tablet hardware.

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 use for this function would be to select an image depending on the tablet device. Create the tablet driver object, get the device ID, pass the device-specific image, and then connect to the tablet.

The creation of a tablet object will fail if the connected tablet is a full screen device such as TabletPC or Wacom Cintiqu. Full screen devices are not supported with SPAcquire objects. Please read Comparison SPAcquire versus SPGuiAcqu for more details.

Please read Tablet creation options for a list of supported drivers

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
iDriver [i] the driver number, pass SP_UNKNOWN_DRV to use any driver.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireGetTablet

SPINT32 __cdecl SPAcquireCreateTabletByAlias pSPACQUIRE_T  pSPAcquire,
const char *  pszAlias
 

Create a new SPTablet object based on an Alias.

Please read Tablet creation options for resolving the Alias

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pszAlias [i] the alias name of the tablet
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreateByAlias, SPAcquireCreateTablet, SPAcquireCreateTabletEx, SPAcquireConnectByAlias

SPINT32 __cdecl SPAcquireCreateTabletByEnum pSPACQUIRE_T  pSPAcquire,
pSPPROPERTYMAP_T  spDescriptor
 

Create a new SPTablet object based on an enumeration.

Please read Tablet creation options for tablet enumeration.

Note:
This function creates a default tablet if spDescriptor is NULL
Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
spDescriptor [i] the descriptor of the tablet as returned from a pSPTABLETENUM object
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreateByEnum, SPAcquireCreateTablet, SPAcquireCreateTabletEx, SPAcquireConnectByEnum

SPINT32 __cdecl SPAcquireCreateTabletEx pSPACQUIRE_T  pSPAcquire,
const char *  pszTabletClass,
const char *  pszConfig
 

Create a native tablet object specified by class name.

This function will not reinstantiate the tablet driver if a driver already exists.

This is a convenience function provided for applications that might need to access the tablet driver before it is connected. In most other cases the tablet driver object will be created when it is internally required, the application does not have to call this function.

A typical application of this function would be to select an image depending on the tablet device. Create the tablet driver object, get the device ID, pass the device specific image, and then connect to the tablet.

The creation of a tablet object will fail if the connected tablet is a full screen device such as TabletPC or Wacom Cintiqu. Full screen devices are not supported with SPAcquire objects. Please read Comparison SPAcquire versus SPGuiAcqu for more details.

Please read Tablet creation options for a list of supported options

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pszTabletClass [i] class name of the Kofax tablet access module.
pszConfig [i] pass optional configuration data. Configuration data depends on the detected hardware driver (see Installation and configuration of various pads):
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireConnectEx, SPAcquireDisconnect, SPAcquireAcquire, SPAcquireAcquireDone, SPTabletCreateEx

SPINT32 __cdecl SPAcquireDisconnect pSPACQUIRE_T  pSPAcquire  ) 
 

Disconnect from a tablet.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPReferenceCreateFromGuiAcqu, SPTabletConnect, SPTabletDisconnect

SPINT32 __cdecl SPAcquireFree pSPACQUIRE_T ppSPAcquire  ) 
 

Free all resources used by an SPAcquire object.

The SPAcquire object must have been created by SPAcquireCreate

It is an error to free an SPAcquire object while processing a windows message for the window handle assigned to that SPAcquire object.

Parameters:
ppSPAcquire [io] pointer to a variable containing a pointer to an SPAcquire object. The variable will be set to NULL if this function succeeds.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireCreate

SPINT32 SPAcquireGetBackgroundColor pSPACQUIRE_T  pSPAcquire,
SPINT32 piBackgroundColor
 

Get the background color.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
piBackgroundColor [i] pointer to a variable that will be filled with the background color (see SPAcquireSetBackgroundColor for details).
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireGetForegroundColor, SPAcquireSetBackgroundColor

SPINT32 __cdecl SPAcquireGetBackgroundImage pSPACQUIRE_T  pSPAcquire,
SPINT32  iSource,
pSPIMAGE_T ppImage
 

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

The image will not contain any partial or fully entered signature strokes.

This function returns SP_NOERR and *ppImage = NULL if no background image was passed.

This function is provided for audit purposes. The resulting image contains a gray-scale image with up to 256 gray levels or a color image.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
iSource [i] select the source of the image:
  • 2 Tablet LCD
ppImage [o] pointer to a variable that will be filled with a pointer to an SPImage object. The caller is responsible for deallocating the new object by calling SPImageFree.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPImageFree

SPINT32 __cdecl SPAcquireGetBackgroundText pSPACQUIRE_T  pSPAcquire,
SPINT32  iSource,
SPCHAR **  ppszText
 

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

This function returns SP_NOERR and *ppText = NULL if no background text was passed.

This function is provided for audit purposes. The resulting text contains all text elements that is diplayed on the tablet.

Note:
This function does not analyse images for text contexts.
Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
iSource [i] select the source of the image:
  • 2 Tablet LCD
ppszText [o] pointer to a char pointer that will be filled with the displayed text. The caller is responsible for deallocating the new object by calling SPFreeString.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPFreeString

SPINT32 __cdecl SPAcquireGetBoolProperty pSPACQUIRE_T  pSPAcquire,
const SPCHAR pszName,
SPBOOL pbValue
 

Set a property.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pszName [i] Name of the property, see SPAcquire Properties
pbValue [i] pointer to avariable that will be filled with the value of the property
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireGetDrawMode pSPACQUIRE_T  pSpAcquire,
SPINT32 piDrawMode
 

Get the draw mode of an SPAcquire object.

Note:
Use SPAcquireSetBoolProperty instead
Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
piDrawMode [o] pointer to a variable that will be filled with the draw mode. See SPAcquireSetDrawMode for details.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireGetBoolProperty

SPINT32 SPAcquireGetForegroundColor pSPACQUIRE_T  pSPAcquire,
SPINT32 piForegroundColor
 

Get the foreground color.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
piForegroundColor [i] pointer to a variable that will be filled with the foreground color (see SPAcquireSetForegroundColor for details).
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireGetBackgroundColor, SPAcquireSetForegroundColor

SPINT32 __cdecl SPAcquireGetHwnd pSPACQUIRE_T  pSPAcquire,
SPHWND pHwnd
 

Get the window handle of the message window associated with an SPAcquire object.

This function returns the handle of the invisible message-only window created by SPAcquireCreate.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pHwnd [o] pointer to a variable that will be filled with the window handle of the window associated with the SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireCreate
Todo:
Implement for Linux

SPINT32 __cdecl SPAcquireGetIntProperty pSPACQUIRE_T  pSPAcquire,
const SPCHAR pszName,
SPINT32 piValue
 

Set a property.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pszName [i] Name of the property, see SPAcquire Properties
piValue [i] pointer to avariable that will be filled with the value of the property
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireGetReference pSPACQUIRE_T  pSPAcquire,
pSPREFERENCE_T ppReference
 

Get the reference after a signature or reference acquiry.

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.

This is a convenience function which behaves exactly like SPReferenceCreateFromAcquire.

The captured signature will be added to the the reference object during processing of SPAcquireDone.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
ppReference [o] pointer to a variable that will be filled with a pointer to an SPReference object containing the reference. The caller is responsible for destroying the new object with SPReferenceFree.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAcquireDone, SPAcquireGetSignature, SPReferenceCreateFromGuiAcqu, SPReferenceFree

SPINT32 __cdecl SPAcquireGetSignature pSPACQUIRE_T  pSPAcquire,
pSPSIGNATURE_T ppSignature
 

Get the signature during acquiry mode.

The returned SPSignature object may not contain all vectors captured so far. This function is provided to check for empty signatures before accepting the signature (see SPAcquireAcquireDone). Modifying the SPSignature object won't have an effect on the signature being captured.

This is a convenience function which behaves exactly like SPSignatureCreateFromAcquire.

No signature object will be returned unless the SPAcquire object is in acquiry mode.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
ppSignature [o] pointer to a variable that will be filled with a pointer to an SPSignature object containing the current signature. The caller is responsible for destroying the new object with SPSignatureFree.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAcquire, SPAcquireGetReference, SPSignatureCreateFromGuiAcqu, SPSignatureFree

SPINT32 __cdecl SPAcquireGetTablet pSPACQUIRE_T  pSPAcquire,
pSPTABLET_T ppTablet
 

Get the associated SPTablet object.

SP_PARAMERR will be returned if the tablet has not yet been created. You should neither register any listeners in the returned tablet nor set any properties. The object is available to query tablet proerties such as tablet type, size etc. only.

Note:
The returned tablet object is not a copy. Do not free this object.
Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
ppTablet [o] pointer to a variable that will receive a pointer to the SPTablet object of the SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireCreateTablet
Example:
 int getTabletSize(pSPACQUIRE_T pGuiAcqu, SIZE *pSize)
 {
     pSPTABLET_T pTablet = 0;
     int rc = SPAcquireGetTablet(pGuiAcqu, &pTablet);
     if(rc != SP_NOERR) return rc;
     int iWidth, iHeight;
     rc = SPTabletGetTabletSize(pTablet, &iWidth, &iHeight);
     if(rc != SP_NOERR) return rc;
     pSize->cx = iWidth;
     pSize->cy = iHeight;
     pTablet = 0;
     return SP_NOERR;
 }

SPINT32 __cdecl SPAcquireGetUserLong pSPACQUIRE_T  pSPAcquire,
SPVPTR plUser
 

Get the optional user parameter of an SPAcquire object.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
plUser [o] pointer to a variable that will be filled with the user parameter of the SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireSetUserLong

SPINT32 __cdecl SPAcquireRegisterDocumentRect pSPACQUIRE_T  pSpAcquire,
SPUINT32  aId,
const SPCHAR pszVirtualButtonDescription
 

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:
pSpAcquire [i] pointer to an SPAcquire object.
aId [i] the unique identifyer of the document
pszVirtualButtonDescription [i] description of the rectangle position, size, text, font etc. Please see element SPSWVirtualButton in Virtual Buttons for details
Returns:
SP_NOERR on success, else error code:
See also:
SPAcquireSetDocumentContent, SPAcquireSetDocumentListener

sec_DocumentDescriptionDTD

SPINT32 __cdecl SPAcquireRegisterRect pSPACQUIRE_T  pSPAcquire,
SPUINT32 pId,
pSPRECT_T  rcl,
SPINT32  iFlags,
const SPCHAR pszName,
pSPACQUIRERECTLISTENER_T  pRectListener
 

Register a rectangle (virtual button) in acquiry mode.

This function is a simplified version of SPAcquireRegisterRect2, the call is actually dispatched to SPAcquireRegisterRect2 with a properly formatted XML description string.

Any registered rectangles will be notified in acquiry mode when the pen is pressed on a rectangle.

You must assure that the rectangles will be updated whenever the coordinates change, such as resizing or moving a component unless you specify the flag SP_TABLET_COORDINATE.

Rectangles can only be drawn to an optional LCD screen on the tablet if they are registered before the tablet enters acquiry mode.

The SPAcquire object should not be deleted within the registered listener. You may, e.g., post a message and delete the object in the windows procedure handling that message.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pId [io] pointer to a variable containing the identifier for the rectangle to be registered or 0 to let this function create the ID. The variable will be filled with the created ID, see SPAcquireRegisterRect2.
rcl [i] pointer to the rectangle to be registered, all coordinates are absolute screen coordinates, ie, point 0, 0 is the upper left corner of the PC screen.
iFlags [i] drawing flags, a bitwise combination of the following:
  • SP_TABLET_COORDINATE the rectangle is passed in ppt of the tablet size, or the entry window size when using a full-screen tablet, will always be set
  • SP_DRAW_ON_EXT_LCD the rectangle will be drawn on an external LCD
  • SP_ONLY_FOR_EXT_LCD ignore this rectangle if the tablet does not have an LCD
pszName [i] string that should be displayed if the draw flags cause the rectangle to be drawn. NULL and "" are legal values, the string length is limited to 160 characters. The string is expected in UTF-8 encoding, use SPUnicodeToUtf8 to convert from Unicode.
pRectListener [i] callback function that will be called when the rectangle is 'clicked'. The global virtual button listener (see SPGuiAcquSetButtonListener) will be called if this parameter is NULL.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAcquire, SPAcquireSetButtonListener, SPTabletHasProximity, SPTabletSetBoolProperty SP_VIRTUAL_BUTTON_CLICK

SPINT32 __cdecl SPAcquireRegisterRect2 pSPACQUIRE_T  pSPAcquire,
SPUINT32 pId,
const SPCHAR pszVirtualButtonDescription,
pSPACQUIRERECTLISTENER_T  pRectListener
 

Register a rectangle (virtual button) in acquiry mode.

Any registered rectangles will be notified in acquiry mode when the pen is pressed on a rectangle.

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.

Note:
Any coordinates with origin window or absscreen may result in undefined behaviour.
Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pId [io] pointer to a variable theat will be filled with the identifier of the virtual button. The descriptor of the virtual button must include an id. The button will be updated if the id in the descriptor alreaady exists, or created if it does not exist.
The Id is used to identify the virtuel button in virtual button callbacks.
pszVirtualButtonDescription [i] description of the rectangle position, size, text, font etc. Please see element SPSWVirtualButton in Virtual Buttons for details.
pRectListener [i] callback function that will be called when the rectangle is 'clicked'. The global virtual button listener (see SPGuiAcquSetButtonListener) will be called if this parameter is NULL.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAcquire, SPTabletHasProximity, SPTabletSetBoolProperty, SP_VIRTUAL_BUTTON_CLICK SPGuiAcqu

SPINT32 __cdecl SPAcquireRemoveBackgroundObjects pSPACQUIRE_T  pSpAcquire  ) 
 

Remove images, text and rectangle fields from the tablet LCD screen.

The Background Objects will be updated on an (optional) LCD screen when the application calls SPAcquireAcquire

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAddBackgroundText, SPAcquireAddBackgroundImage, SPAcquireAddBackgroundObject

SPINT32 __cdecl SPAcquireSetActive pSPACQUIRE_T  pSpAcquire,
SPBOOL  bActive
 

Activate / deactivate the acquire window.

The acquire window is normally active until SPAcquireAcquireDone is called. There may be situations where the application might want to deactivate acquire mode, e.g. in multi page dialogs.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
bActive [i] non-zero to activate acquiry mode, zero to deactive acquiry mode.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 SPAcquireSetBackgroundColor pSPACQUIRE_T  pSPAcquire,
SPINT32  iBackgroundColor
 

Set the background color.

The background color is used to draw a pen stroke that has zero pressure. It will also be used to erase the background if SP_ERASE_BACKGROUND is set.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
iBackgroundColor [i] the new background color as integer 0xrrggbb with rr = red, gg = green, bb = blue, each color being in the range 0 through 0xff.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireGetBackgroundColor, SPAcquireSetForegroundColor, SPTabletSetBackgroundColor

SPINT32 __cdecl SPAcquireSetBackgroundImage pSPACQUIRE_T  pSPAcquire,
const SPUCHAR pbImage,
SPINT32  iImageLen
 

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

The tablet image is composed of all background images, text and rectangles (virtual buttons). The tablet image will be calculated before the tablet enters acquiry mode, that is within the method SPAcquireAcquire.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pbImage [i] pointer to the image data. Most standard image formats such as BMP, TIF, JPG, GIF, and CCITT4 are supported
iImageLen [i] size of the image data (in bytes) pointed to by pbImage.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireSetBackgroundObjects pSPACQUIRE_T  pSpAcquire,
pSPBACKGROUNDOBJECTS_T  pSpBackgroundObjects
 

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

Use SPBackgroundObjectsCreateFromFile or SPBackgroundObjectsCreateFromXML 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 SPAcquireCreateTablet, SPAcquireConnect and must not be in aquiry state.
All existing background objects will be deleted and the new objects will be added, see SPAcquireRemoveBackgroundObjects

Any coordinates with origin window or absscreen may result in undefined behaviour.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pSpBackgroundObjects [i] pointer to an SPBackgroundObjects object.
Returns:
SP_NOERR on success, else error code:
  • SP_PARAMERR invalid parameter
  • SP_APPLERR cannot change background in acquiry mode or no tablet instantiated
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireSetBoolProperty pSPACQUIRE_T  pSPAcquire,
const SPCHAR pszName,
SPBOOL  bValue
 

Set a property.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pszName [i] Name of the property, see SPAcquire Properties
bValue [i] the value of the property
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireSetButtonListener pSPACQUIRE_T  pSPAcquire,
pSPACQUIRERECTLISTENER_T  pRectListener,
pSPACQUIREBUTTON_T  pButtonListener
 

Set the tablet button listener.

This listener will be called when a real button on the tablet was pressed, but not for virtual buttons.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pRectListener [i] Callback function that will be called when a virtual button is pressed.If a rectangle is pressed then the registered listener for the rectangle will be called, see SPGuiAcquRegisterRect, SPGuiAcquRegisterRect2 or this listener will be called if no listener was registered with the virtual button (the listener is NULL).
pButtonListener [i] Callback function that will be called when a tablet button is pressed.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireSetDocumentContent pSPACQUIRE_T  pSpAcquire,
SPINT32  aId,
const SPCHAR pContent,
SPINT32  iContent,
SPINT32  aFormat
 

Set the content of a document.

Use SPAcquireAddBackgroundDocument or SPAcquireAddBackgroundObject or SPAcquireSetBackgroundObjects to create and layout of a document view.
Once the document is created you may:

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
aId [i] the unique identifyer of the document
pContent [i] pointer to the document contents, may be the document data, or a file name
iContent [i] the size of the document content in bytes
aFormat [i] format specifyer of the document content:
  • 1: local file, pContent is the UTF-8 encoded FQN of the document
  • 2: document data is passed as an image, pContent is the document data in memory
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPAcquireAddBackgroundObject, SPAcquireAddBackgroundDocument, SPAcquireRemoveBackgroundObjects

sec_DocumentDescriptionDTD

SPINT32 __cdecl SPAcquireSetDocumentListener pSPACQUIRE_T  pSpAcquire,
pSPACQUIREDOCRECTLISTENER_T  pListener
 

Register a virtual button listener for buttons which are assigned to a specific document.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pListener [i] pointer to the listener method, may be NULL to deregister a listener
Returns:
SP_NOERR on success, else error code:
See also:
SPAcquireSetDocumentContent, SPAcquireRegisterDocumentRect

sec_DocumentDescriptionDTD

SPINT32 __cdecl SPAcquireSetDrawMode pSPACQUIRE_T  pSpAcquire,
SPINT32  iDrawMode
 

Set the mode of an SPAcquire object.

Note:
Do not set the draw mode once acquiry mode is turned on.
Use SPAcquireSetBoolProperty instead
Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
iDrawMode [i] drawing mode, a combination of:
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SP_VIRTUAL_BUTTON_MODE, SP_DRAW_MIRROR_TABLET, SP_VIRTUAL_BUTTON_CLICK

SPAcquireSetBoolProperty, SPAcquireGetTablet, SPAcquireGetHwnd, SPTabletAcquire, SPTabletAcquireDone

SPINT32 SPAcquireSetForegroundColor pSPACQUIRE_T  pSPAcquire,
SPINT32  iForegroundColor
 

Set the foreground color.

The foreground color is used to draw a pen stroke that has maximum pressure.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
iForegroundColor [i] the new foreground color as integer 0xrrggbb with rr = red, gg = green, bb = blue, each color being in the range 0 through 0xff.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireGetForegroundColor, SPAcquireSetBackgroundColor, SPTabletSetForegroundColor

SPINT32 __cdecl SPAcquireSetIntProperty pSPACQUIRE_T  pSPAcquire,
const SPCHAR pszName,
SPINT32  iValue
 

Set a property.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
pszName [i] Name of the property, see SPAcquire Properties
iValue [i] the value of the property
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireSetStatusListener pSPACQUIRE_T  pSpAcquire,
pSPACQUIRESTATUS_T  pNotifyStatus
 

Set a status listener of an SPAcquire object.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pNotifyStatus [i] function that is to be called when a hardware status of the tablet changes, or when the tablet driver reports errors.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletSetStatusListener

SPINT32 __cdecl SPAcquireSetTimeout pSPACQUIRE_T  pSpAcquire,
pSPACQUIRETIMEOUT_T  pTimeoutListener,
SPVPTR  ulOptParameter,
SPINT32  iTimeout
 

Set the timeout of an acquiry of an SPAcquire object.

The timeout handler will be called if there was no pen stroke for the duration of iTimeout in milliseconds.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pTimeoutListener [i] function that will be called when the timeout expires.
ulOptParameter [i] user-defined parameter that will be passed to pTimeoutListener (not used by SignWare).
iTimeout [i] timeout (in milliseconds) or 0 to disable timeout checking.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireSetUserLong pSPACQUIRE_T  pSPAcquire,
SPVPTR  lUser
 

Set the optional user parameter of an SPAcquire object.

The optional user parameter is not used inside SignWare, you may add one additional SPVPTR parameter for application purposes.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
lUser [i] application-specific parameter.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireGetUserLong

SPINT32 __cdecl SPAcquireSetVectorListener pSPACQUIRE_T  pSpAcquire,
pSPACQUIRELINETO_T  pNotifyVector
 

Set a vector listener of an SPAcquire object.

Parameters:
pSpAcquire [i] pointer to an SPAcquire object.
pNotifyVector [i] function that is to be called when a vector was captured.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPAcquireUnregisterAllRects pSPACQUIRE_T  pSPAcquire  ) 
 

Unregister all rectangles (virtual buttons) in acquiry mode.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAcquire, SPAcquireRegisterRect, SPAcquireRegisterRect2, SPAcquireUnregisterRect

SPINT32 __cdecl SPAcquireUnregisterRect pSPACQUIRE_T  pSPAcquire,
SPUINT32  uId
 

Unregister a rectangle (virtual button) in acquiry mode.

Parameters:
pSPAcquire [i] pointer to an SPAcquire object.
uId [i] identifier of the rectangle to be unregistered.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPAcquireAcquire, SPAcquireRegisterRect, SPAcquireRegisterRect2, SPAcquireUnregisterAllRects