Platform

Android

Language

Kotlin

Configure Dock

In this example, we will show you how to make dock configurations for the mobile editor. The example is based on the Design Editor, however, it is exactly the same for all the other solutions.

Explore a full code sample on GitHub.

View on GitHub

Dock Architecture#

Dock is a list of items placed horizontally at the bottom of the editor. It has type Dock : EditorComponent and every item in the dock has type Dock.Item : EditorComponent. Dock.Item is an abstract class that currently has two implementations: Dock.Button and Dock.Custom. Dock.Button is an editor component that has an icon and a text positioned in a column, while Dock.Custom is a fully custom editor component that allows drawing arbitrary content. Prefer using Dock.Custom for rendering custom content in the dock over inheriting from Dock.Item.

Dock Configuration#

Dock is part of the EditorConfiguration, therefore, in order to configure the dock we need to configure the EditorConfiguration. Below you can find the list of available configurations of the dock. To demonstrate the default values, all parameters are assigned to their default values. Consider using Dock.rememberFor{solution_name} helper functions when providing a dock for a specific solution.

scope - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access EditorScope to construct the scope, use LocalEditorScope. Consider using Compose State objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the dock. Prefer updating individual Dock.Items over updating the whole dock. Ideally, scope should be updated when the parent scope (scope of the parent component) is updated and when you want to observe changes from the Engine. By default the scope is updated only when the parent scope (accessed via LocalEditorScope) is updated.

listBuilder - a builder that registers the list of Dock.Items that should be part of the dock. Note that registering does not mean displaying. The items will be displayed if Dock.Item.visible is true for them. By default listBuilder does not add anything to the dock. For configuration details, see ListBuilder Configuration section.

horizontalArrangement - the horizontal arrangement that should be used to render the items in the dock horizontally. Default value is Arrangement.SpaceEvenly.

visible - whether the dock should be visible. Default value is always true.

enterTransition - transition of the dock when it enters the parent composable. Default value is always no enter transition.

exitTransition - transition of the dock when it exits the parent composable. Default value is always no exit transition.

decoration - decoration of the dock. Useful when you want to add custom background, foreground, shadow, paddings etc. By default decoration adds background color and applies paddings to the dock.

itemDecoration - decoration of the items in the dock. Useful when you want to add custom background, foreground, shadow, paddings etc to the items. Prefer using this decoration when you want to apply the same decoration to all the items, otherwise set decoration to individual items. Default value is always no decoration.

Dock.ListBuilder Configuration#

There are two main ways to create an instance of Dock.ListBuilder. First way is to call modify on an existing builder, and the second way is to create the builder from scratch. Currently, there are three available builders:

Dock.ListBuilder.rememberForDesign() that is recommended to be used in Design Editor.

Dock.ListBuilder.rememberForPhoto() that is recommended to be used in Photo Editor.

Dock.ListBuilder.rememberForVideo() that is recommended to be used in Video Editor. Note that Dock.Button.rememberImglyCamera() can be used only if ly.img:camera:<same version as editor> dependency is added in yourbuild.gradle file. For more information, check the camera documentation.

Modifying an Existing Builder#

In this example, we will modify Dock.ListBuilder.rememberForDesign. Modifying builders can be used, when you do not want to touch the default general order of the items in the builder, but rather add additional items and replace/hide some of the default items. To achieve that, there are multiple available functions in the scope of modify lambda:

addFirst - prepends a new Dock.Item in the list.

addLast - appends a new Dock.Item in the list.

addAfter - adds a new Dock.Item right after the item with provided id. An exception will be thrown if no item exists with provided id in the default builder.

addBefore - adds a new Dock.Item right before the item with provided id. An exception will be thrown if no item exists with provided id in the default builder.

replace - replaces the Dock.Item with provided id. An exception will be thrown if no item exists with provided id in the default builder. Also note that the new item does not need to have the same id.

remove - removes the Dock.Item with provided id. An exception will be thrown if no item exists with provided id in the default builder.

Warning#

Note that the order of items may change between editor versions, therefore ListBuilder.modify must be used with care. Consider creating a new builder if you want to have strict ordering between different editor versions.

