Mhd/refactor compass action

Documentation/Compass/README.md

@@ -10,7 +10,8 @@ The ArcGIS Maps SDK for Swift currently supports rotating MapViews and SceneView
 
 Compass:
 
-- Can be configured to automatically hide when the rotation is zero.
+- Automatically hides when the rotation is zero.
+- Can be configured to be always visible.
 - Will reset the map/scene rotation to North when tapped on.
 
 ## Key properties
@@ -23,9 +24,8 @@ Compass:
     /// direction toward true East, etc.).
     /// - Parameters:
     ///   - heading: The heading of the compass.
-    ///   - autoHide: A Boolean value that determines whether the compass
-    ///   automatically hides itself when the heading is `0`.
-    public init(heading: Binding<Double>, autoHide: Bool = true)
+    ///   - action: An action to perform when the compass is tapped.
+    public init(heading: Binding<Double>, action: (() async -> Void)? = nil)
 ```
 
 ```swift
@@ -35,27 +35,26 @@ Compass:
     /// - Parameters:
     ///   - viewpointRotation: The viewpoint rotation whose value determines the
     ///   heading of the compass.
-    ///   - autoHide: A Boolean value that determines whether the compass
-    ///   automatically hides itself when the viewpoint rotation is 0 degrees.
-    public init(viewpointRotation: Binding<Double>, autoHide: Bool = true)
+    ///   - action: An action to perform when the compass is tapped.
+    public init(viewpointRotation: Binding<Double>, action: (() async -> Void)? = nil)
 ```
 
 ```swift
     /// Creates a compass with a binding to an optional viewpoint.
     /// - Parameters:
     ///   - viewpoint: The viewpoint whose rotation determines the heading of the compass.
