Platform

iOS

Android

Language

Swift

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#

The dock is a list of items placed horizontally at the bottom of the editor. Every item in the dock conforms to Dock.Item: EditorComponent where its Context is constraint to be of type Dock.Context. Dock.Button is a provided implementation of the Dock.Item protocol that has an icon and a title. You can also create your own fully custom editor component that allows drawing arbitrary content by conforming your type to Dock.Item.

Modifiers#

After initializing an editor SwiftUI view you can apply any SwiftUI modifier to customize it like for any other SwiftUI view. All public Swift extensions of existing types provided by IMG.LY, e.g., for the SwiftUI View protocol, are exposed in a separate .imgly property namespace. The dock configuration to customize the editor is no exception to this rule and is implemented as SwiftUI modifiers.

All dock modifiers and Dock.Items provide the Dock.Context to access the engine, the asset library configuration, and the EditorEventHandler that can be used to send UI events.

dockItems - the @Dock.Builder that registers the Dock.Items and defines their order. Note that registering does not mean displaying. The items will be displayed if Dock.Item.isVisible(_:) returns true for them. The default implementation of this modifier depends on the used editor solution as each editor provides the most reasonable default behavior for its use case with minimal required code. This example shows the default implementation for the Design Editor. Please see the default dock items below for the defaults of the other solutions.

modifyDockItems - the modifications that should be applied to the order of items defined by the .imgly.dockItems builder above. This modifier can be used, when you do not want to touch the default general order of the items, but rather add additional items and replace/hide some of the default items. To achieve that, use the Dock.Modifier provided as the second closure argument, named items in this example, to add, replace, and remove items as highlighted in modify dock items. By default, no modifications are applied.

Default Dock Items#

This example shows the default implementations of the .imgly.dockItems modifier for each solution. You can overwrite these defaults by using the modifier in your code to define your own set of dock items.

These are the default items recommended to be used with the Design Editor.

These are the default items recommended to be used with the Photo Editor.

These are the default items recommended to be used with the Video Editor.

Apparel Editor and Postcard Editor don't expose their default dock item configurations but you can customize them with .imgly.dockItems. This will also allow you to apply .imgly.modifyDockItems.

Modify Dock Items#

In this example, we will modify the Design Editor dock items with the .imgly.modifyDockItems modifier. Each modification is only applied to the items defined by .imgly.dockItems. The operations also accept a @Dock.Builder so that you can define multiple items in the closures.

addFirst - prepends new Dock.Items.

addLast - appends new Dock.Items.

addAfter - adds new Dock.Items right after the item with the provided id. An error will be thrown if no item exists with the provided id.

addBefore - adds new Dock.Items right before the item with the provided id. An error will be thrown if no item exists with the provided id.

replace - replaces the Dock.Item with the provided id with new Dock.Items. An error will be thrown if no item exists with the provided id. The new items don't need to have the same id as the replaced item.

remove - removes the Dock.Item with the provided id. An error will be thrown if no item exists with the provided id.

Warning#

Note that the order of items may change between editor versions, therefore .imgly.modifyDockItems must be used with care. Consider overwriting the default items instead with .imgly.dockItems if you want to have strict ordering between different editor versions.

Dock.Item Configuration#

As mentioned in the Dock Architecture section, Dock.Item conforms to EditorComponent. Its id must be unique which is a requirement of the underlying SwiftUI ForEach type. Depending on your needs there are multiple ways to define an item. In this example, we demonstrate your options with increasing complexity.

Use Predefined Buttons#

The most basic option is to use our predefined buttons which are provided in the nested Dock.Buttons. namespace. All available predefined buttons are listed below.

Customize Predefined Buttons#

All parameters of our predefined buttons are initialized with default values which allows you to change any of them if needed to finetune the button's behavior and style. This example uses the default values of this particular predefined button.

action - the action to perform when the user triggers the button. In this example, the event handler is used to open a sheet with the asset library for adding an image.

title - the title View that should be used to label the button. Don't encode the visibility in this view. Use isVisible instead. In this example, a Text view is used.

icon - the icon View that should be used to label the button. Don't encode the visibility in this view. Use isVisible instead. In this example, an Image view is used. We provide all our used icon images in the nested Image.imgly. namespace.

isEnabled - whether the button is enabled. In this example, true is always used.

isVisible - whether the button should be visible. Prefer using this parameter to toggle the visibility instead of encoding it in the title and icon views. In this example, true is always used.

Create New Buttons#

If our predefined buttons don't fit your needs you can create your own.

id - the unique id of the button. This parameter is required.

action - the action to perform when the user triggers the button. This parameter is required.

label - a View that describes the purpose of the button’s action. Don't encode the visibility in this view. Use isVisible instead. This parameter is required.

isEnabled - whether the button is enabled. By default, true is always used.

isVisible - whether the button should be visible. Prefer using this parameter to toggle the visibility instead of encoding it in the label view. By default, true is always used.

Create New Custom Items#

If you need something completely custom you can use arbitrary views as items.

Therefore, you need to conform your type to the Dock.Item protocol.

var id: EditorComponentID { get } - the unique id of the item. This property is required.

func body(_: Dock.Context) throws -> some View - the body of your view. Don't encode the visibility in this view. Use isVisible instead. This property is required.

func isVisible(_: Dock.Context) throws -> Bool - whether the item should be visible. Prefer using this parameter to toggle the visibility instead of encoding it in the body view. By default, true is always used.


// swiftlint:disable unused_closure_parameter
// swiftformat:disable unusedArguments
import IMGLYDesignEditor
import SwiftUI

struct DockEditorSolution: View {
  let settings = EngineSettings(license: secrets.licenseKey,
                                userID: "<your unique user id>")

