visit Kofax web site
ACTIVESWLib::ISPAcquire

ACTIVESWLib::ISPAcquire Interface Reference

Detailed Description

SignWare Dynamic Development toolkit, ActiveX wrapper for SPAcquireInterface ISPAcquire.

Capture one or more signatures from a Tablet. SPAcquire objects captures a signature or reference without GUI.

Note:
Registered event listeners persistence is bound to the lifetime of the ISPAcquire object, independent of the native object.
Signware also includes an object to capture signatures / references with native GUI ISPGuiAcqu, please read the section comparison of SPAcquire and SPGuiAcqu.


Public Member Functions

HRESULT Acquire ([out, retval] long *result)
 start tablet acquiry mode
HRESULT AcquireDone ([in] long iResult,[out, retval] long *result)
 terminate tablet acquiry mode
HRESULT AcquireWait ([out, retval] long *result)
 Wait until tablet acquiry mode is terminated.
HRESULT AddBackgroundDocument ([in] BSTR description,[out, retval] long *result)
 Add a background document.
HRESULT AddBackgroundDocumentFlatFile ([in] ISPFlatFile *description,[out, retval] long *result)
 Add a background document.
HRESULT AddBackgroundImage ([in] BSTR description,[out, retval] long *result)
 Add a background image.
HRESULT AddBackgroundImageFlatFile ([in] ISPFlatFile *description,[out, retval] long *result)
 Add a background image.
HRESULT AddBackgroundObject ([in] BSTR description,[out, retval] long *result)
 Add images, (visible) rect and text field(s) that will be displayed in the background image.
HRESULT AddBackgroundObjectFlatFile ([in] ISPFlatFile *description,[out, retval] long *result)
 Add images, (visible) rect and text field(s) that will be displayed in the background image.
HRESULT AddBackgroundText ([in] BSTR description,[out, retval] long *result)
 Add a text field that will be displayed in the background image.
HRESULT AddBackgroundTextFlatFile ([in] ISPFlatFile *description,[out, retval] long *result)
 Add a text field that will be displayed in the background image.
HRESULT ClearEntries ([in] long iFlags,[out, retval] long *result)
 Clear all previously acquired input.
HRESULT Connect ([in] long iDriver,[out, retval] long *result)
 connect to a tablet specified by iDriver
HRESULT ConnectByAlias ([in] BSTR bstrTabletAlias,[out, retval] long *result)
 connect to a tablet by an Alias
HRESULT ConnectByEnum ([in] ISPPropertyMap *spDescriptor,[out, retval] long *result)
 connect to a tablet by an enumeration
HRESULT ConnectEx ([in] BSTR bstrTabletClass,[in] BSTR bstrConfig,[out, retval] long *result)
 connect to a tablet specified by iDriver
HRESULT CreateAcquire ([in] long lFlags,[out, retval] long *result)
 Create the native SPAcquire object.
HRESULT CreateTablet ([in] long iDriver,[out, retval] long *result)
 Create a tablet driver object.
HRESULT CreateTabletByAlias ([in] BSTR bstrTabletAlias,[out, retval] long *result)
 create a tablet by an Alias
HRESULT CreateTabletByEnum ([in] ISPPropertyMap *spDescriptor,[out, retval] long *result)
 create a tablet by an enumeration
HRESULT CreateTabletEx ([in] BSTR bstrTabletClass,[in] BSTR bstrConfig,[out, retval] long *result)
 Create a tablet driver object.
HRESULT Disconnect ([out, retval] long *result)
 disconnect from a tablet
HRESULT GetBackgroundImage ([in] long iSource,[out] ISPImage **ppImage,[out, retval] long *result)
 Query the background image as it is displayed on the tablet or the PC screen.
HRESULT GetBackgroundText ([in] long iSource,[out] BSTR *pbstrText,[out, retval] long *result)
 Query the background text as it is displayed on the tablet or the PC screen.
HRESULT GetBoolProperty ([in] BSTR bstrName,[out] long *piValue,[out, retval] long *result)
 Query a property.
HRESULT GetDrawMode ([out] long *piMode,[out, retval] long *result)
 Get the draw mode in the SPAcquire object [in screen pixel].