-    ///   - autoHide: A Boolean value that determines whether the compass automatically hides itself
-    ///   when the viewpoint's rotation is 0 degrees.
-    public init(viewpoint: Binding<Viewpoint?>, autoHide: Bool = true)
+    ///   - action: An action to perform when the compass is tapped.
+    public init(viewpoint: Binding<Viewpoint?>, action: (() async -> Void)? = nil)
 ```
 
-`Compass` has the following modifier:
+`Compass` has the following modifiers:
 
 - `func compassSize(size: CGFloat)` - The size of the `Compass`, specifying both the width and height of the compass.
+- `func automaticallyHides(newAutomaticallyHides: Bool)` - Specifies whether the ``Compass`` should automatically hide when the heading is 0.
 
 ## Behavior:
 
-Whenever the map is not orientated North (non-zero bearing) the compass appears. When reset to north, it disappears. An initializer argument allows you to disable the auto-hide feature so that it always appears.
+Whenever the map is not orientated North (non-zero bearing) the compass appears. When reset to north, it disappears. The `automaticallyHides` view modifier allows you to disable the auto-hide feature so that it is always displayed.
 
 When the compass is tapped, the map orients back to north (zero bearing).
 

Examples/Examples/CompassExampleView.swift

@@ -15,27 +15,118 @@ import ArcGIS
 import ArcGISToolkit
 import SwiftUI
 
+/// An example demonstrating how to use a compass in three different environments.
 struct CompassExampleView: View {
-    /// The data model containing the `Map` displayed in the `MapView`.
-    @StateObject private var dataModel = MapDataModel(
-        map: Map(basemapStyle: .arcGISImagery)
-    )
+    /// A scenario represents a type of environment a compass may be used in.
+    enum Scenario: String {
+        case map
+        case scene
+    }
+
+    /// The active scenario.
+    @State private var scenario = Scenario.map
+
+    var body: some View {
+        Group {
+            switch scenario {
+            case .map:
+                MapWithViewpoint()
+            case .scene:
+                SceneWithCameraController()
+            }
+        }
+        .toolbar {
+            ToolbarItem(placement: .navigationBarTrailing) {
+                Menu(scenario.rawValue.capitalized) {
+                    Button {
+                        scenario = .map
+                    } label: {
+                        Label("Map", systemImage: "map.fill")
+                    }
+
+                    Button {
+                        scenario = .scene
+                    } label: {
+                        Label("Scene", systemImage: "globe.americas.fill")
+                    }
+                }
+                .labelStyle(.titleAndIcon)
+            }
+        }
+    }
+}
+
+/// An example demonstrating how to use a compass with a map view.
+struct MapWithViewpoint: View {
+    /// The `Map` displayed in the `MapView`.
+    @State private var map = Map(basemapStyle: .arcGISImagery)
 
     /// Allows for communication between the Compass and MapView or SceneView.
     @State private var viewpoint: Viewpoint? = Viewpoint(
-        center: Point(x: -117.19494, y: 34.05723, spatialReference: .wgs84),
+        center: .esriRedlands,
         scale: 10_000,
         rotation: -45
     )
 
     var body: some View {
-        MapView(map: dataModel.map, viewpoint: viewpoint)
-            .onViewpointChanged(kind: .centerAndScale) { viewpoint = $0 }
-            .overlay(alignment: .topTrailing) {
-                Compass(viewpoint: $viewpoint)
-                    // Optionally provide a different size for the compass.
-                    // .compassSize(size: <#T##CGFloat#>)
+        MapViewReader { proxy in
+            MapView(map: map, viewpoint: viewpoint)
+                .onViewpointChanged(kind: .centerAndScale) { viewpoint = $0 }
+                .overlay(alignment: .topTrailing) {
+                    Compass(viewpoint: $viewpoint) {
+                        guard let viewpoint else { return }
+                        // Animate the map view to zero when the compass is tapped.
+                        await proxy.setViewpoint(
+                            viewpoint.withRotation(0),
+                            duration: 0.25
+                        )
+                    }
                     .padding()
+                }
+        }
+    }
+}
+
+/// An example demonstrating how to use a compass with a scene view and camera controller.
+struct SceneWithCameraController: View {
+    /// The data model containing the `Scene` displayed in the `SceneView`.
+    @State private var scene = Scene(basemapStyle: .arcGISImagery)
+
+    /// The current heading as reported by the scene view.
+    @State private var heading = Double.zero
+
+    /// The orbit location camera controller used by the scene view.
+    private let cameraController = OrbitLocationCameraController(
+        target: .esriRedlands,
+        distance: 10_000
+    )
+
+    var body: some View {
+        SceneView(scene: scene, cameraController: cameraController)
+            .onCameraChanged { newCamera in
+                heading = newCamera.heading.rounded()
+            }
+            .overlay(alignment: .topTrailing) {
+                Compass(viewpointRotation: $heading) {
+                    // Animate the scene view when the compass is tapped.
+                    _ = try? await cameraController.moveCamera(
+                        distanceDelta: .zero,
+                        headingDelta: heading > 180 ? 360 - heading : -heading,
+                        pitchDelta: .zero,
+                        duration: 0.3
+                    )
+                }
+                .padding()
             }
     }
 }
+
+private extension Point {
+    static var esriRedlands: Point {
+        .init(
+            x: -117.19494,
+            y: 34.05723,
+            spatialReference: .wgs84
+        )
+    }
+}

Sources/ArcGISToolkit/Components/Compass/Compass.swift

@@ -17,21 +17,24 @@ import SwiftUI
 /// A `Compass` (alias North arrow) shows where north is in a `MapView` or
 /// `SceneView`.
 public struct Compass: View {
-    /// A Boolean value indicating whether  the compass should automatically
-    /// hide/show itself when the heading is `0`.
-    private let autoHide: Bool
-
     /// The opacity of the compass.
     @State private var opacity: Double = .zero
 
+    /// An action to perform when the compass is tapped.
+    private let action: (() async -> Void)?
+
+    /// A Boolean value indicating whether  the compass should automatically
+    /// hide/show itself when the heading is `0`.
+    private var autoHide: Bool = true
+
     /// A Boolean value indicating whether the compass should hide based on the
     ///  current heading and whether the compass automatically hides.
     var shouldHide: Bool {
         (heading.isZero || heading.isNaN) && autoHide
     }
 
     /// The width and height of the compass.
-    var size: CGFloat = 44
+    private var size: CGFloat = 44
 
     /// The heading of the compass in degrees.
     @Binding private var heading: Double
@@ -41,14 +44,13 @@ public struct Compass: View {
     /// direction toward true East, etc.).
     /// - Parameters:
     ///   - heading: The heading of the compass.
-    ///   - autoHide: A Boolean value that determines whether the compass
-    ///   automatically hides itself when the heading is `0`.
+    ///   - action: An action to perform when the compass is tapped.
     public init(
         heading: Binding<Double>,
-        autoHide: Bool = true
+        action: (() async -> Void)? = nil
     ) {
         _heading = heading
-        self.autoHide = autoHide
+        self.action = action
     }
 
     public var body: some View {
@@ -60,16 +62,22 @@ public struct Compass: View {
                 }
                 .aspectRatio(1, contentMode: .fit)
                 .opacity(opacity)
-                .onTapGesture { heading = .zero }
                 .frame(width: size, height: size)
+                .onAppear { opacity = shouldHide ? 0 : 1 }
                 .onChange(of: heading) { _ in
                     let newOpacity: Double = shouldHide ? .zero : 1
                     guard opacity != newOpacity else { return }
                     withAnimation(.default.delay(shouldHide ? 0.25 : 0)) {
                         opacity = newOpacity
                     }
                 }
-                .onAppear { opacity = shouldHide ? 0 : 1 }
+                .onTapGesture {
+                    if let action {
+                        Task { await action() }
+                    } else {
+                        heading = .zero
+                    }
+                }
                 .accessibilityLabel("Compass, heading \(Int(heading.rounded())) degrees \(CompassDirection(heading).rawValue)")
         }
     }
@@ -82,28 +90,27 @@ public extension Compass {
     /// - Parameters:
     ///   - viewpointRotation: The viewpoint rotation whose value determines the
     ///   heading of the compass.
-    ///   - autoHide: A Boolean value that determines whether the compass
-    ///   automatically hides itself when the viewpoint rotation is 0 degrees.
+    ///   - action: An action to perform when the compass is tapped.
     init(
         viewpointRotation: Binding<Double>,
-        autoHide: Bool = true
+        action: (() async -> Void)? = nil
     ) {
         let heading = Binding(get: {
             viewpointRotation.wrappedValue.isZero ? .zero : 360 - viewpointRotation.wrappedValue
         }, set: { newHeading in
             viewpointRotation.wrappedValue = newHeading.isZero ? .zero : 360 - newHeading
         })
-        self.init(heading: heading, autoHide: autoHide)
+        self.init(heading: heading, action: action)
     }
 
     /// Creates a compass with a binding to an optional viewpoint.
     /// - Parameters:
     ///   - viewpoint: The viewpoint whose rotation determines the heading of the compass.
-    ///   - autoHide: A Boolean value that determines whether the compass automatically hides itself
+    ///   - action: An action to perform when the compass is tapped.
     ///   when the viewpoint's rotation is 0 degrees.
     init(
         viewpoint: Binding<Viewpoint?>,
-        autoHide: Bool = true
+        action: (() async -> Void)? = nil
     ) {
         let viewpointRotation = Binding {
             viewpoint.wrappedValue?.rotation ?? .nan
@@ -115,7 +122,7 @@ public extension Compass {
                 rotation: newViewpointRotation
             )
         }
-        self.init(viewpointRotation: viewpointRotation, autoHide: autoHide)
+        self.init(viewpointRotation: viewpointRotation, action: action)
     }
 
     /// Define a custom size for the compass.
@@ -125,4 +132,13 @@ public extension Compass {
         copy.size = size
         return copy
     }
+
+    /// Specifies whether the ``Compass`` should automatically hide when the heading is 0.
+    /// - Parameter newAutomaticallyHides: A Boolean value indicating whether  the compass should automatically
+    /// hide/show itself when the heading is `0`.
+    func automaticallyHides(_ newAutomaticallyHides: Bool) -> some View {
+        var copy = self
+        copy.autoHide = newAutomaticallyHides
+        return copy
+    }
 }

Sources/ArcGISToolkit/Extensions/Viewpoint.swift

@@ -0,0 +1,35 @@
+// Copyright 2023 Esri.
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import ArcGIS
+
+public extension Viewpoint {
+    /// Creates a new viewpoint with the same target geometry and scale but with a new rotation.
+    /// - Parameter rotation: The rotation for the new viewpoint.
+    /// - Returns: A new viewpoint.
+    func withRotation(_ rotation: Double) -> Viewpoint {
+        switch self.kind {
+        case .centerAndScale:
+            return Viewpoint(
+                center: self.targetGeometry as! Point,
+                scale: self.targetScale,
+                rotation: rotation
+            )
+        case.boundingGeometry:
+            return Viewpoint(
+                boundingGeometry: self.targetGeometry,
+                rotation: rotation
+            )
+        }
+    }
+}