visit Kofax web site

SPBackgroundObjects.h File Reference


Detailed Description

SignWare Dynamic Development toolkit, background descriptor container.

Author:
uko
SPBackgroundObjects is a container of tablet background descriptors for multiple tablets, which are read from a xml string / file

SPBackgroundObjects hold background descriptors for different tablets, the methods SPAcquireSetBackgroundObjects and SPGuiAcquSetBackgroundObjects will select and copy the descriptor that matches the active tablet.
The matching algorithm differs between tablets with (external) LCD and tablets without LCD:

The tabletname is resolved from the tablet object, see SPTabletGetDeviceStr. The descriptorname is resolved from Attribute Device in the element SPSWDevice.

Please see SPSignware XML Document Type Description for a full description of all background elements

Example: typical BackgroundObjects-File

<?xml version="1.0" encoding="UTF-8"?>
<SPSWDeviceFields>
  <!-- Description for Wacom Signpad STU-520 -->
  <SPSWDevice Device="Wacom SIGNPAD_800x480">
    <SPSWObjects>

      <!-- text line: sign here -->
      <SPSWTextFields>
        <SPSWText ALignment="0" DrawFlags="3" Group="TGN" Format="2" Caption="Sign here" Foreground="0x800000">
            <SPSWCoordinate Origin="Tablet" Left="150" Right="300" Top="780" Bottom="860"/>
            <SPSWFont Face="Helvetica" Size="0" Flags="1"/>
        </SPSWText>
      </SPSWTextFields>
    
      <!-- pass the background image -->
      <SPSWImageFields>
        <SPSWImage DrawFlags="3" Format="1"> eink_800x480.bmp
          <SPSWCoordinate Origin="tablet" Left="0" Top="0" Right="1000" Bottom="1000" />
        </SPSWImage>
      </SPSWImageFields>
    
      <!-- Overwrite OK button -->
      <SPSWVirtualButtonFields>
        <SPSWVirtualButton DrawFlags="3" Background="0xff00" id="1">
          <SPSWCoordinate Origin="tablet" Left="25" Top="900" Right="325" Bottom="980" />
            <SPSWText Caption="OK" DrawFlags="3" Group="ButtonGroup">
            <SPSWFont Face="Helvetica" Size="0" />
          </SPSWText>
        </SPSWVirtualButton>
    
        <!-- Overwrite Erase button -->
        <SPSWVirtualButton DrawFlags="3" Background="0x808080" id="2">
          <SPSWCoordinate Origin="tablet" Left="350" Top="900" Right="650" Bottom="980" />
            <SPSWText Caption="Erase" DrawFlags="3" Group="ButtonGroup">
            <SPSWFont Face="Helvetica" Size="0" />
          </SPSWText>
        </SPSWVirtualButton>
    
        <!-- Overwrite Cancel button -->
        <SPSWVirtualButton DrawFlags="3" Background="0xff0000" id="3">
          <SPSWCoordinate Origin="tablet" Left="675" Top="900" Right="975" Bottom="980" />
            <SPSWText Caption="Cancel" DrawFlags="3" Group="ButtonGroup">
            <SPSWFont Face="Helvetica" Size="0" />
          </SPSWText>
        </SPSWVirtualButton>
      </SPSWVirtualButtonFields>
    
      <!-- Tablet options, STU-520 supports penwidth -->
      <SPSWTabletOption Screen="off" Tablet="on" Image="optimized" PenWidth="170">
        <SPSWCoordinate origin="Tablet" left="0" right="1000" top="0" bottom="890" />
      </SPSWTabletOption>
    </SPSWObjects>
  </SPSWDevice>

  <!-- Description for Wacom Signpad STU-500 -->
  <SPSWDevice Device="Wacom SIGNPAD_640x480">
    <SPSWObjects>

        <!-- Text line: sign here -->
      <SPSWTextFields>
        <SPSWText ALignment="0" DrawFlags="3" Group="TGN" Format="2" Caption="Sign here" >
            <SPSWCoordinate Origin="Tablet" Left="150" Right="300" Top="780" Bottom="860"/>
            <SPSWFont Face="Helvetica" Size="0" Flags="1"/>
        </SPSWText>
      </SPSWTextFields>

      <!-- pass the background image -->
      <SPSWImageFields>
        <SPSWImage DrawFlags="3" Format="1"> eink_640x480.bmp
          <SPSWCoordinate Origin="tablet" Left="0" Top="0" Right="1000" Bottom="1000" />
        </SPSWImage>
      </SPSWImageFields>

      <!-- Overwrite OK button -->
      <SPSWVirtualButtonFields>
        <SPSWVirtualButton DrawFlags="3" id="1">
          <SPSWCoordinate Origin="tablet" Left="25" Top="900" Right="325" Bottom="980" />
            <SPSWText Caption="OK" DrawFlags="3" Group="ButtonGroup">
            <SPSWFont Face="Helvetica" Size="0" />
          </SPSWText>
        </SPSWVirtualButton>

        <!-- Overwrite Erase button -->
        <SPSWVirtualButton DrawFlags="3" id="2">
          <SPSWCoordinate Origin="tablet" Left="350" Top="900" Right="650" Bottom="980" />
            <SPSWText Caption="Erase" DrawFlags="3" Group="ButtonGroup">
            <SPSWFont Face="Helvetica" Size="0" />
          </SPSWText>
        </SPSWVirtualButton>

        <!-- Overwrite Cancel button -->
        <SPSWVirtualButton DrawFlags="3" id="3">
          <SPSWCoordinate Origin="tablet" Left="675" Top="900" Right="975" Bottom="980" />
            <SPSWText Caption="Cancel" DrawFlags="3" Group="ButtonGroup">
            <SPSWFont Face="Helvetica" Size="0" />
          </SPSWText>
        </SPSWVirtualButton>
      </SPSWVirtualButtonFields>

    </SPSWObjects>
  </SPSWDevice>