HRESULT GetHwnd ([out] __int64 *pHwnd,[out, retval] long *result)
 get the window handle of the non visible, message only window associated with the SPAcquire object
HRESULT GetHwnd32 ([out] __int32 *pHwnd,[out, retval] long *result)
 get the window handle of the non visible, message only window associated with the SPAcquire object.
HRESULT GetIntProperty ([in] BSTR bstrName,[out] long *piValue,[out, retval] long *result)
 Query a property.
HRESULT GetReference ([out] ISPReference **ppReference,[out, retval] long *result)
 Query the reference after a signature or reference signature acquiry.
HRESULT GetSignature ([out] ISPSignature **ppSignature,[out, retval] long *result)
 Query the signature during acquiry mode.
HRESULT GetTablet ([out] ISPTablet **ppTablet,[out, retval] long *result)
 get the associated tablet data structure
HRESULT RegisterDocumentRect ([in] long aId,[in] BSTR strVirtualButtonDescription,[out, retval] long *result)
 Register a virtual button in a document.
HRESULT RegisterRect2 ([in, out] long *id,[in] BSTR description,[out, retval] long *result)
 register a virtual button in acquiry mode
HRESULT RegisterRect2FlatFile ([in, out] long *id,[in] ISPFlatFile *description,[out, retval] long *result)
 register a virtual button in acquiry mode
HRESULT RemoveBackgroundObjects ([out, retval] long *result)
 Remove all images, (visible) rect and text field(s) from the background image.
HRESULT SetActive ([in] long bActive,[out, retval] long *result)
 Activate / deactivate acquiory mode.
HRESULT SetBackgroundImage ([in] SAFEARRAY(BYTE)*pszImage,[out, retval] long *result)
 Pass a background image.
HRESULT SetBackgroundObjects ([in] ISPBackgroundObjects *pspBackgroundObjects,[out, retval] long *result)
 Set the background object for the current tablet.
HRESULT SetBoolProperty ([in] BSTR bstrName,[in] long iValue,[out, retval] long *result)
 Set a property.
HRESULT SetDocumentContent ([in] long aId,[in] SAFEARRAY(BYTE)*pContent,[in] long aFormat,[out, retval] long *result)
 Set the content of a document.
HRESULT SetDocumentContentFile ([in] long aId,[in] BSTR strFile,[in] long aFormat,[out, retval] long *result)
 Set the content of a document.
HRESULT SetDocumentContentFlatFile ([in] long aId,[in] ISPFlatFile *pContent,[in] long aFormat,[out, retval] long *result)
 Set the content of a document.
HRESULT SetDrawMode ([in] long iDrawMode,[out, retval] long *result)
 Set the draw mode of a SPAcquire object.
HRESULT SetIntProperty ([in] BSTR bstrName,[in] long iValue,[out, retval] long *result)
 Set a property.
HRESULT SetTimeout ([in] long iTimeout,[out, retval] long *result)
 Set the timeout of an acquiry in a SPAcquire object.
HRESULT UnregisterAllRects ([out, retval] long *result)
 unregister all rectangles in acquiry mode
HRESULT UnregisterRect ([in] long id,[out, retval] long *result)
 unregister a rectangle in acquiry mode

Member Function Documentation

HRESULT ACTIVESWLib::ISPAcquire::Acquire (  [out, retval] long *  result  ) 
 

start tablet acquiry mode

Parameters:
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAcquire, AcquireDone, AcquireWait
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 the tablet object, the state will be SP_TABLET_STATE_ACQUIRE on success

CreateTablet, Connect, Disconnect, Acquire, AcquireDone and AcquireWait must all be called from one thread

HRESULT ACTIVESWLib::ISPAcquire::AcquireDone (  [in] long  iResult,
[out, retval] long *  result
) 
 

terminate tablet acquiry mode

Parameters:
iResult [i] Command, SPAcquireDone, either SPAcquireDone::SPX_IDOK (add signature to reference), or SPAcquireDone::SPX_IDCANCEL (ignore signature)
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
Acquire, AcquireWait, SPAcquireAcquireDone, SPAcquireDone
Note:
CreateTablet, Connect, Disconnect, Acquire, AcquireDone and AcquireWait must all be called from one thread