  var editor: some View {
    DesignEditor(settings)
      .imgly.dockItems { context in
        Dock.Buttons.elementsLibrary()
        Dock.Buttons.photoRoll()
        Dock.Buttons.systemCamera()
        Dock.Buttons.imagesLibrary()
        Dock.Buttons.textLibrary()
        Dock.Buttons.shapesLibrary()
        Dock.Buttons.stickersLibrary()
      }
      .imgly.modifyDockItems { context, items in
        items.addFirst {
          Dock.Button(id: "my.package.dock.button.first") { context in
            print("First Button action")
          } label: { context in
            Label("First Button", systemImage: "arrow.backward.circle")
          }
        }
        items.addLast {
          Dock.Button(id: "my.package.dock.button.last") { context in
            print("Last Button action")
          } label: { context in
            Label("Last Button", systemImage: "arrow.forward.circle")
          }
        }
        items.addAfter(id: Dock.Buttons.ID.photoRoll) {
          Dock.Button(id: "my.package.dock.button.afterPhotoRoll") { context in
            print("After Photo Roll action")
          } label: { context in
            Label("After Photo Roll", systemImage: "arrow.forward.square")
          }
        }
        items.addBefore(id: Dock.Buttons.ID.systemCamera) {
          Dock.Button(id: "my.package.dock.button.beforeSystemCamera") { context in
            print("Before Camera action")
          } label: { context in
            Label("Before Camera", systemImage: "arrow.backward.square")
          }
        }
        items.replace(id: Dock.Buttons.ID.textLibrary) {
          Dock.Button(id: "my.package.dock.button.replacedTextLibrary") { context in
            print("Replaced Text action")
          } label: { context in
            Label("Replaced Text ", systemImage: "arrow.uturn.down.square")
          }
        }
        items.remove(id: Dock.Buttons.ID.shapesLibrary)
      }
  }

  @State private var isPresented = false

  var body: some View {
    Button("Use the Editor") {
      isPresented = true
    }
    .fullScreenCover(isPresented: $isPresented) {
      ModalEditor {
        editor
      }
    }
  }
}

#Preview {
  DockEditorSolution()
}

List of Available Dock.Buttons#

This is a comprehensive list of all predefined buttons. Some of them were already used in the previous sections. They are static functions that look like this: Dock.Buttons.{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 the Customize Predefined Buttons section.

Button	ID	Description
Button `Dock.Buttons.elementsLibrary`	ID `Dock.Buttons.ID.elementsLibrary`	Description Opens library sheet with elements via editor event `.openSheet`. By default, the corresponding library is picked from the Asset Library.
Button `Dock.Buttons.overlaysLibrary`	ID `Dock.Buttons.ID.overlaysLibrary`	Description Opens library sheet with overlays via editor event `.openSheet`. By default, the corresponding library is picked from the Asset Library.
Button `Dock.Buttons.stickersAndShapesLibrary`	ID `Dock.Buttons.ID.stickersAndShapesLibrary`	Description Opens library sheet with stickers and shapes via editor event `.openSheet`. By default, the corresponding library is picked from the Asset Library.
Button `Dock.Buttons.imagesLibrary`	ID `Dock.Buttons.ID.imagesLibrary`	Description Opens library sheet with images via editor event `.openSheet`. By default, the corresponding library is picked from the Asset Library.
Button `Dock.Buttons.textLibrary`	ID `Dock.Buttons.ID.textLibrary`	Description Opens library sheet with text via editor event `.openSheet`. By default, the corresponding library is picked from the Asset Library.
Button `Dock.Buttons.shapesLibrary`	ID `Dock.Buttons.ID.shapesLibrary`	Description Opens library sheet with shapes via editor event `.openSheet`. By default, the corresponding library is picked from the Asset Library.
Button `Dock.Buttons.stickersLibrary`	ID `Dock.Buttons.ID.stickersLibrary`	Description Opens library sheet with stickers via editor event `.openSheet`. By default, the corresponding library is picked from the Asset Library.
Button `Dock.Buttons.audioLibrary`	ID `Dock.Buttons.ID.audioLibrary`	Description Opens library sheet with audio via editor event `.openSheet`. By default, the corresponding library is picked from the Asset Library.
Button `Dock.Buttons.photoRoll`	ID `Dock.Buttons.ID.photoRoll`	Description Opens the photo roll via via editor event `.addFromPhotoRoll`.
Button `Dock.Buttons.systemCamera`	ID `Dock.Buttons.ID.systemCamera`	Description Opens the system camera via editor event `.addFromSystemCamera`.
Button `Dock.Buttons.imglyCamera`	ID `Dock.Buttons.ID.imglyCamera`	Description Opens the IMG.LY camera via editor event `.addFromIMGLYCamera`.
Button `Dock.Buttons.voiceover`	ID `Dock.Buttons.ID.voiceover`	Description Opens voiceover sheet via editor event `.openSheet`.
Button `Dock.Buttons.reorder`	ID `Dock.Buttons.ID.reorder`	Description Opens reorder sheet via editor event `.openSheet`.
Button `Dock.Buttons.adjustments`	ID `Dock.Buttons.ID.adjustments`	Description Opens adjustment sheet via editor event `.openSheet`.
Button `Dock.Buttons.filter`	ID `Dock.Buttons.ID.filter`	Description Opens filter sheet via editor event `.openSheet`.
Button `Dock.Buttons.effect`	ID `Dock.Buttons.ID.effect`	Description Opens effect sheet via editor event `.openSheet`.
Button `Dock.Buttons.blur`	ID `Dock.Buttons.ID.blur`	Description Opens blur sheet via editor event `.openSheet`.
Button `Dock.Buttons.crop`	ID `Dock.Buttons.ID.crop`	Description Opens crop sheet via editor event `.openSheet`.