visit Kofax web site

SPTablet.h File Reference


Detailed Description

SignWare Dynamic Development toolkit, tablet access.

Author:
uko
This header includes all definitions for low-level tablet access using the SPTablet object. SPTablet abstracts the tablet hardware, it does not interprete any tablet vectors e. g. to capture a signature. Please see SPGuiAcqu.h for tablet access with graphical representation or SPAcquire.h for tablet access without graphical representation.

The object SPTabletEnum enumerates all tablets for either a specific driver or all drivers. You may use an enumeration object to create the specific tablet,

See also:
SPTabletCreateByEnum.
Acquiring a signature typically involves several steps: Some low-level drivers use windows messages to communicate with the application. Wintab uses message ID's in the range WM_USER + 0x7BF0 (0x7FF0) through WM_USER + 0xFBFF (0x7FFF), the Kofax drivers use message ID's in the range WM_USER + 0xFBD0 (0x7FD0) through WM_USER + 0xFBDF (0x7FDF).

Please assure that these message ID's do not conflict with message ID's in your application.

SPTablet normalizes the data passed from different tablets, applications will not have to care about the attached device. The normalisation covers:

Tablet vectors are passed to registered listeners with normalized pressure and coordinates.

Tablet Status Change Notifications

Some tablet drivers cannot execute status changes synchronously but have to dispatch the status request and perform the requested operation later. This applies e. g. to TabletPCs, which cannot directy enter acquiry state but post a message to the assigned native window handle and change the state when processing the message.
Errors and warnings can thus not be returned to the application directly, the application will be informed via status change notification / callback.

The callback passes two parameters to describe the event: a major number and a detail number.
These notifications are passed:
Major reason for the event.


Detail information for the event The value depends on the major event type:


Defines

#define SP_ACQUIRE_RETURN_IMMEDIATELY   2
 Flag for SPTabletSetFlags: return immediately from SPTabletAcquire.
#define SP_ACQUIRE_TRANSFER_0_VECTORS   8
 Flag for SPTabletSetFlags: send all vectors having a pressure value of 0.
#define SP_DONT_ECHO_STROKES   0x10
 Flag for SPTabletSetFlags: don't echo strokes on the tablet LCD.
#define SP_SYNCHRONOUS_START_ACQUIRE   0x40
 Flag for SPTabletSetFlags: execute SPTabletStartAcquire synchronously.
#define SP_TABLET_STATE_ACQUIRE   2
 Tablet state: acquiring.
#define SP_TABLET_STATE_CONNECT   1
 Tablet state: connected.
#define SP_TABLET_STATE_IDLE   0
 Tablet state: idle.

Typedefs

typedef int(_cdecl * pSPENDNOTIFY_T )(pSPTABLET_T pTablet)
 Callback function that is called after sending one or more vectors.
typedef int(_cdecl * pSPLINETO2_T )(pSPTABLET_T pTablet, SPINT32 iX, SPINT32 iY, SPINT32 iPress, SPINT32 iTime)
 Callback function that is called for each vector.
typedef int(_cdecl * pSPLINETO_T )(pSPTABLET_T pTablet, SPINT32 iX, SPINT32 iY, SPINT32 iPress)
 Callback function that is called for each vector.
typedef int(_cdecl * pSPSTARTNOTIFY_T )(pSPTABLET_T pTablet)
 Callback function that is called when vectors are available.
typedef int(_cdecl * pSPTABLETBUTTON_T )(pSPTABLET_T pTablet, SPINT32 iButtonId, SPINT32 iPress)
 Callback function that is called when a hardware button is pressed on the tablet.
typedef int(_cdecl * pSPTABLETSTATUS_T )(pSPTABLET_T pTablet, SPINT32 iMajor, SPINT32 iMinor)
 Callback function that is called when the status of a tablet changes, please read tablet status change notifications for more details.

Functions

SPINT32 __cdecl SPTabletAcquire (pSPTABLET_T pTablet, SPHWND hwndParent)
 Put an SPTablet object into acquiry mode.
SPINT32 __cdecl SPTabletAcquireDone (pSPTABLET_T pTablet)
 Terminate acquiry mode of an SPTablet object.
SPINT32 __cdecl SPTabletClearBackgroundImage (pSPTABLET_T pTablet, SPINT32 iImFlags)
 Clear the background image of an SPTablet object.
SPINT32 __cdecl SPTabletConnect (pSPTABLET_T pTablet)
 Connect an SPTablet object to a tablet.
SPINT32 __cdecl SPTabletCreate (pSPTABLET_T *ppTablet, SPINT32 iDriverId)
 Create a new SPTablet object.
SPINT32 __cdecl SPTabletCreateByAlias (pSPTABLET_T *ppTablet, const char *pszAlias)
 Create a new SPTablet object based on an Alias.
SPINT32 __cdecl SPTabletCreateByEnum (pSPTABLET_T *ppTablet, pSPPROPERTYMAP_T spDescriptor)
 Create a new SPTablet object.
SPINT32 __cdecl SPTabletCreateEx (pSPTABLET_T *ppTablet, const char *pszTabletClass, const char *pszConfig)
 Create a new SPTablet object.
SPINT32 __cdecl SPTabletDisconnect (pSPTABLET_T pTablet)
 Disconnect a tablet from an SPTablet object.
SPINT32 __cdecl SPTabletFree (pSPTABLET_T *ppTablet)
 Deallocate an SPTablet object.
SPINT32 __cdecl SPTabletGetDevice (pSPTABLET_T pTablet, SPINT32 *piDevice)
 Get the device ID of an SPTablet object.
SPINT32 __cdecl SPTabletGetDeviceStr (SPINT32 iDeviceId, SPCHAR *pszName, SPINT32 iNameLen)
 Get the name of the tablet device.
SPINT32 __cdecl SPTabletGetDisplayType (pSPTABLET_T pTablet, SPINT32 *piDisplayType)
 Query the display type of the tablet used by this SPTablet object.
SPINT32 __cdecl SPTabletGetDriver (pSPTABLET_T pTablet, SPINT32 *piDriver)
 Get the driver ID of an SPTablet object.
SPINT32 __cdecl SPTabletGetDriverStr (SPINT32 iDriverId, SPCHAR *pszName, SPINT32 iNameLen)
 Get the name of a tablet driver.
SPINT32 __cdecl SPTabletGetFlags (pSPTABLET_T pTablet, SPINT32 *piFlags)
 Get the tablet flags for acquiry mode of an SPTablet object.
SPINT32 __cdecl SPTabletGetHardwareName (pSPTABLET_T pTablet, SPCHAR *pszHardwareName, SPINT32 iHardwareNameLen)
 Get the hardware file name of an SPTablet object.
SPINT32 __cdecl SPTabletGetLCD (pSPTABLET_T pTablet, SPINT32 *piLCD)
 Check if the tablet used by an SPTablet object is a full-screen tablet.
SPINT32 __cdecl SPTabletGetLCDBitsPerPixel (pSPTABLET_T pTablet, SPINT32 *piBitsPerPixel)
 Get the bit depth of the LCD of the tablet.
SPINT32 __cdecl SPTabletGetLCDOffset (pSPTABLET_T pTablet, SPINT32 *piOffsetX, SPINT32 *piOffsetY)
 Get the offset of the LCD of the tablet used by an SPTablet object.
SPINT32 __cdecl SPTabletGetLCDSize (pSPTABLET_T pTablet, SPINT32 *piWidth, SPINT32 *piHeight)
 Get the size of the LCD of the tablet used by an SPTablet object.
SPINT32 __cdecl SPTabletGetMaxPressure (pSPTABLET_T pTablet, SPINT32 *piMaxPressure)
 Get the pressure range of an SPTablet object.
