The Signature Capture Form Cell¶

Use the signature capture form cell to capture and save user signatures. The cell puts signature data in a wrapper so that the application developer can retrieve values of interest about the cell. The values included are: title, date/time, a bitmap of the signature, an SVG representation of the signature, and a flag indicating whether the signature is valid.

Using the Signature Capture Form Cell¶

This form cell can be used within your activity like any traditional Android view and has many customizable options:

        <com.sap.cloud.mobile.fiori.formcell.SignatureCaptureFormCell
          android:id="@+id/signature_formcell"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          app:watermarkTitle="@string/testTitle"
          app:dateTimeFormatter="@string/testDateFormat"
          app:watermarkTextAppearance="@style/WatermarkTheme"
          app:isEditable="true"
          android:maxLines="4"
          app:penColor="@color/black"
          app:penStrokeMinimumWidth="5dp"
          app:penStrokeMaximumWidth="6dp"
          app:penVelocityFilterWeight="0.9"
          app:underlineHeight="4dp"
          app:underlineColor="@color/dark_gray"
          app:underlineEnabled="true"
          app:xmarkEnabled="false"
          app:xmarkTextAppearance="@style/XmarkTheme"
          app:clearOnDoubleClick="true"
             app:bitmapMode="regular_with_watermark"
        />

Listening for Cell Value Changes¶

To listen for updates to a cell value, attach a CellValueChangeListener\<SignatureInfo> using setCellValueChangeListener:

SignatureCaptureFormCell mSignatureCell = findViewById(R.id.signature_cell);
mSignatureCell.setCellValueChangeListener(new FormCell.CellValueChangeListener<SignatureInfo>() {
            @Override
            protected void cellChangeHandler(@NonNull SignatureInfo value) {
                // App level logic
            }
        });

Also, see FormCell.

The SignatureInfo object wraps all of the important information about the cell. It can also be retrieved via mSignatureCell.getValue(). Information contained in SignatureInfo can be accessed using SignatureInfo getter methods:

Return Type	Java API	Description
`String`	`getTitle()`	Retrieve the title of the formcell.
`String`	`getDateTime()`	Retrieve the date/time of this formcell.
`Bitmap`	`getBitmap()`	Retrieve the bitmap (may or may not contain signature). See Bitmap Mode below.
`String`	`getSVG()`	Retrieve an SVG representation of the signature.
`Boolean`	`isValid()`	True if the user has signed.

The Pen¶

The signature capture form cell renders a line as the user signs with their finger.

The following attributes and APIs are available to help you control different aspects of the Pen:

XML Attribute	Java API	Description
`penColor`	`setPenColor(int)` `setPenColorFromResource(int)`	Set the color of the signature pen.
`penStrokeMinimumWidth`	`setPenStrokeMinimumWidth(float)`	Set the minimum stroke of the signature pen. Default: 3 dp
`penStrokeMaximumWidth`	`setPenStrokeMaximumWidth(float)`	Set the maximum stroke of the signature pen. Default: 7 dp
`penVelocityFilterWeight`	`setPenVelocityFilterWeight(float)`	Set the velocity filter weight of the signature pen. Default: 0.9
`isEditable`	`setEditable(boolean)`	If false, the user cannot sign the form. Default: true

Signature Pen

Watermark¶

The signature capture form cell supports a watermark that provides visual information about a signature (for validation purposes). The watermark is invisible to the user and only visible to the developer after the user has submitted their signature. The watermark label has two basic components: title and date. The title represents the reason for signing. By default, the date format is based on the user's locale. The developer cannot set the date.

The following attributes and APIs are available to help you control different aspects of the watermark:

XML Attribute	Java API	Description
`watermarkTitle`	`setWatermarkTitle(String)`	Set the reason for signing. Default: ""
`android:maxLines`	`setMaxLines(int)`	Set the maximum number of lines allowed on the title. Default: 5
`watermarkTextAppearance`	`setWatermarkTextAppearance(int)`	Set the text appearence of the watermark.
`dateTimeFormatter`	`setDateTimeFormatter(DateFormat)`	Set the date formatter.

Signature Watermark

The signature capture form cell also supports a header containing either a key or Cancel button. Both the key and Cancel button components are disabled by default.

