Getting Started - PDF Generator

📋 Requirements

Before you begin, make sure your project meets the following requirements:

Requirement	Minimum	Recommended
Android SDK	API 24 (Android 7.0)	API 26+
Kotlin	1.8.0	1.9.0+
Gradle	7.0	8.0+
Java	11	17

📦 Installation

Add the PDF Generator dependency to your module's build.gradle.kts file:

Kotlin DSL (build.gradle.kts)

app/build.gradle.kts

dependencies {
    implementation("io.github.alims-repo:pdf-generator:1.0.6-beta")
}

Groovy (build.gradle)

app/build.gradle

dependencies {
    implementation 'io.github.alims-repo:pdf-generator:1.0.6-beta'
}

Then sync your project with Gradle files.

💡 Maven Central

PDF Generator is published on Maven Central. Most projects have Maven Central configured by default. If not, add mavenCentral() to your repositories in settings.gradle.kts.

⚡ Basic Usage

Creating a PDF is straightforward with the Kotlin DSL:

MainActivity.kt

import io.github.alimsrepo.pdf.generator.pdf
import io.github.alimsrepo.pdf.generator.saveToFile
import io.github.alimsrepo.pdf.generator.config.PageSize
import io.github.alimsrepo.pdf.generator.config.PageMargins
import java.io.File

// Create output file
val outputFile = File(context.cacheDir, "my_document.pdf")

// Generate PDF using DSL
val result = pdf {
    // Configure page settings
    pageSize(PageSize.A4)
    margins(PageMargins.NORMAL)

    // Add content
    title("Hello, PDF Generator!")

    spacer(16f)

    text("This is a simple paragraph of text.")

    spacer(24f)

    heading("Features")
    bulletList(
        "Easy to use",
        "Kotlin DSL",
        "Automatic pagination"
    )

    spacer(24f)

    divider()

    spacer(24f)

    table {
        header("Name", "Email", "Role")
        row("John Doe", "john@example.com", "Developer")
        row("Jane Smith", "jane@example.com", "Designer")
    }
}.saveToFile(outputFile)

// Handle result
result.fold(
    onSuccess = { file ->
        println("PDF saved to: ${file.absolutePath}")
        // Open or share the PDF
    },
    onFailure = { error ->
        println("Error generating PDF: ${error.message}")
    }
)

✅ Best Practice

Always handle the result properly using fold(), getOrNull(), or similar Result handling methods to gracefully handle any errors.

🔄 DSL vs Builder API

PDF Generator offers two ways to create PDFs:

1. Kotlin DSL (Recommended)

The DSL provides a clean, declarative syntax that's easy to read and write:

pdf {
    pageSize(PageSize.A4)
    title("My Document")
    text("Some content...")
    table {
        header("Col1", "Col2")
        row("A", "B")
    }
}.saveToFile(file)

2. Builder API

The builder API provides a fluent, chainable interface:

PdfBuilder()
    .setPageSize(PageSize.A4)
    .addTitle("My Document")
    .addText("Some content...")
    .addTable(listOf(
        TableRow(listOf(TableCell("Col1"), TableCell("Col2")), isHeader = true),
        TableRow(listOf(TableCell("A"), TableCell("B")))
    ))
    .buildSync(PdfOutput.ToFile(file))

Both approaches produce identical results. Choose the one that fits your coding style!

📤 Output Options

PDF Generator supports multiple output formats:

Save to File

val file = File(context.cacheDir, "document.pdf")
pdf { ... }.saveToFile(file)

Save to Path

pdf { ... }.saveToPath(
    directoryPath = context.cacheDir.absolutePath,
    fileName = "document.pdf"
)

Get as ByteArray

val result = pdf { ... }.toByteArray()
result.onSuccess { bytes ->
    // Use byte array for upload, etc.
}

Write to OutputStream

val outputStream = FileOutputStream(file)
pdf { ... }.toOutputStream(outputStream)

🔐 Permissions

PDF Generator doesn't require any special permissions when saving to app-private directories like cacheDir or filesDir.

However, if you need to save to external storage or share PDFs, consider:

For Sharing PDFs

Use FileProvider to share PDFs with other apps:

// In AndroidManifest.xml, add FileProvider
<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/file_paths" />
</provider>

// Share the PDF
val uri = FileProvider.getUriForFile(
    context,
    "${context.packageName}.fileprovider",
    pdfFile
)

val shareIntent = Intent(Intent.ACTION_SEND).apply {
    type = "application/pdf"
    putExtra(Intent.EXTRA_STREAM, uri)
    addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
}

startActivity(Intent.createChooser(shareIntent, "Share PDF"))

🎯 Next Steps

Now that you have PDF Generator installed, explore more features:

📋 Features - Explore all available content elements
📖 API Reference - Detailed documentation of all methods
💡 Examples - Real-world examples and use cases

📣 Need Help?

If you encounter any issues, please open an issue on GitHub.

🚀 Getting Started