HRESULT ACTIVESWLib::ISPAcquire::AcquireWait (  [out, retval] long *  result  ) 
 

Wait until tablet acquiry mode is terminated.

This function waits until AcquireDone is called in acquiry mode.

Applications that do not proccess a message loop, or application that create the SPAcquire Object in a separate thread should call AcquireWait to dispatch the messages for this object.

Parameters:
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAcquireWait, AcquireDone, Acquire
Note:
CreateTablet, Connect, Disconnect, Acquire, AcquireDone and AcquireWait must all be called from one thread

HRESULT ACTIVESWLib::ISPAcquire::AddBackgroundDocument (  [in] BSTR  description,
[out, retval] long *  result
) 
 

Add a background document.

Parameters:
description [i] XML description of the document, supported encodings in the XML declaration is UTF-8, sec_XML_Data, sec_DocumentDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAddBackgroundDocument

HRESULT ACTIVESWLib::ISPAcquire::AddBackgroundDocumentFlatFile (  [in] ISPFlatFile *  description,
[out, retval] long *  result
) 
 

Add a background document.

Parameters:
description [i] XML description of the document embedded in a FlatFile, supported encodings in the XML declaration are ASCII, UTF-8 and ISO-8859-1, sec_XML_Data, sec_DocumentDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAddBackgroundDocument

HRESULT ACTIVESWLib::ISPAcquire::AddBackgroundImage (  [in] BSTR  description,
[out, retval] long *  result
) 
 

Add a background image.

Parameters:
description [i] XML description of the Image, supported encodings in the XML declaration is UTF-8, sec_XML_Data, sec_ImageDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAddBackgroundImage

HRESULT ACTIVESWLib::ISPAcquire::AddBackgroundImageFlatFile (  [in] ISPFlatFile *  description,
[out, retval] long *  result
) 
 

Add a background image.

