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.

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 solutions.

• 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.

• 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.

• 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.

• 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.

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.

• 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.

• 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.

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

1. icon is replaced with vectorIcon lambda, that returns VectorIcon instead of drawing the icon content.
2. text is replaced with text lambda, that returns String instead of drawing the text content.
3. An extra parameter contentDescription is added that is used by accessibility services to describe what the button does. Note that it is not required to provide value when text is not null, since its value will be used by accessibility services, however having both text and contentDescription as null will cause a crash.

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.

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
Dock.Button.rememberElementsLibrary	Dock.Button.Id.elementsLibrary	Opens library sheet with elements via EditorEvent.Sheet.Open. By default, the LibraryCategory is picked from the Asset Library.
Dock.Button.rememberOverlaysLibrary	Dock.Button.Id.overlaysLibrary	Opens library sheet with overlays via EditorEvent.Sheet.Open. By default, the LibraryCategory is picked from the Asset Library.
Dock.Button.rememberImagesLibrary	Dock.Button.Id.imagesLibrary	Opens library sheet with images via EditorEvent.Sheet.Open. By default, the LibraryCategory is picked from the Asset Library.
Dock.Button.rememberTextLibrary	Dock.Button.Id.textLibrary	Opens library sheet with text via EditorEvent.Sheet.Open. By default, the LibraryCategory is picked from the Asset Library.
Dock.Button.rememberShapesLibrary	Dock.Button.Id.shapesLibrary	Opens library sheet with shapes via EditorEvent.Sheet.Open. By default, the LibraryCategory is picked from the Asset Library.
Dock.Button.rememberStickersLibrary	Dock.Button.Id.stickersLibrary	Opens library sheet with stickers via EditorEvent.Sheet.Open. By default, the LibraryCategory is picked from the Asset Library.
Dock.Button.rememberAudiosLibrary	Dock.Button.Id.audiosLibrary	Opens library sheet with audios via EditorEvent.Sheet.Open. By default, the LibraryCategory is picked from the Asset Library.
Dock.Button.rememberSystemGallery	Dock.Button.Id.systemGallery	Opens the system gallery via EditorEvent.LaunchContract.
Dock.Button.rememberSystemCamera	Dock.Button.Id.systemCamera	Opens the system camera via EditorEvent.LaunchContract.
Dock.Button.rememberImglyCamera	Dock.Button.Id.imglyCamera	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.
Dock.Button.rememberReorder	Dock.Button.Id.reorder	Opens reorder sheet via EditorEvent.Sheet.Open.
Dock.Button.rememberAdjustments	Dock.Button.Id.adjustments	Opens adjustment sheet via EditorEvent.Sheet.Open.
Dock.Button.rememberFilter	Dock.Button.Id.filter	Opens filter sheet via EditorEvent.Sheet.Open.
Dock.Button.rememberEffect	Dock.Button.Id.effect	Opens effect sheet via EditorEvent.Sheet.Open.
Dock.Button.rememberBlur	Dock.Button.Id.blur	Opens blur sheet via EditorEvent.Sheet.Open.
Dock.Button.rememberCrop	Dock.Button.Id.crop	Opens crop sheet via EditorEvent.Sheet.Open.