SPINT32 __cdecl SPTabletGetPadSerial (pSPTABLET_T pTablet, SPUCHAR *pbPadSerial, SPINT32 *piPadSerialLength)
 Get the tablet serial ID of an SPTablet object.
SPINT32 __cdecl SPTabletGetPhysicalSize (pSPTABLET_T pTablet, SPINT32 *piWidth, SPINT32 *piHeight)
 Get the tablet size of an SPTablet object.
SPINT32 __cdecl SPTabletGetResolution (pSPTABLET_T pTablet, SPINT32 *piResolution)
 Get the logical resolution of an SPTablet object.
SPINT32 __cdecl SPTabletGetResolution2 (pSPTABLET_T pTablet, SPINT32 iDetail, SPINT32 *piResolution)
 Get the resolution of an SPTablet object.
SPINT32 __cdecl SPTabletGetSampleRate (pSPTABLET_T pTablet, SPINT32 *piSampleRate)
 Get the logical sample rate of an SPTablet object.
SPINT32 __cdecl SPTabletGetSampleRate2 (pSPTABLET_T pTablet, SPINT32 iDetail, SPINT32 *piSampleRate)
 Get the sample rate of an SPTablet object.
SPINT32 __cdecl SPTabletGetState (pSPTABLET_T pTablet, SPINT32 *piState)
 Get the state of an SPTablet object.
SPINT32 __cdecl SPTabletGetTabletSize (pSPTABLET_T pTablet, SPINT32 *piWidth, SPINT32 *piHeight)
 Get the tablet size of an SPTablet object.
SPINT32 __cdecl SPTabletGetTabletType (pSPTABLET_T pTablet, SPINT32 *piType)
 Query the tablet type.
SPINT32 __cdecl SPTabletGetTimeStamp (pSPTABLET_T pTablet, SPUINT32 *puTimeStamp)
 Get the timestamp of the signature. most recently acquired by an SPTablet object.
SPINT32 __cdecl SPTabletGetUserLong (pSPTABLET_T pTablet, SPVPTR *plUserLong)
 Get the optional user parameter of an SPTablet object.
SPINT32 __cdecl SPTabletHasExternalLCD (pSPTABLET_T pTablet, SPINT32 *piExtLCD)
 Check if the tablet used by an SPTablet object has an integrated LCD.
SPINT32 __cdecl SPTabletHasProximity (pSPTABLET_T pTablet, SPINT32 *piProximity)
 Get the proximity capability of an SPTablet object.
SPINT32 __cdecl SPTabletReloadParameters (pSPTABLET_T pTablet)
 Reload the tablet characteristics.
SPINT32 __cdecl SPTabletReset (SPBOOL bReset)
 Reset all tablet drivers.
SPINT32 __cdecl SPTabletSetBackgroundImage (pSPTABLET_T pTablet, const SPUCHAR *pbImageData, SPINT32 iImageDataLen)
 Set the background image of an SPTablet object.
SPINT32 __cdecl SPTabletSetBackgroundImage2 (pSPTABLET_T pTablet, SPINT32 iImFlags, const SPUCHAR *pbImageData, SPINT32 iImageDataLen)
 Set the background image of an SPTablet object.
SPINT32 __cdecl SPTabletSetButtonListener (pSPTABLET_T pTablet, pSPTABLETBUTTON_T pNotifyButton)
 Set the hardware button listener of an SPTablet object.
SPINT32 __cdecl SPTabletSetClipRectangle (pSPTABLET_T pTablet, SPINT32 iLeft, SPINT32 iTop, SPINT32 iRight, SPINT32 iBottom)
 Set the clipping rectangle for the tablet display.
SPINT32 __cdecl SPTabletSetDevice (pSPTABLET_T pTablet, SPINT32 iDevice)
 Set the device ID of an SPTablet object.
SPINT32 __cdecl SPTabletSetDisplayType (pSPTABLET_T pTablet, SPINT32 iDisplayType)
 Set the display type of the tablet used by this SPTablet object.
SPINT32 __cdecl SPTabletSetDriver (pSPTABLET_T pTablet, SPINT32 iDriver)
 Set the driver ID of an SPTablet object.
SPINT32 __cdecl SPTabletSetFlags (pSPTABLET_T pTablet, SPINT32 iFlags)
 Set the tablet flags for acquiry mode of an SPTablet object.
SPINT32 __cdecl SPTabletSetLCD (pSPTABLET_T pTablet, SPINT32 iLCD)
 Change an SPTablet object's notion of the presence of a full-screen tablet.
SPINT32 __cdecl SPTabletSetListeners (pSPTABLET_T pTablet, pSPSTARTNOTIFY_T pStartNotify, pSPLINETO_T pLineTo, pSPENDNOTIFY_T pEndNotify)
 Set listeners of an SPTablet object.
SPINT32 __cdecl SPTabletSetListeners2 (pSPTABLET_T pTablet, pSPSTARTNOTIFY_T pStartNotify, pSPLINETO2_T pLineTo, pSPENDNOTIFY_T pEndNotify)
 Set listeners of an SPTablet object.
SPINT32 __cdecl SPTabletSetMaxPressure (pSPTABLET_T pTablet, SPINT32 iMaxPressure)
 Set the pressure range of an SPTablet object.
SPINT32 __cdecl SPTabletSetPadSerial (pSPTABLET_T pTablet, const SPUCHAR *pbPadSerial, SPINT32 iPadSerialLength)
 Set the tablet serial ID of an SPTablet object.
SPINT32 __cdecl SPTabletSetResolution (pSPTABLET_T pTablet, SPINT32 iResolution)
 Set the resolution of an SPTablet object.
SPINT32 __cdecl SPTabletSetSampleRate (pSPTABLET_T pTablet, SPINT32 iSampleRate)
 Set the sample rate of an SPTablet object.
SPINT32 __cdecl SPTabletSetStatusListener (pSPTABLET_T pTablet, pSPTABLETSTATUS_T pNotifyStatus)
 Set the hardware status listener of an SPTablet object.
SPINT32 __cdecl SPTabletSetTabletOption (pSPTABLET_T pTablet, const SPCHAR *pszName, SPINT32 iValue)
 Set a tablet parameter.
SPINT32 __cdecl SPTabletSetTabletSize (pSPTABLET_T pTablet, SPINT32 iWidth, SPINT32 iHeight)
 Set the tablet size of an SPTablet object.
SPINT32 __cdecl SPTabletSetTicket (pSPTABLET_T pTablet, pSPTICKET_T pTicket)
 Pass a license ticket for the next signature capture(s).
SPINT32 __cdecl SPTabletSetUserLong (pSPTABLET_T pTablet, SPVPTR lUserLong)
 Set the optional user parameter of an SPTablet object.
SPINT32 __cdecl SPTabletSwitchSerialType (pSPTABLET_T pTablet, SPINT32 iSerialType)
 Chooses a different type of serial ID to be returned by SPTabletGetSerial.


Define Documentation

#define SP_ACQUIRE_RETURN_IMMEDIATELY   2
 

Flag for SPTabletSetFlags: return immediately from SPTabletAcquire.

If this flag is set, SPTabletAcquire will return immediately. If this flag is not set, SPTabletAcquire will not return until SPTabletAcquireDone is called.

SPTabletAcquireDone must be called in either case.

Note:
Currently, this flag is assumed to be always set under Linux.
See also:
SPTabletAcquire, SPTabletAcquireDone, SPTabletSetFlags
Todo:
Implement for Linux

#define SP_ACQUIRE_TRANSFER_0_VECTORS   8
 

Flag for SPTabletSetFlags: send all vectors having a pressure value of 0.

If this flag is set, SPTabletAcquire will send all vectors (samples) that have a pressure value of 0. If this flag is not set, SPTabletAcquire will send only one vector having a pressure value of 0 for a sequence of vectors having a pressure value of 0.

See also:
SPTabletAcquire, SPTabletSetFlags