/**

Parameters:
description [i] XML description of the Image embedded in a FlatFile, supported encodings in the XML declaration are ASCII, UTF-8 and ISO-8859-1, sec_XML_Data, sec_ImageDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAddBackgroundImage

HRESULT ACTIVESWLib::ISPAcquire::AddBackgroundObject (  [in] BSTR  description,
[out, retval] long *  result
) 
 

Add images, (visible) rect and text field(s) that will be displayed in the background image.

Parameters:
description [i] XML description of the object, supported encodings in the XML declaration is UTF-8, sec_XML_Data, sec_ObjectDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAddBackgroundObject

HRESULT ACTIVESWLib::ISPAcquire::AddBackgroundObjectFlatFile (  [in] ISPFlatFile *  description,
[out, retval] long *  result
) 
 

Add images, (visible) rect and text field(s) that will be displayed in the background image.

Parameters:
description [i] XML description of the object embedded in a FlatFile, supported encodings in the XML declaration are ASCII, UTF-8 and ISO-8859-1, sec_XML_Data, sec_ObjectDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAddBackgroundObject

HRESULT ACTIVESWLib::ISPAcquire::AddBackgroundText (  [in] BSTR  description,
[out, retval] long *  result
) 
 

Add a text field that will be displayed in the background image.

Parameters:
description [i] XML description of the text, supported encodings in the XML declaration is UTF-8, sec_XML_Data, sec_TextDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAddBackgroundText

HRESULT ACTIVESWLib::ISPAcquire::AddBackgroundTextFlatFile (  [in] ISPFlatFile *  description,
[out, retval] long *  result
) 
 

Add a text field that will be displayed in the background image.

Parameters:
description [i] XML description of the text embedded in a FlatFile, supported encodings in the XML declaration are ASCII, UTF-8 and ISO-8859-1, sec_XML_Data, sec_TextDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireAddBackgroundText

HRESULT ACTIVESWLib::ISPAcquire::ClearEntries (  [in] long  iFlags,
[out, retval] long *  result
) 
 

Clear all previously acquired input.

Parameters:
iFlags [i] reserved parameter, should be set to 0
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
Acquire, AcquireDone, SPAcquireClearEntries

HRESULT ACTIVESWLib::ISPAcquire::Connect (  [in] long  iDriver,
[out, retval] long *  result
) 
 

connect to a tablet specified by iDriver

Please read Tablet creation options

Parameters:
iDriver [i] Driver number, pass SP_UNKNOWN_DRV to use any driver
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireConnect, Disconnect, CreateTablet, ConnectEx
Note:
CreateTablet, Connect, Disconnect, Acquire, AcquireDone and AcquireWait must all be called from one thread

HRESULT ACTIVESWLib::ISPAcquire::ConnectByAlias (  [in] BSTR  bstrTabletAlias,
[out, retval] long *  result
) 
 

connect to a tablet by an Alias

Please read Tablet creation options for resolving the alias

Parameters:
bstrTabletAlias [i] alias name of the desired tablet
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireConnectEx, Disconnect

CreateTabletEx

HRESULT ACTIVESWLib::ISPAcquire::ConnectByEnum (  [in] ISPPropertyMap *  spDescriptor,
[out, retval] long *  result
) 
 

connect to a tablet by an enumeration

Please read Tablet creation options for enumerating tablets

Note:
This function connects with the default tablet if spDescriptor is NULL.
Parameters:
spDescriptor [i] descriptor of the desired tablet
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireConnectByEnum, Disconnect

CreateTabletByEnum

HRESULT ACTIVESWLib::ISPAcquire::ConnectEx (  [in] BSTR  bstrTabletClass,
[in] BSTR  bstrConfig,
[out, retval] long *  result
) 
 

connect to a tablet specified by iDriver

Please read Tablet creation options for a list of supported options

Parameters:
bstrTabletClass [i] class name of Kofax tablet access module.
bstrConfig [i] pass optional configuration data. Configuration data depends on the detected hardware driver, see Installation and configuration of various pads
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireConnectEx, Disconnect

CreateTabletEx

HRESULT ACTIVESWLib::ISPAcquire::CreateAcquire (  [in] long  lFlags,
[out, retval] long *  result
) 
 

Create the native SPAcquire object.

Parameters:
lFlags [i] Flags, must be SP_GAWW_EVENTS.
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
The default draw Mode is set to SP_VIRTUAL_BUTTON_CLICK
See also:
SPAcquireCreate, SetDrawMode, SP_VIRTUAL_BUTTON_CLICK

HRESULT ACTIVESWLib::ISPAcquire::CreateTablet (  [in] long  iDriver,
[out, retval] long *  result
) 
 

Create a tablet driver object.

Please read Tablet creation options

Parameters:
iDriver [i] Driver number, pass SP_UNKNOWN_DRV to use any driver Pass 0 to use any driver.
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireCreateTablet, Connect, ConnectEx, CreateTabletEx
Note:
CreateTablet, Connect, Disconnect, Acquire and AcquireDone must all be called from the event dispatch thread

HRESULT ACTIVESWLib::ISPAcquire::CreateTabletByAlias (  [in] BSTR  bstrTabletAlias,
[out, retval] long *  result
) 
 

create a tablet by an Alias

Please read Tablet creation options for resolving the alias

Parameters:
bstrTabletAlias [i] alias name of the desired tablet
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireConnectEx, Disconnect

CreateTabletEx

HRESULT ACTIVESWLib::ISPAcquire::CreateTabletByEnum (  [in] ISPPropertyMap *  spDescriptor,
[out, retval] long *  result
) 
 

create a tablet by an enumeration

Please read Tablet creation options for enumerating tablets

Note:
This function creates a default tablet if spDescriptor is NULL.
Parameters:
spDescriptor [i] descriptor of the desired tablet
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireCreateTabletByEnum, Disconnect

ConnectByEnum

HRESULT ACTIVESWLib::ISPAcquire::CreateTabletEx (  [in] BSTR  bstrTabletClass,
[in] BSTR  bstrConfig,
[out, retval] long *  result
) 
 

Create a tablet driver object.

Please read Tablet creation options for a list of supported options

Parameters:
bstrTabletClass [i] class name of Kofax tablet access module.
bstrConfig [i] pass optional configuration data. Configuration data depends on the detected hardware driver, see Installation and configuration of various pads
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireCreateTabletEx

ConnectEx, Connect, CreateTablet

HRESULT ACTIVESWLib::ISPAcquire::Disconnect (  [out, retval] long *  result  ) 
 

disconnect from a tablet

Parameters:
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
Connect, SPAcquireDisconnect
Note:
CreateTablet, Connect, Disconnect, Acquire, AcquireDone and AcquireWait must all be called from one thread

HRESULT ACTIVESWLib::ISPAcquire::GetBackgroundImage (  [in] long  iSource,
[out] ISPImage **  ppImage,
[out, retval] long *  result
) 
 

Query the background image as it is displayed on the tablet or the PC screen.

Parameters:
iSource [i] select the source of the image
  • 1 PC screen
  • 2 Tablet LCD
ppImage [o] pointer to a ISPImage object pointer that will be filled with the resulting image
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
The image will NOT contain any partial or fully entered signature strokes.

HRESULT ACTIVESWLib::ISPAcquire::GetBackgroundText (  [in] long  iSource,
[out] BSTR *  pbstrText,
[out, retval] long *  result
) 
 

Query the background text as it is displayed on the tablet or the PC screen.

Parameters:
iSource [i] select the source of the text
  • 1 PC screen
  • 2 Tablet LCD
pbstrText [o] pointer to a BSTR that will be filled with the resulting text
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
The image will NOT contain any partial or fully entered signature strokes.

HRESULT ACTIVESWLib::ISPAcquire::GetBoolProperty (  [in] BSTR  bstrName,
[out] long *  piValue,
[out, retval] long *  result
) 
 

Query a property.

Parameters:
bstrName [i] Name of the property, see SPAcquire Properties
piValue [i] pointer to avariable that will be filled with the value of the property
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result

HRESULT ACTIVESWLib::ISPAcquire::GetDrawMode (  [out] long *  piMode,
[out, retval] long *  result
) 
 

Get the draw mode in the SPAcquire object [in screen pixel].

Parameters:
piMode [o] a pointer to a SPINT32, that will be filled with the draw mode
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
Default Border is 5 pixel
See also:
SetDrawMode, SPAcquireGetDrawMode

HRESULT ACTIVESWLib::ISPAcquire::GetHwnd (  [out] __int64 *  pHwnd,
[out, retval] long *  result
) 
 

get the window handle of the non visible, message only window associated with the SPAcquire object

Parameters:
pHwnd [o] a pointer to a window handle, that will be filled with the window handle of the associated SPGui object
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireGetHwnd

HRESULT ACTIVESWLib::ISPAcquire::GetHwnd32 (  [out] __int32 *  pHwnd,
[out, retval] long *  result
) 
 

get the window handle of the non visible, message only window associated with the SPAcquire object.

Note:
This method is exclusively for 32-bit applications, it will return an error (SPX_PARAMERR) in a 64-bit process
Parameters:
pHwnd [o] a pointer to a window handle, that will be filled with the window handle of the associated SPGui object
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireGetHwnd

HRESULT ACTIVESWLib::ISPAcquire::GetIntProperty (  [in] BSTR  bstrName,
[out] long *  piValue,
[out, retval] long *  result
) 
 

Query a property.

Parameters:
bstrName [i] Name of the property, see SPAcquire Properties
piValue [i] pointer to avariable that will be filled with the value of the property
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result

HRESULT ACTIVESWLib::ISPAcquire::GetReference (  [out] ISPReference **  ppReference,
[out, retval] long *  result
) 
 

Query the reference after a signature or reference signature acquiry.

Parameters:
ppReference [o] a pointer to a ISPReference object that will be filled with the reference
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
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 ISPReference.CreateFromAcquire

HRESULT ACTIVESWLib::ISPAcquire::GetSignature (  [out] ISPSignature **  ppSignature,
[out, retval] long *  result
) 
 

Query the signature during acquiry mode.

Parameters:
ppSignature [o] a pointer to a ISPSignature object that will be filled with the signature
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
The returned signature must not contain all captured vectors. This function is provided to check for empty signatures BEFORE accepting the signature (see SPAcquireAcquireDone).

No signature object will be returned when not in acquiry mode.

this is a convenience function which behaves exactly like ISPSignature.CreateFromAcquire

HRESULT ACTIVESWLib::ISPAcquire::GetTablet (  [out] ISPTablet **  ppTablet,
[out, retval] long *  result
) 
 

get the associated tablet data structure

Parameters:
ppTablet [o] address of a variable that will receive the pSPTABLET_T data structure.
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
SPX_PARAMERR will be returned, if the tablet has not yet been created.
See also:
SPAcquireGetTablet

HRESULT ACTIVESWLib::ISPAcquire::RegisterDocumentRect (  [in] long  aId,
[in] BSTR  strVirtualButtonDescription,
[out, retval] long *  result
) 
 

Register a virtual button in a document.

Note:
The virtual button description includes an id which may not be 0. The button id should be a unique id for each button. Subsequent registrations of virtual buttons with the same id will modify the already registered virtual button, e. g. set an icon, or move the button.
Parameters:
aId [i] unique identifyer of the document
strVirtualButtonDescription [i] description of the rectangle position, size, text, font etc. Please see element SPSWVirtualButton in sec_VirtualButtonDescriptionDTD for details
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SetDocumentContent, SetDocumentContentFile, SPAcquireRegisterDocumentRect

HRESULT ACTIVESWLib::ISPAcquire::RegisterRect2 (  [in, out] long *  id,
[in] BSTR  description,
[out, retval] long *  result
) 
 

register a virtual button in acquiry mode

Parameters:
id [io] the id of the virtual button to be registered or updated.
The variable will be filled with the created ID.
  • If the content of id is 0 then a new virtual button will be created. id will reflect the actual Id that was assigned to the button.
  • If the content of id is not 0 and a virtual button with the same Id is already registered then the existing virtual button will be updated with the passed descriptor
  • If the content of id is not 0 and a virtual button with the same Id is not yet registered then a new virtual button will be created. The content of id will be used as the Id for the new virtual button.
description [i] XML description of the rectangle, supported encodings in the XML declaration is UTF-8, sec_XML_Data, sec_VirtualButtonDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
SPTablet switches the tablet from pointer mode to pen entry mode during acquiry. A registered component will be notified in pen entry mode, when the pen is pressed above a rectangle.

Pen entry mode is exclusive and will not send any notifications to any other applications as a pointer movement.

See also:
SPAcquireRegisterRect2, UnregisterRect, UnregisterAllRects

HRESULT ACTIVESWLib::ISPAcquire::RegisterRect2FlatFile (  [in, out] long *  id,
[in] ISPFlatFile *  description,
[out, retval] long *  result
) 
 

register a virtual button in acquiry mode

Parameters:
id [io] the id of the virtual button to be registered or updated.
The variable will be filled with the created ID.
  • If the content of id is 0 then a new virtual button will be created. id will reflect the actual Id that was assigned to the button.
  • If the content of id is not 0 and a virtual button with the same Id is already registered then the existing virtual button will be updated with the passed descriptor
  • If the content of id is not 0 and a virtual button with the same Id is not yet registered then a new virtual button will be created. The content of id will be used as the Id for the new virtual button.
description [i] XML description of the rectangle embedded in a FlatFile, supported encodings in the XML declaration are ASCII, UTF-8 and ISO-8859-1, sec_XML_Data, sec_VirtualButtonDescriptionDTD
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
Note:
SPTablet switches the tablet from pointer mode to pen entry mode during acquiry. A registered component will be notified in pen entry mode, when the pen is pressed above a rectangle.

Pen entry mode is exclusive and will not send any notifications to any other applications as a pointer movement.

See also:
SPAcquireRegisterRect2, UnregisterRect, UnregisterAllRects

HRESULT ACTIVESWLib::ISPAcquire::RemoveBackgroundObjects (  [out, retval] long *  result  ) 
 

Remove all images, (visible) rect and text field(s) from the background image.

Parameters:
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireRemoveBackgroundObjects

HRESULT ACTIVESWLib::ISPAcquire::SetActive (  [in] long  bActive,
[out, retval] long *  result
) 
 

Activate / deactivate acquiory mode.

Parameters:
bActive [i] activate if not equal 0, else deactivate
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireSetActive

HRESULT ACTIVESWLib::ISPAcquire::SetBackgroundImage (  [in] SAFEARRAY(BYTE)*  pszImage,
[out, retval] long *  result
) 
 

Pass a background image.

Parameters:
pszImage,: [i] byte array with one dimension and arbitrary length
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPGuiAcquSetBackgroundImage

HRESULT ACTIVESWLib::ISPAcquire::SetBackgroundObjects (  [in] ISPBackgroundObjects *  pspBackgroundObjects,
[out, retval] long *  result
) 
 

Set the background object for the current tablet.

Parameters:
pspBackgroundObjects [i] valid instance of ISPBackgroundObjects
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireSetBackgroundObjects

HRESULT ACTIVESWLib::ISPAcquire::SetBoolProperty (  [in] BSTR  bstrName,
[in] long  iValue,
[out, retval] long *  result
) 
 

Set a property.

Parameters:
bstrName [i] Name of the property, see SPAcquire Properties
iValue [i] the value of the property
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result

HRESULT ACTIVESWLib::ISPAcquire::SetDocumentContent (  [in] long  aId,
[in] SAFEARRAY(BYTE)*  pContent,
[in] long  aFormat,
[out, retval] long *  result
) 
 

Set the content of a document.

Parameters:
aId [i] unique identifyer of the document
pContent [i] content of the document
aFormat [i] always 2 to specify a data in memory
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireSetDocumentContent

HRESULT ACTIVESWLib::ISPAcquire::SetDocumentContentFile (  [in] long  aId,
[in] BSTR  strFile,
[in] long  aFormat,
[out, retval] long *  result
) 
 

Set the content of a document.

Parameters:
aId [i] unique identifyer of the document
strFile [i] File name of the document
aFormat [i] always 1 to specify a local file
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireSetDocumentContent

HRESULT ACTIVESWLib::ISPAcquire::SetDocumentContentFlatFile (  [in] long  aId,
[in] ISPFlatFile *  pContent,
[in] long  aFormat,
[out, retval] long *  result
) 
 

Set the content of a document.

Parameters:
aId [i] unique identifyer of the document
pContent [i] content of the document embedded in a ISPFlatFile object
aFormat [i] always 2 to specify a data in memory
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireSetDocumentContent

HRESULT ACTIVESWLib::ISPAcquire::SetDrawMode (  [in] long  iDrawMode,
[out, retval] long *  result
) 
 

Set the draw mode of a SPAcquire object.

Parameters:
iDrawMode [i] drawing mode
  • SP_VIRTUAL_BUTTON_MODE don't draw any strokes neither on PC screen nor on tablet LCD screen
  • SP_VIRTUAL_BUTTON_CLICK virtual buttons are clicked when the pen is pressed and released in the virtual button region, else virtual buttons are clicked when the pen is pressed in the virtual button region
  • SP_DRAW_MIRROR_TABLET use the tablet 'upside down' (or rotated by 180 degrees)
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireSetDrawMode, GetDrawMode

HRESULT ACTIVESWLib::ISPAcquire::SetIntProperty (  [in] BSTR  bstrName,
[in] long  iValue,
[out, retval] long *  result
) 
 

Set a property.

Parameters:
bstrName [i] Name of the property, see SPAcquire Properties
iValue [i] the value of the property
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result

HRESULT ACTIVESWLib::ISPAcquire::SetTimeout (  [in] long  iTimeout,
[out, retval] long *  result
) 
 

Set the timeout of an acquiry in a SPAcquire object.

Parameters:
iTimeout [i] timeout [in msec] or 0 to disable timeout checking
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
SPAcquireSetTimeout

HRESULT ACTIVESWLib::ISPAcquire::UnregisterAllRects (  [out, retval] long *  result  ) 
 

unregister all rectangles in acquiry mode

Parameters:
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
Acquire, SPAcquireUnregisterAllRects, UnregisterRect

HRESULT ACTIVESWLib::ISPAcquire::UnregisterRect (  [in] long  id,
[out, retval] long *  result
) 
 

unregister a rectangle in acquiry mode

Parameters:
id [i] identifier for the the rectangle to be unregistered
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
Returns:
automation result
See also:
Acquire, SPAcquireUnregisterRect, UnregisterAllRects, RegisterRect2

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