Quick Tutorial - Capturing a Signature
Description
This tutorial will demonstrate the controls and methods used to create an area where customer signatures may be recorded, stored and retrieved.
Resources
The Scribble Control
A user’s signature can be captured via the form control known as a Scribble. This scribble control captures the input of a stylus over its bounds, and is represented by default as a white, bordered box when dragged and dropped onto the form from the Controls toolbar.
Scribbles have several properties which can change its behaviour on execution.
When incorporating signatures in an application, the size of the box, the width of the pen and the colour may be useful properties to consider when defining the scribble. Most importantly, ensure that the ‘Read Only’ property is set as ‘false’, otherwise a scribble that will not register user input within its bounds will be created. It is set to false by default.
The Scribble Object
Scribbles are also similar to other controls, as they have a number of methods associated with it under the Form > Controls > [scribble name] folder of the data source tree. However, they also contain unique methods such as IsDirty(), which determines if the scribble has had any user input assigned to it, and Reset() which will clear any captured data.
The scribble can also be used to load a binary image, or an image from a file.
Scribbles and the Database
Scribbles can be written to the database as is, provided that the output field of the specified query is defined as a base64Binary under the Tables of a project. For example:
Database.Reset();
Database.SetQueryParam("pItemID", id_field);
Database.AddColumn("SIGNATURE", sig_field);
Database.UpdateRecords("qSignFilter");
Like most form controls, the binary image data can be accessed and assigned through the Forms > Controls folder in the data source tree. For example, a binary image from a scribble can be assigned to a binary variable as shown below.
Variable1 = sig_field
Data can also be loaded into a scribble, typically through the assignment operator. Therefore, the following line in an expression, for example:
sig_field = SIGNATURE
In the above example the SIGNATURE operand is a data source located under Form > Data of a form which uses Data Binding via a Form Query. Similarly, scribbles can be loaded or saved to through the Data Binding tab in the Forms tab.
When saved, scribble data is stored within the local database
as a compressed binary, encoded in the base64binary format. BrightXpress
Applications may read this or uncompressed data directly from
the device database, however, if required to be saved as-is on
the server, decompression via the 'Needs to Decompress' mapping
option may be used between device and server table sync points.
For more information, please refer to the BrightServer
> Mappings section of this document.
Alternatively, the scribble image data may be unzipped on the device before saving to the local database, for example, local.vData = Zip.UnzipBinary(sig_field).
For more information on these processes, please refer to the Synchronising Scribble Data tutorial.
Exercise
The Signature form contains a status box which you can use to test the features of the scribble, and display the status of the application. Complete the application by creating expressions for the following controls:
Load_btn_Click: Loads whatever is in the database under the given ID into the sig_field control. Depending on what is loaded (i.e., if there is an image existing or not), the application will update the status_field control to notify the user. The data binding portion of this exercise has already been completed.
Clear_btn_Click: Clears the scribble on click and displays a status message notifying the user of this state.
Save_btn_Click: Stores the scribble in the database, using the database object. If the scribble contains no data, display an error message, else, if a signature is valid, close the form. Use the Objects > Controls > sig_field.IsDirty() method to check if the scribble contains valid information.
A possible solution is contained in ScribbleFinished.bsp.