#define SP_DONT_ECHO_STROKES   0x10
 

Flag for SPTabletSetFlags: don't echo strokes on the tablet LCD.

If this flag is set, strokes won't be echoed to the tablet LCD. If this flag is not set, strokes will be echoed to the tablet LCD

This flag is ignored for tablets that don't have an LCD.

See also:
SPTabletAcquire, SPTabletSetFlags

#define SP_SYNCHRONOUS_START_ACQUIRE   0x40
 

Flag for SPTabletSetFlags: execute SPTabletStartAcquire synchronously.

Some tablet drivers require windows messages posted to finally start acquiry mode. The normal behaviour is to post the messages and return. Set this flag if you want the SPTablet object to wait until the messages have been processed (SPTablet will then process and dispatch windows messages).

This flag is currently ignored under Linux.

See also:
SPTabletAcquire, SPTabletSetFlags
Todo:
Implement for Linux

#define SP_TABLET_STATE_ACQUIRE   2
 

Tablet state: acquiring.

See also:
SPTabletGetState, SPTabletAcquire

#define SP_TABLET_STATE_CONNECT   1
 

Tablet state: connected.

See also:
SPTabletGetState, SPTabletConnect

#define SP_TABLET_STATE_IDLE   0
 

Tablet state: idle.

See also:
SPTabletGetState


Typedef Documentation

typedef int( _cdecl * pSPENDNOTIFY_T)(pSPTABLET_T pTablet)
 

Callback function that is called after sending one or more vectors.

A pointer to a function that is called whenever all vectors (samples) of a set of samples have been transferred in acquiry mode. This notification can be used for painting vectors when no vectors are coming in.

Parameters:
pTablet [i] pointer to the SPTablet object that generated the event.
Returns:
always SP_NOERR, currently ignored.
See also:
SPTabletSetListeners, pSPSTARTNOTIFY_T, pSPLINETO_T

typedef int( _cdecl * pSPLINETO2_T)(pSPTABLET_T pTablet, 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.

Parameters:
pTablet [i] pointer to the SPTablet 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.
See also:
pSPLINETO_T, SPTabletSetListeners2

typedef int( _cdecl * pSPLINETO_T)(pSPTABLET_T pTablet, SPINT32 iX, SPINT32 iY, SPINT32 iPress)
 

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.

Use SPTabletSetFlags to define behaviour for vectors having a pressure value of 0.

Coordinates are sent in tablet coordinates. It is the application's responsibility to convert coordinates into user coordinate space. Tablet coordinates are by default normalized to a resolution of 300 DPI.

The coordinate origin is the top left corner of the display window, or the lower left corner of the screen (converted to tablet coordinates) when using an full screen LCD tablet.

Coordinate space: 0, 0 equals top left corner. The bottom right corner is calculated phys. height * resolution / 25.4, and phys width * resolution / 25.5, where resolution equals the value returned by SPTabletGetReolution.
On Full screen devices the coordinate origin is set to the top left corner of the screen. The application must subtract the offset from top left screen coordinate to the top left acquisition window coordinate (converted to tablet coordinates).

Parameters:
pTablet [i] pointer to the SPTablet 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.
Returns:
always SP_NOERR, currently ignored.
See also:
SPTabletGetLCD, SPTabletSetLCD, SPTabletSetListeners, SPTabletSetFlags, SP_ACQUIRE_TRANSFER_0_VECTORS, pSPSTARTNOTIFY_T , pSPENDNOTIFY_T

typedef int( _cdecl * pSPSTARTNOTIFY_T)(pSPTABLET_T pTablet)
 

Callback function that is called when vectors are available.

A pointer to a function that is called whenever a new set of vectors (samples) is available from the tablet in acquiry mode. The function is called before the vectors of that set are sent to the application.

Parameters:
pTablet [i] pointer to the SPTablet object that generated the event.
Returns:
always SP_NOERR, currently ignored.
See also:
SPTabletSetListeners, pSPLINETO_T , pSPENDNOTIFY_T

typedef int( _cdecl * pSPTABLETBUTTON_T)(pSPTABLET_T pTablet, SPINT32 iButtonId, SPINT32 iPress)
 

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

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

Parameters:
pTablet [i] pointer to the SPTablet object that generated the event.
iButtonId [i] a value identifying the button that was pressed. The value depends on the tablet, see Tablet Hardware button Assignment
iPress [i] the pen pressure if available The value depends on the tablet, see Tablet Hardware button Assignment
Returns:
always SP_NOERR, currently ignored.
See also:
SPTabletSetButtonListener

typedef int( _cdecl * pSPTABLETSTATUS_T)(pSPTABLET_T pTablet, SPINT32 iMajor, SPINT32 iMinor)
 

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

A pointer to a function that is called to notify the application about a hardware events.

Parameters:
pTablet [i] pointer to the SPTablet object that generated the event.
iMajor [i] a value identifying the major reason for the event.
iMinor [i] additional information for the event
Returns:
always SP_NOERR, currently ignored.
See also:
SPTabletSetStatusListener


Function Documentation

SPINT32 __cdecl SPTabletAcquire pSPTABLET_T  pTablet,
SPHWND  hwndParent
 

Put an SPTablet object into acquiry mode.

This function enables acquiry mode and sends all vectors (samples) from the tablet to the registered listener.
Tablet PC and Cintiq devices will be exclusively locked for any other SignWare processes until acquiry mode will be terminated (see SPTabletAcquireDone).

If SP_ACQUIRE_TRANSFER_0_VECTORS is set, all vectors having a pressure value of 0 will be sent; if SP_ACQUIRE_TRANSFER_0_VECTORS is not set, only one vector having a pressure value of 0 will be sent for a sequence of vectors having a pressure level of 0.

This function will return immediately if SP_ACQUIRE_RETURN_IMMEDIATELY is set. If SP_ACQUIRE_RETURN_IMMEDIATELY is not set, this function will block until SPTabletAcquireDone is called.

Note:
Acquire mode may be dispatched and activated within the message processing thread (this restriction is required by some tablet drivers, e. g. MS TabletPC). 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 theis object, the state will be SP_TABLET_STATE_ACQUIRE on success.
Parameters:
pTablet [i] pointer to an SPTablet object.
hwndParent [i] parent window handle or NULL.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletAcquireDone, SPTabletCreate, SPTabletSetFlags

SPINT32 __cdecl SPTabletAcquireDone pSPTABLET_T  pTablet  ) 
 

Terminate acquiry mode of an SPTablet object.

This function terminates acquiry mode, the device state changes to the connect state (see SPTabletGetState).
TabletPC and Wacom PL-400 / Cintiq devics release the device lock.
Wacom tablets always return a sample rate of 100 Hz though the real sample rate may differ. This function attempts to compute the real sample rate, the computed sample rate can be retrieved with SPTabletGetSampleRate. You should set the sample rate of the signature to the computed sample rate.

Parameters:
pTablet [i] pointer to an SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletAcquire, SPTabletGetSampleRate, SPGuiAcquAcquireDone, SPSignatureSetSampleRate

SPINT32 __cdecl SPTabletClearBackgroundImage pSPTABLET_T  pTablet,
SPINT32  iImFlags
 

Clear the background image of an SPTablet object.

The tablet used by the SPTablet object must have an LCD.

Not all tablets support displaying idle images; currently only Wacom SignPad tablets support a background image that will be displayed in idle mode (more precise whenever the application disconnects the device (SPTabletDisconnect)).
Not all tablets support displaying immediate images; currently only Wacom SignPad tablets support immediate images that will be displayed immediately.

Note:
Immediate images cannot be displayed in acquiry mode.
Parameters:
pTablet [i] pointer to an SPTablet object.
iImFlags [i] image destination:
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletConnect pSPTABLET_T  pTablet  ) 
 

Connect an SPTablet object to a tablet.

