Sain

https://joelkanyi.github.io/sain/
Admin
Sain is a Compose Multiplatform library for capturing and exporting customizable signatures as...
Tokens:6,183
Snippets:74
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Sain Usage Example

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-sain.html

An example of implementing the Sain composable with custom signature pad styling and completion handling.

```kotlin
Sain(
    signatureHeight = 250.dp,
    signaturePadColor = Color.White,
    signatureBorderStroke = BorderStroke(
        width = .5.dp,
        color = MaterialTheme.colorScheme.onSurface,
    ),
    signaturePadShape = RoundedCornerShape(8.dp),
    onComplete = onComplete
) { action ->  }
```

--------------------------------

### SignatureLine(start: Offset, end: Offset)

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-line/-signature-line.html

Creates a SignatureLine instance with the given start and end offsets.

```APIDOC
## SignatureLine(start: Offset, end: Offset)

### Description
Creates a SignatureLine with the specified start and end points.

### Parameters
- **start** (Offset) - Required - The starting point of the line.
- **end** (Offset) - Required - The ending point of the line.

```

--------------------------------

### SignatureLine properties

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-line/index.html

Read-only properties of SignatureLine representing the start and end offsets.

```APIDOC
## SignatureLine properties

### Description
Read-only properties of SignatureLine representing the start and end offsets.

### Properties
- **start** (Offset) - The starting point of the line.
- **end** (Offset) - The ending point of the line.

```

--------------------------------

### Add Multiplatform Dependency via Version Catalog

Source: https://joelkanyi.github.io/sain/get-started

Configure the library in libs.versions.toml and apply it in build.gradle.kts.

```toml
[versions]
sain = "<latest-version>"

[libraries]
sain = { module = "io.github.joelkanyi:sain", version.ref = "sain" }

```

```kotlin
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation(libs.sain)
            }
        }
    }
}

```

--------------------------------

### Configure Version Catalog for Multiplatform

Source: https://joelkanyi.github.io/sain

Define the Sain library in your libs.versions.toml file.

```toml
[versions]
sain = "<latest-version>"

[libraries]
sain = { module = "io.github.joelkanyi:sain", version.ref = "sain" }
```

--------------------------------

### Implement Version Catalog Dependency in Multiplatform

Source: https://joelkanyi.github.io/sain

Add the library dependency to your build.gradle.kts using the version catalog reference.

```kotlin
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation(libs.sain)
            }
        }
    }
}
```

--------------------------------

### Add Android Dependency via Version Catalog

Source: https://joelkanyi.github.io/sain/get-started

Configure the library in libs.versions.toml and apply it in the Android app's build.gradle.kts.

```toml
[versions]
sain = "<latest-version>"

[libraries]
sain = { module = "io.github.joelkanyi:sain", version.ref = "sain" }

```

```kotlin
dependencies {
    implementation(libs.sain)
}

```

--------------------------------

### SignatureState constructor

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-state/index.html

Creates a new instance of SignatureState.

```APIDOC
## SignatureState()

### Description
Creates a new instance of SignatureState.

### Constructor
`SignatureState()`
```

--------------------------------

### Implement Version Catalog Dependency in Android

Source: https://joelkanyi.github.io/sain

Add the library dependency to your Android app's build.gradle.kts using the version catalog reference.

```kotlin
dependencies {
    implementation(libs.sain)
}
```

--------------------------------

### Export signature as PNG bytes and Base64

Source: https://joelkanyi.github.io/sain/usage

Inside the onComplete callback, converts the signature bitmap to PNG bytes and a Base64 string using toPngByteArray() and toBase64(). toBase64() returns only the Base64 payload; prefix with data:image/png;base64, for HTML img tags.

```Kotlin
Sain(
    onComplete = { signatureBitmap ->
        if (signatureBitmap != null) {
            val pngBytes = signatureBitmap.toPngByteArray()
            val base64 = signatureBitmap.toBase64()
            // Store or transfer the bytes or the Base64 string as needed
        }
    },
    ...
)

```

--------------------------------

### SignatureAction.COMPLETE

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-action/index.html

Represents the action to finalize the signature and deliver the rendered ImageBitmap via the onComplete callback.

```APIDOC
## SignatureAction.COMPLETE

### Description
Finalizes the signature and delivers the rendered androidx.compose.ui.graphics.ImageBitmap via the onComplete callback.

### Enum Entry
COMPLETE

### Usage
This entry is used to indicate that the signature is complete and should be processed.
```

--------------------------------

### Basic Sain composable usage with Clear and Complete buttons

Source: https://joelkanyi.github.io/sain/usage

