Skip to content

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 key, represented as a header. This component is disabled by default. 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 header, 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.

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:editable="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: January 11, 2021