This function establishes a connection to a tablet. The state changes from idle to connect (see SPTabletGetState)
The device will be exclusively locked for any other SignWare processes until the device will be disconnected, unless it is a TabletPC or a Wacom PL-400 / Cintiq device.

Parameters:
pTablet [i] pointer to an SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate , SPTabletDisconnect, SPTabletSetTicket, SPSignwareSetTicket

SPINT32 __cdecl SPTabletCreate pSPTABLET_T ppTablet,
SPINT32  iDriverId
 

Create a new SPTablet object.

This function checks if the requested driver can be loaded and if a device for this driver can be found. All device-specific information will be available, if a device is found. Call SPTabletGetDevice to get the identifier of the device that was detected.

Please read Tablet creation options

Parameters:
ppTablet [o] pointer to a variable that will be filled with a pointer to a new SPTablet object. The caller is responsible for deallocating the new object by calling SPTabletFree.
iDriverId [i] identifier for the driver to use:
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreateEx, SPTabletFree, SPTabletGetDevice

SPINT32 __cdecl SPTabletCreateByAlias pSPTABLET_T ppTablet,
const char *  pszAlias
 

Create a new SPTablet object based on an Alias.

Please read Tablet creation options for resolving the Alias

Parameters:
ppTablet [o] pointer to a variable that will be filled with a pointer to a new SPTablet object. The caller is responsible for deallocating the new object by calling SPTabletFree.
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)
See also:
SPTabletCreate, SPtabletCreateEx, SPTabletFree

SPINT32 __cdecl SPTabletCreateByEnum pSPTABLET_T ppTablet,
pSPPROPERTYMAP_T  spDescriptor
 

Create a new SPTablet object.

Please read Tablet creation options for a list of supported options

Note:
This function creates a default tablet if spDescriptor is NULL
Parameters:
ppTablet [o] pointer to a variable that will be filled with a pointer to a new SPTablet object. The caller is responsible for deallocating the new object by calling SPTabletFree.
spDescriptor [i] A propertyMap as returned from a pSPTABLETENUM_T object. Under Linux, only SPTabletWSignPad is supported.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletFree

SPINT32 __cdecl SPTabletCreateEx pSPTABLET_T ppTablet,
const char *  pszTabletClass,
const char *  pszConfig
 

Create a new SPTablet object.

Please read Tablet creation options for a list of supported options

Parameters:
ppTablet [o] pointer to a variable that will be filled with a pointer to a new SPTablet object. The caller is responsible for deallocating the new object by calling SPTabletFree.
pszTabletClass [i] class name of the Kofax tablet access module. Under Linux, only SPTabletWSignPad is supported.
pszConfig [i] optional configuration data can be passed through this parameter. 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:
SPTabletCreate, SPTabletFree

SPINT32 __cdecl SPTabletDisconnect pSPTABLET_T  pTablet  ) 
 

Disconnect a tablet from an SPTablet object.

This function terminates a connection to a tablet. The state changes from connect to idle (see SPTabletGetState)
the device lock will be released (TabletPC and Wacom PL-400 / Cintiq devics free the lock in APTabletAcquireDone).
The idle image will be loaded on devices that support idle images (see SPTabletSetBackgroundImage2).

Parameters:
pTablet [i] pointer to an SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletConnect, SPTabletSetBackgroundImage2

SPINT32 __cdecl SPTabletFree pSPTABLET_T ppTablet  ) 
 

Deallocate an SPTablet object.

The SPTablet object must have been allocated with SPTabletCreate or SPTabletCreateEx.

Parameters:
ppTablet [io] pointer to a variable containing a pointer to an SPTablet 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:
SPTabletCreate, SPTabletCreateEx, SPTabletCreateByAlias

SPINT32 __cdecl SPTabletGetDevice pSPTABLET_T  pTablet,
SPINT32 piDevice
 

Get the device ID of an SPTablet object.

Wacom drivers do not pass information about the connected devices, the detected device may differ from the physically connected tablet. SPTablet uses the size of the device to identify the connected model.

Parameters:
pTablet [i] pointer to an SPTablet object.
piDevice [o] pointer to a variable that will be filled with the tablet device ID from the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletGetDeviceStr, SPTabletGetDriver, SPTabletSetDevice

SPINT32 __cdecl SPTabletGetDeviceStr SPINT32  iDeviceId,
SPCHAR pszName,
SPINT32  iNameLen
 

Get the name of the tablet device.

The buffer should have a size of at least 256 bytes.
The required buffer size will be returned when SPTabletGetDeviceStr is called with parameter pszName set to NULL.

Parameters:
iDeviceId [i] device identification as returned by SPTabletGetDevice.
pszName [io] pointer to a buffer that will be filled with the name of the device.
iNameLen [i] length (in bytes) of the buffer pointed to by pszName.
Returns:
the required buffer size if pszName is NULL, or SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
Example:
// Query the device name (dynamically allocated buffer)
char *QueryTabletDeviceName(int iDevice)
{
    char *pszName = 0;
    // Query the size of the required buffer
    int rc = SPTabletGetDeviceStr(iDevice, NULL, 0);
    pszName = malloc(rc);
    rc = SPTabletGetDeviceStr(iDevice, pszName, rc);
    if(rc == SP_NOERR) return pszName;
    return NULL;
}

SPINT32 __cdecl SPTabletGetDisplayType pSPTABLET_T  pTablet,
SPINT32 piDisplayType
 

Query the display type of the tablet used by this SPTablet object.

SPTablet differentiates 3 types of tablet displays

  • SP_TABLET_NO_DISPLAY: tablets without a screen (such as Wacom Intuos)
  • SP_TABLET_LCD_DISPLAY: tablets with an integrated LCD screen (such as Wacom Signpad)
  • SP_TABLET_PC_DISPLAY: PCs with integrated tablet functionality (such as TabletPC)
Parameters:
pTablet [i] pointer to an SPTablet object.
piDisplayType [o] pointer to a variable that will be filled with the display type of the tablet
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
Since:
Version 2.5
See also:
SPTabletSetDisplayType

SPINT32 __cdecl SPTabletGetDriver pSPTABLET_T  pTablet,
SPINT32 piDriver
 

Get the driver ID of an SPTablet object.

Parameters:
pTablet [i] pointer to an SPTablet object.
piDriver [o] pointer to a variable that will be filled with the driver ID used by the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPTabletCreate, SPTabletSetDriver

SPINT32 __cdecl SPTabletGetDriverStr SPINT32  iDriverId,
SPCHAR pszName,
SPINT32  iNameLen
 

Get the name of a tablet driver.

The buffer should have a size of at least 256 bytes.
The required buffer size will be returned when SPTabletGetDriverStr is called with parameter pszName set to NULL.

Parameters:
iDriverId [i] driver identification as returned by SPTabletGetDriver.
pszName [io] pointer to a buffer that will be filled with the name of the driver.
iNameLen [i] length (in bytes) of the buffer pointed to by pszName.
Returns:
the required buffer size if pszName is NULL, or SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletGetDeviceStr, SPTabletGetDriver
Todo:
Don't return "Wintab" under Linux
Example:
// Query the driver name (dynamically allocated buffer)
char *QueryTabletDriverName(int iDriver)
{
    char *pszName = 0;
    // Query the size of the required buffer
    int rc = SPTabletGetDriverStr(iDriver, NULL, 0);
    pszName = malloc(rc);
    rc = SPTabletGetDriverStr(iDriver, pszName, rc);
    if(rc == SP_NOERR) return pszName;
    return NULL;
}

SPINT32 __cdecl SPTabletGetFlags pSPTABLET_T  pTablet,
SPINT32 piFlags
 

Get the tablet flags for acquiry mode of an SPTablet object.