Creating a New Builder#

In this example, we will create a builder from scratch that will be used in the Dock of DesignEditor solution. Creating a new builder is recommended, when you want to touch the default order of available builders, as well as when available builders do not contain the items that you want. This example mimics reordering the default order of items in Dock.ListBuilder.rememberForDesign builder. In addition, some items are removed and a new custom item is prepended.

Dock.Item Configuration#

As mentioned in the Dock Architecture section, Dock.Item is an EditorComponent and it has two subtypes: Dock.Button and Dock.Custom.

Dock.Button Configuration#

In order to create a dock button, use Dock.Button.remember composable function. Below you can find the list of available configurations when creating a Dock.Button. To demonstrate the default values, all parameters are assigned to their default values whenever possible.

id - the id of the button. Note that it is highly recommended that every unique EditorComponent has a unique id. Parameter does not have a default value.

scope - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access EditorScope to construct the scope, use LocalEditorScope. Consider using Compose State objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the button. Ideally, scope should be updated when the parent scope (scope of the parent component Dock - Dock.Scope) is updated and when you want to observe changes from the Engine. By default the scope is updated only when the parent component scope (Dock.scope, accessed via LocalEditorScope) is updated.

onClick - the callback that is invoked when the button is clicked. Parameter does not have a default value.

icon - the icon content of the button. If null, it will not be rendered. Default value is null.

text - the text content of the button. If null, it will not be rendered. Default value is null.

enabled - whether the button is enabled. Default value is always true.

visible - whether the button should be visible. Default value is always true.

enterTransition - transition of the button when it enters the parent composable. Default value is always no enter transition.

exitTransition - transition of the button when it exits the parent composable. Default value is always no exit transition.

decoration - decoration of the button. Useful when you want to add custom background, foreground, shadow, paddings etc. Default value is always no decoration.

Other than the main Dock.Button.remember function, there is one more convenience overload that has two differences:

icon is replaced with vectorIcon lambda, that returns VectorIcon instead of drawing the icon content.
text is replaced with text lambda, that returns String instead of drawing the text content.

Dock.Custom Configuration#

In order to create a custom dock item, use Dock.Custom.remember composable function. Below you can find the list of available configurations when creating a Dock.Custom item. To demonstrate the default values, all parameters are assigned to their default values whenever possible.

id - the id of the custom item. Note that it is highly recommended that every unique EditorComponent has a unique id. Parameter does not have a default value.

scope - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access EditorScope to construct the scope, use LocalEditorScope. Consider using Compose State objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the custom item. Ideally, scope should be updated when the parent scope (scope of the parent component Dock - Dock.Scope) is updated and when you want to observe changes from the Engine. Parameter does not have a default value.

visible - whether the custom item should be visible. Default value is always true.

enterTransition - transition of the custom item when it enters the parent composable. Default value is always no enter transition.

exitTransition - transition of the custom item when it exits the parent composable. Default value is always no exit transition.

content - the content of the custom item. You are responsible for drawing it, handling clicks etc. Parameter does not have a default value.


import androidx.compose.animation.EnterTransition
import androidx.compose.animation.ExitTransition
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.navigation.NavHostController
import ly.img.editor.DesignEditor
import ly.img.editor.EditorConfiguration
import ly.img.editor.EngineConfiguration
import ly.img.editor.core.LocalEditorScope
import ly.img.editor.core.component.Dock
import ly.img.editor.core.theme.surface1
import ly.img.editor.rememberForDesign

