The map shows three kinds of things you put on it: annotations, pins, and 3D models (see 3D content). This page covers the first two, and how to react to taps.
- Annotations are live SwiftUI views, for a few rich things: a callout, a button, the selected place.
- Pins are pictures the map draws itself, for many things: hundreds or thousands of places, photos, icons.
Annotations
Any SwiftUI view can stand at a coordinate:
ImmersiveMapView()
.annotations(places, coordinate: \.coordinate) { place in
Label(place.name, systemImage: "mappin")
.padding(6)
.background(.thinMaterial, in: Capsule())
}
places is a collection of Identifiable items. The view follows its coordinate on every frame, on the globe and on the flat map, and fades out behind the globe’s horizon. anchor: sets which point of the view stands on the coordinate, the centre by default. The last item draws on top.
An annotation handles its own taps, with a Button or .onTapGesture. Touches outside the annotations go to the map. A later .annotations(...) call replaces the earlier set.
Make your items Equatable when you can. The map then leaves an annotation’s view untouched while its item stays equal, so adding or removing a few annotations costs only those few. The view has to be made from the item alone: state it reads from elsewhere does not reach an annotation whose item did not change.
Use annotations for a few rich views. Each one is a live view, and a map with hundreds of them slows down. For many points, use pins or a layer.
Pins
Pins are pictures drawn by the map itself, so many of them stay smooth where SwiftUI views would not. A pin shows its picture in a round frame. Keep an ImmersiveMapPinsController and attach it:
@State private var pins = ImmersiveMapPinsController()
var body: some View {
ImmersiveMapView()
.pins(pins)
.onAppear {
pins.set([
ImmersiveMapPin(id: 1,
coordinate: GeoCoordinate(latitude: 55.75, longitude: 37.62),
image: .remote(photoURL, placeholder: placeholder)),
])
}
}
- The picture. A
CGImage, or.remote(url, placeholder:), which the map downloads and shows the placeholder until then. - Look.
borderColor,screenSizeScale, anddrawPriority, where a higher priority draws on top. - Changes.
add,upsert,set,move(id:to:),update(id:image:borderColor:isSelected:),remove(ids:)andclear(). The controller is thread-safe, so you can update it from any thread. - Groups.
merge(ids:...)shows several pins as one, with a counter and their pictures in turn, andunmerge(mergedID:)splits them again.
The size and the border of every pin are set with .pinSettings(size:sizeScale:borderWidthPx:...).
Pins that make room
Pins that would overlap push each other apart. A pin pushed off its place stays tied to it by a beam, like a pin on a rubber band, and comes back when there is room. Turn it off when the exact place matters more than seeing every pin whole:
ImmersiveMapView()
.pinSettings(spreadsApart: false)
Then every pin stands exactly on its coordinate, and pins may cover each other.
Taps
ImmersiveMapView()
.onPinTap { event in
print("tapped pin \(event.pin.id)")
}
.onSceneModelTap { event in
print("tapped model \(event.model.id)")
}
Both arrive on every tap, also on an object that is already selected. A tap on the map itself, away from everything, reaches onMapBackgroundTap of the camera controller or the selection controller.
Selection
To have the map remember what is selected, attach an ImmersiveMapSelectionController:
@State private var selection = ImmersiveMapSelectionController()
ImmersiveMapView()
.selection(selection)
A tap selects a pin, a model or a shape of a layer, and a tap on the empty map clears the selection. onSelectionChanged and onSelectionCleared report it, and select(_:) and clearSelection() change it from code:
selection.select(ImmersiveMapSelection(kind: .pin, objectID: 1))
A selection names its object by a kind and the object’s id: .pin, .sceneModel, or .layer("zones") for a shape of a layer (see Your own data). The kinds are an open set, so a switch over one needs a default.