Adds the Sain composable with a signature pad and action buttons. The actions trailing lambda provides an action callback to control the pad via SignatureAction.CLEAR and SignatureAction.COMPLETE. The onComplete callback receives the signature bitmap or null if empty.

```Kotlin
var imageBitmap by remember { mutableStateOf<ImageBitmap?>(null) }

Sain(
    signatureHeight = 250.dp,
    signaturePadColor = Color.White,
    signatureBorderStroke = BorderStroke(
        width = .5.dp,
        color = MaterialTheme.colorScheme.onSurface,
    ),
    signaturePadShape = RoundedCornerShape(8.dp),
    onComplete = { signatureBitmap ->
        if (signatureBitmap != null) {
            imageBitmap = signatureBitmap
        } else {
            println("Signature is empty")
        }
    },
) { action ->
    Row(
        modifier = Modifier
            .padding(top = 16.dp)
            .fillMaxWidth(),
        horizontalArrangement = Arrangement.spacedBy(16.dp),
    ) {
        Button(
            modifier = Modifier.weight(1f),
            onClick = {
                imageBitmap = null
                action(SignatureAction.CLEAR)
            },
        ) {
            Text("Clear")
        }
        Button(
            modifier = Modifier.weight(1f),
            onClick = {
                action(SignatureAction.COMPLETE)
            },
        ) {
            Text("Complete")
        }
    }
}

```

--------------------------------

### fun ImageBitmap.toBase64(): String

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/to-base64.html

Encodes this ImageBitmap to a Base64 string of its PNG representation. The returned string contains only the Base64 payload; prepend 'data:image/png;base64,' for use in HTML img tags.

```APIDOC
## fun ImageBitmap.toBase64(): String

### Description
Encodes this ImageBitmap to a Base64 string of its PNG representation. The returned string contains only the Base64 payload. To use it in an HTML `img` tag or similar, prepend `data:image/png;base64,` to it.

### Method
Extension function

### Signature
`fun ImageBitmap.toBase64(): String`

### Parameters
None

### Return
- **String** - The Base64-encoded PNG representation of this bitmap.

### Usage Example
```kotlin
val base64String = imageBitmap.toBase64()
val dataUri = "data:image/png;base64,$base64String"
```
```

--------------------------------

### Add Maven Central Repository

Source: https://joelkanyi.github.io/sain/get-started

Ensure the Maven Central repository is included in your project's repositories block.

```kotlin
repositories {
    mavenCentral()
}

```

--------------------------------

### Add Multiplatform Dependency via Kotlin DSL

Source: https://joelkanyi.github.io/sain/get-started

Add the Sain dependency to your commonMain source set using Kotlin DSL.

```kotlin
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("io.github.joelkanyi:sain:<latest-version>")
            }
        }
    }
}

```

--------------------------------

### Import Sain Composable

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-sain.html

The import statement required to use the Sain composable in your project.

```kotlin
import io.github.joelkanyi.sain.Sain
```

--------------------------------

### rememberSignatureState()

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/remember-signature-state.html

Creates and remembers a SignatureState that survives configuration changes (e.g. screen rotation) via rememberSaveable. Returns a remembered SignatureState instance.

```APIDOC
## rememberSignatureState()

### Description
Creates and remembers a SignatureState that survives configuration changes (e.g. screen rotation) via rememberSaveable.

### Method
@Composable fun rememberSignatureState(): SignatureState

### Parameters
None

### Return
A remembered SignatureState instance.

```

--------------------------------

### Sain composable function

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/index.html

A composable that allows the user to draw a signature on the screen. The resulting signature is returned as an ImageBitmap.