By default, the flags are set to SP_ACQUIRE_RETURN_IMMEDIATELY, that is:

  • do not transfer 0 pressure vectors
  • SPTabletAcquire returns immediately
  • strokes are echoed
  • SPTabletAcquire does not wait until the tablet enters acquire state
Note:
SP_ACQUIRE_RETURN_IMMEDIATELY is set internally.
Parameters:
pTablet [i] pointer to an SPTablet object.
piFlags [i] pointer to a variable that will be filled with the current set of flags (see SPTabletSetFlags):
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletSetFlags

SPINT32 __cdecl SPTabletGetHardwareName pSPTABLET_T  pTablet,
SPCHAR pszHardwareName,
SPINT32  iHardwareNameLen
 

Get the hardware file name of an SPTablet object.

The hardware file name equals the name that was used to connect to the device. Serial Connections use "\\.\COMi" (i equals the COM port number), USB file names are composed of the device id, manufacturer id like "\\?\hid#vid_056a&pid_00a1#6&37604930&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}".
Normally SPTabletGetHardwareName is not needed, but if the application must repeatedly address a specific device then you may want to check the hardware name, see Installation and configuration of various pads.

Note:
Hardware file names are supported by Wacom SignPad devices.
Parameters:
pTablet [i] pointer to an SPTablet object.
pszHardwareName [io] pointer to a buffer that will be filled with the hardware file name from the SPTablet object, the buffer size should be at least 256 bytes.
iHardwareNameLen [i] size of the buffer [bytes]
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
Since:
Version 2.5
See also:
SPTabletCreate
Todo:
Implement for Linux

SPINT32 __cdecl SPTabletGetLCD pSPTABLET_T  pTablet,
SPINT32 piLCD
 

Check if the tablet used by an SPTablet object is a full-screen tablet.

This function checks for tablets which are integrated into the PC screen.

Tablets identified by these tablet ID's are full-screen tablets:

SPTablet differentiates 3 types of tablets
  • tablets without an LCD screen (such as Wacom Intuos), SPTabletGetLCD and SPTabletHasExternalLCD return 0, SPTabletGetDisplayType returns SP_TABLET_NO_DISPLAY
  • tablets with an integrated LCD screen (such as Wacom Signpad), SPTabletGetLCD returns 0, SPTabletHasExternalLCD returns 1, SPTabletGetDisplayType returns SP_TABLET_LCD_DISPLAY
  • PCs with integrated tablet functionality (such as TabletPC), SPTabletGetLCD returns 1, SPTabletHasExternalLCD returns 0, SPTabletGetDisplayType returns SP_TABLET_PC_DISPLAY
Note:
The result of this function can be overridden by SPTabletSetLCD.
Parameters:
pTablet [i] pointer to an SPTablet object.
piLCD [o] pointer to a variable that will be filled with a value telling whether the tablet used by the SPTablet object is a full-screen tablet:
  • 0: the tablet is not a full-screen tablet (ie, it does not have an LCD or the tablet has an external LCD)
  • 1: the tablet is a full-screen tablet (ie, the capture device is integrated into the PC screen)
Returns:
SP_NOERR on success, else error code:
Deprecated:
This function is replaced by SPTabletGetDisplayType
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
Since:
Version 2.5
See also:
SPTabletHasExternalLCD, SPTabletSetLCD

SPINT32 __cdecl SPTabletGetLCDBitsPerPixel pSPTABLET_T  pTablet,
SPINT32 piBitsPerPixel
 

Get the bit depth of the LCD of the tablet.

The currently supported tabletts with external LCD have 1 bit per pixel, black/white screens.

Parameters:
pTablet [i] pointer to an SPTablet object.
piBitsPerPixel [io] pointer to a variable that will be filled with the bits per pixel of the LCD.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletGetLCDOffset pSPTABLET_T  pTablet,
SPINT32 piOffsetX,
SPINT32 piOffsetY
 

Get the offset of the LCD of the tablet used by an SPTablet object.

The offset is typically 0, however full screeen devices may be operated in multi monitor configurations, that may result in a screen offset.
The operating system handles all monitors as one virtual display, each monitor might be offset within the virtual display, see MSDN 'Multiple Display Monitors'.

Note:
The sensitive monitor must be the primary monitor or must be configured as a separate display (dual view), else the tablet will not be usable.
The tablet vectors are transformed to match the virtual screen coordinates, but the tablet size equals the physical dimension of the sensitive monitor!
Parameters:
pTablet [i] pointer to an SPTablet object.
piOffsetX [io] pointer to a variable that will be filled with the x-offset (in pixels) of the LCD.
piOffsetY [io] pointer to a variable that will be filled with the y-offset (in pixels) of the LCD.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletGetLCDSize

SPINT32 __cdecl SPTabletGetLCDSize pSPTABLET_T  pTablet,
SPINT32 piWidth,
SPINT32 piHeight
 

Get the size of the LCD of the tablet used by an SPTablet object.

Parameters:
pTablet [i] pointer to an SPTablet object.
piWidth [io] pointer to a variable that will be filled with the width (in pixels) of the LCD.
piHeight [io] pointer to a variable that will be filled with the height (in pixels) of the LCD.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletGetLCD, SPTabletSetBackgroundImage

SPINT32 __cdecl SPTabletGetMaxPressure pSPTABLET_T  pTablet,
SPINT32 piMaxPressure
 

Get the pressure range of an SPTablet object.

The maximum pressure value is read from the capabilities of the tablet used by the SPTablet object. The pressure values of the signature data are normalized to the range 0 through 1023.

Parameters:
pTablet [i] pointer to an SPTablet object.
piMaxPressure [o] pointer to a variable that will be filled with the maximum pressure value of the tablet used by the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletSetMaxPressure, SPSignatureGetMaxPressure

SPINT32 __cdecl SPTabletGetPadSerial pSPTABLET_T  pTablet,
SPUCHAR pbPadSerial,
SPINT32 piPadSerialLength
 

Get the tablet serial ID of an SPTablet object.

The size of a tablet serial ID is limited to 20 bytes within the SignWare data structures, more limitations may apply depending on the tablet.

Tablets that support serial ID's:

  • Wacom Signpad series (STU-300, STU-500): The serial ID is limited to a 4 digit hex number, the parameter pbPadSerial is passed as a 8-digit hex string, range '0' ... 'FFFFFFFF'. Note that leading zero's are truncated.
    Tablets are delivered with a serial number is set to '0', the application may pass a serial number (see SPTabletSetPadSerial).
Parameters:
pTablet [i] pointer to an SPTablet object.
pbPadSerial [o] pointer to an array of bytes that will be filled with the serial ID of the tablet used to capture the signature contained in the SPSignature object.
piPadSerialLength [io] pointer to a variable that contains the size (in bytes) of the buffer pointed to by pbPadSerial. That variable will be filled with the number of bytes written to the buffer.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletSetPadSerial, SPSignatureGetPadSerial

SPINT32 __cdecl SPTabletGetPhysicalSize pSPTABLET_T  pTablet,
SPINT32 piWidth,
SPINT32 piHeight
 

Get the tablet size of an SPTablet object.

Note:
SPTabletGetTabletSize returns the size of the tablet in tablet coordinates, SPTabletGetPhysicalSize returns the size of the tablet in mm.
Parameters:
pTablet [i] pointer to an SPTablet object.
piWidth [o] pointer to a variable that will be filled with the width (in mm) of the tablet used by the SPTablet object.
piHeight [o] pointer to a variable that will be filled with the height (in mm) of the tablet used by the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletGetTabletSize

SPINT32 __cdecl SPTabletGetResolution pSPTABLET_T  pTablet,
SPINT32 piResolution
 

Get the logical resolution of an SPTablet object.

By default, the resolution is set to 300 DPI.

Tablets have a resolution defined by the physical resolution in the tablet hardware. The SPTablet implementation 'resamples' the vectors and transforms each vector to the given resolution. The absolute position of the pen is calculated by the tablet coordinate * 25.4 / iResolution.

