# dotLottie Android Player API Reference API reference for the dotLottie Android player. Details for Composable function, XML attributes, Widget class, Controller class, EventListener, types, and enums. # dotLottie Android Player API Reference ## DotLottieAnimation Composable Function API This page documents all parameters and methods for the Android player API, including the `DotLottieAnimation` composable, XML attributes, Widget class, Controller, EventListener interface, and all supporting types. ### Parameters | Parameter | Description | Type | Default Value | | ----------------------- | --------------------------------------------------------------- | ------------------------------ | ----------------------- | | `modifier` | The modifier to be applied to the animation view. | `Modifier` | `Modifier` | | `source`\* | The URL source of the animation. | `DotLottieSource` | `null` | | `autoplay` | Determines if the animation will start playing automatically. | `Boolean` | `false` | | `loop` | Determines whether the animation should loop. | `Boolean` | `false` | | `loopCount` | Maximum number of loop iterations (0 = infinite). | `UInt` | `0u` | | `useFrameInterpolation` | Enables or disables frame interpolation for smoother animation. | `Boolean` | `true` | | `themeId` | The themeId to be loaded. | `String` | `null` | | `marker` | The segment name or marker to be played. | `String` | `null` | | `speed` | The playback speed of the animation. | `Float` | `1f` | | `segment` | The segment to be played. | `Pair` | `null` | | `playMode` | The play mode of the animation (e.g., forward, reverse). | `Mode` | `Mode.FORWARD` | | `controller` | The controller for managing animation playback and state. | `DotLottieController` | `null` | | `layout` | Sets the the layout of the Animation. | `Layout` | `createDefaultLayout()` | | `eventListeners` | A list of event listeners for animation events. | `List` | `emptyList()` | | `stateMachineId` | The ID of a state machine to load automatically on init. | `String?` | `null` | | `threads` | Number of rendering threads. | `UInt?` | `null` | ### Functionality - **Loading Animations**: The `DotLottieAnimation` composable function supports loading animations from various sources, including URLs, asset files, raw resources, or raw data using the `DotLottieSource` type. At least one source must be provided (either via the `source` parameter or the `controller`). - **Playback Control**: The function integrates with `DotLottieController` for controlling animation playback, including play, pause, and stop functionalities. The `autoplay` and `loop` parameters provide initial playback behavior. - **Customization**: Parameters such as `speed`, `playMode`, `useFrameInterpolation`, `marker`, and `segment` allow for customization of the animation playback, including its speed, direction, smoothness, and specific parts to play. - **Event Handling**: The `eventListeners` parameter allows developers to attach multiple event listeners to handle various animation events, such as loading errors or completion, using the `DotLottieEventListener` interface. - **Theming**: The `themeId` parameter allows applying pre-defined themes packed within a `.lottie` file. - **Layout**: The `layout` parameter controls how the animation fits and aligns within the composable's bounds. - **State Machine**: The `stateMachineId` parameter allows a state machine to be loaded automatically when the animation loads. ### Example Usage ```kotlin import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color import androidx.compose.foundation.background import com.lottiefiles.dotlottie.core.util.DotLottieSource import com.dotlottie.dlplayer.Mode import com.lottiefiles.dotlottie.core.widget.DotLottieController import com.lottiefiles.dotlottie.core.model.DotLottieEventListener DotLottieAnimation( modifier = Modifier.background(Color.LightGray), source = DotLottieSource.Url("https://lottie.host/294b684d-d6b4-4116-ab35-85ef566d4379/VkGHcqcMUI.lottie"), autoplay = true, loop = true, speed = 1.5f, playMode = Mode.FORWARD, ) ``` --- ## DotLottieAnimation XML Attributes The `DotLottieAnimation` class utilizes a set of XML attributes for configuration within layout XML files. These attributes allow for the customization of animation properties directly from XML. Below is a table summarizing the available XML attributes and their functionalities: | XML Attribute | Description | Format | Default Value | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------------- | | `dotLottie_src` | Specifies the source of the Lottie animation. This can be a local asset filename or a URL to a `.lottie` or `.json` file. | `string` | None | | `dotLottie_loop` | Determines whether the animation should loop indefinitely. | `boolean` | `false` | | `dotLottie_playMode` | Defines the play mode of the animation when it reaches the end and the repeat count is greater than 0 or infinite. | `enum` | normal (1) | | `dotLottie_speed` | Adjusts the playback speed of the animation. A value of 1.0 plays the animation at its normal speed, values greater than 1.0 speed up the playback, and values less than 1.0 slow it down. | `float` | `1.0f` | | `dotLottie_autoplay` | Determines if the animation will start playing automatically upon loading. | `boolean` | `false` | | `dotLottie_backgroundColor` | Sets the background color of the animation view. | `integer` | None | | `dotLottie_useFrameInterpolation` | Enables or disables frame interpolation for smoother animation playback. | `boolean` | `true` | | `dotLottie_themeId` | Sets the `themeId` to load. | `string` | `""` | | `dotLottie_stateMachineId` | Sets the state machine ID to load on initialization. | `string` | `""` | | `dotLottie_marker` | Sets the marker to play. | `string` | `""` | | `dotLottie_animationId` | Sets the animation ID for multi-animation `.lottie` files. | `string` | `""` | These XML attributes provide a convenient way to configure `DotLottieAnimation` properties directly within layout files, offering flexibility in setting up animations without the need for additional code. --- ## DotLottieAnimation Widget Class API Reference This reference details the properties, methods, and events available in the `com.lottiefiles.dotlottie.core.widget.DotLottieAnimation` class (used with XML layouts), providing a comprehensive guide for developers to effectively utilize this class in their Android applications. ### Properties | Property | Description | Type | Access | | ----------------------- | ------------------------------------------------------------------ | -------------------- | ------ | | `speed` | Gets the playback speed of the animation. | `Float` | Read | | `loop` | Checks if the animation is set to loop. | `Boolean` | Read | | `autoplay` | Determines if the animation will start playing automatically. | `Boolean` | Read | | `isPlaying` | Indicates whether the animation is currently playing. | `Boolean` | Read | | `isPaused` | Indicates whether the animation is paused. | `Boolean` | Read | | `isStopped` | Indicates whether the animation is stopped. | `Boolean` | Read | | `isLoaded` | Checks if the animation has been loaded successfully. | `Boolean` | Read | | `totalFrames` | Gets the total number of frames in the animation. | `Float` | Read | | `currentFrame` | Gets the current frame of the animation. | `Float` | Read | | `playMode` | Gets the current play mode of the animation. | `Mode` | Read | | `segment` | Gets the start and end frames of the current segment being played. | `Pair` | Read | | `duration` | Gets the duration of the animation in seconds. | `Float` | Read | | `loopCount` | Gets the number of times the animation will loop. | `UInt` | Read | | `useFrameInterpolation` | Checks if frame interpolation is enabled for smoother animation. | `Boolean` | Read | | `marker` | Gets the current marker of the animation. | `String` | Read | | `markers` | Gets the list of markers in the animation. | `List` | Read | | `activeThemeId` | Retrieves the ID of the currently active theme. | `String` | Read | | `activeAnimationId` | Retrieves the ID of the currently active animation. | `String` | Read | ### Methods | Method | Description | | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `setFrame(frame: Float)` | Sets the animation to the specified frame. | | `setUseFrameInterpolation(enable: Boolean)` | Enables or disables frame interpolation for smoother animation playback. | | `setSegment(firstFrame: Float, lastFrame: Float)` | Defines a specific segment of the animation to play, specified by start and end frames. | | `setLoop(loop: Boolean)` | Sets whether the animation should loop. | | `freeze()` | Freezes the animation at the current frame, effectively pausing it. | | `unFreeze()` | Unfreezes the animation, allowing it to continue playing from the frozen frame. | | `setSpeed(speed: Float)` | Adjusts the playback speed of the animation. | | `play()` | Starts or resumes the animation playback. | | `stop()` | Stops the animation and resets it to the beginning. | | `setPlayMode(repeatMode: Mode)` | Sets the play mode of the animation (e.g., forward, reverse). | | `pause()` | Pauses the animation playback. | | `destroy()` | Releases resources associated with the animation. | | `load(config: Config)` | Loads the animation with the specified configuration. | | `resize(width: Int, height: Int)` | Resizes the animation view to the specified width and height. | | `addEventListener(listener: DotLottieEventListener)` | Adds an event listener to receive animation events. | | `removeEventListener(listener: DotLottieEventListener)` | Removes an event listener. | | `setTheme(themeId: String)` | Loads a theme by its ID. | | `setThemeData(themeData: String)` | Loads a theme from the provided theme data. | | `resetTheme()` | Resets the theme to the default theme. | | `loadAnimation(animationId: String)` | Loads a specific animation by ID from a multi-animation `.lottie` file. | | `manifest(): Manifest?` | Returns the dotLottie manifest. | | `setLoopCount(loopCount: UInt)` | Sets the number of times the animation loops. | | `setMarker(marker: String)` | Sets the animation to play from a named marker. | | `setLayout(fit: Fit, alignment: Pair)` | Sets the layout fit and alignment for the animation. | | `setLayout(fit: Fit, alignment: LayoutUtil.Alignment)` | Sets the layout fit and alignment using the alignment enum. | | `setColorSlot(slotId: String, color: Int): Boolean` | Sets a color slot value. Returns `true` on success. | | `setScalarSlot(slotId: String, value: Float): Boolean` | Sets a scalar slot value. Returns `true` on success. | | `setTextSlot(slotId: String, text: String): Boolean` | Sets a text slot to the given plain string, preserving all other text styling. Returns `true` on success. | | `setTextSlot(slotId: String, document: TextDocument): Boolean` | Sets a text slot with full styling control via a `TextDocument`. Returns `true` on success. | | `setVectorSlot(slotId: String, vector: PointF): Boolean` | Sets a vector slot value. Returns `true` on success. | | `setPositionSlot(slotId: String, position: PointF): Boolean` | Sets a position slot value. Returns `true` on success. | | `setImageSlotPath(slotId: String, path: String): Boolean` | Sets an image slot by file path. Returns `true` on success. | | `setImageSlotDataUrl(slotId: String, dataUrl: String): Boolean` | Sets an image slot by data URL. Returns `true` on success. | | `setSlots(slots: String)` | Sets multiple slots at once from a JSON string. | | `clearSlot(slotId: String)` | Clears the value of a specific slot, resetting it to its default. | | `clearSlots()` | Clears all slot values, resetting them to their defaults. | | `stateMachineLoad(stateMachineId: String)` | Loads a state machine by its ID. | | `stateMachineLoadData(data: String): Boolean` | Loads a state machine from a raw JSON string. | | `stateMachineStart()` | Starts the loaded state machine. | | `stateMachineStop()` | Stops the active state machine. | | `stateMachineFireEvent(event: String)` | Fires a named event to the active state machine. | | `stateMachinePostEvent(event: Event)` | Posts a typed event to the active state machine. | | `stateMachineSetBooleanInput(key: String, value: Boolean)` | Sets a boolean input on the state machine. | | `stateMachineSetNumericInput(key: String, value: Float)` | Sets a numeric input on the state machine. | | `stateMachineSetStringInput(key: String, value: String)` | Sets a string input on the state machine. | | `stateMachineGetBooleanInput(key: String): Boolean?` | Gets the current value of a boolean state machine input. | | `stateMachineGetNumericInput(key: String): Float?` | Gets the current value of a numeric state machine input. | | `stateMachineGetStringInput(key: String): String?` | Gets the current value of a string state machine input. | | `stateMachineCurrentState(): String?` | Returns the name of the currently active state machine state. | | `stateMachineAddEventListener(listener: StateMachineEventListener)` | Adds a listener for state machine events. | | `stateMachineRemoveEventListener(listener: StateMachineEventListener)` | Removes a state machine event listener. | | `clearEventListeners()` | Removes all registered event listeners. | ### Events The `DotLottieAnimation` class uses the `DotLottieEventListener` interface to notify about various animation events. Implementations of this interface can listen for the events defined in the [DotLottieEventListener Interface](#dotlottieeventlistener-interface) section below (e.g., `onPlay()`, `onPause()`, `onFrame(frame: Float)`, etc.). --- ## DotLottieController Class The `DotLottieController` class provides a comprehensive interface for managing the playback and configuration of dotLottie animations within Jetpack Compose. ### Properties | Property | Description | Type | Access | | ----------------------- | ---------------------------------------------------------------- | --------------------------------- | ------ | | `isPlaying` | Checks if the animation is playing. | `StateFlow` | Read | | `isLoaded` | Determines if the animation has been loaded successfully. | `StateFlow` | Read | | `isComplete` | Checks if the animation has completed playing. | `StateFlow` | Read | | `isStopped` | Indicates whether the animation is stopped. | `StateFlow` | Read | | `isPaused` | Indicates whether the animation is paused. | `StateFlow` | Read | | `speed` | The playback speed of the animation. | `Float` | Read | | `loop` | Determines whether the animation should loop. | `Boolean` | Read | | `autoplay` | Determines if the animation will start playing automatically. | `Boolean` | Read | | `totalFrames` | The total number of frames in the animation. | `Float` | Read | | `currentFrame` | The current frame of the animation. | `StateFlow` | Read | | `playMode` | The play mode of the animation (e.g., forward, reverse). | `Mode` | Read | | `segment` | The start and end frames of the current segment being played. | `Pair?` | Read | | `duration` | The duration of the animation in seconds. | `Float` | Read | | `loopCount` | The number of times the animation will loop. | `UInt` | Read | | `useFrameInterpolation` | Checks if frame interpolation is enabled for smoother animation. | `Boolean` | Read | | `activeThemeId` | Retrieves the ID of the currently active theme. | `StateFlow` | Read | | `activeAnimationId` | Retrieves the ID of the currently active animation. | `String` | Read | | `currentState` | Observable player state flow. | `StateFlow` | Read | | `width` | Current animation width. | `StateFlow` | Read | | `height` | Current animation height. | `StateFlow` | Read | | `markers` | List of available markers. | `List` | Read | | `stateMachineIsActive` | Whether a state machine is currently running. | `Boolean` | Read | ### Methods | Method | Description | Returns | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------- | | `play()` | Starts or resumes the animation. | `void` | | `pause()` | Pauses the animation. | `void` | | `stop()` | Stops the animation and resets to the beginning. | `void` | | `freeze()` | Freezes rendering. | `void` | | `unFreeze()` | Resumes rendering. | `void` | | `resize(width: UInt, height: UInt)` | Resizes the animation view. | `void` | | `setFrame(frame: Float)` | Sets the current frame of the animation. | `void` | | `setUseFrameInterpolation(enable: Boolean)` | Enables or disables frame interpolation. | `void` | | `setSegment(firstFrame: Float, lastFrame: Float)` | Defines the start and end frames for a segment. | `void` | | `setLoop(loop: Boolean)` | Sets whether the animation should loop. | `void` | | `setSpeed(speed: Float)` | Sets the playback speed of the animation. | `void` | | `setPlayMode(mode: Mode)` | Sets the play mode (e.g., forward, reverse, bounce). | `void` | | `setLoopCount(loopCount: UInt)` | Sets the number of times the animation loops. | `void` | | `setMarker(marker: String)` | Sets the animation to play from a named marker. | `void` | | `setLayout(fit: Fit, alignment: Pair)` | Sets the layout fit and alignment. | `void` | | `setLayout(fit: Fit, alignment: LayoutUtil.Alignment)` | Sets the layout fit and alignment using the enum. | `void` | | `loadAnimation(animationId: String)` | Loads a specific animation by ID from a multi-animation `.lottie` file. | `void` | | `setTheme(themeId: String)` | Applies a theme by ID. | `void` | | `setThemeData(themeData: String)` | Applies a theme from a raw JSON string. | `void` | | `resetTheme()` | Resets the theme to the default theme. | `void` | | `manifest(): Manifest?` | Retrieves the dotLottie manifest. | `Manifest?` | | `setColorSlot(slotId: String, color: Int): Boolean` | Sets a color slot value. | `Boolean` | | `setScalarSlot(slotId: String, value: Float): Boolean` | Sets a scalar slot value. | `Boolean` | | `setTextSlot(slotId: String, text: String): Boolean` | Sets a text slot to the given plain string, preserving all other text styling. | `Boolean` | | `setTextSlot(slotId: String, document: TextDocument): Boolean` | Sets a text slot with full styling control via a `TextDocument`. | `Boolean` | | `setVectorSlot(slotId: String, vector: PointF): Boolean` | Sets a vector slot value. | `Boolean` | | `setPositionSlot(slotId: String, position: PointF): Boolean` | Sets a position slot value. | `Boolean` | | `setImageSlotPath(slotId: String, path: String): Boolean` | Sets an image slot by file path. | `Boolean` | | `setImageSlotDataUrl(slotId: String, dataUrl: String): Boolean` | Sets an image slot by data URL. | `Boolean` | | `setSlots(slots: String)` | Sets multiple slots at once from a JSON string. | `void` | | `clearSlot(slotId: String): Boolean` | Clears a specific slot. | `Boolean` | | `clearSlots(): Boolean` | Clears all slots. | `Boolean` | | `addEventListener(listener: DotLottieEventListener)` | Adds an event listener. | `void` | | `removeEventListener(listener: DotLottieEventListener)` | Removes an event listener. | `void` | | `clearEventListeners()` | Removes all registered event listeners. | `void` | | `stateMachineLoad(stateMachineId: String)` | Loads a state machine by its ID. | `Boolean` | | `stateMachineLoadData(data: String)` | Loads a state machine from a raw JSON string. | `Boolean` | | `stateMachineStart(openUrl: OpenUrlPolicy, onOpenUrl: ((url: String) -> Unit)?)` | Starts the loaded state machine with URL policy. | `Boolean` | | `stateMachineStop()` | Stops the active state machine. | `Boolean` | | `stateMachineFire(event: String)` | Fires a named event to the active state machine. | `Boolean` | | `stateMachinePostEvent(event: Event)` | Posts a typed event to the state machine. | `Boolean` | | `stateMachinePostEvent(event: Event, force: Boolean)` | Posts an event with force option. | `Boolean` | | `stateMachineSetBooleanInput(key: String, value: Boolean)` | Sets a boolean input. | `Boolean` | | `stateMachineSetNumericInput(key: String, value: Float)` | Sets a numeric input. | `Boolean` | | `stateMachineSetStringInput(key: String, value: String)` | Sets a string input. | `Boolean` | | `stateMachineGetBooleanInput(key: String)` | Gets a boolean input value. | `Boolean?` | | `stateMachineGetNumericInput(key: String)` | Gets a numeric input value. | `Float?` | | `stateMachineGetStringInput(key: String)` | Gets a string input value. | `String?` | | `stateMachineCurrentState()` | Returns the name of the currently active state. | `String?` | | `stateMachineAddEventListener(listener: StateMachineEventListener)` | Adds a state machine event listener. | `void` | | `stateMachineRemoveEventListener(listener: StateMachineEventListener)` | Removes a state machine event listener. | `void` | ### Static Methods (Companion Object) These methods are available on the `DotLottieController` companion object and operate on the global font registry shared by all player instances. | Method | Description | Returns | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `DotLottieController.loadFont(name: String, data: ByteArray): Boolean` | Registers a custom font into ThorVG's global font registry. The font is available to all player instances. Returns `true` on success. | `Boolean` | | `DotLottieController.unloadFont(name: String): Boolean` | Removes a font previously registered with `loadFont` from the global registry. Returns `true` on success. | `Boolean` | ```kotlin // Load a font from assets val fontBytes = context.assets.open("fonts/MyFont.ttf").readBytes() DotLottieController.loadFont("MyFont", fontBytes) // Unload when no longer needed DotLottieController.unloadFont("MyFont") ``` > **Note:** Both the Widget and the Controller expose `freeze()` / `unFreeze()`. The Widget implementation toggles the drawable's freeze flag directly; the Controller implementation calls `pause()` / `play()` and updates the playback state accordingly. --- ## Event Handling The `DotLottieController` class allows for the registration of event listeners that implement the [DotLottieEventListener Interface](#dotlottieeventlistener-interface) interface. These listeners can respond to various animation events. ## DotLottieEventListener Interface The `DotLottieEventListener` interface defines a set of callback methods that respond to various animation events. Implementing this interface allows for handling animation lifecycle events, playback state changes, and rendering updates. ### Methods | Event Method | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `onLoop(loopCount: Int)` | Called when the animation completes a loop. loopCount indicates the number of times the animation has looped. | | `onRender(frameNo: Float)` | Invoked for each frame rendered. frameNo is the current frame number. | | `onStop()` | Triggered when the animation stops. | | `onFrame(frame: Float)` | Called with the current frame number whenever the animation updates. | | `onPause()` | Invoked when the animation is paused. | | `onPlay()` | Triggered when the animation starts playing. | | `onComplete()` | Called when the animation completes all its loops and stops. | | `onLoad()` | Invoked when the animation is successfully loaded and ready to play. | | `onLoadError(error: Throwable)` | Called if there is an error loading the animation. | | `onError(error: Throwable)` | Called if there is a runtime error. | | `onFreeze()` | Triggered when the animation is frozen at the current frame. | | `onUnFreeze()` | Invoked when the animation resumes from a frozen state. | | `onDestroy()` | Called when the animation is destroyed and resources are released. | --- ## StateMachineEventListener Interface The `StateMachineEventListener` interface defines callbacks for state machine events: | Method | Description | | ------------------------------------------------------------------------------------ | ------------------------------------------------- | | `onStart()` | Fired when the state machine starts. | | `onStop()` | Fired when the state machine stops. | | `onStateEntered(enteringState: String)` | Fired when entering a state. | | `onStateExit(leavingState: String)` | Fired when exiting a state. | | `onTransition(previousState: String, newState: String)` | Fired on a state transition. | | `onCustomEvent(message: String)` | Fired when a custom event is emitted. | | `onError(message: String)` | Fired when the state machine encounters an error. | | `onInputFired(inputName: String)` | Fired when an input fires. | | `onBooleanInputValueChange(inputName: String, oldValue: Boolean, newValue: Boolean)` | Fired when a boolean input changes. | | `onNumericInputValueChange(inputName: String, oldValue: Float, newValue: Float)` | Fired when a numeric input changes. | | `onStringInputValueChange(inputName: String, oldValue: String, newValue: String)` | Fired when a string input changes. | --- ## DotLottieSource The `DotLottieSource` sealed class represents the different animation sources: | Variant | Constructor | Description | | ------- | ------------------------------------------ | -------------------------------------------- | | `Url` | `DotLottieSource.Url(url: String)` | Loads from a URL (`.json` or `.lottie`). | | `Asset` | `DotLottieSource.Asset(path: String)` | Loads from the `assets` folder. | | `Res` | `DotLottieSource.Res(resourceId: Int)` | Loads from Android `res/raw` resources. | | `Data` | `DotLottieSource.Data(data: ByteArray)` | Loads from raw byte data (`.lottie` format). | | `Json` | `DotLottieSource.Json(jsonString: String)` | Loads from a Lottie JSON string. | --- ## Event Sealed Class (State Machine) The `Event` sealed class represents events that can be posted to a state machine: ```kotlin sealed class Event(val type: Int) { data class PointerDown(val x: Float, val y: Float) : Event(0) data class PointerUp(val x: Float, val y: Float) : Event(1) data class PointerMove(val x: Float, val y: Float) : Event(2) data class PointerEnter(val x: Float, val y: Float) : Event(3) data class PointerExit(val x: Float, val y: Float) : Event(4) data class Click(val x: Float, val y: Float) : Event(5) object OnComplete : Event(6) object OnLoopComplete : Event(7) } ``` --- ## DotLottiePlayerState Enum Represents the current state of the player: | Value | Description | | ----------- | ------------------------------------- | | `PLAYING` | The animation is currently playing. | | `PAUSED` | The animation is paused. | | `STOPPED` | The animation is stopped. | | `COMPLETED` | The animation has completed playback. | | `INITIAL` | The player is in its initial state. | | `LOADED` | The animation has been loaded. | | `ERROR` | An error occurred. | --- ## Fit Enum Controls how the animation scales within its container: | Value | Description | | ------------ | --------------------------------------------------------------------------- | | `CONTAIN` | Scale to fit within the container while maintaining aspect ratio (default). | | `COVER` | Scale to cover the entire container while maintaining aspect ratio. | | `FILL` | Stretch to fill the container, ignoring aspect ratio. | | `FIT_WIDTH` | Scale to match the container's width, maintaining aspect ratio. | | `FIT_HEIGHT` | Scale to match the container's height, maintaining aspect ratio. | | `NONE` | No scaling applied — renders at original size. | --- ## LayoutUtil.Alignment Enum Predefined alignment positions for the animation within its container: | Value | Description | | --------------- | ---------------------------------- | | `TOP_LEFT` | Aligns to the top-left corner. | | `TOP_CENTER` | Aligns to the top center. | | `TOP_RIGHT` | Aligns to the top-right corner. | | `CENTER_LEFT` | Aligns to the center-left. | | `CENTER` | Aligns to the center (default). | | `CENTER_RIGHT` | Aligns to the center-right. | | `BOTTOM_LEFT` | Aligns to the bottom-left corner. | | `BOTTOM_CENTER` | Aligns to the bottom center. | | `BOTTOM_RIGHT` | Aligns to the bottom-right corner. | --- ## Layout Data Class The `Layout` data class configures the fit and alignment of the animation. Use `createDefaultLayout()` for the default configuration (Contain fit, centered alignment). --- ## TextDocument Data Class The `TextDocument` data class represents a Lottie text document used to drive a text slot. It provides Kotlin-friendly properties for controlling all aspects of text styling. Only `text` is required — leave remaining properties `null` to preserve the values already present in the animation. :::warning\[Breaking Change in v0.15.0] `setTextSlot()` no longer accepts a raw JSON string. To update only the text content, pass a plain `String`. To control styling, pass a `TextDocument`. ```kotlin // Before (v0.14.x and earlier) player.setTextSlot("title", """{"k":[{"t":0,"s":{"t":"Hello","s":42}}]}""") // After (v0.15.0+) player.setTextSlot("title", "Hello") // plain string — text only player.setTextSlot("title", TextDocument(text = "Hello", fontSize = 42f)) // full styling ``` ::: ### Properties | Property | Type | Required | Description | | ---------------- | -------------- | -------- | --------------------------------------------------------------------------------------------- | | `text` | `String` | Yes | The text content to display. | | `fontName` | `String?` | No | The font family name (must match a font registered via `loadFont` or embedded in the file). | | `fontSize` | `Float?` | No | The font size in points. | | `fillColor` | `List?` | No | Fill color as RGBA components in the `0.0..1.0` range, e.g. `listOf(1f, 0f, 0f, 1f)`. | | `strokeColor` | `List?` | No | Stroke color as RGBA components in the `0.0..1.0` range. | | `strokeWidth` | `Float?` | No | Stroke width in points. | | `strokeOverFill` | `Boolean?` | No | When `true`, the stroke is drawn on top of the fill. | | `lineHeight` | `Float?` | No | Line height multiplier. | | `tracking` | `Float?` | No | Character tracking (letter-spacing) in points. | | `justify` | `Int?` | No | Text justification. `0` = left, `1` = right, `2` = center, `3` = justify with last line left. | | `textCaps` | `Int?` | No | Capitalization. `0` = none, `1` = all caps, `2` = small caps, `3` = mixed. | | `baselineShift` | `Float?` | No | Baseline shift in points. | | `wrapSize` | `List?` | No | Text box dimensions as `[width, height]` in points. | | `wrapPosition` | `List?` | No | Text box position as `[x, y]` in points. | ### Helper Methods | Method | Description | | ----------------------------------------------------- | -------------------------------------------------------------------------------------- | | `TextDocument.fillColorOf(color: Int): List` | Converts an Android `@ColorInt` to an RGBA `0.0..1.0` list suitable for `fillColor`. | | `TextDocument.strokeColorOf(color: Int): List` | Converts an Android `@ColorInt` to an RGBA `0.0..1.0` list suitable for `strokeColor`. | ### Example Usage ```kotlin import com.dotlottie.dlplayer.TextDocument import android.graphics.Color // Change text only — preserves all existing styling controller.setTextSlot("headline", "Hello, World!") // Change text and font size controller.setTextSlot( "headline", TextDocument( text = "Hello, World!", fontSize = 48f ) ) // Full styling control controller.setTextSlot( "headline", TextDocument( text = "Hello, World!", fontName = "MyCustomFont", fontSize = 36f, fillColor = TextDocument.fillColorOf(Color.RED), strokeColor = TextDocument.strokeColorOf(Color.BLACK), strokeWidth = 2f, justify = 2 // center ) ) ``` --- ## OpenUrlPolicy Data Class Configures URL opening behavior for state machines: | Property | Type | Description | | ------------------------ | -------------- | --------------------------------------------------------- | | `requireUserInteraction` | `Boolean` | Whether user interaction is required before opening URLs. | | `whitelist` | `List` | List of allowed URL patterns. | --- ## Marker Data Class Represents a named marker in the animation: | Property | Type | Description | | ---------- | -------- | -------------------------------- | | `name` | `String` | The marker name. | | `time` | `Float` | The time position of the marker. | | `duration` | `Float` | The duration of the marker. | --- ## Manifest Data Class Represents the dotLottie manifest from a `.lottie` file: | Property | Type | Description | | ------------------- | --------------------- | --------------------------------------- | | `activeAnimationId` | `String?` | The ID of the default active animation. | | `animations` | `List` | List of animations in the file. | | `author` | `String?` | The author of the file. | | `description` | `String?` | Description of the file. | | `generator` | `String?` | The generator tool used. | | `keywords` | `String?` | Keywords associated with the file. | | `revision` | `Int?` | The revision number. | | `themes` | `List?` | List of available themes. | | `stateMachines` | `List?` | List of available state machines. | | `version` | `String?` | The manifest version. | | `customData` | `Map?` | Custom metadata. | ### Manifest.Animation | Property | Type | Description | | -------- | -------- | ----------------- | | `id` | `String` | The animation ID. | ### Manifest.Theme | Property | Type | Description | | -------- | -------- | ------------- | | `id` | `String` | The theme ID. | ### Manifest.StateMachine | Property | Type | Description | | -------- | -------- | --------------------- | | `id` | `String` | The state machine ID. | --- ## Config.Builder The `Config.Builder` class constructs an animation configuration for loading with the Widget's `load(config)` method: | Method | Description | | ---------------------------------------------------- | ------------------------------------------------ | | `.autoplay(value: Boolean)` | Sets autoplay behavior. | | `.loop(value: Boolean)` | Sets looping behavior. | | `.speed(value: Float)` | Sets playback speed. | | `.source(source: DotLottieSource)` | Sets the animation source. | | `.useFrameInterpolation(value: Boolean)` | Enables/disables frame interpolation. | | `.playMode(mode: Mode)` | Sets the play mode. | | `.layout(fit: Fit, alignment: Pair)` | Sets layout fit and alignment. | | `.layout(fit: Fit, alignment: LayoutUtil.Alignment)` | Sets layout fit and alignment using the enum. | | `.themeId(themeId: String)` | Sets the theme to load. | | `.marker(marker: String)` | Sets the marker to play. | | `.animationId(animationId: String)` | Sets the animation ID for multi-animation files. | | `.stateMachineId(stateMachineId: String)` | Sets the state machine to load on init. | | `.threads(threads: UInt)` | Sets the number of rendering threads. | | `.loopCount(loopCount: UInt)` | Sets the maximum number of loop iterations. | | `.build()` | Builds the `Config` object. | ```kotlin val config = Config.Builder() .autoplay(true) .speed(1f) .loop(true) .source(DotLottieSource.Url("https://example.com/animation.lottie")) .useFrameInterpolation(true) .playMode(Mode.FORWARD) .build() dotLottieAnimationView.load(config) ```