```APIDOC
## Sain composable function

### Description
A composable that allows the user to draw a signature on the screen. The resulting signature is returned as an ImageBitmap.

### Signature
@Composable
fun Sain(
    onComplete: (signature: ImageBitmap?) -> Unit,
    modifier: Modifier = Modifier,
    signatureColor: Color = Color.Black,
    signatureThickness: Dp = 5.dp,
    signatureHeight: Dp = 250.dp,
    signaturePadColor: Color = Color.White,
    signatureBorderStroke: BorderStroke = BorderStroke(color = Color.Black, width = .5.dp),
    signaturePadShape: CornerBasedShape = RoundedCornerShape(8.dp),
    state: SignatureState = rememberSignatureState(),
    showGuideline: Boolean = true,
    guidelineColor: Color = Color.Gray,
    guidelineStrokeWidth: Dp = 1.dp,
    guidelineDashIntervals: FloatArray = floatArrayOf(16f, 16f),
    guidelinePadding: Dp = 16.dp,
    guidelineCornerRadius: Dp = 8.dp,
    hintText: String = "Sign within this area",
    hintTextStyle: TextStyle = TextStyle(color = Color.Gray, fontSize = 16.sp, textAlign = TextAlign.Center),
    actions: @Composable (action: (SignatureAction) -> Unit) -> Unit
)

### Parameters
- **onComplete** (function) - Required - Callback invoked with the resulting signature as an ImageBitmap or null.
- **modifier** (Modifier) - Optional - Modifier to be applied to the composable.
- **signatureColor** (Color) - Optional - Color of the signature strokes.
- **signatureThickness** (Dp) - Optional - Thickness of the signature strokes.
- **signatureHeight** (Dp) - Optional - Height of the signature pad.
- **signaturePadColor** (Color) - Optional - Background color of the signature pad.
- **signatureBorderStroke** (BorderStroke) - Optional - Border stroke of the signature pad.
- **signaturePadShape** (CornerBasedShape) - Optional - Shape of the signature pad.
- **state** (SignatureState) - Optional - State object holding the signature lines and bitmap.
- **showGuideline** (Boolean) - Optional - Whether to show a guideline.
- **guidelineColor** (Color) - Optional - Color of the guideline.
- **guidelineStrokeWidth** (Dp) - Optional - Stroke width of the guideline.
- **guidelineDashIntervals** (FloatArray) - Optional - Dash intervals for the guideline.
- **guidelinePadding** (Dp) - Optional - Padding around the guideline.
- **guidelineCornerRadius** (Dp) - Optional - Corner radius of the guideline.
- **hintText** (String) - Optional - Hint text displayed on the signature pad.
- **hintTextStyle** (TextStyle) - Optional - Style for the hint text.
- **actions** (composable function) - Required - Composable lambda that provides an action dispatcher for signature actions.
```

--------------------------------

### SignatureAction.CLEAR

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-action/index.html

Represents the action to clear the signature pad, erasing all drawn lines and resetting it to its initial empty state.

```APIDOC
## SignatureAction.CLEAR

### Description
Clears all drawn lines, resetting the signature pad to its initial empty state.

### Enum Entry
CLEAR

### Usage
This entry is used to indicate that the signature pad should be cleared.
```

--------------------------------

### Add Android Dependency via Kotlin DSL

Source: https://joelkanyi.github.io/sain/get-started

Add the Sain dependency directly to your Android app's build.gradle.kts.

```kotlin
dependencies {
    implementation("io.github.joelkanyi:sain:<latest-version>")
}

```

--------------------------------

### updateSignature

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-state/index.html

Updates the rendered signature bitmap.

```APIDOC
## updateSignature(bitmap: ImageBitmap)

### Description
Updates the rendered signature bitmap.

### Function
`fun updateSignature(bitmap: ImageBitmap)`

### Parameters
- **bitmap** (ImageBitmap) - Required - The new signature bitmap.
```

--------------------------------

### ImageBitmap.toPngByteArray()

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/to-png-byte-array.html

Encodes this ImageBitmap to a PNG byte array. Returns the PNG-encoded bytes of the bitmap.

```APIDOC
## ImageBitmap.toPngByteArray()

### Description
Encodes this ImageBitmap to a PNG byte array.

### Method
Extension function

### Signature
actual fun ImageBitmap.toPngByteArray(): ByteArray
expect fun ImageBitmap.toPngByteArray(): ByteArray

### Return
ByteArray - The PNG-encoded bytes of this bitmap.
```

--------------------------------

### Deprecated Sain composable

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-sain.html

The deprecated overload of the Sain composable. It has been deprecated in favor of using the main Sain composable with additional parameters for signatureHeight, signaturePadColor, signatureBorderStroke, and signaturePadShape.

```APIDOC
## Deprecated Sain composable

### Description
This function has been deprecated in favor of using the Sain composable with the signatureHeight, signaturePadColor, signatureBorderStroke, and signaturePadShape parameters.

### Deprecation
Deprecated: This function has been deprecated in favor of using the Sain composable with the signatureHeight, signaturePadColor, signatureBorderStroke, and signaturePadShape parameters.

### Replace With
```kotlin
import io.github.joelkanyi.sain.Sain

