📖 API Reference

Complete documentation of all classes, methods, and configurations

PdfDsl

The main DSL class for building PDFs with a declarative syntax.

Entry Point

pdf { }

Function

Creates a new PDF document using the DSL syntax.

fun pdf(block: PdfDsl.() -> Unit): PdfBuilder
Parameters
block PdfDsl.() -> Unit DSL block for configuring the PDF

Page Configuration Methods

pageSize(size: PageSize)

Set the page size using a predefined size.

Parameters
size PageSize A4, A3, A5, A6, LETTER, LEGAL

pageSizeMm(width: Float, height: Float)

Set a custom page size in millimeters.

orientation(orientation: PageOrientation)

Set page orientation (PORTRAIT or LANDSCAPE).

margins(margins: PageMargins)

Set page margins using a preset.

margins(top: Float, bottom: Float, left: Float, right: Float)

Set custom page margins in points.

Content Methods

title(content: String, size: Float = 24f, align: TextAlign = LEFT)

Add a title text element with large, bold styling.

heading(content: String, size: Float = 18f, align: TextAlign = LEFT)

Add a heading text element.

subheading(content: String, size: Float = 14f, align: TextAlign = LEFT)

Add a subheading text element.

text(content: String, size: Float = 12f, color: Int, typeface: Typeface, align: TextAlign)

Add a text paragraph with full customization options.

Parameters
content String The text content
size Float Font size in points (default: 12f)
color Int Text color as ARGB integer (default: black)
typeface Typeface Android Typeface (default: Typeface.DEFAULT)
align TextAlign LEFT, CENTER, or RIGHT (default: LEFT)

image(bitmap: Bitmap, width: Float?, height: Float?, align: TextAlign)

Add an image to the document.

spacer(height: Float)

Add vertical space in points.

divider(thickness: Float = 1f, color: Int)

Add a solid horizontal line.

dashedDivider(thickness: Float = 1f, color: Int)

Add a dashed horizontal line.

bulletList(vararg items: String)

Add a bullet list.

numberedList(vararg items: String)

Add a numbered list.

pageBreak()

Force content to start on a new page.

table { }

Add a table using the table DSL.

table {
    header("Col1", "Col2", "Col3")
    row("A", "B", "C")
    row("D", "E", "F")
}

PdfBuilder

The fluent builder class for creating PDFs programmatically.

PdfBuilder()
    .setPageSize(PageSize.A4)
    .setOrientation(PageOrientation.PORTRAIT)
    .setMargins(PageMargins.NORMAL)
    .addTitle("Document")
    .addText("Content...")
    .buildSync(PdfOutput.ToFile(file))

Build Methods

buildSync(output: PdfOutput): Result<PdfResult>

Build the PDF synchronously and return the result.

build(output: PdfOutput, listener: PdfGenerationListener)

Build the PDF asynchronously with a callback listener.

Page Configuration Classes

PageSize

enum class PageSize {
    A3,      // 297 × 420 mm
    A4,      // 210 × 297 mm (default)
    A5,      // 148 × 210 mm
    A6,      // 105 × 148 mm
    LETTER,  // 216 × 279 mm (8.5 × 11 in)
    LEGAL    // 216 × 356 mm (8.5 × 14 in)
}

PageOrientation

enum class PageOrientation {
    PORTRAIT,   // Vertical orientation (default)
    LANDSCAPE   // Horizontal orientation
}

PageMargins

data class PageMargins(
    val top: Float,
    val bottom: Float,
    val left: Float,
    val right: Float
) {
    companion object {
        val NONE = PageMargins(0f, 0f, 0f, 0f)
        val NARROW = PageMargins(36f, 36f, 36f, 36f)
        val NORMAL = PageMargins(72f, 72f, 72f, 72f)
        val WIDE = PageMargins(108f, 108f, 108f, 108f)

        fun uniform(margin: Float): PageMargins
        fun fromMm(top: Float, bottom: Float, left: Float, right: Float): PageMargins
    }
}

TextAlign

enum class TextAlign {
    LEFT,    // Left-aligned (default)
    CENTER,  // Centered
    RIGHT    // Right-aligned
}

Content Elements

TextElement

data class TextElement(
    val content: String,
    val textSize: Float = 12f,
    val textColor: Int = 0xFF000000.toInt(),
    val typeface: Typeface = Typeface.DEFAULT,
    val alignment: TextAlign = TextAlign.LEFT,
    val lineSpacing: Float = 1.2f,
    val spacingAfter: Float = 8f
) : PdfElement

