diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/Compass.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/Compass.xml deleted file mode 100644 index b3a933902415..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/Compass.xml +++ /dev/null @@ -1,134 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Object - - - - Monitor changes to the orientation of the user's device. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.Boolean - - - Gets if compass is actively being monitored. - If compass is being monitored. - - - - - - - - Event - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.EventHandler<Microsoft.Maui.Essentials.CompassChangedEventArgs> - - - Event triggered when compass reading changes. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - Determines if the calibration screen should be displayed. - Gets or sets if this should be displayed when started. - Only available on iOS - - - - - - - Method - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.Void - - - - - - The speed to monitor for changes. - Start monitoring for changes to the compass. - Will throw FeatureNotSupportedException if not supported on device. Will throw ArgumentNullException if handler is null. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Void - - - - - - - The speed to monitor for changes. - Whether or not to apply a moving average filter (only used on Android). - Start monitoring for changes to the compass. - Will throw FeatureNotSupportedException if not supported on device. Will throw ArgumentNullException if handler is null. - - - - - - - Method - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.Void - - - - Stop monitoring for changes to the compass. - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/CompassChangedEventArgs.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/CompassChangedEventArgs.xml deleted file mode 100644 index 5a996f18248d..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/CompassChangedEventArgs.xml +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.EventArgs - - - - Event arguments when compass reading changes. - - - - - - - - Constructor - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - - - The current compass reading. - Public constructor - To be added. - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - Microsoft.Maui.Essentials.CompassData - - - Gets the current reading. - The reading. - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/CompassData.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/CompassData.xml deleted file mode 100644 index 8c8d8b14235e..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/CompassData.xml +++ /dev/null @@ -1,199 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.ValueType - - - - System.IEquatable<Microsoft.Maui.Essentials.CompassData> - - - - - System.Runtime.CompilerServices.IsReadOnly - - - - - Contains the orientation of the user's device. - - - - - - - - - Constructor - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - - - A reading of compass data for heading magnetic north. - Public constructor. - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - Object to compare - If equal to another object - If equal - - - - - - - - Method - - M:System.IEquatable`1.Equals(`0) - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - Other AccelerometerData to compare with. - Compares the underlying doubles. - True if they are equal, otherwise false. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Int32 - - - - Get the hash code for object. - The hash code - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.Double - - - The heading (measured in degrees) relative to magnetic north. - The magnetic north heading. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - Left to compare - Right to compare - Equality operator for equals - If equal - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - Left to check - Right to check - Inequality check - If not equal - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.String - - - - Current string representation of the data. - - To be added. - - - - diff --git a/src/Essentials/src/Compass/Compass.ios.cs b/src/Essentials/src/Compass/Compass.ios.cs index a22f1e9f9150..35d1bda75332 100644 --- a/src/Essentials/src/Compass/Compass.ios.cs +++ b/src/Essentials/src/Compass/Compass.ios.cs @@ -4,7 +4,7 @@ namespace Microsoft.Maui.Devices.Sensors { partial class CompassImplementation : ICompass, IPlatformCompass { - // The angular distance is measured relative to the last delivered heading event. Align with UWP numbers + // The angular distance is measured relative to the last delivered heading event. Align with Windows numbers internal const double FastestFilter = .01; internal const double GameFilter = .5; internal const double NormalFilter = 1; diff --git a/src/Essentials/src/Compass/Compass.shared.cs b/src/Essentials/src/Compass/Compass.shared.cs index 742fbe366099..996718695ad0 100644 --- a/src/Essentials/src/Compass/Compass.shared.cs +++ b/src/Essentials/src/Compass/Compass.shared.cs @@ -4,21 +4,48 @@ namespace Microsoft.Maui.Devices.Sensors { + /// + /// Monitor changes to the orientation of the user's device. + /// public interface ICompass { + /// + /// Gets a value indicating whether reading the compass is supported on this device. + /// bool IsSupported { get; } + /// + /// Gets if compass is actively being monitored. + /// bool IsMonitoring { get; } + /// + /// Start monitoring for changes to the compass. + /// + /// The speed to monitor for changes. void Start(SensorSpeed sensorSpeed); + /// + /// Start monitoring for changes to the compass. + /// + /// The speed to monitor for changes. + /// Whether or not to apply a moving average filter (only used on Android). void Start(SensorSpeed sensorSpeed, bool applyLowPassFilter); + /// + /// Stop monitoring for changes to the compass. + /// void Stop(); + /// + /// Occurs when compass reading changes. + /// event EventHandler ReadingChanged; } + /// + /// Platform-specific APIs for use with + /// public interface IPlatformCompass { #if IOS || MACCATALYST @@ -26,35 +53,66 @@ public interface IPlatformCompass #endif } - /// + /// + /// Monitor changes to the orientation of the user's device. + /// public static class Compass { + /// + /// Occurs when compass reading changes. + /// public static event EventHandler ReadingChanged { add => Current.ReadingChanged += value; remove => Current.ReadingChanged -= value; } + /// + /// Gets a value indicating whether reading the compass is supported on this device. + /// public static bool IsSupported => Current.IsSupported; - /// + /// + /// Gets a value indicating whether the compass is actively being monitored. + /// public static bool IsMonitoring => Current.IsMonitoring; - /// + /// + /// Start monitoring for changes to the compass. + /// + /// + /// Will throw if not supported on device. + /// Will throw if is . + /// + /// The speed to monitor for changes. public static void Start(SensorSpeed sensorSpeed) => Start(sensorSpeed, true); - /// + /// + /// Start monitoring for changes to the compass. + /// + /// + /// Will throw if not supported on device. + /// Will throw if is . + /// + /// The speed to monitor for changes. + /// Whether or not to apply a moving average filter (only used on Android). public static void Start(SensorSpeed sensorSpeed, bool applyLowPassFilter) => Current.Start(sensorSpeed, applyLowPassFilter); - /// + /// + /// Stop monitoring for changes to the compass. + /// public static void Stop() => Current.Stop(); #if IOS || MACCATALYST + /// + /// Gets or sets a value specifying whether the calibration screen should be displayed. + /// + /// Only available on iOS. public static bool ShouldDisplayHeadingCalibration { get @@ -75,6 +133,9 @@ public static bool ShouldDisplayHeadingCalibration static ICompass? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static ICompass Default => defaultImplementation ??= new CompassImplementation(); @@ -82,9 +143,16 @@ internal static void SetDefault(ICompass? implementation) => defaultImplementation = implementation; } + /// + /// /// This class contains static extension methods for use with . + /// public static class CompassExtensions { #if IOS || MACCATALYST + /// + /// Gets or sets a value specifying whether the calibration screen should be displayed. + /// + /// Only available on iOS. public static void SetShouldDisplayHeadingCalibration(this ICompass compass, bool shouldDisplay) { if (compass is IPlatformCompass platform) @@ -95,46 +163,82 @@ public static void SetShouldDisplayHeadingCalibration(this ICompass compass, boo #endif } - /// + /// + /// Event arguments when compass reading changes. + /// public class CompassChangedEventArgs : EventArgs { - /// + /// + /// Initializes a new instance of the class. + /// + /// The compass data reading. public CompassChangedEventArgs(CompassData reading) => Reading = reading; - /// + /// + /// The current values of the compass. + /// public CompassData Reading { get; } } - /// + /// + /// Contains the orientation of the user's device. + /// public readonly struct CompassData : IEquatable { - /// + /// + /// Initializes a new instance of the class. + /// + /// A reading of compass data for heading magnetic north. public CompassData(double headingMagneticNorth) => HeadingMagneticNorth = headingMagneticNorth; - /// + /// + /// The heading (measured in degrees) relative to magnetic north. + /// public double HeadingMagneticNorth { get; } - /// + /// + /// Compares the underlying instances. + /// + /// Object to compare with. + /// if they are equal, otherwise . public override bool Equals(object? obj) => (obj is CompassData data) && Equals(data); - /// + /// + /// Compares the underlying instances. + /// + /// Object to compare with. + /// if they are equal, otherwise . public bool Equals(CompassData other) => HeadingMagneticNorth.Equals(other.HeadingMagneticNorth); + /// + /// Equality operator for equals. + /// + /// Left to compare. + /// Right to compare. + /// if objects are equal, otherwise . public static bool operator ==(CompassData left, CompassData right) => left.Equals(right); + /// + /// Inequality operator. + /// + /// Left to compare. + /// Right to compare. + /// if objects are not equal, otherwise . public static bool operator !=(CompassData left, CompassData right) => !left.Equals(right); - /// public override int GetHashCode() => HeadingMagneticNorth.GetHashCode(); - /// + /// + /// Returns a string representation of the current values of . + /// + /// A string representation of this instance in the format of HeadingMagneticNorth: {value}. public override string ToString() => $"{nameof(HeadingMagneticNorth)}: {HeadingMagneticNorth}"; }