Parameters:
pTablet [i] pointer to an SPTablet object.
piResolution [o] pointer to a variable that will be filled with the resolution (in DPI) of the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletSetResolution, SPSignatureGetResolution

SPINT32 __cdecl SPTabletGetResolution2 pSPTABLET_T  pTablet,
SPINT32  iDetail,
SPINT32 piResolution
 

Get the resolution of an SPTablet object.

By default, the resolution is set to 300 DPI.

Tablets have a resolution defined by the physical resolution in the tablet hardware. The SPTablet implementation 'resamples' the vectors and transforms each vector to the given resolution. The absolute position of the pen is calculated by the tablet coordinate * 25.4 / iResolution.

Parameters:
pTablet [i] pointer to an SPTablet object.
iDetail [i] query the physical (SP_TABLET_PHYSICAL) or logical (SP_TABLET_LOGICAL) resolution
piResolution [o] pointer to a variable that will be filled with the resolution (in DPI) of the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletSetResolution, SPSignatureGetResolution
Since:
Version 3.2.2

SPINT32 __cdecl SPTabletGetSampleRate pSPTABLET_T  pTablet,
SPINT32 piSampleRate
 

Get the logical sample rate of an SPTablet object.

Query the sample rate of the tablet. Some tablets allow to set the sample rate below the maximum physical sample rate

Parameters:
pTablet [i] pointer to an SPTablet object.
piSampleRate [o] pointer to a variable that will be filled with the sample rate (in Hz) of the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletSetSampleRate, SPTabletAcquireDone, SPSignatureGetSampleRate, SPSignatureSetSampleRate

SPINT32 __cdecl SPTabletGetSampleRate2 pSPTABLET_T  pTablet,
SPINT32  iDetail,
SPINT32 piSampleRate
 

Get the sample rate of an SPTablet object.

Query the sample rate of the tablet. Some tablets allow to set the sample rate below the maximum physical sample rate

Parameters:
pTablet [i] pointer to an SPTablet object.
iDetail [i] query the physical (SP_TABLET_PHYSICAL) or logical (SP_TABLET_LOGICAL) resolution
piSampleRate [o] pointer to a variable that will be filled with the sample rate (in Hz) of the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletSetSampleRate, SPTabletAcquireDone, SPSignatureGetSampleRate, SPSignatureSetSampleRate
Since:
Version 3.2.2

SPINT32 __cdecl SPTabletGetState pSPTABLET_T  pTablet,
SPINT32 piState
 

Get the state of an SPTablet object.

Parameters:
pTablet [i] pointer to an SPTablet object.
piState [o] pointer to a variable that will be filled with the state:
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletGetTabletSize pSPTABLET_T  pTablet,
SPINT32 piWidth,
SPINT32 piHeight
 

Get the tablet size of an SPTablet object.

To convert from tablet coordinates to mm, use this formula:

 tablet_size_mm = tablet_coordinate / (SPTabletGetResolution(pTablet) * 25.4)

Note:
SPTabletGetTabletSize returns the size of the tablet in tablet coordinates, SPTabletGetPhysicalSize returns the size of the tablet in mm.
Parameters:
pTablet [i] pointer to an SPTablet object.
piWidth [o] pointer to a variable that will be filled with the width (in tablet coordinates) of the tablet used by the SPTablet object.
piHeight [o] pointer to a variable that will be filled with the height (in tablet coordinates) of the tablet used by the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletSetTabletSize, SPTabletGetPhysicalSize

SPINT32 __cdecl SPTabletGetTabletType pSPTABLET_T  pTablet,
SPINT32 piType
 

Query the tablet type.

The tablet size is set during initialization and cannot be overwritten.

The tablet type defines some special behaviour of e. g. standalone tablets.

The application should display a wait indicator instead of the realtime signature strokes, if SP_TABLET_NO_REALTIME_VECTORS is set.

The application should register a hardware button listener to process virtual buttons, if SP_TABLET_HARDWARE_AS_VIRTUAL_BUTTONS is set, see pSPTABLETBUTTON_T.

Parameters:
pTablet [i] pointer to an SPTablet object.
piType [o] pointer to an integer that will be set to the tablet type
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SP_TABLET_NO_REALTIME_VECTORS, SP_TABLET_HARDWARE_AS_VIRTUAL_BUTTONS, pSPTABLETBUTTON_T
Since:
Version 2.6.2

SPINT32 __cdecl SPTabletGetTimeStamp pSPTABLET_T  pTablet,
SPUINT32 puTimeStamp
 

Get the timestamp of the signature. most recently acquired by an SPTablet object.

The timestamp can be retrieved after calling SPTabletAcquire until SPTabletDisconnect is called.

Parameters:
pTablet [i] pointer to an SPTablet object.
puTimeStamp [o] pointer to a variable that will be filled with the timestamp (seconds since 1970-01-01 00:00:00 UTC) of the signature most recently acquired by the SPTablet object.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletAcquire, SPTabletCreate, SPTabletDisconnect

SPINT32 __cdecl SPTabletGetUserLong pSPTABLET_T  pTablet,
SPVPTR plUserLong
 

Get the optional user parameter of an SPTablet object.

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

SPINT32 __cdecl SPTabletHasExternalLCD pSPTABLET_T  pTablet,
SPINT32 piExtLCD
 

Check if the tablet used by an SPTablet object has an integrated LCD.

This function checks for tablets with a built-in LCD. Full-screen tablets (capture devices integrated into the PC screen) are not considered to be tablets having an integrated LCD.

Tablets identified by these tablet ID's have an integrated LCD:

Tablet connected via SPRemoteTablet or SPGenericTablet access modules might have integrated LCD's or use the host monitor.

SPTablet differentiates 3 types of tablets

  • tablets without an LCD screen (such as Wacom Intuos), SPTabletGetLCD and SPTabletHasExternalLCD return 0, SPTabletGetDisplayType returns SP_TABLET_NO_DISPLAY
  • tablets with an integrated LCD screen (such as Wacom Signpad), SPTabletGetLCD returns 0, SPTabletHasExternalLCD returns 1, SPTabletGetDisplayType returns SP_TABLET_LCD_DISPLAY
  • PCs with integrated tablet functionality (such as TabletPC), SPTabletGetLCD returns 1, SPTabletHasExternalLCD returns 0, SPTabletGetDisplayType returns SP_TABLET_PC_DISPLAY
Note:
The result of this function can be overridden by SPTabletSetLCD.
Parameters:
pTablet [i] pointer to an SPTablet object.
piExtLCD [o] pointer to a variable that will be filled with the LCD capability of the tablet used by the SPTablet object:
  • 0: the tablet does not have a built-in LCD or the tablet is a full-screen tablet (integrated into the PC screen)
  • 1: the tablet has an LCD integrated (and is not a full-screen tablet)
Returns:
SP_NOERR on success, else error code:
Deprecated:
This function is replaced by SPTabletGetDisplayType
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletGetLCD, SPTabletSetLCD

SPINT32 __cdecl SPTabletHasProximity pSPTABLET_T  pTablet,
SPINT32 piProximity
 

Get the proximity capability of an SPTablet object.

Devices that do not support proximity don't send the current pen position as long as the pen is up. Special care must therefore be taken when drawing the first vector (sample) having a non-zero pressure value. The SPTablet object will insert a vector having a pressure value of 0 and the coordinates of the first vector having a non-zero pressure value to inform all listeners on the current pen position for these devices.

These tablets support proximity:

Parameters:
pTablet [i] pointer to an SPTablet object.
piProximity [o] pointer to a variable that will be filled with the proximity capability of the tablet used by the SPTablet object:
  • 0: the tablet sends vectors only while the pen touches the tablet
  • 1: the tablet sends vectors when the pen is raised (up to 5 mm)
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletReloadParameters pSPTABLET_T  pTablet  ) 
 

