SignatureCapture Meta Tag

PocketBrowser 3.x API

The SignatureCapture Meta Tag presents a rectangular box that captures a signature, hand-written notes or other data entered using the device stylus.

SignatureCapture (META Tag) Syntax 
<META HTTP-Equiv="SignatureCapture" content="[method / parameter>
 
<META HTTP-Equiv="SignatureCapture" content="SignatureSaveEvent:url('[jsFunction | url]')">

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name Description
Default Value
Clear Clears the capture area. N/A
Capture Saves the signature as a bitmap on the device and attempts to send that bitmap to the location specified in the 'Destination' parameter. N/A
Copy methods template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

Items listed in this section indicate parameters, or attributes which can be set.

Name Possible Values Description
Default Value
Visibility:[Value] 'Visible' or 'Hidden' Shows or hides the rectangular capture area By default the capture area is hidden
Border:[Value] 'Visible' or 'Hidden' Shows or hides a border for the rectangular capture area By default the border is on
Width:[Value] Positive number Sets the width of the rectangular capture area in pixels 200
Height:[Value] Positive number Sets the height of the rectangular capture area in pixels 150
Left:[Value] Positive number Sets the top left horizontal position of the rectangular capture area in pixels 15
Top:[Value] Positive number Sets the top left vertical position of the rectangular capture area in pixels 60
Penwidth:[Value] Positive number but values less than 5 are advised Sets the width of the pen line in pixels when using the device's stylus 1
Pencolor:[Value] #000000 to #FFFFFF RGB value that sets the color of the stylus pen ink using HTML web colors. #000000
BGColor:[Value] #000000 to #FFFFFF RGB value that sets the backgound color of the signature capture area #FFFFFF
Destination:[Value] Fully qualified URL or file name. Supports HTTP, FTP and File protocols. Sets the destination path and name for the signature bitmap when the 'capture' method is called. See Remarks N/A
Username:[Value] String The username for the HTTP or FTP server if required No username
Password:[Value] String The password for the HTTP or FTP server if required No password
Name:[Value] String compiant with Windows Naming restrictions When the 'Capture' method is invoked the contents of the signature capture area are saved in a bitmap in the root directory of the device. This parameter is used to specify the filename when storing the bitmap locally. Signature
Copy parameters template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

Modules return information back to their web pages via retrieval tags, for example the scanner has a retrieval tag called 'DecodeEvent' which is called whenever it decodes a barcode. To register to receive a retrieval tag call the module as follows: 

<META HTTP-Equiv="[Module]" content="[RetrievalTag]:url('[URI]')">
So to register to retrieve the Scanner's DecodeEvent the following syntax would be used: 
<META HTTP-Equiv="Scanner" content="DecodeEvent:url('Javascript:doScan('%6', '%s', %3, '%2');')">

Retrieval tags return information by replacing the text in place holders, defined as '%s' or '%<number>'. Each place holder represents 1 return value with '%s' being populated sequentially or '%<number>' providing direct acces to the desired value.

If the content for the Scanner's DecodeEvent is:

"url('Javascript:doScan('%6', '%s', %3, '%2');')"

The function would be called as follows:
"Javascript:doScan('Decode', '5449000053879', 0x35, 'SCN:EAN13');"


SignatureSaveEvent
The Signature Save Event is called when the captured signature has been successfully transfered to the specified destination. When 'Capture' is called with the HTTP protocol, the destination server message is returned. When 'Capture' is called with the FTP protocol, either 'OK: File Sent', 'OK: File Received' or 'ERROR' is returned. This tag should be used in conjunction with the Capture method.

ID Name Description
1 Transfer (Save) Result Success or failure of transfer, see note above.
Copy this return value template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript


VectorEvent
Signature data is formatted into a series of vectors and returned to the application via this callback function. The received data may not represent the entire signature as the vectors will be sent in batches if the signature is large. A single vector (array entry) contains an X, Y coordinate and the beginning / end of the signature is defined by (0xFFFF, 0xFFFF). This event is independant of the SignatureSaveEvent or capture method, when specified the event will be called whenever a 'pen up' occurs in the signature box.

ID Name Description
1 Vector Array JavaScript array of vectors which represent the signature.
Copy this return value template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript



The following META Tag example sets up a yellow rectangular area that has a border with a pen color of burgundy. When the Capture method is invoked via JavaScript the signature will be transferred to a server via HTTP and an alert will inform the user whether or not the transfer succeeded.

