Fiori Signature Capture Inline

FioriSignatureCaptureInline is a flexible Composable designed to enable inline signature capturing within your Android Jetpack Compose UI. When initialized, it overlays a scrim with a helper text instructing users to tap and begin drawing a signature. As users interact with the Composable, its state transitions through several phases – from indicating its readiness to capture a signature, to the actual capturing and eventually to the submission of the signature.

When a user submits their signature, the Composable returns a SignatureInfo object. This object stores the bitmap representation of the signature along with additional metadata, such as the date/time of the signature, its SVG representation, and the reason for signing.

Usage

FioriSignatureCaptureInline(
    onSubmit = { signatureInfo ->
        // Handle the submitted signature
    }
    // ... Add other parameters as needed
)

Customization and Parameters for Fiori Signature Capture Inline

The FioriSignatureCaptureInline provides various parameters for customization:

• onSubmit: A lambda called when the user submits their signature.
• modifier: A common parameter for applying modifications on UI elements.
• sectionHeaderText: A header displaying text, usually "Signature" or a reason for signing.
• signatureBitmap: Used to repopulate the signature, typically after a configuration change.
• bitmapMode: Allows you to control the output format of the signature.
• dateTimeFormatter: Formats the date and time shown in the watermark of the output bitmap.
• watermarkText: The text that appears on the output bitmap as a watermark.
• helperText: Text that is displayed at the center of the scrim, indicating the user should "Tap to Sign".
• showLineGuidance: Toggles the visual line guidance for the user, indicating that a signature can be drawn on top of the line.
• showXMark: Toggles the display of an x-mark, indicating that a signature can be drawn after the "x".
• colors: Defines the color palette for SignatureCaptureInline.
• styles: Sets the styles for SignatureCaptureInline.
• textStyles: Determines the text styles for SignatureCaptureInline.
• isRequiredField: If true, an asterisk is appended at the end of the header indicating this is a required field.

Bitmap Output Customization

Determine the bitmap type you'd like to receive upon the user's signature submission using the bitmapMode parameter:

FioriSignatureCaptureInline(
    bitmapMode = REGULAR_WITH_WATERMARK_XMARK_UNDERLINE,
    ...
)

Appearance and Behavior Customization

Tailor FioriSignatureCaptureInline to your needs by adjusting various visual and functional parameters:

FioriSignatureCaptureInline(
    sectionHeaderText = "Signature Confirmation",
    showLineGuidance = true,
    showXMark = true,
    helperText = "Tap here to sign"
    ...
)

The example above sets the header to "Signature Confirmation", displays line guidance and x-mark, and modifies the helper text (the default helper text is "Tap to Sign").

Stateless Signature Capture Inline

The example above illustrates how to implement a simple inline signature capture in a stateful Composable. A stateful Composable internally handles its own state, reducing boilerplate, at the cost of flexibility. Thus, the SDK also provides a stateless Composable if control of state is needed.

Signature Capture Inline State

Before diving into how to use the stateless SignatureCaptureInline, it is important to understand the states:

• ScrimPresent: The initial state. The scrim is present, prompting the user to tap to sign.
• ReadyToCapture: The component is ready to start capturing the user's signature, before any drawing action.
• Capturing: This state is active when the user is in the process of drawing the signature.
• Submitted: Triggered when the user clicks submit after drawing. At this stage, a SignatureInfo object is returned via the onSubmit callback.

Use SignatureCaptureInline in your Jetpack Compose UI, providing the necessary parameters based on your needs:

@`Composable`
fun SignatureScreen() {

    SignatureCaptureInline(
        state = SignatureCaptureInlineState.ScrimPresent,
        onScrimDismiss = {
            // Handle the scrim dismiss action callback
        },
        onSigned = {
            // Handle the initial sign action callback
        },
        onSubmit = { signatureInfo ->
            // Handle the submitted signature callback
        },
        onClear = {
            // Handle the cleared signature callback
        },
        onCancel = {
            // Handle the canceled signature callback
        },
        onReenter = {
            // Handle the re-enter signature callback
        }
    )
}

In the example above:

• We start with a state ScrimPresent, indicating that the user hasn't started drawing a signature yet.
• The onClear callback is invoked when the user clears their signature.
• The onSigned callback is invoked upon the initial signing.
• Finally, the onSubmit callback provides you with the SignatureInfo object when the user submits their signature.