Reload the tablet characteristics.

Tablet characteristics are typically bound to the hardware and do not change, except for TabletPCs where the screen resolution or screen orientation might change. Both screen resolution and orientation must be considered to calculate the physical tablet width / height and tablet LCD width and height.

Applications that support display resolution or orientation changes while acquiring a signature should call SPTabletReloadParameters while or after processing the WM_DISPLAYCHANGE message, see example below.

Parameters:
pTablet [i] pointer to an SPTablet object.
Returns:
SP_NOERR on success, else error code:
  • SP_NOPADERR no tablet assigned to the object
  • SP_APPLERR wrong state, SPTabletReloadParameters cannot be called while acquiring a signature.
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
Example:
void OnDisplayChanged()
{
    SPINT32 iLcd = 0;
    SPTabletGetLCD(pTablet, &iLcd);
    // Display changes only effect TabletPC and Wacom PL / Cintiq devices
    if(!iLcd) return;

    SPINT32 iState = SP_TABLET_STATE_IDLE;
    SPTabletGetState(pTablet, &iState);
    if(iState == SP_TABLET_STATE_ACQUIRE)
        SPTabletAcquireDone(pTablet);
    SPTabletReloadParameters(pTablet);
    // .. update the application specific data that refers to display
    // size and orientation ...

    // finally recover the tablet state
    if(iState == SP_TABLET_STATE_ACQUIRE)
        SPTabletAcquire(pTablet, mHwnd);
}

SPINT32 __cdecl SPTabletReset SPBOOL  bReset  ) 
 

Reset all tablet drivers.

This will unload all tablet drivers and reset the internal states to "unconnected". The next request for a tablet operation will reload the drivers.

Note:
Normally, you should not call this function unless there is a special condition that requires a full reset such as reconnecting a device to a different port.
Parameters:
bReset [i] must be true
Returns:
SP_NOERR on success, else error code
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletSetBackgroundImage pSPTABLET_T  pTablet,
const SPUCHAR pbImageData,
SPINT32  iImageDataLen
 

Set the background image of an SPTablet object.

The tablet used by the SPTablet object must have an LCD.

The image will be converted to the format required by the tablet. This includes size and color-depth conversions, however the conversion may be lossy. It is therefore recommended to create the image using the size and color depth of the tablet LCD and in a format that is directly supported by the device.

Parameters:
pTablet [i] pointer to an SPTablet object.
pbImageData [i] pointer to the image. Most standard image formats such as BMP, TIF, JPG, GIF, and CCITT4 are supported.
iImageDataLen [i] length (in bytes) of the buffer pointed to by pbImageData.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM) SPTabletHasExternalLCD

SPINT32 __cdecl SPTabletSetBackgroundImage2 pSPTABLET_T  pTablet,
SPINT32  iImFlags,
const SPUCHAR pbImageData,
SPINT32  iImageDataLen
 

Set the background image of an SPTablet object.

The tablet used by the SPTablet object must have an LCD.

The image will be converted to the format required by the tablet. This includes size and color-depth conversions, however the conversion may be lossy. It is therefore recommended to create the image using the size and color depth of the tablet LCD and in a format that is directly supported by the device.

Not all tablets support displaying idle images; currently only Wacom SignPad tablets support a background image that will be displayed in idle mode (more precise whenever the application disconnects the device (SPTabletDisconnect)).
Not all tablets support displaying immediate images; currently only Wacom SignPad tablets support immediate images that will be displayed immediately.

Note:
Immediate images cannot be displayed in acquiry mode.
Parameters:
pTablet [i] pointer to an SPTablet object.
iImFlags [i] image destination:
pbImageData [i] pointer to the image. Most standard image formats such as BMP, TIF, JPG, GIF, and CCITT4 are supported.
iImageDataLen [i] length (in bytes) of the buffer pointed to by pbImageData.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletSetButtonListener pSPTABLET_T  pTablet,
pSPTABLETBUTTON_T  pNotifyButton
 

Set the hardware button listener of an SPTablet object.

Parameters:
pTablet [i] pointer to an SPTablet object.
pNotifyButton [i] function that is to be called when a hardware button of the tablet is pressed. The function pointer may be NULL to deregister all button event listeners.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletSetClipRectangle pSPTABLET_T  pTablet,
SPINT32  iLeft,
SPINT32  iTop,
SPINT32  iRight,
SPINT32  iBottom
 

Set the clipping rectangle for the tablet display.

Strokes outside the clipping rectangle will not be drawn on the tablet screen.
Currently only supported on Signpad STU-520.

Parameters:
pTablet [i] pointer to an SPTablet object.
iLeft [i] left coordinate of the signature entry region, in ppm (1/1000, thousands)
iTop [i] top coordinate of the signature entry region, in ppm (1/1000, thousands)
iRight [i] right coordinate of the signature entry region, in ppm (1/1000, thousands)
iBottom [i] bottom coordinate of the signature entry region, in ppm (1/1000, thousands)
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletSetDevice pSPTABLET_T  pTablet,
SPINT32  iDevice
 

Set the device ID of an SPTablet object.

The device ID is set during initialization and should not be overwritten unless you know what you do.

Parameters:
pTablet [i] pointer to an SPTablet object.
iDevice [i] new device identifier.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletGetDevice

SPINT32 __cdecl SPTabletSetDisplayType pSPTABLET_T  pTablet,
SPINT32  iDisplayType
 

Set the display type of the tablet used by this SPTablet object.

SPTablet differentiates 3 types of tablet displays

  • SP_TABLET_NO_DISPLAY: tablets without a screen (such as Wacom Intuos)
  • SP_TABLET_LCD_DISPLAY: tablets with an integrated LCD screen (such as Wacom Signpad)
  • SP_TABLET_PC_DISPLAY: PCs with integrated tablet functionality (such as TabletPC)
Parameters:
pTablet [i] pointer to an SPTablet object.
iDisplayType [i] the display type of the tablet
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
Since:
Version 2.5
See also:
SPTabletGetDisplayType

SPINT32 __cdecl SPTabletSetDriver pSPTABLET_T  pTablet,
SPINT32  iDriver
 

Set the driver ID of an SPTablet object.

The driver ID is set during initialization and should not be overwritten unless you know what you do.

Parameters:
pTablet [i] pointer to an SPTablet object.
iDriver [i] new driver identifier.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPTabletCreate, SPTabletGetDevice, SPTabletGetDriverStr

SPINT32 __cdecl SPTabletSetFlags pSPTABLET_T  pTablet,
SPINT32  iFlags
 

Set the tablet flags for acquiry mode of an SPTablet object.

Parameters:
pTablet [i] pointer to an SPTablet object.
iFlags [i] a bitwise combination of these flags:
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletSetListeners

SPINT32 __cdecl SPTabletSetLCD pSPTABLET_T  pTablet,
SPINT32  iLCD
 

Change an SPTablet object's notion of the presence of a full-screen tablet.

The tablet's LCD capability is determined during initialization and should not be overwritten unless you know what you do.

Parameters:
pTablet [i] pointer to an SPTablet object.
iLCD [i] desired notion of presence of a full-screen tablet:
Returns:
SP_NOERR on success, else error code:
Deprecated:
This function is replaced by SPTabletSetDisplayType
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletGetLCD, SPTabletHasExternalLCD

SPINT32 __cdecl SPTabletSetListeners pSPTABLET_T  pTablet,
pSPSTARTNOTIFY_T  pStartNotify,
pSPLINETO_T  pLineTo,
pSPENDNOTIFY_T  pEndNotify
 

Set listeners of an SPTablet object.

The SPTablet object calls the listener that was registered last. Call SPTabletSetListener(0, 0, 0) to deregister any listeners.

