Skip to main content

Using the SignatureCapture Interface

This guide explains how to implement signature capture using the SignatureCapture interface, introduced alongside version 4.10 of the Wacom Ink SDK for signature for Windows. It should be read alongside the 4.10 COM API Updates reference, which documents every interface and member used below.

Initialize the SignatureCapture object​

The first step is to create an instance of the SignatureCapture coclass. This object is the foundation for interacting with devices and for managing signature capture windows:

[uuid(20003f57-77ec-4602-9bb8-5851072d706e)]
coclass SignatureCapture
{
    [default] interface ISignatureCapture;
};

Retrieve and monitor the device list​

Next, call ISignatureCapture.GetDeviceList to retrieve an ISignatureDeviceList of the currently connected devices. Register a listener on _ISignatureDeviceListEvents.OnSignatureDeviceListChanged so the application is notified whenever a device is connected or disconnected:

[DISPINTERFACE_ATTRIBUTES(2000fc61-db99-4558-b8ee-325984a909e5)]
dispinterface _ISignatureDeviceListEvents
{
    properties:
    methods:
        [id(DispId_SignatureDeviceListEvents_OnSignatureDeviceListChanged)] HRESULT OnSignatureDeviceListChanged();
};

This ensures the application always has an up-to-date view of the devices available for signature capture.

Device selection behavior​

The SDK follows a consistent set of rules when choosing which device is used for capture:

  • If exactly one licensed device is connected and none has been explicitly selected, that device is used automatically.
  • If two or more devices are connected, a device must be explicitly selected - via the Device parameter of CreateCaptureWindow - before any signature functionality can be used.
  • Only a licensed device can be selected. Attempting to use an unlicensed device returns an error.
  • If a connected device is replaced with another unit of the same model, the SDK identifies it as a different device by its unique ID. The new device must be selected again before signature capture can continue.

Set the license​

Ensure the application is properly licensed by configuring the appropriate license key. The license object is retrieved from ISignatureCapture.License:

[propget, id(DispId_SignatureCapture_License)]
HRESULT License([out, retval] ILicense** pVal);

Query device information​

Once the device list has been retrieved, query each ISignatureDevice in the ISignatureDeviceList for its Name, Type and LicenceStatus. This information helps the application choose the appropriate device for signature capture; see ISignatureDevice for the full property reference.

Create the capture window​

Once the desired device has been identified, create the capture window by passing it to ISignatureCapture.CreateCaptureWindow:

[id(DispId_SignatureCapture_CreateCaptureWindow)]
HRESULT CreateCaptureWindow([in] ISignatureDevice* Device, [in] BSTR Who, [in] BSTR Why,
    [in] IHash* What, [out] enum CaptureResult* Result, [out] BSTR* ErrorDescription,
    [out, retval] ICaptureWindow** retVal);

This returns an ICaptureWindow for the selected device.

Manage the CaptureWindow object​

The capture process is driven by the resulting CaptureWindow object, which represents the on-screen capture window. Register for its events on _ICaptureWindowEvents to track the capture lifecycle:

  • OnSignatureStarted - indicates the beginning of the signature process.
  • OnButtonClick - detects button interactions.
  • OnClose - signals the closure of the capture window.

Handle capture completion​

After OnClose fires, and if the capture was successful, call ICaptureWindow.GetSignature to retrieve the captured signature:

[id(DispId_CaptureWindow_GetSignature)]
HRESULT GetSignature([in] enum SignatureStorageType storageType,
    [in, defaultvalue(EncryptionType_None)] enum EncryptionType encryptionType,
    [in, optional] VARIANT encryptionKey, [out, retval] VARIANT* retVal);

This makes the signature available for storage or further processing in the application.

Troubleshooting and debugging​

If issues are encountered while implementing the SignatureCapture interface, enable logging by setting the following registry key:

[HKEY_CURRENT_USER\Software\Wacom\SignatureCapture]
"Logging"=dword:ffffffff
"ServerConsole"=dword:00000001

Once this is set, run the application. On interacting with the SDK, a console opens showing the relevant logs.

If further assistance is needed:

  • Copy and save the contents of the log file.
  • Describe in detail the steps taken to reach the issue and how to reproduce it.
  • Send this information, with the log file attached, in a support ticket on the Developer Support site.