</SPSWDeviceFields>


Functions

SPINT32 __cdecl SPBackgroundObjectsCreateFromFile (pSPBACKGROUNDOBJECTS_T *ppBackgroundObjects, const SPCHAR *pszFile, const SPCHAR *pszLanguage)
 Create a background descriptor container from a file.
SPINT32 __cdecl SPBackgroundObjectsCreateFromXML (pSPBACKGROUNDOBJECTS_T *ppBackgroundObjects, const SPCHAR *pszXML)
 Create a background descriptor container from a xml-string.
SPINT32 __cdecl SPBackgroundObjectsFree (pSPBACKGROUNDOBJECTS_T *ppBackgroundObjects)
 Free the resources used by the container.


Function Documentation

SPINT32 __cdecl SPBackgroundObjectsCreateFromFile pSPBACKGROUNDOBJECTS_T ppBackgroundObjects,
const SPCHAR pszFile,
const SPCHAR pszLanguage
 

Create a background descriptor container from a file.

Note:
The file must contain a valid xml description for the tablet background, the root element must be SPSWDeviceFields, see SPSignware XML Document Type Description
The filename will be composed of pszFile + _ + pszLanguage if parameter pszLanguage contains a valid language specifier. If the language file is not found then the file pszFile will be read.
Example:
     pSPBACKGROUNDOBJECTS_T pBackgroundObjects = 0;
     SPBackgroundObjectsCreateFromFile(&pBackgroundObjects, "SignwareBackground.xml", "de");
will locate SignwareBackground_de.xml in all locations, and read the first file found. If no file is found then it will locate the file SignwareBackground.xml and return an error if the file is not found, else read the file found.
Parameters:
ppBackgroundObjects [io] pointer to a variable that will be filled with an instance of the container
pszFile [i] name of the file to read. If the filename is a fully qualified path then this path will be read. Else under Windows the file will be located in:
  • %USERPROFILE%\SOFTPRO
  • %USERPROFILE%
  • %HOMEPATH%\SOFTPRO
  • %HOMEPATH%
  • %ALLUSERSPROFILE%\SOFTPRO
  • %ALLUSERSPROFILE%
  • %APPDATA%\SOFTPRO
  • %APPDATA%
  • %PATH%
  • SystemDirectory, only Windows
  • WindowsDirectory, only Windows
pszLanguage [i] language specifier, two char language code, may be NULL
Returns:
SP_NOERR on success, else error code:
  • SP_PARAMERR invalid parameter
  • SP_OPENERR the file is not accessible or does not exist
  • SP_FILEERR the file cannot be read
  • SP_MEMERR out of memory
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPBackgroundObjectsFree, SPAcquireSetBackgroundDescriptor, SPGuiAcquSetBackgroundDescriptor

SPINT32 __cdecl SPBackgroundObjectsCreateFromXML pSPBACKGROUNDOBJECTS_T ppBackgroundObjects,
const SPCHAR pszXML
 

Create a background descriptor container from a xml-string.

Note:
the XML string must contain a valid xml description for the tablet background, the root element must be SPSWDeviceFields, see SPSignware XML Document Type Description
Parameters:
ppBackgroundObjects [io] pointer to a variable that will be filled with an instance of the container
pszXML [i] the xml string
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64), Linux (ARM)
See also:
SPBackgroundObjectsFree, SPAcquireSetBackgroundDescriptor, SPGuiAcquSetBackgroundDescriptor

SPINT32 __cdecl SPBackgroundObjectsFree pSPBACKGROUNDOBJECTS_T ppBackgroundObjects  ) 
 

Free the resources used by the container.