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 is used for providing 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 will be 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 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

User Guidance: Underline and X-Mark

The signature capture form cell also supports visual guidance for the user by providing an x-mark and a signature underline. These components are enabled by default, but (by default) are invisible to the developer when the user submits their signature.

The following attributes and APIs are available to help you control different aspects of these two components. Note: there is no attribute for underline width but it can be modified by modifying the horizontal margin.

XML Attribute Java API Description
underlineHeight setUnderlineWidthAndHeight(int, int) Set the dimensions of the signature underline.
underlineColor setUnderlineColor(int) setUnderlineColorFromResource(int) Set the color of the underline.
underlineEnabled setUnderlineEnabled(boolean) Enable or disable the underline, altering its visibility.
xmarkTextAppearance setXmarkTextAppearance(int) Set the text appearence of the watermark.
xmarkEnabled setXmarkEnabled(boolean) Enable or disable the x-mark, altering its visibility.

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: August 12, 2020