SpatialEventGesture

A gesture that provides information about ongoing spatial events like clicks and touches.

StructureiOS 18.0+macOS 15.0+watchOS 11.0+visionOS 1.0+SpatialEventGesture in SwiftUI

Declaration

React
type SpatialEventGesture = { coordinateSpace?: CoordinateSpaceProtocol; };
Swift
nonisolated struct SpatialEventGesture

Type methods

Properties

Overview

Use a gesture of this type to track multiple simultaneous spatial events and gain access to detailed information about each. For example, you can place a particle emitter at every location in a Canvas that has an ongoing spatial event:

struct ParticlePlayground: View {
    @State private var model = ParticlesModel()
```swift

var body: some View {
    Canvas { context, size in
        for particle in model.particles {
            context.fill(Path(ellipseIn: particle.frame),
                         with: .color(particle.color))
        }
    }
    .gesture(
        SpatialEventGesture()
            .onChanged { events in
                for event in events {
                    if event.phase == .active {
                        // Update particle emitters.
                        model.emitters[event.id] = ParticlesModel.Emitter(
                            location: event.location
                        )
                    } else {
                        // Remove emitters when no longer active.
                        model.emitters[event.id] = nil
                    }
                }
            }
            .onEnded { events in
                for event in events {
                    // Remove emitters when no longer active.
                    model.emitters[event.id] = nil
                }
            }
    )
}

}


The gesture provides a [`SpatialEventCollection`](/docs/values/spatialeventcollection) structure when it detects
changes. The collection contains [`SpatialEventCollection.Event`](/docs/values/spatialeventcollection#event) values
that represent ongoing spatial events. Each event contains a stable, unique
identifier so that you can track how the event changes over time. The event
also indicates its current location, a timestamp, the pose of the
input device that creates it, and other useful information.

The phase of events in the collection can change
to [`SpatialEventCollection.Event.Phase.ended`](/docs/values/spatialeventcollection#event) or
[`SpatialEventCollection.Event.Phase.cancelled`](/docs/values/spatialeventcollection#event) while the gesture itself
remains active. Individually track state for each event inside
[`Gesture.onChanged(_:)`](/docs/values/gesture#onchanged) or [`Gesture.updating(_:body:)`](/docs/values/gesture#updating) and clean up all
state in [`Gesture.onEnded(_:)`](/docs/values/gesture#onended).

> **Tip:** Only use a spatial event gesture if you need to access low-level event information, like when you create a complex multi-touch experience. For most use cases, it's better to rely on gestures that recognize targeted interactions, like a [`SpatialTapGesture`](/docs/values/spatialtapgesture), [`MagnifyGesture`](/docs/values/magnifygesture), or [`DragGesture`](/docs/values/draggesture).

From Apple’s SwiftUI documentation. Code samples there are Swift.

See also

More in Gestures and input.