Controlling State

Since SignatureCaptureInline is a stateless Composable, it is the responsibility of the application to update the state upon callbacks. For those who prefer a stateful version, consider using FioriSignatureCaptureInline.

@`Composable`
fun SignatureScreen() {

    var signatureState by remember { mutableStateOf(SignatureCaptureInlineState.ScrimPresent) }

    SignatureCaptureInline(
        state = signatureState,
        onScrimDismiss = {
            signatureState = SignatureCaptureInlineState.ReadyToCapture
        },
        onSigned = {
            signatureState = SignatureCaptureInlineState.Capturing
        },
        onSubmit = { signatureInfo ->
            signatureState = SignatureCaptureInlineState.Submitted
        },
        onClear = {
            signatureState = SignatureCaptureInlineState.ReadyToCapture
        },
        onCancel = {
            signatureState = SignatureCaptureInlineState.ScrimPresent
        },
        onReenter = {
            signatureState = SignatureCaptureInlineState.ReadyToCapture
        }
    )
}

In the example above:

• The onScrimDismiss callback now resets the state to SignatureCaptureState.ReadyToCapture.
• The onSigned callback now updates the state to SignatureCaptureInlineState.Capturing.
• The onSubmit callback now resets the state to SignatureCaptureInlineState.Submitted.
• The onClear callback now resets the state to SignatureCaptureInlineState.ReadyToCapture.
• The onCancel callback now resets the state to SignatureCaptureInlineState.ScrimPresent.
• The onReenter callback now resets the state to SignatureCaptureInlineState.ReadyToCapture.

Customization and Parameters for Stateless Signature Capture Inline

The SignatureCaptureInline provides various parameters for customization:

• modifier: A common parameter for applying modifications to UI elements.
• signatureBitmap: Used to repopulate the signature, typically after a configuration change.
• state: Helps to display the correct UI.
• bitmapMode: Controls the output format of the signature.
• dateTimeFormatter: Formats the date and time shown in the watermark of the output bitmap.
• watermarkText: The text that appears on the output bitmap as a watermark.
• onScrimDismiss: A lambda called when the user taps the scrim.
• onSigned: A lambda called when the user starts drawing a signature.
• onSubmit: A lambda called when the user submits their signature.
• onCancel: A lambda called when the user cancels their signature.
• onReenter: A lambda called when the user reenters their signature.
• sectionHeaderText: A header Composable displaying text, usually "Signature" or a reason for signing.
• topActionButton: A Composable displayed at the top-end corner of the component after the scrim has been tapped. If providing a custom cancel button, then the onClick callback should set the state to SignatureCaptureInlineState.ScrimPresent.
• helperText: Text that is displayed at the center of the scrim, indicating the user should "Tap to Sign".
• footerBeforeSubmit: A footer Composable to be displayed before the user submits.
• footerAfterSubmit: A footer Composable to be displayed after the user submits.
• showLineGuidance: Toggles line guidance for the user.
• showXMark: Toggles the display of an x-mark.
• colors: Defines the color palette for SignatureCaptureInline.
• styles: Sets the styles for SignatureCaptureInline.
• textStyles: Determines the text styles for SignatureCaptureInline.

Controlling Bitmap Output

Based on requirements, you can modify the type of bitmap you wish to receive once the user submits their signature using the bitmapMode parameter:

SignatureCaptureInline(
    bitmapMode = REGULAR_WITH_WATERMARK_XMARK_UNDERLINE
    ...
)

Customizing Appearance and Behavior

SignatureCaptureInline is designed for flexibility. You can customize its header text, action buttons, helper text, footers, and various visual elements:

SignatureCaptureInline(
    sectionHeaderText = {
        Text(text = "Please Sign Below")
    },
    topActionButton = {
        IconButton(onClick = { /* Handle custom action */ }) {
            Icon(Icons.Default.Close, contentDescription = "Cancel Signature")
        }
    },
    helperText = "Tap to begin your signature"
    ...
)

This snippet customizes the header to display "Please Sign Below", adds a close icon as the top action button, and sets the helper text.

---

Last update: December 13, 2024