The Inline Signature Capture Form Cell¶

The scrolling-friendly signing pad is an extension of SignatureCaptureFormCell. It is intended for use as a list item (such as a RecyclerView row item), but may also be used like any other widget in an activity. At first glance, a scrim and a helper text are visible, prompting the user to "tap to start signing." The user can either ignore the form cell (and keep scrolling) or tap the scrim to start signing. The user can then save or clear the form with the buttons provided in the footer.

Signature Inline Demo

The default behavior upon clicking Save consists of:

The form becomes no longer editable, which means any user input will be interpreted as scrolling.
The footer containing the Clear and Save buttons is swapped with another footer containing a Re-enter button that allows the user to re-enter their signature.
Reduced opacity is applied to the signature to indicate the signature has been saved.
If there is no signature present, the form will return to its initial UI state (the scrim and helper text become enabled).

Example of the form cell within a RecyclerView:

Signature Inline Tablet

Using the Inline Signature Capture Form Cell¶

This form cell inherits attributes from SignatureCaptureFormCell. A new capability is the support of helper text, described below:

        <com.sap.cloud.mobile.fiori.formcell.SignatureCaptureInline
        android:id="@+id/signature_formcell_inline"
        android:layout_width="match_parent"
        android:layout_height="300dp"
        app:helperEnabled="true"
        app:helperTextAppearance="@style/text_appearance"
        app:helperText="Tap to sign" />

Listening for Cell Value Changes¶

See SignatureCaptureFormCell.

Helper Text¶

To enable or disable the helper text on the view, callsetHelperEnabled.

You can also use the app:helperEnabled XML attribute to enable support for this feature. Once enabled, you can call setHelperText to set the helper text. Once set, the helper text will remain enabled until the user taps the scrim or setHelperEnabled(false) is called.

The signature capture form cell also supports a header containing either a key or Cancel button. Unlike the header in the base class SignatureCaptureFormCell, the header on this view is enabled by default.

Key¶

The main difference between the key and the watermark title is that the key may be visible to the user. 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 key 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 will be enabled when the user taps the scrim.

When the user clicks the Cancel button, the form will be cleared of any signature input and the scrim will reappear (the Cancel button will be hidden again).

There is an additional set of methods that are not included in the base class: setUseCancelButton(boolean) and isUsingCancelButton(). Please note that setCancelButtonEnabled(boolean) and setUseCancelButton(boolean) are used differently:

setCancelButtonEnabled(boolean) toggles the visibility of the Cancel button but is also called internally based on the presence of a submitted signature or the scrim overlay.
setUseCancelButton(boolean) dismisses the use of the Cancel button throughout the entire user flow as well as being ignored internally.

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.
Not Avaliable	`setUseCancelButton(Boolean)`	Dismisses the use of of the Cancel button throughout the entire user flow as well as being ignored internally.

This form cell adds some internal functionality to the Save button (as described above), all of which may be overridden. The Clear button also has one predefined behavior (clearing the form). The footer is enabled by default.

Signature Inline Default Footer

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

XML Attribute	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 2 buttons on the footer.

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

This form cell makes use of switching between two footers, both of type PersistentFooter. By default, this footer becomes enabled after the user has signed and clicked Save.

When the user clicks the Re-enter button, the form clears and the initial footer is swapped back in, allowing the user to start signing again.

Signature Inline Reenter Footer

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

XML Attribute	API	Description
Not Available	`setOnReenterClickListener(View.OnClickListener)`	(Optional) Add a callback to be triggered when the user clicks Re-enter.

If more customization of the re-enter footer is required, call getReenterFooter(), which will return a PersistentFooter.

Editable and Non-Editable Modes¶

For the inline 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.

Required Field Indicator¶

The inline signature capture can be marked as a required, appending an asterisk symbol at the end of the header.

       mSignatureCell.setIsRequired(true);

For more information about the editable attributes, see FormCell.

Restoring UI State After a Configuration Change¶

An important feature to note is that saving the UI state is automatic when a configuration change occurs. The method of saving involves a ViewModel which stores a SignatureInlineUIState. The contents are destroyed as soon as the Activity or Fragment is destroyed.

A SignatureInlineUIState consists of:

The view's id
A flag indicating whether the scrim is visible
A dark signature Bitmap(for dark mode)
A light signature Bitmap (for light mode)

Signature Inline Configuration Change

Note

If there is a signature present and the user has not clicked Save, the signature will not be restored upon a configuration change. This results in the initial UI state being loaded (with the scrim and helper text present).

Last update: December 13, 2024