API Reference

Complete API documentation for Pix Image Picker.

Overview

The Pix API is generated using Dokka, Kotlin's documentation engine. This provides comprehensive documentation for all public classes, functions, and properties.

Accessing the API Documentation

Online Documentation

The full Dokka-generated API documentation is available at:

Pix API Documentation

This includes: - Complete class hierarchy - All public methods and properties - Parameter descriptions - Return type information - Usage examples - Source code links

Generating Locally

To generate API documentation on your machine:

./gradlew :pix:dokkaHtml

Documentation will be generated at: pix/build/dokka/html/index.html

To open in browser:

./gradlew :pix:dokkaHtmlOpen

Main Classes

Pix

Entry point for the library.

object Pix {
    fun pixFragment(
        options: Options,
        callback: (PixEventCallback) -> Unit
    ): Fragment
}

See full documentation in API Reference

Options

Configuration class for customizing the picker.

Key Properties: - count: Int - Maximum items to select - mode: Mode - Selection mode (Picture, Video, All) - ratio: Ratio - Capture aspect ratio - spanCount: Int - Grid columns - path: String - Storage path for captures - isFrontFacing: Boolean - Start with front camera - flash: Flash - Flash mode - videoDurationLimitInSeconds: Int - Max video length - preSelectedUrls: List<Uri> - Pre-selected items

Example:

val options = Options().apply {
    count = 5
    mode = Mode.All
    ratio = Ratio.RATIO_AUTO
}

PixEventCallback

Result callback interface.

interface PixEventCallback {
    enum class Status {
        SUCCESS,      // Selection successful
        BACK_PRESSED  // User pressed back
    }

    data class Result(
        val status: Status,
        val data: List<Uri>  // Selected URIs
    )
}

PixBus

Global event bus for picker results.

object PixBus {
    val results: Flow<PixEventCallback.Result>

    suspend fun results(
        callback: suspend (PixEventCallback.Result) -> Unit
    )
}

Usage:

lifecycleScope.launch {
    PixBus.results.collect { result ->
        when (result.status) {
            PixEventCallback.Status.SUCCESS -> {
                val uris = result.data
            }
            PixEventCallback.Status.BACK_PRESSED -> {}
        }
    }
}

Enums

Mode

enum class Mode {
    Picture,  // Images only
    Video,    // Videos only
    All       // Both images and videos
}

Ratio

enum class Ratio {
    RATIO_4_3,   // 4:3 aspect ratio
    RATIO_16_9,  // 16:9 aspect ratio
    RATIO_AUTO   // Automatic
}

Flash

enum class Flash {
    On,   // Always on
    Off,  // Always off
    Auto  // Automatic
}

Function Reference

Creating Picker Fragment

fun pixFragment(
    options: Options,
    callback: (PixEventCallback) -> Unit
): Fragment

Creates a Pix picker fragment with the specified configuration.

Parameters: - options: Options - Configuration for the picker - callback: (PixEventCallback) -> Unit - Called when user completes selection

Returns: A Fragment instance that can be added to your activity/fragment

Example:

val options = Options().apply { count = 5 }
val fragment = pixFragment(options) { result ->
    when (result.status) {
        PixEventCallback.Status.SUCCESS -> {
            val uris = result.data
        }
        PixEventCallback.Status.BACK_PRESSED -> {}
    }
}

Adding to Activity

fun Activity.addPixToActivity(
    containerId: Int,
    options: Options,
    callback: (PixEventCallback) -> Unit
): Fragment

Convenience extension function to add Pix picker to an activity.

Parameters: - containerId: Int - ViewGroup container ID - options: Options - Configuration - callback: (PixEventCallback) -> Unit - Result callback

Returns: The added fragment

Example:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        addPixToActivity(R.id.container, Options()) { result ->
            // Handle result
        }
    }
}

Extension Functions

Fragment.pixFragment

fun Fragment.pixFragment(
    options: Options,
    callback: (PixEventCallback) -> Unit
): Fragment

Create picker fragment from within another fragment.

AppCompatActivity.pixFragment

fun AppCompatActivity.pixFragment(
    options: Options,
    callback: (PixEventCallback) -> Unit
): Fragment

Create picker fragment from within an activity.

Data Classes

Result

data class Result(
    val status: PixEventCallback.Status,
    val data: List<Uri>
)

Properties: - status: Status - Operation status (SUCCESS or BACK_PRESSED) - data: List<Uri> - Selected media URIs (empty if BACK_PRESSED)

Advanced Usage

Custom Result Handling

val options = Options().apply {
    count = 10
}

val fragment = pixFragment(options) { result ->
    when (result.status) {
        PixEventCallback.Status.SUCCESS -> {
            result.data.forEach { uri ->
                // Process each selected URI
                val bitmap = MediaStore.Images.Media.getBitmap(
                    contentResolver,
                    uri
                )
            }
        }
        PixEventCallback.Status.BACK_PRESSED -> {
            Log.d("Pix", "Selection cancelled")
        }
    }
}

Error Handling

try {
    val fragment = pixFragment(options) { result ->
        try {
            if (result.status == PixEventCallback.Status.SUCCESS) {
                processUris(result.data)
            }
        } catch (e: Exception) {
            Log.e("Pix", "Error processing result", e)
        }
    }
} catch (e: IllegalArgumentException) {
    Log.e("Pix", "Invalid options", e)
}

Frequently Used APIs

Most Common: Basic Selection

// 1. Create options
val options = Options().apply {
    count = 5
    mode = Mode.All
}

// 2. Create picker
val fragment = pixFragment(options) { result ->
    if (result.status == PixEventCallback.Status.SUCCESS) {
        val selectedUris = result.data
        // Use URIs
    }
}

// 3. Add to activity
supportFragmentManager.beginTransaction()
    .add(R.id.container, fragment)
    .commit()

Common: Using PixBus

lifecycleScope.launch {
    PixBus.results.collect { result ->
        when (result.status) {
            PixEventCallback.Status.SUCCESS -> {
                updateUI(result.data)
            }
            PixEventCallback.Status.BACK_PRESSED -> {}
        }
    }
}

Deprecated APIs

Currently, there are no deprecated APIs in v1.6.8.

Deprecations will be announced in advance for compatibility.

Version Compatibility

Minimum: API 16 (Android 4.1)
Target: API 34+ (Android 15)
Tested: API 11 - 34

Documentation Formatting

The API documentation uses Dokka conventions:

/**
 * Detailed function description.
 *
 * @param paramName Parameter description
 * @return Description of return value
 * @throws ExceptionType When this condition occurs
 *
 * Example usage:
 * ```kotlin
 * // Code example here
 * ```
 */

Finding What You Need

Search

Use the search box in the Dokka documentation to find classes, methods, or properties.

Browse

Packages - Grouped by namespace
Classes - All classes organized hierarchically
Functions - Top-level functions
Properties - Class and object properties

Quick Links

Troubleshooting

Can't find a class

Try searching in Dokka docs
Check the GitHub source
Ask in GitHub Discussions

API changed in new version

Check the Changelog for breaking changes.

Source Code

The source code is available on GitHub.

Each API reference in Dokka includes a link to the source code, allowing you to see the implementation details.

Contributing to Documentation

Found an issue or have suggestions for the API docs?

See Contributing Guide for details.

Next Steps: - Review Configuration for detailed options - Check Examples for common patterns - Read Usage Guide for complete walkthrough