// Add this composable to your NavHost
@Composable
fun SimpleDockSolution(navController: NavHostController) {
    val engineConfiguration =
        EngineConfiguration.rememberForDesign(
            license = "<your license here>",
        )

    val editorConfiguration =
        EditorConfiguration.rememberForDesign(
            dock = {
                Dock.remember(
                    scope =
                        LocalEditorScope.current.run {
                            remember(this) { Dock.Scope(parentScope = this) }
                        },
                    listBuilder = Dock.ListBuilder.remember { },
                    horizontalArrangement = { Arrangement.SpaceEvenly },
                    visible = { true },
                    enterTransition = { EnterTransition.None },
                    exitTransition = { ExitTransition.None },
                    decoration = {
                        // Also available via Dock.defaultDecoration
                        Box(
                            modifier =
                                Modifier
                                    .fillMaxWidth()
                                    .background(MaterialTheme.colorScheme.surface1.copy(alpha = 0.95f))
                                    .padding(vertical = 10.dp),
                        ) {
                            it()
                        }
                    },
                    // default value is { it() }
                    itemDecoration = {
                        Box(modifier = Modifier.padding(2.dp)) {
                            it()
                        }
                    },
                )
            },
        )
    DesignEditor(
        engineConfiguration = engineConfiguration,
        editorConfiguration = editorConfiguration,
    ) {
        // You can set result here
        navController.popBackStack()
    }
}

List of Available Dock.Buttons#

As you often saw in the previous sections, there are composable functions that look like this: Dock.Button.remember{name}. All these functions return a Dock.Button, they are public and can be used in your application. Note that all the parameters of these functions have default values, therefore, you do not need to provide any values, however, if you want to modify any of the parameters, it is exactly the same as described in Dock.Button Configuration section.

Button	Id	Description
Button `Dock.Button.rememberElementsLibrary`	Id `Dock.Button.Id.ElementsLibrary`	Description Opens library sheet with elements via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the Asset Library.
Button `Dock.Button.rememberOverlaysLibrary`	Id `Dock.Button.Id.OverlaysLibrary`	Description Opens library sheet with overlays via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the Asset Library.
Button `Dock.Button.rememberImagesLibrary`	Id `Dock.Button.Id.ImagesLibrary`	Description Opens library sheet with images via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the Asset Library.
Button `Dock.Button.rememberTextLibrary`	Id `Dock.Button.Id.TextLibrary`	Description Opens library sheet with text via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the Asset Library.
Button `Dock.Button.rememberShapesLibrary`	Id `Dock.Button.Id.ShapesLibrary`	Description Opens library sheet with shapes via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the Asset Library.
Button `Dock.Button.rememberStickersLibrary`	Id `Dock.Button.Id.StickersLibrary`	Description Opens library sheet with stickers via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the Asset Library.
Button `Dock.Button.rememberAudiosLibrary`	Id `Dock.Button.Id.AudiosLibrary`	Description Opens library sheet with audios via `EditorEvent.Sheet.Open`. By default, the `LibraryCategory` is picked from the Asset Library.
Button `Dock.Button.rememberSystemGallery`	Id `Dock.Button.Id.SystemGallery`	Description Opens the system gallery via `EditorEvent.LaunchContract`.
Button `Dock.Button.rememberSystemCamera`	Id `Dock.Button.Id.SystemCamera`	Description Opens the system camera via `EditorEvent.LaunchContract`.
Button `Dock.Button.rememberImglyCamera`	Id `Dock.Button.Id.ImglyCamera`	Description Opens the IMG.LY camera via `EditorEvent.LaunchContract`. Note that the button can be used only if `ly.img:camera:<same version as editor>` dependency is added in your `build.gradle` file. For more information, check the camera documentation.
Button `Dock.Button.rememberReorder`	Id `Dock.Button.Id.Reorder`	Description Opens reorder sheet via `EditorEvent.Sheet.Open`.
Button `Dock.Button.rememberAdjustments`	Id `Dock.Button.Id.Adjustments`	Description Opens adjustment sheet via `EditorEvent.Sheet.Open`.
Button `Dock.Button.rememberFilter`	Id `Dock.Button.Id.Filter`	Description Opens filter sheet via `EditorEvent.Sheet.Open`.
Button `Dock.Button.rememberEffect`	Id `Dock.Button.Id.Effect`	Description Opens effect sheet via `EditorEvent.Sheet.Open`.
Button `Dock.Button.rememberBlur`	Id `Dock.Button.Id.Blur`	Description Opens blur sheet via `EditorEvent.Sheet.Open`.
Button `Dock.Button.rememberCrop`	Id `Dock.Button.Id.Crop`	Description Opens crop sheet via `EditorEvent.Sheet.Open`.