ImageElement

data class ImageElement(
    val bitmap: Bitmap,
    val width: Float? = null,
    val height: Float? = null,
    val alignment: TextAlign = TextAlign.CENTER,
    val scaleType: ImageScaleType = ImageScaleType.FIT,
    val spacingAfter: Float = 8f
) : PdfElement

BoxElement

data class BoxElement(
    val elements: List<PdfElement>,
    val padding: Float = 12f,
    val backgroundColor: Int? = null,
    val borderColor: Int? = null,
    val borderWidth: Float = 1f,
    val cornerRadius: Float = 4f,
    val spacingAfter: Float = 12f
) : PdfElement

CheckboxItem

data class CheckboxItem(
    val label: String,
    val isChecked: Boolean = false
)

Table Classes

TableRow

data class TableRow(
    val cells: List<TableCell>,
    val isHeader: Boolean = false,
    val backgroundColor: Int? = null
)

TableCell

data class TableCell(
    val content: String,
    val textSize: Float = 11f,
    val textColor: Int = 0xFF000000.toInt(),
    val backgroundColor: Int? = null,
    val typeface: Typeface = Typeface.DEFAULT,
    val alignment: TextAlign = TextAlign.LEFT,
    val padding: Float = 8f,
    val colSpan: Int = 1
)

TableDsl

class TableDsl {
    fun header(vararg cells: String)
    fun row(vararg cells: String)
    fun row(cells: List<TableCell>)
    fun headerCells(vararg cells: TableCell)
}

QR Code

QRCodeElement

data class QRCodeElement(
    val data: String,
    val size: Float = 150f,
    val alignment: TextAlign = TextAlign.CENTER,
    val foregroundColor: Int = 0xFF000000.toInt(),
    val backgroundColor: Int = 0x00000000,
    val errorCorrectionLevel: QRErrorCorrectionLevel = QRErrorCorrectionLevel.MEDIUM,
    val margin: Int = 1,
    val spacingAfter: Float = 8f
) : PdfElement

QRErrorCorrectionLevel

enum class QRErrorCorrectionLevel {
    LOW,      // ~7% error correction
    MEDIUM,   // ~15% error correction (default)
    QUARTILE, // ~25% error correction
    HIGH      // ~30% error correction
}

QR Code Factory Methods

// In PdfDsl
fun qrCode(data: String, size: Float = 150f, align: TextAlign = CENTER)
fun qrCodeUrl(url: String, size: Float = 150f, align: TextAlign = CENTER)
fun qrCodeEmail(email: String, subject: String? = null, body: String? = null, size: Float = 150f)
fun qrCodePhone(phone: String, size: Float = 150f)
fun qrCodeSms(phone: String, message: String? = null, size: Float = 150f)
fun qrCodeWifi(ssid: String, password: String? = null, size: Float = 150f)
fun qrCodeVCard(firstName: String, lastName: String?, phone: String?, email: String?, organization: String?, size: Float = 150f)
fun qrCodeLocation(latitude: Double, longitude: Double, size: Float = 150f)

Output Classes

PdfOutput

sealed class PdfOutput {
    data class ToFile(val file: File) : PdfOutput()
    data class ToPath(val directoryPath: String, val fileName: String) : PdfOutput()
    object ToByteArray : PdfOutput()
    data class ToOutputStream(val outputStream: OutputStream) : PdfOutput()
}

PdfResult

sealed class PdfResult {
    data class FileResult(val file: File, val pageCount: Int) : PdfResult()
    data class ByteArrayResult(val bytes: ByteArray, val pageCount: Int) : PdfResult()
    data class StreamResult(val bytesWritten: Long, val pageCount: Int) : PdfResult()
}

PdfGenerationListener

interface PdfGenerationListener {
    fun onProgress(current: Int, total: Int)
    fun onComplete(result: PdfResult)
    fun onError(error: PdfError)
}

Extension Functions

Convenient extension functions for saving PDFs:

PdfBuilder.saveToFile(file: File): Result<File>

Save the PDF to a file and return the file.

PdfBuilder.saveToPath(directoryPath: String, fileName: String): Result<File>

Save the PDF to a path and return the file.

PdfBuilder.toByteArray(): Result<ByteArray>

Get the PDF as a byte array.

PdfBuilder.toOutputStream(outputStream: OutputStream): Result<Long>

Write the PDF to an output stream and return bytes written.