SPGuiAcqu.h File Reference
Detailed Description
SignWare Dynamic Development toolkit, acquire signatures.
- Author:
- uko
Signware also includes an object to capture signatures / references without native GUI, please read Comparison SPAcquire versus SPGuiAcqu for a comparison of SPAcquire and SPGuiAcqu.
The functions declared in this header are not yet implemented for Linux.
SPGuiAcqu
The SPGuiAcqu object captures one or more signatures from a tablet. It will either create a new window (SPGuiAcquCreate) or use an existing client window (SPGuiAcquCreateInClient) and draw all vectors inside the client window.It supports the Standard window properties and adds capabilities to define special regions. These regions will be interpreted as clickable areas, virtual buttons. When the user clicks these regions then either a window message will be sent to the component or a callback function will be called.
The acquiry object creates a signature and a reference object. The signature object will be filled during acquiry (as long as acquire mode is active). The signature object will be appended to the reference object if SPGuiAcquAcquireDone is called with SP_IDOK. In any case, the signature object will not be accessable after calling SPGuiAcquAcquireDone. The typical usage of the signature object is to check for empty signatures and to deny accepting empty signatures. Always use the created reference object as the result of an acquire operation.
The application must differentiate several types of tablet hardware:
- Standard tablets: these devices have no display, so there is no feedback for users when they hit any special regions or virtual buttons. It is thus not recommended to define virtual buttons on these devices.
- Full-screen tablets: these devices include a screen that typically displays the entire workstation. It is recommended to use buttons on these devices and handle the according button notifications.
TabletPCs are supported by SignWare, SPGuiAcqu subclasses the main application window to detect display changes (either resolution or ratation changes) and handle this event correctly.
The WM_DISPLAYCHANGE event is also passed to the application. - Tablets with integrated screen: these devices integrate a screen that allows for direct feedback of the strokes. These devices also allow for a visual representation of virtual buttons. It is recommended to register virtual buttons on these devices. Set the flag SP_TABLET_COORDINATE to display virtual buttons at the correct position on the screen, else the application must trace position and size of the registered rectangle.
Screen updates on these devices are typically relatively slow, it is not recommended to dynamically update the screen.
The tablet screen is only updated during state transitions from connect state to acquire state, the screen can thus not be updated when acquiry mode is active. - Tablets which cannot send vectors in real time (SPTabletGetTybletType() returns bit SP_TABLET_NO_REALTIME_VECTORS is set): a GUI should not display a OK-button unless the the user can see the tablet contents.
- The application must evaluate hardware buttons for tablets that set the flag SP_TABLET_HARDWARE_AS_VIRTUAL_BUTTONS.
- Buttons with a native window assigned, see SPGuiAcquRegisterComponent
- Virtual buttons, see SPGuiAcquRegisterRect and SPGuiAcquRegisterRect2
- Note:
- Some low-level tablet drivers use window messages to communicate with the application.
- Wintab uses message ID's in the range WM_USER + 0x7BF0 (0x7FF0) through WM_USER + 0xFBFF (0x7FFF),
- Kofax drivers use message ID's in the range WM_USER + 0x7BD0 (0x7FD0) through WM_USER + 0x7BDF (0x7FDF).
- SPGuiAcqu uses message ID's in the range WM_USER + 0x7BB0 (0x7FB0) through WM_USER + 0x7BBF (0x7FBF).
Mobile Devices
Mobile devices such as iPad are becoming popular and many people would like to use a mobile device as an input to enter the signature.A few limitations apply due to technical limitations of these devices:
- the sample rate is too low to evaluate the biometrical identity, captured signatures cannot be compared.
The module TabletServer is currently rated experimental, it is not recommended to access this module at this time.
The module RemoteTablet is currently rated experimental, it is not recommended to access this module at this time.
An application may need to implement some special requirements to support Tablets that communicate through the Kofax TabletServer module, please see SPTabletServer for details.
An application may need to implement some special requirements to support Tablets that communicate through the Kofax RemoteTablet module, please see SPRemoteTablet for details.
Standard window properties
SignWare GUI objects support these properties:- Flags:
- SP_ERASE_BACKGROUND: the signware object will erase the background using the background color whenever the WM_ERASEBKGND message is sent, else the WM_ERASEBKGND message will be dispatched to the parent or standard window procedure.
- SP_DRAW_TABLET_BORDER: draw a rectangle around the active tablet region in black color to display the active tablet size. Without this property, no rectangle is drawn.
- SP_DRAW_HWND_BORDER: draw a border around the size of the window, excluding the borders.
- Borders set the size of a border within the window rectangle.
- Foreground color: the color used for tablet strokes with maximum pressure
- Background color: the color used for tablet strokes with no pressure
Supported properties
The table below lists all supported Properties.
Name | Default | Range | Description |
---|---|---|---|
"BackgroundColor" | 0xFFFFFF | Background color, format 0xrrggbb, rr: red, gg: green, bb: blue | |
"ForegroundColor" | 0x000000 | Foreground color, format 0xrrggbb, rr: red, gg: green, bb: blue | |
"RectangleColor" | 0x000000 | Border color, format 0xrrggbb, rr: red, gg: green, bb: blue | |
"PenThickness" | 127 | 1 ... 255 | Pen thickness, see SPTabletSetTabletOption for details |
"ScrBorder" | 5 | 0 ... 255 | Size of the border in pixel |
"WindowBorder" | false | SPBOOL | Draw a border around the window, see SP_DRAW_HWND_BORDER for details |
"TabletBorder" | false | SPBOOL | Draw a border around the tablet, see SP_DRAW_TABLET_BORDER for details |
"MirrorTablet" | false | SPBOOL | Mirror tablet, see SP_DRAW_MIRROR_TABLET for details |
"NoStrokeEcho" | false | SPBOOL | set stroke echo, see SP_VIRTUAL_BUTTON_MODE for details |
"ButtonClickMode" | true | SPBOOL | set button click mode, see SP_VIRTUAL_BUTTON_CLICK for details |
"ReleaseFokus" | false | SPBOOL | end acquiry when loosing the focus, see SP_RELEASE_FOCUS for details |
"EraseBackground" | false | SPBOOL | erase the background, see SP_ERASE_BACKGROUND for details |
"EmulateCursor" | false | SPBOOL | emulate the cursor, see SP_EMULATE_PEN_CURSOR for details |
"DisableCursor" | false | SPBOOL | disable the cursor, see SP_DISABLE_CURSOR for details |
"DrawBackgroundImage" | false | SPBOOL | display the background image, see SP_DRAW_BACKGROUND_IMAGE for details |
"DrawTabletImage" | false | SPBOOL | display the tablet background image, see SP_DRAW_TABLET_IMAGE_IN_WINDOW for details |
"DrawBuffered" | false | SPBOOL | double buffer the screen image, see SP_DRAW_BUFFERED for details |
Description of parameters passed as XML strings
Virtual Buttons
Several regions on the tablet may be defined as virtual buttons. These regions are passed in a call to either SPGuiAcquRegisterRect or SPGuiAcquRegisterRect2. SPGuiAcquRegisterRect passes all parameters directly, which is a bit simpler to use, but lacks flexibility. SPGuiAcquRegisterRect2 passes an XML string that describes the position, text, font etc. to be displayed within the registered region.A virtual button is defined by element SPSWVirtualButton. It validates to the SPSignware XML Document Type Description.
Please use the XML declaration to specify the character encoding of the XML document. Supported encodings are ASCII, UTF-8, and ISO-8859-1.
Example (C):
void registerButton(pSPGUIACQU_T pSpGA, const char *aText, RECT rcl, int *piId, pSPGUIACQURECTLISTENER_T pRectListener) { int rc; char szXML[8192]; _snprintf (szXML, sizeof(szXML), "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" "<!DOCTYPE SPSWObjects SYSTEM "SPSWObjects.dtd">\n" "<SPSWVirtualButton DrawFlags=\"%d\">\n" " <SPSWCoordinate Origin=\"tablet\" Left=\"%d\" Right=\"%d\" Top=\"%d\" Bottom=\"%d\" />\n" " <SPSWText Caption=\"%s\" DrawFlags=\"%d\">\n" " <SPSWFont Face=\"Arial\" Size=\"12\" />\n" " <SPSWCoordinate Origin=\"tablet\" Left=\"%d\" Right=\"%d\" Top=\"%d\" Bottom=\"%d\" />\n" " </SPSWText>\n" "</SPSWVirtualButton>\n" 3, // DrawFlags rcl.left, rcl.right, rcl.top, rcl.bottom, pszName, // caption text 3, rcl.left, rcl.right, rcl.top, rcl.bottom ); // DrawFlags rc = SPGuiAcquRegisterRect2(pSpGA, piId, szXML, pRectListener); return rc; }
Text fields
It may be required to dynamically draw text on the screen of a tablet. The text is passed in a call to SPGuiAcquAddBackgroundText. This function requires a string that is interpreted according to the SPSignware XML Document Type Description.Please use the XML declaration to specify the character encoding of the XML document. Supported encodings are ASCII, UTF-8, and ISO-8859-1.
A text entry is defined by element SPSWText for a single text field, or element SPSWTextFields to define several text regions in one descriptor.
- Note:
- The element SPSWCoordinate is mandatory in text descriptors (although the DTD marks it optional).
Example (C):
void addBackroundText(pSPGUIACQU_T pSpGA, const char *aText, RECT rcl) { char szXML[8192]; int rc; _snprintf (szXML, sizeof(szXML), "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" "<!DOCTYPE SPSWObjects SYSTEM "SPSWObjects.dtd">\n" "<SPSWObjects>\n" " <SPSWTextFields>\n" " <SPSWText Caption=\"%s\" DrawFlags=\"%d\">\n" " <SPSWCoordinate Origin=\"tablet\" Left=\"%d\" Top=\"%d\" Right=\"%d\" Bottom=\"%d\" />\n" " <SPSWFont Face=\"Arial\" Size=\"12\" />\n" " </SPSWText>\n" " </SPSWTextFields>\n" "</SPSWObjects>\n", aText, 3, // SPSW_TEXT_DRAW_TABLET | SPSW_TEXT_DRAW_SCREEN, rcl.left, rcl.top, rcl.right, rcl.bottom); rc = SPGuiAcquAddBackgroundText(pSpGA, szXML); return rc; }
Image fields
It may be required to dynamically draw images on the screen of a tablet. The images are passed in a call to SPGuiAcquAddBackgroundImage. This function requires a string that is interpreted according to the SPSignware XML Document Type Description.An image is defined by element SPSWImage for a single image, or by element SPSWImageFields for several image regions in one descriptor.
- Note:
- The element SPSWCoordinate is mandatory in image descriptors (although the DTD marks it optional).
void addBackroundImage(pSPGUIACQU_T pSpGA, const char *aImage, int aImageLen, RECT rcl) { char *pszImage = 0; int rc; int iBase64 = 0; char *pszBase64 = 0; SPBase64Encode(aImage, aImageLen, &pszBase64); iBase64 = strlen(pszBase64); pszImage = malloc(iBase64 + 1024); _snprintf (pszImage, iBase64 + 1024, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" "<!DOCTYPE SPSWObjects SYSTEM "SPSWObjects.dtd">\n" "<SPSWObjects>\n" " <SPSWImageFields>\n" " <SPSWImage DrawFlags=\"%d\" Format=\"3\">\n" " <SPSWCoordinate Origin=\"tablet\" Left=\"%d\" Top=\"%d\" Right=\"%d\" Bottom=\"%d\" />\n" " %s\n" " </SPSWImage>\n" " </SPSWImageFields>\n" "</SPSWObjects>\n", 0x13, // SPSW_IMAGE_DRAW_TABLET | SPSW_IMAGE_DRAW_SCREEN | SPSWIMAGE_DRAW_TRANSPARENT, rcl.left, rcl.top, rcl.right, rcl.bottom, pszBase64); rc = SPGuiAcquAddBackgroundImage(pSpGA, pszImage); free(spzImage; SPFreeString(&pszBase64); return rc; }
Image fields
It may be required to dynamically view documents on the screen of a tablet. The documents are passed in a call to SPGuiAcquAddBackgroundDocument. This function requires a string that is interpreted according to the SPSignware XML Document Type Description.A document is defined by element SPSWDocument for a single document, or by element SPSWDocumentFields for several document in one descriptor. A document view may add vertical and horizontal sliders, and virtual buttons, predefined built-in actions are zoom-in and zoom-out.
The document descriptor may reference an empty document, the application may assign the document dynamically, see SPAcquireSetDocumentContent, SPGuiAcquSetDocumentContent). The application may add one or more virtual virtual buttons dynamically (see SPAcquireRegisterDocumentRect, SPGuiAcquRegisterDocumentRect).
A typical application will load the generic document descriptor with empty content. It will then render the document to an image and set document content. The application may register virtual buttons for all entry fields in the document.
The application may modify the visual representation of a virtual button whenever the virtual button is registered again (the button id defines which virtual button will be overwritten).
Virtual buttons in a document require an Action attribute, which must ne "none" for buttons that should invoke the registered listener or one of the predefined actions.
- Note:
- The element SPSWCoordinate is mandatory in document descriptors (although the DTD marks it optional).
void addBackroundDocument(pSPGUIACQU_T pSpGA, const char *aDocument, int aDocumentLen, RECT rcl) { char *pszDocument = 0; int rc; int iBase64 = 0; char *pszBase64 = 0; SPBase64Encode(aDocument, aDocumentLen, &pszBase64); iBase64 = strlen(pszBase64); pszDocument = malloc(iBase64 + 1024); _snprintf (pszDocument, iBase64 + 1024, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" "<!DOCTYPE SPSWObjects SYSTEM "SPSWObjects.dtd">\n" " <SPSWDocumentFields>\n" " <SPSWDocument DrawFlags=\"%d\" Format=\"3\">\n" " <SPSWCoordinate Origin=\"tablet\" Left=\"%d\" Top=\"%d\" Right=\"%d\" Bottom=\"%d\" />\n" " %s\n" " <SPSWSlider DrawFlags=\"%d\" Clickable=\"pen-and-mouse\" orientation=\"vertical\" " " Foreground=\"0x008000\" >\n" "</SPSWSlider>\n" " <SPSWSlider DrawFlags=\""%d" Clickable=\"pen-and-mouse\" orientation=\"horizontal\" " " Foreground=\"0x008000\" >" " <SPSWCoordinate Origin=\"Tablet\" Left=\"0\" Right=\"950\" Top=\"850\" Bottom=\"900\" />\n" "</SPSWSlider>\n" " <SPSWVirtualButton DrawFlags=\"" + iDrawFlags + "\" Clickable=\"pen-and-mouse\" " " Foreground=\"0x008000\" Action=\"zoom-in\" Id=\"0x10000\">" " <SPSWCoordinate Origin=\"Tablet\" Left=\"100\" Right=\"150\" Top=\"0\" Bottom=\"100\" />\n" " <SPSWText DrawFlags=\"%d\" Group=\"ButtonGroup\">\n" " <SPSWFont Face=\"Helvetica\" Size=\"0\" />\n + \n" " </SPSWText>\n" " </SPSWVirtualButton>\n" " <SPSWVirtualButton DrawFlags=\"%d\" Clickable=\"pen-and-mouse\" " " Foreground=\"0x008000\" Action=\"zoom-out\" Id=\"0x10001\">" " <SPSWCoordinate Origin=\"Tablet\" Left=\"180\" Right=\"230\" Top=\"0\" Bottom=\"100\" />\n" + " <SPSWText DrawFlags=\"%d\" Group=\"ButtonGroup\">\n" + " <SPSWFont Face=\"Helvetica\" Size=\"0\" />\n - \n" " </SPSWText>\n" " </SPSWVirtualButton>\n" " </SPSWDocument>\n" " </SPSWDocumentFields>\n", 0x13, // SPSW_IMAGE_DRAW_TABLET | SPSW_IMAGE_DRAW_SCREEN | SPSWIMAGE_DRAW_TRANSPARENT, rcl.left, rcl.top, rcl.right, rcl.bottom, pszBase64, 0x13 , 0x13 , 0x13 , 0x13, 0x13 , 0x13 ); rc = SPGuiAcquAddBackgroundDocument(pSpGA, pszDocument); free(pszDocument; SPFreeString(&pszBase64); return rc; }
Mixed image, document and text fields
It may be required to dynamically draw images, documents, text and rectangle on the screen of a tablet. Images, Documents, Rectangles and text are passed in a call to SPGuiAcquAddBackgroundObject. This function requires a string containing an XML document that is interpreted according to SPSignware XML Document Type Description.Please use the XML declaration to specify the character encoding of the XML document. Supported encodings are ASCII, UTF-8, and ISO-8859-1. Don't forget to use character references for '"' ("), '&' (&), and '<' (<).
- Note:
- SPGuiAcquAddBackgroundObject allows SPSWRect, SPSWRectfields, SPSWVirtualButton, SPSWVirtualButtonfields, SPSWText, SPSWTextfields, SPSWImage, SPSWImageFields, SPSWDocument and SPSWDocumentFields elements. SPSWRect, SPSWRectfields are not assigned an action, these elements will only be drawn. SPSWVirtualButton, SPSWVirtualButtonfields will be assigned to an action defined by the id that must be specified.
SPSignware XML Document Type Description
All SignWare XML strings must comply with these rules (DTD):
<?xml version="1.0" encoding="UTF-8"?> <!ENTITY % Text "I | B | U | S | Sub | Sup | Font | P | BR | Color"> <!-- Nested text formatting --> <!ELEMENT SPSWDeviceFields (SPSWDevice+)> <!ATTLIST SPSWDeviceFields> <!-- Contents: SPSWDevice one or more SPSWDevice elements --> <!ELEMENT SPSWObjects (SPSWRect*, SPSWRectFields?, SPSWVirtualButton*, SPSWVirtualButtonFields?, SPSWText*, SPSWTextFields?, SPSWImage*, SPSWImageFields?, SPSWDocumentFields?, SPSWTabletOption?)> <!ATTLIST SPSWObjects> <!-- Contents: one of SPSWRect zero or more SPSWRect elements SPSWRectFields zero or one SPSWRectFields element SPSWRVirtualButton zero or more SPSWVirtualButton elements SPSWVirtualButtonFields zero or one SPSWVirtualButtonFields element SPSWText zero or more SPSWText elements SPSWTextFields zero or one SPSWTextFields element SPSWImage zero or more SPSWImage elements SPSWImageFields zero or one SPSWImageFields element SPSWDocumentFields zero or one SPSWDocumentFields element SPSWTabletOption zero or one SPSWTabletOption element --> <!ELEMENT SPSWDevice (SPSWObjects+)> <!ATTLIST SPSWDevice Device CDATA #REQUIRED > <!-- Contents: SPSWObjects one or more SPSWObjects elements Attributes: Device the name of the device: Apple iPad Apple iPhone Apple iPod ENSign10 HTC flyer Interlink ePos Interlink eSig Interlink ePad II Interlink ePad ID Interlink ePad ID Pro Interlink eInk Interlink eInk Pro Interlink ePad LS mobile touch any mobile android device Olivetti zPad-B8001 Samsung GT-N7000 Stepover blueM III Stepover blueM III LCD Stepover blueM III LCD_320x240 TabletPC Topaz SigLite SE LCD Topaz SigLite SE LCD_240x64 Topaz SigLite SE LCD_240x128 Topaz SigLite SE LCD_320x240 VPSign Wacom Intuos Wacom SIGNPAD_640x480 Wacom SIGNPAD_396x100 Wacom SIGNPAD_800x480 Wacom Graphire Wacom PL 400 Wacom PenPartner LCD NonLCD Default --> <!ELEMENT SPSWRectFields (SPSWRect+)> <!ATTLIST SPSWRectFields> <!-- Contents: SPSWRect one or more SPSWRect elements --> <!ELEMENT SPSWVirtualButtonFields (SPSWVirtualButton+)> <!ATTLIST SPSWVirtualButtonFields> <!-- Contents: SPSWVirtualButton one or more SPSWVirtualButton elements --> <!ELEMENT SPSWTextFields (SPSWText+)> <!ATTLIST SPSWTextFields> <!-- Contents: SPSWText one or more SPSWText elements --> <!ELEMENT SPSWImageFields (SPSWImage+)> <!ATTLIST SPSWImageFields> <!-- Contents: SPSWImage one or more SPSWImage elements --> <!ELEMENT SPSWDocumentFields (SPSWDocument+)> <!ATTLIST SPSWDocumentFields> <!-- Contents: SPSWDocument one or more SPSWDocument elements --> <!ELEMENT SPSWTabletOption (SPSWCoordinate)> <!ATTLIST SPSWTabletOption Screen (off|on) "off" Tablet (off|on) "off" Image (blackwhite|optimized) "optimized" PenThickness CDATA #IMPLIED PenWidth CDATA #IMPLIED Background CDATA #IMPLIED Foreground CDATA #IMPLIED StrokeEcho (off|on|undefined) "undefined" > <!-- Contents: Elements: SPSWCoordinate coordinate that defines the active signing region Attributes: Screen "on" to clip vectors outside the signature region on the PC screen. If screen is off then the vectors will not be rendered and not be added to the signature object. Tablet "on" to clip vectors outside the signature region on the tablet display. Vectors may still be added to the signature if screen equals "on". Image Force the image type, either of the following options - blackwhite: pass a black/white image, even if the Tablet can display color images - optimized pass a color image if the tablet supports color, else pass a black/white image PenThickness Width of the pen to draw pen strokes, range 1 ... 255, 1: thin, 255 bold pen, please see SPTabletSetOption("PenThickness") for details PenWidth same as PenThickness Background background color, color of the pen when the pressure is 0, format: 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent background, default is transparent Foreground foreground color, color of the pen when the pressure is maximum format: 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, default is 0x00 (black) StrokeEcho turn on or off stroke echo on the tablet LCD, undefined will leave the property unchanged Notes: The SPSWTabletOptions element describes a clipping region for tablet vectors. All vectors outside the clipping region will not be drawn. Virtual buttons outside the clipping region will furtheron be clickable. Clipping regions and PenThickness are currently only supported with SignPad STU-520 --> <!ELEMENT SPSWRect (SPSWCoordinate, SPSWText?, SPSWImage?)> <!ATTLIST SPSWRect Screen (off|on|fullscreen-tablet-only) "off" Tablet (off|on) "off" Enable (always|external-tablet-only) "always" Clickable (pen|pen-and-mouse) "pen" Background CDATA #IMPLIED Foreground CDATA #IMPLIED Penwidth CDATA #IMPLIED DrawFlags CDATA #IMPLIED Diameter CDATA #IMPLIED > <!-- Contents: SPSWCoordinate one coordinate element SPSWText zero or one text element SPSWImage zero or one image element Attributes: Screen "on" to draw the rectangle in the acquiry window, "fullscreen-tablet-only" to draw the rectangle in the acquiry window only on full-screen tablets (Tablet PCs and Wacom PL series) Tablet "on" to draw the rectangle on the tablet LCD Enable "always" to enable the rectangle unconditionally; "external-tablet-only" to disable the rectangle (in the aquiry window and on the tablet LCD) if the tablet has no external LCD Background background color, 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent background, default: use current background color Foreground foreground color, 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent, default is current pen Penwidth The width of the pen in pixel, default 1 pixel The border is not drawn if the width is set to 0 DrawFlags deprecated. A bitwise OR of these values: 0x00000001 equivalent to Screen="on" 0x00000002 equivalent to Tablet="on" 0x00000004 equivalent to Screen="fullscreen-tablet-only" 0x00000008 equivalent to Enable="external-tablet-only" 0x00000010 equivalent to Clickable="pen-and-mouse" Diameter The diameter of round edges, pass 0 to draw rectangle edges, the diameter in pixel is calculated as min(width_pixel, height_pixel) * Diameter / 100 default is 20 --> <!ELEMENT SPSWVirtualButton (SPSWCoordinate, SPSWText?, SPSWImage?)> <!ATTLIST SPSWVirtualButton Screen (off|on|fullscreen-tablet-only) "off" Tablet (off|on) "off" Enable (always|external-tablet-only) "always" Clickable (pen|pen-and-mouse) "pen" Background CDATA #IMPLIED Foreground CDATA #IMPLIED Penwidth CDATA #IMPLIED DrawFlags CDATA #IMPLIED Diameter CDATA #IMPLIED Id CDATA #REQUIRED Action (none|zoom-in|zoom-out) "none" > <!-- Contents: SPSWCoordinate one coordinate element SPSWText zero or one text element SPSWImage zero or one image element Attributes: Screen "on" to draw the rectangle in the acquiry window, "fullscreen-tablet-only" to draw the rectangle in the acquiry window only on full-screen tablets (Tablet PCs and Wacom PL series) Tablet "on" to draw the rectangle on the tablet LCD Enable "always" to enable the rectangle unconditionally; "external-tablet-only" to disable the rectangle (in the aquiry window and on the tablet LCD) if the tablet has no external LCD Background background color, 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent background, default: use current background color Foreground foreground color, 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent, default is current pen Penwidth The width of the pen in pixel, default 1 pixel The border is not drawn if the width is set to 0 DrawFlags deprecated. A bitwise OR of these values: 0x00000001 equivalent to Screen="on" 0x00000002 equivalent to Tablet="on" 0x00000004 equivalent to Screen="fullscreen-tablet-only" 0x00000008 equivalent to Enable="external-tablet-only" 0x00000010 equivalent to Clickable="pen-and-mouse" Diameter The diameter of round edges, pass 0 to draw rectangle edges, the diameter in pixel is calculated as min(width_pixel, height_pixel) * Diameter / 100 default is 20 Id unique identifier for the button. The application must know the Id and must be able to respond to clicks on the virtual button identified by this Id. Range 1 .. 65535 Action predefined built-in action, only if the button is embedded in a document, else the action will be ignored --> <!ELEMENT SPSWCoordinate EMPTY> <!ATTLIST SPSWCoordinate Origin (tablet | window | absscreen | document) #REQUIRED Left CDATA #REQUIRED Right CDATA #REQUIRED Top CDATA #REQUIRED Bottom CDATA #REQUIRED > <!-- Attributes: Origin origin for the coordinates: tablet: all coordinates are relative to the top left corner of the tablet window: all coordinates are relative to the top left corner of the according window absscreen: all coordinates are relative to the top left corner of the PC screen document: all coordinates are relative to the top left corner of the parent document, only applicable to SPSWVirtualButton elements that are embedded in a document Left the left position [in parts per thousand] Right the right position [in parts per thousand] Top the top position [in parts per thousand] Bottom the bottom position [in parts per thousand] Notes: some objects do not support all origins. The SPImage parser maps all coordinates to the base image size --> <!ELEMENT SPSWText (#PCDATA | SPSWCoordinate | SPSWFont | %Text;)* > <!ATTLIST SPSWText Screen (off|on|fullscreen-tablet-only) "off" Tablet (off|on) "off" HAlign (left|center|right) "left" VAlign (top|center|bottom) "center" LineBreak (off|simple) "off" Tabs (space|expand) "space" Path CDATA #IMPLIED Group CDATA #IMPLIED Format CDATA #IMPLIED Default CDATA #IMPLIED DrawFlags CDATA #IMPLIED Alignment CDATA #IMPLIED Caption CDATA #IMPLIED Background CDATA #IMPLIED Foreground CDATA #IMPLIED > <!-- Contents: SPSWCoordinate zero or one coordinate element, coordinate is required if the text is not embedded e. g. in a SPSWRect element SPSWFont zero or one font element (see also the Font, B, I, etc. elements). The system font will be used if no SPSWFont element is specified. Text with formatting elements. Whitespace immediately after start tags and immediately before end tags is ignored. Sequences of whitespace characters are collapsed, the formatting attributes of the first whitespace character of such a sequence will be used. Attributes: Screen "on" to draw the text in the acquiry window, "fullscreen-tablet-only" to draw the text in the acquiry window only on full-screen tablets (Tablet PCs and Wacom PL series) Tablet "on" to draw the text on the tablet LCD HAlign horizontal alignment VAlign vertical alignment LineBreak "simple" for simple automatic word break (multi line), "off" for a single line (with truncation) Tabs "space" to replace a TAB character with a single space character, "expand" to expand to spaces to get to move to the next multiple of 8 characters (works for fixed-width fonts only); not used if the text is specified inside the SPSWText element (ie, used only if the text is specified by the Caption or Default attribute) Path the pathname for values 1 (file-utf-8), file-xml and 5 (file-latin-1) of the Format attribute Group a group name, all group members share the same font size when using auto font size calculation, default is no group Format one of the following values: "base64" the Caption attribute contains the Base64-encoded text (text is UTF-8-encoded) "file-latin-1" the Path attribute (or the Caption attribute, if present) specifies the name of a file containing Latin-1-encoded text "file-utf-8" the Path attribute (or the Caption attribute, if present) specifies the name of a file containing UTF-8-encoded text "file-xml" the Path attribute (or the Caption attribute, if present) specifies the name of a file containing the text with XML markup. The XML document must conform to SPSWObjects.dtd and must contain exactly one SPSWText element (called "that SPSWText element" in this description, while "this SPSWText element" is the one having the Format="file-xml" attribute). That SPSWText element must not have Caption, Default, Format, and Path attributes; any other attributes override the attributes of this SPSWText element. If that SPSWText element contains SPSWCoordinate or SPSWFont elements, those elements will override the respective elements of this SPSWText element. Apart from SPSWCoordinate and SPSWFont, this SPSWText element must not contain any contents. "text" the element (or the Caption attribute, if present) contains the text (default) "zlib-base64" the Caption attribute contains the zlib-compressed and then Base64-encoded text (text is UTF-8-encoded) 0x00000001 deprecated, equivalent to "file-utf-8" 0x00000002 deprecated, equvialent to "text" 0x00000003 deprecated, equvialent to "base64" 0x00000004 deprecated, equvialent to "zlib-base64" 0x00000005 deprecated, equvialent to "file-latin-1" Default the text that will be displayed if Caption cannot be resolved (empty, file not found etc) DrawFlags deprecated. A bitwise OR of these values: 0x00000001 equivalent to Screen="on" 0x00000002 equivalent to the Tablet attribute 0x00000004 equivalent to Screen="fullscreen-tablet-only" Alignment deprecated. A bitwise OR of these values: 0x00000000 equivalent to HAlign=left (default) 0x00000001 equivalent to HAlign=center 0x00000002 equivalent to HAlign=right 0x00000000 equivalent to VAlign=top 0x00000004 equivalent to VAlign=center (default) 0x00000008 equivalent to VAlign=bottom 0x00000010 equivalent to LineBreak=simple 0x00000020 equivalent to LineBreak=off (default) 0x00000040 equivalent to Tabs=expand Caption deprecated. The text to be displayed (or the pathname of the file). If this attribute is present, its value will be used instead of the element's contents (except for SPSWCoordinate and SPSWFont) and instead of the Path attribute, depending on the value of the Format attribute. To use formatted text, this attribute must be omitted Background background color, 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent background, default: use current text background color Foreground foreground color, 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, default: use current text color If the Format-attribute specifies a file (file-latin-1, file-utf-8 or file-xml) then this search order is used to locate the file: - current folder - executable folder - folder defined in USERPROFILE\SOFTPRO environment - folder defined in USERPROFILE environment - folder defined in HOMEPATH\SOFTPRO environment - folder defined in HOMEPATH environment - folder defined in ALLUSERSPROFILE\SOFTPRO environment - folder defined in ALLUSERSPROFILE environment - folder defined in APPDATA\SOFTPRO environment - folder defined in APPDATA environment - all folders defined in PATH environment - Windows folder - System folder --> <!ELEMENT B (#PCDATA | %Text;)*> <!-- bold --> <!ELEMENT I (#PCDATA | %Text;)*> <!-- italic --> <!ELEMENT U (#PCDATA | %Text;)*> <!-- underline --> <!ELEMENT S (#PCDATA | %Text;)*> <!-- strike-through --> <!ELEMENT Sub (#PCDATA | %Text;)*> <!-- subscript --> <!ELEMENT Sup (#PCDATA | %Text;)*> <!-- superscript --> <!-- If U and S elements are nested, the innermost one will take precedence. If Sub and Sup elements are nested, the innermost one will take precedence. --> <!ELEMENT BR EMPTY> <!-- line break. Don't forget the end tag! --> <!ELEMENT P (#PCDATA | %Text;)*> <!-- start new paragraph --> <!ATTLIST P LineSkip CDATA #IMPLIED> <!-- Attributes: LineSkip Distance between baselines in points; by default, the distance is controlled by font metrics. If the value starts with +, multiply the distance by the number following +, if the value starts with -, divide the distance by the number follwing -. Examples: <P LineSkip="10"> 10 points <P LineSkip="+1.0"> Default <P LineSkip="-1.2"> Divide distance by 1.2 --> <!ELEMENT Color (#PCDATA | %Text;)*> <!-- text color --> <!ATTLIST Color Foreground CDATA #IMPLIED Background CDATA #IMPLIED> <!-- Attributes: Foreground The text color, format 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, default is black (0x00000000) Backround The background color, format 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent background, default: use current text background color --> <!ELEMENT Font (#PCDATA | %Text;)*> <!ATTLIST Font Face CDATA #IMPLIED Size CDATA #IMPLIED> <!-- Attributes (at least one must be specified): Face Face name of the font family (keep current face name one if omitted) Size Absolute font size in points or font magnification (relative font size) if starting with + or - (keep the current font size if omitted). Examples: <Font Size="12"> Switch to 12 points <Font Size="+1.2"> Multiply current font size with 1.2 <Font Size="-1.2"> Divide current font size by 1.2 --> <!ELEMENT SPSWImage (#PCDATA | SPSWCoordinate)*> <!ATTLIST SPSWImage Format CDATA #REQUIRED Screen (off|on|fullscreen-tablet-only) "off" Tablet (off|on) "off" Mode (opaque|transparent) "opaque" DrawFlags CDATA #IMPLIED Width CDATA #IMPLIED Height CDATA #IMPLIED FillColor CDATA #IMPLIED TransparentColor CDATA #IMPLIED > <!-- Contents: SPSWCoordinate zero or one coordinate element, coordinate is required if the image is not embedded e.g. in an SPSWRect element Attributes: Format image format, one of the following values: "base64" Base64-encoded bitmap "binary" binary bitmap (it may be difficult to embed binary data "empty" create an empty image (width and height must be specified) "file" fully qualified file name (on the local file system, http or ftp requests are not supported) "zlib-base64" Base64-encoded compressed bitmap 0x00000001 deprecated, equivalent to "file" 0x00000002 deprecated, equivalent to "binary" 0x00000003 deprecated, equivalent to "base64" 0x00000004 deprecated, equivalent to "zlib-base64" 0x00000005 deprecated, equivalent to "empty" Screen "on" to draw the image in the acquiry window, "fullscreen-tablet-only" to draw the image in the acquiry window only on full-screen tablets (Tablet PCs and Wacom PL series) Tablet draw the image on the tablet LCD if "on" Mode draw the image transparently (bitwise AND with background) if "transparent" Width image width (optional, may be 0), required for empty images Height image height (optional, may be 0), required for empty images DrawFlags: deprecated. A bitwise OR of these values: 0x00000001 equivalent to Screen="on" 0x00000002 equivalent to Tablet="on" 0x00000004 equivalent to Screen="fullscreen-tablet-only" 0x00000010 equivalent to Mode="transparent" FillColor The image will be filled with FillColor if Format equals "empty". Color format: 0xrrggbb, rr: red, gg: green, bb: blue The default fill color is white (xFFFFFF) TransparentColor The color that should be made transparent, if transparent mode is activated, Color format: 0xrrggbb, rr: red, gg: green, bb: blue The default transparent color is white (0xFFFFFF) If the Format-attribute specifies a file (file) then this search order is used to locate the file: - current folder - executable folder - folder defined in USERPROFILE\SOFTPRO environment - folder defined in USERPROFILE environment - folder defined in HOMEPATH\SOFTPRO environment - folder defined in HOMEPATH environment - folder defined in ALLUSERSPROFILE\SOFTPRO environment - folder defined in ALLUSERSPROFILE environment - folder defined in APPDATA\SOFTPRO environment - folder defined in APPDATA environment - all folders defined in PATH environment - Windows folder - System folder --> <!ELEMENT SPSWSlider (SPSWCoordinate)*> <!ATTLIST SPSWSlider Screen (off|on|fullscreen-tablet-only) "off" Tablet (off|on) "off" Enable (always | external-tablet-only) "always" Clickable (pen|pen-and-mouse) "pen" Background CDATA #IMPLIED Foreground CDATA #IMPLIED Slider CDATA #IMPLIED Orientation (vertical|horizontal) #REQUIRED > <!-- Contents: SPSWCoordinate zero or one coordinate element, required if the slider is not embedded in a SPSWDocument object The SPSWDocument places horizontal sliders at the bottom and vertical sliders at the right side of the document Attributes: Screen "on" to draw the image in the acquiry window, "fullscreen-tablet-only" to draw the image in the acquiry window only on full-screen tablets (Tablet PCs and Wacom PL series) Tablet draw the image on the tablet LCD if "on" Enable "always" to enable the rectangle unconditionally; "external-tablet-only" to disable the rectangle (in the aquiry window and on the tablet LCD) if the tablet has no external LCD Background background color, 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent background, default: use current background color Foreground foreground color, 0x00rrggbb with bb = blue, gg = green, rr = red, each color being in the range 0x00 through 0xff, specify 0xffffffff to draw transparent, default is current pen DrawFlags deprecated. A bitwise OR of these values: 0x00000001 equivalent to Screen="on" 0x00000002 equivalent to Tablet="on" 0x00000004 equivalent to Screen="fullscreen-tablet-only" 0x00000008 equivalent to Enable="external-tablet-only" 0x00000010 equivalent to Clickable="pen-and-mouse" Orientation vertical | horizontal --> <!ELEMENT SPSWDocument (#PCDATA | SPSWCoordinate | SPSWSlider | SPSWVirtualButton)*> <!ATTLIST SPSWDocument Format CDATA #REQUIRED Screen (off|on|fullscreen-tablet-only) "off" Tablet (off|on) "off" Mode (opaque|transparent) "opaque" DrawFlags CDATA #IMPLIED Width CDATA #IMPLIED Height CDATA #IMPLIED FillColor CDATA #IMPLIED TransparentColor CDATA #IMPLIED Zoom CDATA #IMPLIED Id CDATA #IMPLIED > <!-- Contents: SPSWCoordinate one coordinate element, coordinate is required if the image is not embedded e.g. in an SPSWRect element SPSWSlider zero or more slider elements to scroll the document horizontally or vertically SPSWVirtualButton zero or more virtual buttons. The SPSWDocument object supports built-in actions zoom-in and zoom-out Attributes: Format image format, one of the following values: "base64" Base64-encoded bitmap "binary" binary bitmap (it may be difficult to embed binary data "empty" create an empty image (width and height must be specified) "file" fully qualified file name (on the local file system, http or ftp requests are not supported) in XML) "zlib-base64" Base64-encoded compressed bitmap 0x00000001 deprecated, equivalent to "file" 0x00000002 deprecated, equivalent to "binary" 0x00000003 deprecated, equivalent to "base64" 0x00000004 deprecated, equivalent to "zlib-base64" 0x00000005 deprecated, equivalent to "empty" Screen "on" to draw the image in the acquiry window, "fullscreen-tablet-only" to draw the image in the acquiry window only on full-screen tablets (Tablet PCs and Wacom PL series) Tablet draw the image on the tablet LCD if "on" Mode draw the image transparently (bitwise AND with background) if "transparent" Width image width (optional, may be 0), required for empty images Height image height (optional, may be 0), required for empty images DrawFlags: deprecated. A bitwise OR of these values: 0x00000001 equivalent to Screen="on" 0x00000002 equivalent to Tablet="on" 0x00000004 equivalent to Screen="fullscreen-tablet-only" 0x00000010 equivalent to Mode="transparent" FillColor The image will be filled with FillColor if Format equals "empty". Color format: 0xrrggbb, rr: red, gg: green, bb: blue The default fill color is white (xFFFFFF) TransparentColor The color that should be made transparent, if transparent mode is activated, Color format: 0xrrggbb, rr: red, gg: green, bb: blue The default transparent color is white (0xFFFFFF) Zoom FitWidth, FitHeight, FitAll or the zoom factor, e. g. 2.0 Id optional unique identifier for the document. Range 1 .. 65535 If the Format-attribute specifies a file (file) then this search order is used to locate the file: - current folder - executable folder - folder defined in USERPROFILE\SOFTPRO environment - folder defined in USERPROFILE environment - folder defined in HOMEPATH\SOFTPRO environment - folder defined in HOMEPATH environment - folder defined in ALLUSERSPROFILE\SOFTPRO environment - folder defined in ALLUSERSPROFILE environment - folder defined in APPDATA\SOFTPRO environment - folder defined in APPDATA environment - all folders defined in PATH environment - Windows folder - System folder --> <!ELEMENT SPSWFont EMPTY> <!ATTLIST SPSWFont Face CDATA #REQUIRED Size CDATA #REQUIRED Flags CDATA #IMPLIED > <!-- Attributes: Face the face name of the font family Size the size of the font (in points) Flags deprecated (use B, I, U, S, Sup, and Sub). A bitwise OR of these values: 0x00000001 Bold 0x00000002 Italic 0x00000004 Underline 0x00000008 StrikeOut 0x00000010 SuperScript (only supported in embedded formatting options) 0x00000020 Subscript (only supported in embedded formatting options) -->
Typedefs | |
typedef int(_cdecl * | pSPGUIACQUBUTTON_T )(pSPGUIACQU_T pSpGuiAcqu, SPINT32 iButtonId, SPINT32 iPress) |
Callback function that is called when a hardware button is pressed on the tablet. | |
typedef int(_cdecl * | pSPGUIACQUDOCRECTLISTENER_T )(pSPGUIACQU_T pSpGuiAcqu, SPUINT32 iDocId, SPUINT32 uRectId) |
Callback function that is called when a virtual button (registered rectangle) is 'clicked'. | |
typedef int(_cdecl * | pSPGUIACQULINETO_T )(pSPGUIACQU_T pSpGuiAcqu, SPINT32 iX, SPINT32 iY, SPINT32 iPress, SPINT32 iTime) |
Callback function that is called for each vector. | |
typedef int(_cdecl * | pSPGUIACQURECTLISTENER_T )(pSPGUIACQU_T pSpGuiAcqu, SPUINT32 uId) |
Callback function that is called when a virtual button (registered rectangle) is 'clicked'. | |
typedef int(_cdecl * | pSPGUIACQUSTATUS_T )(pSPGUIACQU_T pSpGuiAcqu, int iMajor, int iDetail) |
Callback function that is called when the tablet hardware status changes, please read tablet status change notifications for more details. | |
typedef int(_cdecl * | pSPGUIACQUTIMEOUT2_T )(pSPGUIACQU_T pSpGuiAcqu) |
Callback function that is called when a timeout occurs. | |
typedef int(_cdecl * | pSPGUIACQUTIMEOUT_T )(SPVPTR ulOptParameter) |
Callback function that is called when a timeout occurs. | |
Functions | |
SPINT32 __cdecl | SPGuiAcquAcquire (pSPGUIACQU_T pSPGuiAcqu) |
Start tablet acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquAcquireDone (pSPGUIACQU_T pSPGuiAcqu, SPINT32 iResult) |
Terminate tablet acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquAddBackgroundDocument (pSPGUIACQU_T pSpGui, const SPCHAR *pszXMLDocumentDescription) |
Add documents to the tablet LCD screen or the acquiry window. | |
SPINT32 __cdecl | SPGuiAcquAddBackgroundImage (pSPGUIACQU_T pSpGui, const SPCHAR *pszXMLImageDescription) |
Add images to the tablet LCD screen or the acquiry window. | |
SPINT32 __cdecl | SPGuiAcquAddBackgroundObject (pSPGUIACQU_T pSpGui, const SPCHAR *pszXMLDescription) |
Add images, rectangles and text fields to the tablet LCD screen or the acquiry window. | |
SPINT32 __cdecl | SPGuiAcquAddBackgroundText (pSPGUIACQU_T pSpGui, const SPCHAR *pszXMLTextDescription) |
Add some text to the tablet LCD screen or the acquiry window. | |
SPINT32 __cdecl | SPGuiAcquClearEntries (pSPGUIACQU_T pSpGui, int iFlags) |
Clear all internal signature data of any acquiries of an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquConnect (pSPGUIACQU_T pSPGuiAcqu, SPINT32 iDriver) |
Connect to a tablet specified by driver number. | |
SPINT32 __cdecl | SPGuiAcquConnectByAlias (pSPGUIACQU_T pSPGuiAcqu, const char *pszAlias) |
Connect to a tablet specified by an alias name. | |
SPINT32 __cdecl | SPGuiAcquConnectByEnum (pSPGUIACQU_T pSPGuiAcqu, pSPPROPERTYMAP_T spDescriptor) |
Connect to a tablet specified by a descriptor. | |
SPINT32 __cdecl | SPGuiAcquConnectEx (pSPGUIACQU_T pSPGuiAcqu, const char *pszTabletClass, const char *pszConfig) |
Connect to a tablet specified by class name. | |
SPINT32 __cdecl | SPGuiAcquCreate (pSPGUIACQU_T *ppSPGuiAcqu, SPHWND hwndParent) |
Create an SPGuiAcqu object (window). | |
SPINT32 __cdecl | SPGuiAcquCreateInClient (pSPGUIACQU_T *ppSPGuiAcqu, SPHWND hwndChild, SPHWND hwndParent) |
Create an SPGuiAcqu object inside a given window. | |
SPINT32 __cdecl | SPGuiAcquCreateTablet (pSPGUIACQU_T pSPGuiAcqu, SPINT32 iDriver) |
Create the native tablet object that is required to connect to or acquire from the tablet hardware. | |
SPINT32 __cdecl | SPGuiAcquCreateTabletByAlias (pSPGUIACQU_T pSPGuiAcqu, const char *pszAlias) |
Create a new SPTablet object based on an Alias. | |
SPINT32 __cdecl | SPGuiAcquCreateTabletByEnum (pSPGUIACQU_T pSPGuiAcqu, pSPPROPERTYMAP_T spDescriptor) |
Create a new SPTablet object based on an enumeration. | |
SPINT32 __cdecl | SPGuiAcquCreateTabletEx (pSPGUIACQU_T pSPGuiAcqu, const char *pszTabletClass, const char *pszConfig) |
Create a native tablet object specified by class name. | |
SPINT32 __cdecl | SPGuiAcquDisconnect (pSPGUIACQU_T pSPGuiAcqu) |
Disconnect from a tablet. | |
SPINT32 __cdecl | SPGuiAcquFree (pSPGUIACQU_T *ppSPGuiAcqu) |
Free all resources used by an SPGuiAcqu object. | |
SPINT32 | SPGuiAcquGetBackgroundColor (pSPGUIACQU_T pSPGuiAcqu, SPINT32 *piBackgroundColor) |
Get the background color. | |
SPINT32 __cdecl | SPGuiAcquGetBackgroundImage (pSPGUIACQU_T pSPGuiAcqu, SPINT32 iSource, pSPIMAGE_T *ppImage) |
Get the background image as it is displayed on the tablet or the PC screen. | |
SPINT32 __cdecl | SPGuiAcquGetBackgroundText (pSPGUIACQU_T pSPGuiAcqu, SPINT32 iSource, SPCHAR **ppszText) |
Get the background text as it is displayed on the tablet. | |
SPINT32 __cdecl | SPGuiAcquGetBoolProperty (pSPGUIACQU_T pSPGuiAcqu, const SPCHAR *pszName, SPBOOL *pbValue) |
Query a property. | |
SPINT32 | SPGuiAcquGetBorder (pSPGUIACQU_T pSPGuiAcqu, SPINT32 *piBorder) |
Get the size of the border in an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquGetDrawMode (pSPGUIACQU_T pSpGui, SPINT32 *piDrawMode) |
Get the draw mode of an SPGuiAcqu object. | |
SPINT32 | SPGuiAcquGetForegroundColor (pSPGUIACQU_T pSPGuiAcqu, SPINT32 *piForegroundColor) |
Get the foreground color. | |
SPINT32 __cdecl | SPGuiAcquGetHwnd (pSPGUIACQU_T pSPGuiAcqu, SPHWND *pHwnd) |
Get the window handle of the window associated with an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquGetHwndRect (pSPGUIACQU_T pSPGuiAcqu, RECT *pRect) |
Get the rectangle (size) of an SPGuiAcqu object's window. | |
SPINT32 __cdecl | SPGuiAcquGetIntProperty (pSPGUIACQU_T pSPGuiAcqu, const SPCHAR *pszName, SPINT32 *piValue) |
Query a property. | |
SPINT32 __cdecl | SPGuiAcquGetReference (pSPGUIACQU_T pSPGuiAcqu, pSPREFERENCE_T *ppReference) |
Get the reference after a signature or reference acquiry. | |
SPINT32 __cdecl | SPGuiAcquGetSignature (pSPGUIACQU_T pSPGuiAcqu, pSPSIGNATURE_T *ppSignature) |
Get the signature during acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquGetTablet (pSPGUIACQU_T pSPGuiAcqu, pSPTABLET_T *ppTablet) |
Get the associated SPTablet object. | |
SPINT32 __cdecl | SPGuiAcquGetTabletRect (pSPGUIACQU_T pSPGuiAcqu, RECT *pRect) |
Get the rectangle (size) of an SPGuiAcqu object's tablet window. | |
SPINT32 __cdecl | SPGuiAcquGetUserLong (pSPGUIACQU_T pSPGuiAcqu, SPVPTR *plUser) |
Get the optional user parameter of an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquNew (pSPGUIACQU_T *ppSPGuiAcqu) |
Create an SPGuiAcqu object (window). | |
SPINT32 __cdecl | SPGuiAcquRegisterComponent (pSPGUIACQU_T pSPGuiAcqu, SPHWND hwndComponent) |
Register a component in acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquRegisterDocumentRect (pSPGUIACQU_T pSpGui, SPUINT32 aId, const SPCHAR *pszVirtualButtonDescription) |
Register a virtual button in a document. | |
SPINT32 __cdecl | SPGuiAcquRegisterRect (pSPGUIACQU_T pSPGuiAcqu, SPUINT32 *pId, pSPRECT_T rcl, SPINT32 iFlags, const SPCHAR *pszName, pSPGUIACQURECTLISTENER_T pVirtualButtonListener) |
Register a virtual button or rectangle in acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquRegisterRect2 (pSPGUIACQU_T pSPGuiAcqu, SPUINT32 *pId, const SPCHAR *pszVirtualButtonDescription, pSPGUIACQURECTLISTENER_T pVirtualButtonListener) |
Register a virtual button or rectangle in acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquRemoveBackgroundObjects (pSPGUIACQU_T pSpGui) |
Remove images, text and rectangle fields from the tablet LCD screen or the acquiry window. | |
SPINT32 __cdecl | SPGuiAcquSetActive (pSPGUIACQU_T pSpGui, SPBOOL bActive) |
Activate / deactivate the acquire window. | |
SPINT32 | SPGuiAcquSetBackgroundColor (pSPGUIACQU_T pSPGuiAcqu, SPINT32 iBackgroundColor) |
Set the background color. | |
SPINT32 __cdecl | SPGuiAcquSetBackgroundImage (pSPGUIACQU_T pSPGuiAcqu, const SPUCHAR *pbImage, SPINT32 iImageLen) |
Set the background image of a tablet that includes an LCD display. | |
SPINT32 __cdecl | SPGuiAcquSetBackgroundObjects (pSPGUIACQU_T pSpGui, pSPBACKGROUNDOBJECTS_T pSpBackgroundObjects) |
Set images, text fields or rectangles to the tablet LCD screen or the acquiry window. | |
SPINT32 __cdecl | SPGuiAcquSetBoolProperty (pSPGUIACQU_T pSPGuiAcqu, const SPCHAR *pszName, SPBOOL bValue) |
Set a property. | |
SPINT32 | SPGuiAcquSetBorder (pSPGUIACQU_T pSPGuiAcqu, SPINT32 iBorder) |
Set the size of the border in an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquSetButtonListener (pSPGUIACQU_T pSPGuiAcqu, pSPGUIACQURECTLISTENER_T pRectListener, pSPGUIACQUBUTTON_T pButtonListener) |
Set the tablet button listener. | |
SPINT32 __cdecl | SPGuiAcquSetClient (pSPGUIACQU_T pSPGuiAcqu, SPHWND hwndChild, SPHWND hwndParent) |
Create visual components for a SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquSetDocumentContent (pSPGUIACQU_T pSpGui, SPINT32 aId, const SPCHAR *pContent, SPINT32 iContent, SPINT32 aFormat) |
Set the content of a document. | |
SPINT32 __cdecl | SPGuiAcquSetDocumentListener (pSPGUIACQU_T pSpGui, pSPGUIACQUDOCRECTLISTENER_T pListener) |
Register a virtual button listener for buttons which are assigned to a specific document. | |
SPINT32 __cdecl | SPGuiAcquSetDrawMode (pSPGUIACQU_T pSpGui, SPINT32 iDrawMode) |
Set the draw mode of an SPGuiAcqu object. | |
SPINT32 | SPGuiAcquSetForegroundColor (pSPGUIACQU_T pSPGuiAcqu, SPINT32 iForegroundColor) |
Set the foreground color. | |
SPINT32 __cdecl | SPGuiAcquSetIntProperty (pSPGUIACQU_T pSPGuiAcqu, const SPCHAR *pszName, SPINT32 iValue) |
Set a property. | |
SPINT32 __cdecl | SPGuiAcquSetStatusListener (pSPGUIACQU_T pSpGuiAcqu, pSPGUIACQUSTATUS_T pNotifyStatus) |
Set the hardware status listener of an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquSetTicket (pSPGUIACQU_T pSPGuiAcqu, pSPTICKET_T pTicket) |
Pass a license ticket for the next signature capture(s). | |
SPINT32 __cdecl | SPGuiAcquSetTimeout (pSPGUIACQU_T pSpGui, pSPGUIACQUTIMEOUT_T pTimeoutListener, SPVPTR ulOptParameter, SPINT32 iTimeout) |
Set the timeout of an acquiry of an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquSetTimeout2 (pSPGUIACQU_T pSpGuiAcqu, SPINT32 iTimeout) |
Set the timeout of an acquiry of an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquSetTimeoutListener (pSPGUIACQU_T pSpGuiAcqu, pSPGUIACQUTIMEOUT2_T pNotifyTimeout) |
Set the hardware status listener of an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquSetUserLong (pSPGUIACQU_T pSPGuiAcqu, SPVPTR lUser) |
Set the optional user parameter of an SPGuiAcqu object. | |
SPINT32 __cdecl | SPGuiAcquSetVectorListener (pSPGUIACQU_T pSpGuiAcqu, pSPGUIACQULINETO_T pNotifyVector) |
Set a vector listener of an SPAcquire object. | |
SPINT32 __cdecl | SPGuiAcquUnregisterAllComponents (pSPGUIACQU_T pSPGuiAcqu) |
Unregister all components in acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquUnregisterAllRects (pSPGUIACQU_T pSPGuiAcqu) |
Unregister all virtual buttons in acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquUnregisterComponent (pSPGUIACQU_T pSPGuiAcqu, SPHWND hwndComponent) |
Unregister a component in acquiry mode. | |
SPINT32 __cdecl | SPGuiAcquUnregisterRect (pSPGUIACQU_T pSPGuiAcqu, SPUINT32 uId) |
Unregister a virtual button in acquiry mode. |
Typedef Documentation
|
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 tablet button being pressed during acquiry mode.
|
|
Callback function that is called when a virtual button (registered rectangle) is 'clicked'.
|
|
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.
|
|
Callback function that is called when a virtual button (registered rectangle) is 'clicked'.
|
|
Callback function that is called when the tablet hardware status changes, please read tablet status change notifications for more details. A pointer to a function that is called to notify the application about tablet hardware status changes.
|
|
Callback function that is called when a timeout occurs. A pointer to a function that is called to notify the application about a timeout condition during acquiry mode.
|
|
Callback function that is called when a timeout occurs. A pointer to a function that is called to notify the application about a timeout condition during acquiry mode.
|
Function Documentation
|
Start tablet acquiry mode. Switch the tablet into acquiry mode. SPTablet switches the tablet from pointer mode to pen entry mode during acquiry. Any registered rectangles will be notified in pen entry mode when the pen is pressed on a rectangle. Pen entry mode is exclusive and will not send any pointer move notifications to any application. This function enables aquiry mode and returns immediately. The actual state change of the tablet is signaled by callback functions, see SPAcquireSetStatusListener. Further callbacks are called during aquiry mode, see SPAcquireSetTimeout, SPAcquireRegisterRect, SPAcquireRegisterRect2, SPAcquireSetButtonListener. Events resulting in callbacks being called are stored in a queue. If the object was created by SPGuiAcquCreate or SPGuiAcquCreateInClient, or if SP_GAWW_EVENTS was set in iFlags of SPGuiAcquCreateWithoutWindow, the system's queue will be used, that is, either the Windows message queue (for Windows) or the X11 event queue (for X11, not yet implemented). If SP_GAWW_EVENTS was not set in iFlags of SPGuiAcquCreateWithoutWindow, an event queue internal to SignWare will be used. In all cases, the queue must be read. This is done by
|
|
Terminate tablet acquiry mode. Turn off tablet aquiry mode. This function makes SPGuiAcquAcquireWait return.
|
|
Add documents to the tablet LCD screen or the acquiry window. The XML string is described in Image fields, element SPSWDocumentFields must be used. The Objects will be displayed on an (optional) LCD screen when the application calls SPGuiAcquAcquire
|
|
Add images to the tablet LCD screen or the acquiry window. The XML string is described in Image fields, element SPSWImageFields must be used. The Objects will be displayed on an (optional) LCD screen when the application calls SPGuiAcquAcquire
|
|
Add images, rectangles and text fields to the tablet LCD screen or the acquiry window. The XML string is described in Mixed image, document and text fields. Element SPSWObjects must be the root element, SPSWImageFileds, SPSWImage, SPSWRect, SPSWRectFields, SPSWTextFields and SPSWText elements will be displayed.
|
|
Add some text to the tablet LCD screen or the acquiry window. The XML string is described in Text fields, element SPSWTextFields must be used. The Objects will be displayed on an (optional) LCD screen when the application calls SPGuiAcquAcquire
|
|
Clear all internal signature data of any acquiries of an SPGuiAcqu object. This function will clear the SPReference object that is embedded in this object; this means that all signatures that were entered so far will be deleted. This function may be required to reenter a signature / reference when the prior entry was not accepted, e.g., because the reference did not satisfy the quality criteria.
|
|
Connect to a tablet specified by driver number. Please read Tablet creation options for a list of supported drivers
|
|
Connect to a tablet specified by an alias name. Please read Tablet creation options for resolving the Alias
|
|
Connect to a tablet specified by a descriptor. Please read Tablet creation options for resolving the enumeration
|
|
Connect to a tablet specified by class name. Please read Tablet creation options for a list of supported options
|
|
Create an SPGuiAcqu object (window). The default draw mode is set to SP_RELEASE_FOCUS | SP_VIRTUAL_BUTTON_CLICK. SPGuiAcqu creates a native window. It sends user messages to this window with message ID's starting at WM_USER + 1000.
|
|
Create an SPGuiAcqu object inside a given window. The default draw mode is set to SP_RELEASE_FOCUS | SP_VIRTUAL_BUTTON_CLICK. If hwndChild is a valid window handle then SPGuiAcqu subclasses the native window identified by hwndChild. It uses this window to draw background objects and tablet strokes, and sends user messages to this window with message ID's starting at WM_USER + 1000. If hwndChild is a not valid window handle then SPGuiAcqu creates a native window. It sends user messages to the created window with message ID's starting at WM_USER + 1000.
|
|
Create the native tablet object that is required to connect to or acquire from the tablet hardware. This is a convenience function provided for applications that might need to access the tablet driver before it is connected. The tablet driver object will be created when it is internally required, the application does not have to call this function. A typical use for this function would be to select an image depending on the tablet device. Create the tablet driver object, get the device ID, pass the device-specific image, and then connect to the tablet. Please read Tablet creation options for a list of supported drivers
|
|
Create a new SPTablet object based on an Alias. Please read Tablet creation options for resolving the Alias
|
|
Create a new SPTablet object based on an enumeration. Please read Tablet creation options for tablet enumeration.
|
|
Create a native tablet object specified by class name. This is a convenience function provided for applications that might need to access the tablet driver before it is connected. In most other cases the tablet driver object will be created when it is internally required, the application does not have to call this function. A typical use for this function would be to select an image depending on the tablet device. Create the tablet driver object, get the device ID, pass the device specific image, and then connect to the tablet. This function will not reinstantiate the tablet driver if a driver already exists. Please read Tablet creation options for a list of supported options
|
|
Disconnect from a tablet.
|
|
Free all resources used by an SPGuiAcqu object. The SPGuiAcqu object must have been created by SPGuiAcquCreate, SPGuiAcquCreateInClient. It is an error to free an SPGuiAcqu object while processing a windows message for the window handle assigned to that SPGuiAcqu object.
|
|
Get the background color.
|
|
Get the background image as it is displayed on the tablet or the PC screen. The image will not contain any partial or fully entered signature strokes. This function returns SP_NOERR and *ppImage = NULL if no background image was passed. This function is provided for audit purposes. The resulting image contains a gray-scale image with up to 256 gray levels or a color image.
|
|
Get the background text as it is displayed on the tablet. This function returns SP_NOERR and *ppText = NULL if no background text was passed. This function is provided for audit purposes. The resulting text contains all text elements that is diplayed on the tablet.
|
|
Query a property.
|
|
Get the size of the border in an SPGuiAcqu object. The border size is 5 pixels by default.
|
|
Get the draw mode of an SPGuiAcqu object.
|
|
Get the foreground color.
|
|
Get the window handle of the window associated with an SPGuiAcqu object. For an SPGuiAcqu object created with SPGuiAcquCreateInClient, this function returns the handle of the client window.
|
|
Get the rectangle (size) of an SPGuiAcqu object's window. The returned rectangle reflects the size and position of the SPGuiAcqu window in client coordinates.
|
|
Query a property.
|
|
Get the reference after a signature or reference acquiry. The returned reference may contain a single signature (in this case a signature was captured), or multiple signatures (when a true reference was captured). It is the responsability of the application to convert the reference to a signature if the returned object includes a single signature. This is a convenience function which behaves exactly like SPReferenceCreateFromGuiAcqu.
|
|
Get the signature during acquiry mode. The returned SPSignature object may not contain all vectors captured so far. This function is provided to check for empty signatures before accepting the signature (see SPGuiAcquAcquireDone). Modifying the SPSignature object won't have an effect on the signature being captured. This is a convenience function which behaves exactly like SPSignatureCreateFromGuiAcqu.
|
|
Get the associated SPTablet object. SP_PARAMERR will be returned if the tablet has not yet been created. You should neither register any listeners in the returned tablet nor set any properties. The object is available to get tablet type, size etc. only.
|
|
Get the rectangle (size) of an SPGuiAcqu object's tablet window. The returned rectangle reflects the size and position of the tablet window in client coordinates, relative to the SPGuiAcqu window. The tablet window is always smaller than the SPGuiAcqu window, as the zoom factor is calculated such that the aspect ratio of the tablet hardware is maintained and the entire tablet will be visible within the SPGuiAcqu window.
|
|
Get the optional user parameter of an SPGuiAcqu object.
|
|
Create an SPGuiAcqu object (window).
SPGuiAcquNew creates the native object, but does not instantiate any visual components.
|
|
Register a component in acquiry mode. Any registered components will be notified in acquiry mode when the pen is pressed on a component. Supported window classes:
|
|
Register a virtual button in a document.
|
|
Register a virtual button or rectangle in acquiry mode. This function is a simplified version of SPGuiAcquRegisterRect2, the call is actually dispatched to SPGuiAcquRegisterRect2 with a properly formatted XML description string. Any registered virtual buttons will be notified in acquiry mode when button is pressed with the pen. Registering a rectangle with an ID that has been already registered will be interpreted as an update on the rectangle coordinates. You must assure that the rectangles will be updated whenever the coordinates change, such as resizing or moving a component unless you specify the flag SP_TABLET_COORDINATE. Virtual buttons can only be drawn to an optional LCD screen on the tablet if they are registered before the tablet enters acquiry mode. The SPGuiAcqu object should not be deleted within the registered listener. You may, e.g., post a message and delete the object in the windows procedure handling that message.
|
|
Register a virtual button or rectangle in acquiry mode. Any registered virtual buttons will be notified in acquiry mode when the virtual button is pressed by the pen. Rectangles can only be drawn to an optional LCD screen on the tablet if they are registered before the tablet enters acquiry mode. TextFields will be positioned within the rectangle (centered, excluding optional image space) if no valid coordinate is specified. Images will be positioned within the rectangle (left aligned) if no valid coordinate is specified.
|
|
Remove images, text and rectangle fields from the tablet LCD screen or the acquiry window. The Background Objects will be updated on an (optional) LCD screen when the application calls SPGuiAcquAcquire
|
|
Activate / deactivate the acquire window. The acquire window is normally active until SPAcquireAcquireDone is called. There are situations where the application might want to deactivate acquire mode, e.g. in multi page dialogs.
|
|
Set the background color. The background color is used to draw a pen stroke that has zero pressure. It will also be used to erase the background if SP_ERASE_BACKGROUND is set.
|
|
Set the background image of a tablet that includes an LCD display. The tablet image is composed of all background images, text and rectangles (virtual buttons). The tablet image will be calculated before the tablet enters acquiry mode, that is within the method SPGuiAcquAcquire.
|
|
Set images, text fields or rectangles to the tablet LCD screen or the acquiry window. Use SPBackgroundObjectsCreateFromFile or SPBackgroundObjectsCreateFromXML to create the background objects container. The proper objects will be selected based on the created tablet type, and all elements of the selected objects will be copied to the background
|
|
Set a property.
|
|
Set the size of the border in an SPGuiAcqu object. The border size is 5 pixels by default.
|
|
Set the tablet button listener. This listener will be called when a real button (hardware button) on the tablet was pressed, but not for virtual buttons.
|
|
Create visual components for a SPGuiAcqu object. If hwndChild is a valid window handle then SPGuiAcqu subclasses the native window identified by hwndChild. It uses this window to draw background objects and tablet strokes, and sends user messages to this window with message ID's starting at WM_USER + 1000. If hwndChild is a not valid window handle then SPGuiAcqu creates a native window. It sends user messages to the created window with message ID's starting at WM_USER + 1000.
|
|
Set the content of a document.
Use SPGuiAcquAddBackgroundDocument or SPGuiAcquAddBackgroundObject or SPGuiAcquSetBackgroundObjects to create and layout of a document view.
|
|
Register a virtual button listener for buttons which are assigned to a specific document.
|
|
Set the draw mode of an SPGuiAcqu object. The tablet area may be smaller than the window area because the tablet area will be zoomed to maintain the aspect ratio of the tablet hardware. SP_RELEASE_FOCUS is implemented by subclassing the parent window. The subclassing is released when acquiry mode is stopped. SP_RELEASE_FOCUS causes SPTabletAcquireDone(SPGuiAcquGetTablet(pSpGui)) to be called when loosing focus and SPTabletAcquire(SPGuiAcquGetTablet(pSpGui), SPGuiAcquGetHwnd(pSpGui)) to be called when gaining focus. The pen position is normally drawn as a caret. Carets cannot be used when the client window is not the topmost window. The emulated pen cursor is available for these cases. However the emulated pen cursor may not be erased in all cases - especially if the application draws on the client area.
|
|
Set the foreground color. The foreground color is used to draw a pen stroke that has maximum pressure.
|
|
Set a property.
|
|
Set the hardware status listener of an SPGuiAcqu object.
|
|
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.
|
|
Set the timeout of an acquiry of an SPGuiAcqu object. The timeout handler will be called if there was no pen stroke for the duration of iTimeout milliseconds.
|
|
Set the timeout of an acquiry of an SPGuiAcqu object. The timeout handler will be called if there was no pen stroke for the duration of iTimeout milliseconds.
|
|
Set the hardware status listener of an SPGuiAcqu object.
|
|
Set the optional user parameter of an SPGuiAcqu object. The optional user parameter is not used inside SignWare, you may add one additional SPVPTR parameter for application purposes.
|
|
Set a vector listener of an SPAcquire object.
|
|
Unregister all components in acquiry mode.
|
|
Unregister all virtual buttons in acquiry mode.
|
|
Unregister a component in acquiry mode.
|
|
Unregister a virtual button in acquiry mode.
|