UI Events

import IMGLYEditor
import IMGLYEngine
import SwiftUI

@MainActor
final class UiEventsLog: ObservableObject {
  @Published var lastEvent: String = "Waiting for editor events"
}

struct UiEventsEditorSolution: View {
  let settings = EngineSettings(license: secrets.licenseKey, // pass nil for evaluation mode with watermark
                                userID: "<your unique user id>")

  @StateObject private var log = UiEventsLog()
  @State private var isPresented = false

  var editor: some View {
    Editor(settings)
      .imgly.configuration {
        GuideEditorConfiguration { builder in
          builder.onChanged { [log] update, _, existing in
            try existing()
            let message: String = switch update {
            case let .viewMode(_, new):
              "View mode changed to \(new.editorViewMode)"
            case let .page(_, new):
              "Page index changed to \(new)"
            case let .editMode(_, new):
              "Edit mode changed to \(new)"
            case let .gestureActive(_, isActive):
              isActive ? "Canvas touch started" : "Canvas touch ended"
            }
            log.lastEvent = message
          }

          builder.onLoaded { [log] context, existing in
            try await existing()
            context.eventHandler.send(.setExtraCanvasInsets(24))
            log.lastEvent = "Editor loaded"
          }

          builder.dock { dock in
            dock.items { _ in
              Dock.Buttons.elementsLibrary()
              Dock.Button(id: "app.dock.button.preview") { context in
                context.eventHandler.send(.setViewMode(.preview))
              } label: { _ in
                Label("Preview", systemImage: "eye")
              }
            }
          }
        }
      }
  }

  var body: some View {
    Button("Use the Editor") { isPresented = true }
      .fullScreenCover(isPresented: $isPresented) {
        ModalEditor {
          editor
            .safeAreaInset(edge: .top) {
              Text(log.lastEvent)
                .font(.footnote)
                .padding(.horizontal, 12)
                .padding(.vertical, 6)
                .background(.thinMaterial, in: Capsule())
                .padding(.top, 4)
            }
        }
      }
  }
}

#Preview {
  UiEventsEditorSolution()
}

This guide walks through both APIs. The examples build on GuideEditorConfiguration, a minimal baseline that ships only a navigation bar (close, undo, redo). See the Configuration guide for how EditorConfiguration and EngineSettings set up the editor as a whole. If you need CreativeEngine block lifecycle changes (created, updated, or destroyed blocks) instead, use Events — that guide uses engine.event.subscribe() and is separate from both editor APIs covered here.

Sending Editor Events#

An EditorEvent is a value your app dispatches to the editor to drive an action — change the view mode, open a sheet, start an export, share a file, close the editor, surface an error. You dispatch by calling send(_:) on an EditorEventHandler, which the editor makes available in every component context and in every EditorConfiguration.Builder lifecycle callback except onCreate and onUpload. onLoaded and onChanged expose it via context.eventHandler; onExport, onClose, and onError receive it as a dedicated parameter.

The built-in events are defined as static functions or properties on EditorEvent. See the List of Available Editor Events below for the full catalog.

From a Lifecycle Callback#

onLoaded is a natural place to dispatch an event once the editor is ready:

builder.onLoaded { [log] context, existing in
  try await existing()
  context.eventHandler.send(.setExtraCanvasInsets(24))
  log.lastEvent = "Editor loaded"
}

Other callbacks fit specific event families: dispatch .exportProgress(_:) and .shareFile(_:) from onExport, or .showErrorAlert(_:) from onError.

From a Custom UI Component#

Every editor component receives its event handler through its component context. This example declares a dock that includes a custom button which switches the editor into preview mode when tapped. dock.items { ... } replaces the dock’s item list wholesale, so any button you want to keep must be included in the closure.

builder.dock { dock in
  dock.items { _ in
    Dock.Buttons.elementsLibrary()
    Dock.Button(id: "app.dock.button.preview") { context in
      context.eventHandler.send(.setViewMode(.preview))
    } label: { _ in
      Label("Preview", systemImage: "eye")
    }
  }
}

Observing Editor State Changes#

builder.onChanged is a separate mechanism: instead of your app driving the editor, the editor notifies your app when its own state advances. Configure the handler on the EditorConfiguration.Builder. It runs on the main actor and receives an EditorStateChange that covers the four state axes the editor tracks.

builder.onChanged { [log] update, _, existing in
  try existing()
  let message: String = switch update {
  case let .viewMode(_, new):
    "View mode changed to \(new.editorViewMode)"
  case let .page(_, new):
    "Page index changed to \(new)"
  case let .editMode(_, new):
    "Edit mode changed to \(new)"
  case let .gestureActive(_, isActive):
    isActive ? "Canvas touch started" : "Canvas touch ended"
  }
  log.lastEvent = message
}

The EditorStateChange cases are:

Call try existing() to chain any previously registered handler — including the Starter Kits’ defaults — before running your own logic.

Some state changes are downstream effects of events you sent (dispatching .setViewMode(.preview) eventually flips the observed view mode); others come from user interaction the app never sees directly (a canvas gesture emits .gestureActive with no matching event).

Route Observed State into SwiftUI#

Keep UI state in regular SwiftUI storage and update it from the observation handler. A small ObservableObject bridges the editor’s callbacks into your app’s @StateObject, so any view that reads it stays in sync with editor activity.

editor
  .safeAreaInset(edge: .top) {
    Text(log.lastEvent)
      .font(.footnote)
      .padding(.horizontal, 12)
      .padding(.vertical, 6)
      .background(.thinMaterial, in: Capsule())
      .padding(.top, 4)
  }

safeAreaInset(edge: .top) layers your view above the editor without pushing content into the canvas area. Because the store is @MainActor, @Published updates from inside the handler flow into the overlay immediately.

Lifecycle Callbacks#

EditorConfiguration.Builder exposes seven callbacks that fire at specific points in the editor’s lifetime. Five of them expose an EditorEventHandler (as covered in Sending Editor Events); two receive only the engine.

Each callback receives an existing closure — call try existing() (or try await existing()) to chain the previous handler, including the Starter Kits’ defaults, before running your own logic.

List of Available Editor Events#

Built-in events are static factory functions or properties on EditorEvent. Selection, add-from, and navigation events live in nested namespaces on EditorEvents.

API Reference#

Methods#

Key Types#

Next Steps#

• Events — Subscribe to CreativeEngine block lifecycle events for created, updated, or destroyed blocks.
• Configuration — Configure EditorConfiguration and EngineSettings for the editor as a whole.
• Design Editor Starter Kit — Explore a complete iOS editor surface built on the same configuration layer.