<META HTTP-Equiv="SignatureCapture" Content="width:200">
<META HTTP-Equiv="SignatureCapture" Content="height:100">
<META HTTP-Equiv="SignatureCapture" Content="left:20">
<META HTTP-Equiv="SignatureCapture" Content="top:60">
<META HTTP-Equiv="SignatureCapture" Content="penwidth:2">
<META HTTP-Equiv="SignatureCapture" Content="name:Sig">
<META HTTP-Equiv="SignatureCapture" Content="pencolor:#AA0000">
<META HTTP-Equiv="SignatureCapture" Content="bgcolor:#FFFF00">
<META HTTP-Equiv="SignatureCapture" Content="Visibility:Visible">
<META HTTP-Equiv="SignatureCapture" Content="Destination:url('HTTP://192.168.1.1:80/SPBlog/upload.aspx')">
<META HTTP-Equiv="SignatureCapture" Content="SignatureSaveEvent:url('javascript:alert('%s');')">
Copy example to clipboard Copy example to clipboard

The following javascript will show a Signature Capture box with default settings when the JavaScript function onDisplay is called:

<script>
function onDisplay()
{
var objGeneric = new ActiveXObject("PocketBrowser.Generic");

objGeneric.InvokeMETAFunction('SignatureCapture', 'Visibility:Visible');
}
</script>
Copy example to clipboard Copy example to clipboard

The following example shows signature vectors being displayed in an HTML table

<META HTTP-Equiv="SignatureCapture" Content="Height:200">
<META HTTP-Equiv="SignatureCapture" Content="BGColor:#FFFF00">
<META HTTP-Equiv="SignatureCapture" Content="Width:400">
<META HTTP-Equiv="SignatureCapture" Content="Visibility:Visible">
<META HTTP-Equiv="SignatureCapture" Content="PenColor:#FF00FF">
<META HTTP-Equiv="SignatureCapture" Content="PenWidth:4">
<META HTTP-Equiv="SignatureCapture" Content="VectorEvent:url('Javascript:onVectors(%s);')">

<script type="text/javascript">
function onVectors(data)
{
var VectorAsHTML = "<TABLE><TR><TH>X</TH><TH>Y</TH><TH>X</TH><TH>Y</TH><TH>X</TH><TH>Y</TH></TR>";
for (var i=0; i<data.length; i = i + 6)
{
VectorAsHTML = VectorAsHTML + "<TR>"
VectorAsHTML = VectorAsHTML + "<TD>" + data[i] + "</TD><TD>" + data[i+1] + "</TD>";
VectorAsHTML = VectorAsHTML + "<TD>" + data[i+2] + "</TD><TD>" + data[i+3] + "</TD>";
VectorAsHTML = VectorAsHTML + "<TD>" + data[i+4] + "</TD><TD>" + data[i+5] + "</TD>";
VectorAsHTML = VectorAsHTML + "</TR>"
}
VectorAsHTML + "</TABLE>"
vectorOut.innerHTML = VectorAsHTML;
}
</script>

</HEAD>
<BODY>
<BR><BR><BR><BR>
<BR><BR><BR><BR><BR>
<DIV id="vectorOut">Vectors Will Appear Here:</div>
</BODY>
Copy example to clipboard Copy example to clipboard
Scrolling
The signature capture area is not compatible with scrolling the browser window.


Parameters which clear the Signature


The signature capture area is designed to be set up prior to capturing the signature, as such the following parameters will clear any current signature: "Width", "Height", "PenColor", "BGColor".




Common Issues


The 'Visibility:Visible' parameter must be set in order to display the signature capture area.




Format of the Destination URL


The protocol, port number, username (optional) and password (optional) are all derived from the URL string and should be specified in the following manner: [protocol]://[username]:[password@]Server[:Port]FileNameAndPath.  FTP Example: ftp://admin:root@192.168.1.1:2500/Folder/Sig.bmp.  HTTP Example: http://admin:root@192.168.1.1:8080/Folder/Upload.aspx.  File Example: file://\path\Sig.bmp














Supported Platforms
Windows Mobile, Windows CE




Persistence
The signature box and Save / Vector events will be cleared during page navigation but other parameters such as position and color will persist across page loads.




Min. Requirements
Touch Screen.