Sain(
    signatureHeight = 250.dp,
    signaturePadColor = Color.White,
    signatureBorderStroke = BorderStroke(
        width = .5.dp,
        color = MaterialTheme.colorScheme.onSurface,
    ),
    signaturePadShape = RoundedCornerShape(8.dp),
    onComplete = onComplete
) { action ->  }
```

### Function Signature
```kotlin
@Composable
fun ~~Sain~~(
    onComplete: (signature: ImageBitmap?) -> Unit,
    modifier: Modifier = Modifier,
    signatureColor: Color = Color.Black,
    signatureThickness: Dp = 5.dp,
    state: SignatureState = rememberSignatureState(),
    actions: @Composable (action: (SignatureAction) -> Unit) -> Unit
)
```

### Parameters
- **onComplete** (callback) - Required - The callback that is called when the signature is completed. This callback receives a nullable ImageBitmap of the signature and can be utilized to check if the signature is empty.
- **modifier** (Modifier) - Optional - The modifier to apply to the signature.
- **signatureColor** (Color) - Optional - The color of the signature.
- **signatureThickness** (Dp) - Optional - The thickness of the signature. Note that the thickness is multiplied by 3 to make the signature more visible.
- **state** (SignatureState) - Optional - The state of the signature.
- **actions** (composable) - Required - The composable that provides the actions that can be performed on the signature. We only have two actions: SignatureAction.CLEAR and SignatureAction.COMPLETE.
```

--------------------------------

### ImageBitmap.toPngByteArray extension function

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/index.html

Encodes this ImageBitmap to a PNG byte array. Available on Android, common, and Skiko platforms.

```APIDOC
## ImageBitmap.toPngByteArray extension function

### Description
Encodes this ImageBitmap to a PNG byte array. Available on Android, common, and Skiko platforms.

### Signature
actual fun ImageBitmap.toPngByteArray(): ByteArray
expect fun ImageBitmap.toPngByteArray(): ByteArray
actual fun ImageBitmap.toPngByteArray(): ByteArray

### Returns
- **ByteArray** - The PNG-encoded byte array of the image.
```

--------------------------------

### values()

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-action/values.html

Returns an array containing the constants of the SignatureAction enum type, in the order they're declared. This method may be used to iterate over the constants.

```APIDOC
## values()

### Description
Returns an array containing the constants of the SignatureAction enum type, in the order they're declared. This method may be used to iterate over the constants.

### Method
values()

### Return Type
Array<SignatureAction>

### Returns
An array of SignatureAction enum constants in declaration order.
```

--------------------------------

### entries

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-action/entries.html

Returns a representation of an immutable list of all enum entries, in the order they're declared. This method may be used to iterate over the enum entries.

```APIDOC
## entries

### Description
Returns a representation of an immutable list of all enum entries, in the order they're declared. This method may be used to iterate over the enum entries.

### Property
`val entries: EnumEntries<SignatureAction>`

### Returns
- **EnumEntries<SignatureAction>** - An immutable list of all enum entries in declaration order.
```

--------------------------------

### Saver

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-state/-companion/index.html

A property that provides a Saver for SignatureState, allowing state to be saved and restored.

```APIDOC
## Saver

### Description
A val property of type Saver<SignatureState, Any> that provides a mechanism to save and restore SignatureState instances.

### Declaration
val Saver: Saver<SignatureState, Any>

### Type
Saver<SignatureState, Any>

### Usage
This property is part of the Companion object of SignatureState and can be accessed as SignatureState.Companion.Saver.
```

--------------------------------

### addSignatureLine

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-state/index.html

Adds a signature line to the internal state.

```APIDOC
## addSignatureLine(signatureLine: SignatureLine)

### Description
Adds a signature line to the internal state.

### Function
`fun addSignatureLine(signatureLine: SignatureLine)`

### Parameters
- **signatureLine** (SignatureLine) - Required - The signature line to add.
```

--------------------------------

### clearSignatureLines

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-state/index.html

Clears all signature lines from the internal state.

```APIDOC
## clearSignatureLines()

### Description
Clears all signature lines from the internal state.

### Function
`fun clearSignatureLines()`
```

--------------------------------

### valueOf(value: String): SignatureAction

Source: https://joelkanyi.github.io/sain/kdoc/sain/io.github.joelkanyi.sain/-signature-action/value-of.html

Returns the enum constant of SignatureAction with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. Throws IllegalArgumentException if no constant with the specified name exists.

```APIDOC
## valueOf(value: String): SignatureAction

### Description
Returns the enum constant of SignatureAction with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. Extraneous whitespace characters are not permitted.

### Method
valueOf

### Parameters
- **value** (String) - Required - The name of the enum constant to return.

### Returns
- **SignatureAction** - The enum constant with the specified name.

### Throws
- **kotlin.IllegalArgumentException** - if this enum type has no constant with the specified name.
```
Tokens:
Raw