Key¶

The main difference between the key and the watermark title is that the key may be visible to the user (the watermark stays hidden). To set the key, enable the feature on the view by calling setKeyEnabled. You can also use the app:keyEnabled XML attribute to enable the support for this feature. Once enabled, you can call setKey(CharSequence) to set the header text. Once set, the header text remains enabled until setKeyEnabled(false) is called.

Cancel Button¶

This form cell provides a Cancel button at the end of the header. The Cancel button on this view is disabled by default.

Enable the component on the view by calling setCancelButtonEnabled. You can also use the app:cancelButtonEnabled XML attribute to enable the support for this feature. Calling setOnCancelListener(View.OnClickListener) will assign a callback for when the button is clicked.

The following attributes and APIs are available to help you control or customize the Cancel button:

XML Attribute	Java API	Description
`cancelButtonEnabled`	`setCancelButtonEnabled(boolean)`	Enable or disable the Cancel button.
`cancelButtonText`	`setCancelButtonText(CharSequence)`	Set the text of the Cancel button.
Not Available	`setOnCancelListener(View.OnClickListener)`	Set a `View.OnClickListener` to trigger when the user clicks Cancel.

The signature capture form cell also supports a PersistentFooter. The footer is disabled by default.

The following attributes and APIs are available to help you control or customize the footer:

XML Attribute	Java API	Description
`footerEnabled`	`setFooterEnabled(boolean)`	Enable or disable the footer.
`saveButtonText`	`setSaveButtonText(CharSequence)`	Set the text of the Save button.
Not Available	`setOnSaveListener(View.OnClickListener)`	Set a View.OnClickListener to trigger when the user clicks Save.
`setClearButtonText`	`setClearButtonText(CharSequence)`	Set the text of the Clear button.
Not Available	`setOnClearListener(View.OnClickListener)`	Set a View.OnClickListener to trigger when the user clicks Clear.
Not Available	`swapSaveAndClearButtons()`	Swap the two buttons on the footer.

If more customization of the footer is required, call getFooter(), which will return a PersistentFooter.

Bitmap Mode¶

Bitmap mode determines which bitmap to store in SignatureInfo. You have five bitmap modes to choose from in which to contain and save the signature, as described below.

Regular¶

The bitmap will include the background of the form and the signature. You can use the app:bitmapMode="regular" XML attribute or the setBitmapMode(BitmapMode.REGULAR) method to set the cell in this mode.

Signature Regular

Regular With Watermark¶

This is the default mode for the cell. The bitmap will include the background of the form, the signature, and the watermark. You can use the app: bitmapMode="regular\_with\_watermark" XML attribute or the setBitmapMode(BitmapMode.REGULAR\_WITH\_WATERMARK) method to set the cell in this mode.

Signature Regular with Watermark

Regular With Watermark, X-Mark, and Underline¶

The bitmap will include the background of the form, the signature, the watermark, x-mark, and underline. You can use the app:bitmapMode="regular\_with\_watermark\_xmark\_underline" XML attribute or the setBitmapMode(BitmapMode.REGULAR\_WITH\_WATERMARK\_XMARK\_UNDERLINE) method to set the cell in this mode.

Signature Underline

Transparent¶

The bitmap will include only the signature itself, with a transparent background. You can use the app:bitmapMode="transparent" XML attribute or the setBitmapMode(BitmapMode.TRANSPARENT) method to set the cell in this mode.

Signature Transparent

Transparent and Trim Blank Space¶

The bitmap will include only the signature itself, with no background. You can use the app:bitmapMode="transparent\_trim\_blank\_space" XML attribute or the setBitmapMode(BitmapMode.TRANSPARENT\_TRIM\_BLANK\_SPACE) method to set the cell in this mode.

Signature Trimmed

Editable and Non-Editable Modes¶

For the signature capture form cell, editable and enabled attributes are the same: a non-editable form cell is not enabled (not signable). By default, the signature capture form cell is editable and enabled. You can control the editability of the cell by using the app:isEditable="false" XML attribute. You can also fetch the view in your activity and set it to be editable:

       mSignatureCell.setIsEditable(false);

For more information about the editable attributes, see FormCell.

Last update: December 13, 2024