Parameters:
pTablet [i] pointer to an SPTablet object.
pStartNotify [i] function to be called before calling pLineTo for the first vector of a set of vectors. NULL if no notification is needed.
pLineTo [i] function to be called for each tablet vector (sample). The function pointer may be NULL to deregister the event listeners
pEndNotify [i] function to be called after calling pLineTo for the last vector of a set of vectors (at the time the function is called, the tablet is not sending vectors). NULL if no notification is needed.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletSetListeners2 pSPTABLET_T  pTablet,
pSPSTARTNOTIFY_T  pStartNotify,
pSPLINETO2_T  pLineTo,
pSPENDNOTIFY_T  pEndNotify
 

Set listeners of an SPTablet object.

The SPTablet object calls the listener that was registered last. Call SPTabletSetListener(0, 0, 0) to deregister any listeners.

Parameters:
pTablet [i] pointer to an SPTablet object.
pStartNotify [i] function to be called before calling pLineTo for the first vector of a set of vectors. NULL if no notification is needed.
pLineTo [i] function to be called for each tablet vector (sample). The function pointer may be NULL to deregister the event listeners
pEndNotify [i] function to be called after calling pLineTo for the last vector of a set of vectors (at the time the function is called, the tablet is not sending vectors). NULL if no notification is needed.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletSetMaxPressure pSPTABLET_T  pTablet,
SPINT32  iMaxPressure
 

Set the pressure range of an SPTablet object.

The maximum pressure value is set during initialization and should not be overwritten unless you know what you do.

Parameters:
pTablet [i] pointer to an SPTablet object.
iMaxPressure [i] new maximum pressure value.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletGetMaxPressure, SPSignatureSetMaxPressure

SPINT32 __cdecl SPTabletSetPadSerial pSPTABLET_T  pTablet,
const SPUCHAR pbPadSerial,
SPINT32  iPadSerialLength
 

Set the tablet serial ID of an SPTablet object.

The size of a tablet serial ID is limited to 20 bytes within the SignWare data structures, more limitations may apply depending on the tablet.

Tablets that support serial ID's:

  • Wacom Signpad series (STU-300, STU-500): The serial ID is limited to a 4 digit hex number, the parameter pbPadSerial is passed as a 8-digit hex string, range '0' ... 'FFFFFFFF'. Note that leading zero's are truncated.
    Tablets are delivered with a serial number is set to '0', the application may pass a serial number.
Parameters:
pTablet [i] pointer to an SPTablet object.
pbPadSerial [i] pointer to an array of bytes that contains the tablet serial ID.
iPadSerialLength [i] the size (in bytes) of the tablet serial ID pointed to by pbPadSerial.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletGetPadSerial, SPSignatureSetPadSerial

SPINT32 __cdecl SPTabletSetResolution pSPTABLET_T  pTablet,
SPINT32  iResolution
 

Set the resolution of an SPTablet object.

The resolution is set during initialization and should not be overwritten unless you know what you do.

Tablets have a resolution defined by the physical resolution in the tablet hardware. The SPTablet implementation 'resamples' the vectors and transforms each vector to the given resolution. The absolute position of the pen is calculated by the tablet coordinate * 25.4 / iResolution.

Parameters:
pTablet [i] pointer to an SPTablet object.
iResolution [i] new resolution (in DPI).
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletGetResolution, SPSignatureSetResolution

SPINT32 __cdecl SPTabletSetSampleRate pSPTABLET_T  pTablet,
SPINT32  iSampleRate
 

Set the sample rate of an SPTablet object.

The sample rate is set during initialization and should not be overwritten unless you know what you do.

Note:
Most tablet drivers ignore the sample rate parameter.
Solution: Wait for a driver update that supports sample rate adjustment.
Parameters:
pTablet [i] pointer to an SPTablet object.
iSampleRate [i] the new sample rate (in Hz).
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate, SPTabletGetSampleRate, SPSignatureSetSampleRate

SPINT32 __cdecl SPTabletSetStatusListener pSPTABLET_T  pTablet,
pSPTABLETSTATUS_T  pNotifyStatus
 

Set the hardware status listener of an SPTablet object.

Parameters:
pTablet [i] pointer to an SPTablet object.
pNotifyStatus [i] function that is to be called when a hardware status of the tablet changes. the function pointer may be NULL to deregister all status event listeners.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
pSPTABLETSTATUS_T

SPINT32 __cdecl SPTabletSetTabletOption pSPTABLET_T  pTablet,
const SPCHAR pszName,
SPINT32  iValue
 

Set a tablet parameter.

Options can only be passed to the tablet when the tablet is in state SP_TABLET_STATE_CONNECT.

Parameters:
pTablet [i] pointer to an SPTablet object.
pszName [i] the name / identifier of the option to set, must be one of the following:
  • "BackgroundColor" the background color of the tablet display. The color format is 0xrrggbb where rr equals the red color component, gg equals the green color component and bb equals the blue color component, each component in the range 0 .. 255.
    Currently only supported on Signpad STU-520
  • "ForegroundColor" the foreground color of the tablet display, pen strokes are drawn in foreground color. The color format is 0xrrggbb where rr equals the red color component, gg equals the green color component and bb equals the blue color component, each component in the range 0 .. 255.
    Currently only supported on Signpad STU-520
  • "PenThickness" Pen thickness is used to render strokes on the tablet LCD. The pen thickness has a range 1 .. 255, where 1 produces a thin stroke and 255 produces a bold line. The number of steps is limited by the tablet hardware.
    Currently only supported on Signpad STU-520. STU-520 supports 3 stroke types, thin (1 ... 85), middle (86 ... 170) and bold (171 .. 255).
  • "IdleTimeout" the entered signature will be accepted when iValue [msecs] have passed after the last stroke.
    Currently only supported on Verifone MX 800 series
iValue [i] Value of the addressed option
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)

SPINT32 __cdecl SPTabletSetTabletSize pSPTABLET_T  pTablet,
SPINT32  iWidth,
SPINT32  iHeight
 

Set the tablet size of an SPTablet object.

The tablet size is set during initialization and should not be overwritten unless you know what you do.

Parameters:
pTablet [i] pointer to an SPTablet object.
iWidth [i] new tablet width (in tablet coordinates).
iHeight [i] new tablet height (in tablet coordinates).
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTabletCreate SPTabletGetTabletSize

SPINT32 __cdecl SPTabletSetTicket pSPTABLET_T  pTablet,
pSPTICKET_T  pTicket
 

Pass a license ticket for the next signature capture(s).

When using the ticket license model, you must pass the ticket before you connect with the tablet. This function copies the SPTicket object.

The ticket must be charged for usage SP_TICKET_CAPTURE.

Deprecated:
Please use a license key.
Parameters:
pTablet [i] pointer to an SPTablet object.
pTicket [i] pointer to a charged SPTicket object.
Returns:
SP_NOERR on success, else error code
Deprecated:
Replaced by SPSignwareSetTicket.
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPTicketCharge

SPINT32 __cdecl SPTabletSetUserLong pSPTABLET_T  pTablet,
SPVPTR  lUserLong
 

Set the optional user parameter of an SPTablet object.

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

Parameters:
pTablet [i] pointer to an SPTablet object.
lUserLong [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:
SPTabletCreate, SPTabletGetUserLong

SPINT32 __cdecl SPTabletSwitchSerialType pSPTABLET_T  pTablet,
SPINT32  iSerialType
 

Chooses a different type of serial ID to be returned by SPTabletGetSerial.

Parameters:
pTablet [i] pointer to an SPTablet object.
iSerialType [i] SP_TABLET_SERIAL_TYPE_DEFAULT: custom settable device ID if available, the factory set ID otherwise. SP_TABLET_SERIAL_TYPE_CUSTOM: use custom settable device ID. SP_TABLET_SERIAL_TYPE_FACTORY: use factory set device ID.
Returns:
SP_NOERR on success