From 4dc1b8591bcaa3a99c89c574d17d6920f37805e6 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 14:55:16 +0100 Subject: [PATCH 01/12] Update Essentials API Docs Misc --- .../Microsoft.Maui.Essentials/DeviceIdiom.xml | 291 ---------------- .../DevicePlatform.xml | 327 ----------------- .../Microsoft.Maui.Essentials/DisplayInfo.xml | 329 ------------------ .../DisplayOrientation.xml | 69 ---- .../DisplayRotation.xml | 103 ------ .../Xamarin.Essentials/DisplayOrientation.xml | 69 ---- .../src/Accelerometer/Accelerometer.shared.cs | 2 + .../src/Barometer/Barometer.shared.cs | 1 + src/Essentials/src/Compass/Compass.shared.cs | 8 +- .../src/FilePicker/FilePicker.shared.cs | 7 + .../src/FileSystem/FileSystem.shared.cs | 6 +- .../src/Magnetometer/Magnetometer.shared.cs | 1 + .../OrientationSensor.shared.cs | 23 ++ .../src/Platform/Platform.shared.cs | 30 +- .../src/Platform/WindowStateManager.ios.cs | 36 ++ .../src/Platform/WindowStateManager.uwp.cs | 42 +++ .../src/Types/DeviceIdiom.shared.cs | 64 +++- .../src/Types/DevicePlatform.shared.cs | 80 ++++- .../src/Types/DisplayInfo.shared.cs | 84 ++++- .../src/Types/DisplayOrientation.shared.cs | 12 +- .../src/Types/DisplayRotation.shared.cs | 18 +- src/Essentials/src/Types/Location.shared.cs | 2 + .../WebAuthenticator.shared.cs | 3 + 23 files changed, 364 insertions(+), 1243 deletions(-) delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/DeviceIdiom.xml delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/DevicePlatform.xml delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/DisplayInfo.xml delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/DisplayOrientation.xml delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/DisplayRotation.xml delete mode 100644 src/Essentials/docs/en/Xamarin.Essentials/DisplayOrientation.xml diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/DeviceIdiom.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/DeviceIdiom.xml deleted file mode 100644 index 3b257f844e3d..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/DeviceIdiom.xml +++ /dev/null @@ -1,291 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.ValueType - - - - System.IEquatable<Microsoft.Maui.Essentials.DeviceIdiom> - - - - - System.Runtime.CompilerServices.IsReadOnly - - - - The idiom (form factor) of the device. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DeviceIdiom - - - - - - The idiom name of the device - Creates a new device idiom. - - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DeviceIdiom - - - Gets the desktop idiom. - - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - The object ot compare. - Checks the equality of the idiom. - If the values are equal - To be added. - - - - - - - Method - - M:System.IEquatable`1.Equals(`0) - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - The object ot compare. - Checks the equality of the idiom. - If the values are equal - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Int32 - - - - Gets the hash code for the idom. - The hashc ode - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - The left idiom to compare. - The right idiom to compare. - Checks the equality of the idiom. - If they are equal - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - The left idiom to compare. - The right idiom to compare. - Checks the equality of the idiom. - If they are inequal - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DeviceIdiom - - - Gets the phone idiom. - The phone idiom - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DeviceIdiom - - - Gets the tablet idiom. - The tablet idiom - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.String - - - - String representation of the idiom. - String representation of the idiom. - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DeviceIdiom - - - Gets the TV idiom. - The TV idiom - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DeviceIdiom - - - Gets the unknown idiom. - An unknown idiom. - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DeviceIdiom - - - Gets the watch idiom. - The watch idiom - To be added. - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/DevicePlatform.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/DevicePlatform.xml deleted file mode 100644 index 3e1b59b3cd81..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/DevicePlatform.xml +++ /dev/null @@ -1,327 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.ValueType - - - - System.IEquatable<Microsoft.Maui.Essentials.DevicePlatform> - - - - - System.Runtime.CompilerServices.IsReadOnly - - - - The device platform that the application is running on. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - Gets the Android platform. - The Android platform - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - - - - The device platform. - Creates a new Device Platform. - The device platform - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - The object compare - Checks the equality of the platform. - If they are equal - To be added. - - - - - - - Method - - M:System.IEquatable`1.Equals(`0) - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - The platform to compare - Checks the equality of the platform. - If they are equal - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Int32 - - - - Gets the hash code of the platform. - The hash code of the platform. - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - Gets the iOS platform. - The iOS Platform - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - To be added. - To be added. - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - The left side to compare. - The right side to compare - Checks the equality of the platform. - If they are equal - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - The left side to compare. - The right side to compare - Checks the equality of the platform. - If they are inequal - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - Gets the Tizen platform - The Tizen platform - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.String - - - - The string representation of the platform. - The string representation of the platform. - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - Gets the tvOS platform - The tvOS platform - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - Gets the unknown platform. - An unknown platform - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - Gets the UWP platform. - The UWP platform - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DevicePlatform - - - Gets the watchOS platform - The watchOS platform. - To be added. - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayInfo.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayInfo.xml deleted file mode 100644 index b5d67b617edb..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayInfo.xml +++ /dev/null @@ -1,329 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.ValueType - - - - System.IEquatable<Microsoft.Maui.Essentials.DisplayInfo> - - - - - System.Runtime.CompilerServices.IsReadOnly - - - - Represents information about the screen. - - - - - - - - Constructor - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - - - - - - - The width of the display - The height of the display - The screen density - The current orientation - The rotation of the device. - Main constructor for Display Information - To be added. - - - - - - - Constructor - - Microsoft.Maui.Essentials - 1.0.0.0 - - - - - - - - - - - The width of the display - The height of the display - The screen density - The current orientation - The rotation of the device. - The refresh rate of the display. - Main constructor for Display Information - To be added. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - Gets a value representing the screen density. - The screen density. - - The density is the scaling or a factor that can be used to convert between physical pixels and scaled pixels. For example, on high resolution displays, the physical number of pixels increases, but the scaled pixels remain the same. - In a practical example for iOS, the Retina display will have a density of 2.0 or 3.0, but the units used to lay out a view does not change much. A view with a UI width of 100 may be 100 physical pixels (density = 1) on a non-Retina device, but be 200 physical pixels (density = 2) on a Retina device. - On Windows or UWP, the density works similarly, and may often relate to the scale used in the display. On some monitors, the scale is set to 100% (density = 1), but on other high resolution monitors, the scale may be set to 200% (density = 2) or even 250% (density = 2.5). - - - - - - - - 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 - - - - - - The other display info to compare. - If equal to another object. - If equal. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Int32 - - - - Gets the hash code for object. - The hash code. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - Gets the height of the screen for the current orientation. - The height in pixels. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - Left to compare. - Right to compare. - If equal to another object. - If equal - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Boolean - - - - - - - Left to compare - Right to compare - If not equal to another object. - If not equal - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayOrientation - - - Gets the orientation of the device. - The orientation. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Single - - - Gets the refresh rate of the display. - The refresh rate in Hz. - - - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayRotation - - - Gets the rotation from the designated orientation. - The rotation - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.String - - - - String representation of information. - String information about display info. - - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - Gets the width of the screen for the current orientation. - The width in pixels. - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayOrientation.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayOrientation.xml deleted file mode 100644 index d8908792ea21..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayOrientation.xml +++ /dev/null @@ -1,69 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Enum - - - Display Orientation - - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayOrientation - - 2 - - Display is in landscape. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayOrientation - - 1 - - Display is in portrait. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayOrientation - - 0 - - Unknown display orientation. - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayRotation.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayRotation.xml deleted file mode 100644 index 5fdcfd89e34b..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/DisplayRotation.xml +++ /dev/null @@ -1,103 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Enum - - - Display rotation. - - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayRotation - - 1 - - Rotated 0 degrees. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayRotation - - 3 - - Rotated 180 degrees. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayRotation - - 4 - - Rotated 270 degrees. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayRotation - - 2 - - Rotated 90 degrees. - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.DisplayRotation - - 0 - - Unknown display rotation. - - - - diff --git a/src/Essentials/docs/en/Xamarin.Essentials/DisplayOrientation.xml b/src/Essentials/docs/en/Xamarin.Essentials/DisplayOrientation.xml deleted file mode 100644 index 5aebde20f9d1..000000000000 --- a/src/Essentials/docs/en/Xamarin.Essentials/DisplayOrientation.xml +++ /dev/null @@ -1,69 +0,0 @@ - - - - - - Xamarin.Essentials - 1.0.0.0 - - - System.Enum - - - Display Orientation - - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.DisplayOrientation - - 2 - - Display is in landscape. - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.DisplayOrientation - - 1 - - Display is in portrait. - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.DisplayOrientation - - 0 - - Unknown display orientation. - - - - diff --git a/src/Essentials/src/Accelerometer/Accelerometer.shared.cs b/src/Essentials/src/Accelerometer/Accelerometer.shared.cs index b6289337a05f..e4b6424b2b06 100644 --- a/src/Essentials/src/Accelerometer/Accelerometer.shared.cs +++ b/src/Essentials/src/Accelerometer/Accelerometer.shared.cs @@ -150,6 +150,7 @@ public AccelerometerData(float x, float y, float z) => /// public Vector3 Acceleration { get; } + /// public override bool Equals(object? obj) => (obj is AccelerometerData data) && Equals(data); @@ -179,6 +180,7 @@ public bool Equals(AccelerometerData other) => public static bool operator !=(AccelerometerData left, AccelerometerData right) => !left.Equals(right); + /// public override int GetHashCode() => Acceleration.GetHashCode(); diff --git a/src/Essentials/src/Barometer/Barometer.shared.cs b/src/Essentials/src/Barometer/Barometer.shared.cs index 7e0c9f267457..16bd693db8ed 100644 --- a/src/Essentials/src/Barometer/Barometer.shared.cs +++ b/src/Essentials/src/Barometer/Barometer.shared.cs @@ -159,6 +159,7 @@ public override bool Equals(object? obj) => public bool Equals(BarometerData other) => PressureInHectopascals.Equals(other.PressureInHectopascals); + /// public override int GetHashCode() => PressureInHectopascals.GetHashCode(); diff --git a/src/Essentials/src/Compass/Compass.shared.cs b/src/Essentials/src/Compass/Compass.shared.cs index 996718695ad0..daa3cc590824 100644 --- a/src/Essentials/src/Compass/Compass.shared.cs +++ b/src/Essentials/src/Compass/Compass.shared.cs @@ -44,11 +44,14 @@ public interface ICompass } /// - /// Platform-specific APIs for use with + /// Platform-specific APIs for use with . /// public interface IPlatformCompass { #if IOS || MACCATALYST + /// + /// Gets or sets if heading calibration should be shown. + /// bool ShouldDisplayHeadingCalibration { get; set; } #endif } @@ -144,7 +147,7 @@ internal static void SetDefault(ICompass? implementation) => } /// - /// /// This class contains static extension methods for use with . + /// This class contains static extension methods for use with . /// public static class CompassExtensions { @@ -232,6 +235,7 @@ public bool Equals(CompassData other) => public static bool operator !=(CompassData left, CompassData right) => !left.Equals(right); + /// public override int GetHashCode() => HeadingMagneticNorth.GetHashCode(); diff --git a/src/Essentials/src/FilePicker/FilePicker.shared.cs b/src/Essentials/src/FilePicker/FilePicker.shared.cs index 7e7c4bac937e..a0a32d00b98b 100644 --- a/src/Essentials/src/FilePicker/FilePicker.shared.cs +++ b/src/Essentials/src/FilePicker/FilePicker.shared.cs @@ -133,6 +133,9 @@ public partial class FilePickerFileType readonly IDictionary> fileTypes; + /// + /// Initializes a new instance of the class. + /// protected FilePickerFileType() => fileTypes = new Dictionary>(); @@ -154,6 +157,10 @@ public FilePickerFileType(IDictionary> fileT /// Thrown if the current platform does not have any file types configured. public IEnumerable Value => GetPlatformFileType(DeviceInfo.Current.Platform); + /// + /// Gets the configured allowed file types that can be picked by the user for the current platform. + /// + /// Thrown if the current platform does not have any file types configured. protected virtual IEnumerable GetPlatformFileType(DevicePlatform platform) { if (fileTypes.TryGetValue(platform, out var type)) diff --git a/src/Essentials/src/FileSystem/FileSystem.shared.cs b/src/Essentials/src/FileSystem/FileSystem.shared.cs index a1a99535d5c8..7e41e78edc24 100644 --- a/src/Essentials/src/FileSystem/FileSystem.shared.cs +++ b/src/Essentials/src/FileSystem/FileSystem.shared.cs @@ -67,7 +67,7 @@ public static Task OpenAppPackageFileAsync(string filename) /// /// Determines whether or not a file exists in the app package. /// - /// The name of the file (excluding the path) to load from the app package. + /// The name of the file (excluding the path) to check for existence /// when the specified file exists in the app package, otherwise . public static Task AppPackageFileExistsAsync(string filename) => Current.AppPackageFileExistsAsync(filename); @@ -89,15 +89,19 @@ internal static void SetCurrent(IFileSystem? implementation) => /// public partial class FileSystemImplementation { + /// public string CacheDirectory => PlatformCacheDirectory; + /// public string AppDataDirectory => PlatformAppDataDirectory; + /// public Task OpenAppPackageFileAsync(string filename) => PlatformOpenAppPackageFileAsync(filename); + /// public Task AppPackageFileExistsAsync(string filename) => PlatformAppPackageFileExistsAsync(filename); } diff --git a/src/Essentials/src/Magnetometer/Magnetometer.shared.cs b/src/Essentials/src/Magnetometer/Magnetometer.shared.cs index 62066acc08dc..5c0d65d3107c 100644 --- a/src/Essentials/src/Magnetometer/Magnetometer.shared.cs +++ b/src/Essentials/src/Magnetometer/Magnetometer.shared.cs @@ -176,6 +176,7 @@ public bool Equals(MagnetometerData other) => public static bool operator !=(MagnetometerData left, MagnetometerData right) => !left.Equals(right); + /// public override int GetHashCode() => MagneticField.GetHashCode(); diff --git a/src/Essentials/src/OrientationSensor/OrientationSensor.shared.cs b/src/Essentials/src/OrientationSensor/OrientationSensor.shared.cs index d169f8887073..c0d16fea5dab 100644 --- a/src/Essentials/src/OrientationSensor/OrientationSensor.shared.cs +++ b/src/Essentials/src/OrientationSensor/OrientationSensor.shared.cs @@ -192,19 +192,39 @@ public override string ToString() => $"{nameof(Orientation.W)}: {Orientation.W}"; } + /// + /// Concrete implementation of the APIs. + /// public partial class OrientationSensorImplementation : IOrientationSensor { bool UseSyncContext => SensorSpeed == SensorSpeed.Default || SensorSpeed == SensorSpeed.UI; SensorSpeed SensorSpeed { get; set; } = SensorSpeed.Default; + /// + /// Occurs when the orientation reading changes. + /// public event EventHandler? ReadingChanged; + /// + /// Gets a value indicating whether reading the orientation sensor is supported on this device. + /// public bool IsSupported => PlatformIsSupported; + /// + /// Gets a value indicating whether the orientation sensor is actively being monitored. + /// public bool IsMonitoring { get; private set; } + /// + /// Start monitoring for changes to the orientation. + /// + /// + /// Will throw if not supported on device. + /// Will throw if is . + /// + /// The speed to listen for changes. public void Start(SensorSpeed sensorSpeed) { if (!PlatformIsSupported) @@ -227,6 +247,9 @@ public void Start(SensorSpeed sensorSpeed) } } + /// + /// Stop monitoring for changes to the orientation. + /// public void Stop() { if (!PlatformIsSupported) diff --git a/src/Essentials/src/Platform/Platform.shared.cs b/src/Essentials/src/Platform/Platform.shared.cs index ecdf3a90b549..e0e5c692b780 100644 --- a/src/Essentials/src/Platform/Platform.shared.cs +++ b/src/Essentials/src/Platform/Platform.shared.cs @@ -7,22 +7,39 @@ namespace Microsoft.Maui.ApplicationModel { + /// + /// A static class that contains platform-specific helper methods. + /// public static class Platform { #if ANDROID - + /// + /// A static class that contains Android specific information about . + /// public static class Intent { + /// + /// The identifier for the used by . + /// public const string ActionAppAction = AppActionsImplementation.IntentAction; } + /// + /// Gets the object that represents the current application context. + /// public static Android.Content.Context AppContext => Android.App.Application.Context; // ActivityStateManager + /// + /// Gets the object that represents the application's current activity. + /// public static Android.App.Activity? CurrentActivity => ActivityStateManager.Default.GetCurrentActivity(); + /// + /// Occurs when the state of an activity of this application changes. + /// public static event EventHandler? ActivityStateChanged { add => ActivityStateManager.Default.ActivityStateChanged += value; @@ -69,7 +86,9 @@ public static void Init(Func? getCurrentUIViewController WindowStateManager.Default.GetCurrentUIViewController(true); #elif WINDOWS - + /// + /// Gets or sets the map service API key for this platform. + /// public static string? MapServiceToken { get => Geocoding.Default.GetMapServiceToken(); @@ -83,6 +102,9 @@ public static void OnActivated(UI.Xaml.Window window, UI.Xaml.WindowActivatedEve WindowStateManager.Default.OnActivated(window, args); #elif TIZEN + /// + /// Gets a object with information about the current application package. + /// public static Tizen.Applications.Package CurrentPackage { get @@ -92,12 +114,14 @@ public static Tizen.Applications.Package CurrentPackage } } + /// + /// Gets or sets the map service API key for this platform. + /// public static string? MapServiceToken { get => Geocoding.Default.GetMapServiceToken(); set => Geocoding.Default.SetMapServiceToken(value); } - #endif } diff --git a/src/Essentials/src/Platform/WindowStateManager.ios.cs b/src/Essentials/src/Platform/WindowStateManager.ios.cs index 16e64f18a1bf..1d7fe3f74ba7 100644 --- a/src/Essentials/src/Platform/WindowStateManager.ios.cs +++ b/src/Essentials/src/Platform/WindowStateManager.ios.cs @@ -5,19 +5,40 @@ namespace Microsoft.Maui.ApplicationModel { + /// + /// Manager object that manages window states on iOS and macOS. + /// public interface IWindowStateManager { + /// + /// Initializes this instance. + /// + /// The function task to retrieve the current . void Init(Func? getCurrentUIViewController); + /// + /// Gets the currently presented . + /// + /// The object that is currently presented. UIViewController? GetCurrentUIViewController(); + /// + /// Gets the currently active . + /// + /// The object that is currently active. UIWindow? GetCurrentUIWindow(); } + /// + /// Manager object that manages window states on iOS and macOS. + /// public static class WindowStateManager { static IWindowStateManager? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IWindowStateManager Default => defaultImplementation ??= new WindowStateManagerImplementation(); @@ -27,6 +48,13 @@ internal static void SetDefault(IWindowStateManager? implementation) => static class WindowStateManagerExtensions { + /// + /// Gets the currently presented . + /// + /// The object to invoke this method on. + /// Throws an exception if no current can be found and this value is set to , otherwise this method returns . + /// The object that is currently presented. + /// Thrown if no current can be found and is set to . public static UIViewController? GetCurrentUIViewController(this IWindowStateManager manager, bool throwOnNull) { var vc = manager.GetCurrentUIViewController(); @@ -35,6 +63,14 @@ static class WindowStateManagerExtensions return vc; } + + /// + /// Gets the currently active . + /// + /// The object to invoke this method on. + /// Throws an exception if no current can be found and this value is set to , otherwise this method returns . + /// The object that is currently active. + /// Thrown if no current can be found and is set to . public static UIWindow? GetCurrentUIWindow(this IWindowStateManager manager, bool throwOnNull) { var window = manager.GetCurrentUIWindow(); diff --git a/src/Essentials/src/Platform/WindowStateManager.uwp.cs b/src/Essentials/src/Platform/WindowStateManager.uwp.cs index e6848ecab142..ac22d2bcb4f3 100644 --- a/src/Essentials/src/Platform/WindowStateManager.uwp.cs +++ b/src/Essentials/src/Platform/WindowStateManager.uwp.cs @@ -5,19 +5,40 @@ namespace Microsoft.Maui.ApplicationModel { + /// + /// Manager object that manages window states on Windows. + /// public interface IWindowStateManager { + /// + /// Occurs when the application's active window changed. + /// event EventHandler ActiveWindowChanged; + /// + /// Gets the application's currently active window. + /// + /// The application's currently active object. Window? GetActiveWindow(); + /// + /// Sets the new active window that can be retrieved with . + /// + /// The object that is activated. + /// The associated event arguments for this window activation event. void OnActivated(Window window, WindowActivatedEventArgs args); } + /// + /// Manager object that manages window states on Windows. + /// public static class WindowStateManager { static IWindowStateManager? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IWindowStateManager Default => defaultImplementation ??= new WindowStateManagerImplementation(); @@ -27,6 +48,13 @@ internal static void SetDefault(IWindowStateManager? implementation) => static class WindowStateManagerExtensions { + /// + /// Gets the application's currently active window. + /// + /// The object to invoke this method on. + /// Throws an exception if no current can be found and this value is set to , otherwise this method returns . + /// The application's currently active object. + /// Thrown if no current can be found and is set to . public static Window? GetActiveWindow(this IWindowStateManager manager, bool throwOnNull) { var window = manager.GetActiveWindow(); @@ -36,6 +64,13 @@ static class WindowStateManagerExtensions return window; } + /// + /// Gets the application's currently active window's pointer. + /// + /// The object to invoke this method on. + /// Throws an exception if no current can be found and this value is set to , otherwise this method returns . + /// The application's currently active window's . + /// Thrown if no current can be found and is set to . public static IntPtr GetActiveWindowHandle(this IWindowStateManager manager, bool throwOnNull) { var window = manager.GetActiveWindow(); @@ -50,6 +85,13 @@ public static IntPtr GetActiveWindowHandle(this IWindowStateManager manager, boo return handle; } + /// + /// Gets the application's currently active app window. + /// + /// The object to invoke this method on. + /// Throws an exception if no current can be found and this value is set to , otherwise this method returns . + /// The application's currently active object. + /// Thrown if no current can be found and is set to . public static AppWindow? GetActiveAppWindow(this IWindowStateManager manager, bool throwOnNull) { var window = manager.GetActiveWindow(); diff --git a/src/Essentials/src/Types/DeviceIdiom.shared.cs b/src/Essentials/src/Types/DeviceIdiom.shared.cs index 99f29651ce4f..851a5e1de8d0 100644 --- a/src/Essentials/src/Types/DeviceIdiom.shared.cs +++ b/src/Essentials/src/Types/DeviceIdiom.shared.cs @@ -2,27 +2,41 @@ namespace Microsoft.Maui.Devices { - /// + /// + /// Represents the idiom (form factor) of the device. + /// public readonly struct DeviceIdiom : IEquatable { readonly string deviceIdiom; - /// + /// + /// Gets an instance of that represents a (mobile) phone idiom. + /// public static DeviceIdiom Phone { get; } = new DeviceIdiom(nameof(Phone)); - /// + /// + /// Gets an instance of that represents a tablet idiom. + /// public static DeviceIdiom Tablet { get; } = new DeviceIdiom(nameof(Tablet)); - /// + /// + /// Gets an instance of that represents a desktop computer idiom. + /// public static DeviceIdiom Desktop { get; } = new DeviceIdiom(nameof(Desktop)); - /// + /// + /// Gets an instance of that represents a television (TV) idiom. + /// public static DeviceIdiom TV { get; } = new DeviceIdiom(nameof(TV)); - /// + /// + /// Gets an instance of that represents a watch idiom. + /// public static DeviceIdiom Watch { get; } = new DeviceIdiom(nameof(Watch)); - /// + /// + /// Gets an instance of that represents an unknown idiom. This is used for when the current device idiom is unknown. + /// public static DeviceIdiom Unknown { get; } = new DeviceIdiom(nameof(Unknown)); DeviceIdiom(string deviceIdiom) @@ -36,22 +50,33 @@ namespace Microsoft.Maui.Devices this.deviceIdiom = deviceIdiom; } - /// + /// + /// Creates a new device idiom instance. This can be used to define your custom idioms. + /// + /// The idiom name of the device. + /// A new instance of with the specified idiom type. public static DeviceIdiom Create(string deviceIdiom) => new DeviceIdiom(deviceIdiom); - /// + /// + /// Compares the underlying instances. + /// + /// object to compare with. + /// if they are equal, otherwise . public bool Equals(DeviceIdiom other) => Equals(other.deviceIdiom); internal bool Equals(string other) => string.Equals(deviceIdiom, other, StringComparison.Ordinal); - /// + /// public override bool Equals(object obj) => obj is DeviceIdiom && Equals((DeviceIdiom)obj); - /// + /// + /// Gets the hash code for this idiom instance. + /// + /// The computed hash code for this device idiom or 0 when the device idiom is . public override int GetHashCode() => deviceIdiom == null ? 0 : deviceIdiom.GetHashCode( #if !NETSTANDARD2_0 @@ -59,13 +84,28 @@ public override int GetHashCode() => #endif ); - /// + /// + /// Returns a string representation of the current value of . + /// + /// A string representation of this instance in the format of {device idiom} or an empty string when no device idiom is set. public override string ToString() => deviceIdiom ?? string.Empty; + /// + /// Equality operator for equals. + /// + /// Left to compare. + /// Right to compare. + /// if objects are equal, otherwise . public static bool operator ==(DeviceIdiom left, DeviceIdiom right) => left.Equals(right); + /// + /// Inequality operator. + /// + /// Left to compare. + /// Right to compare. + /// if objects are not equal, otherwise . public static bool operator !=(DeviceIdiom left, DeviceIdiom right) => !left.Equals(right); } diff --git a/src/Essentials/src/Types/DevicePlatform.shared.cs b/src/Essentials/src/Types/DevicePlatform.shared.cs index 974ac523148f..c4c1031579e2 100644 --- a/src/Essentials/src/Types/DevicePlatform.shared.cs +++ b/src/Essentials/src/Types/DevicePlatform.shared.cs @@ -2,38 +2,64 @@ namespace Microsoft.Maui.Devices { - /// + /// + /// Represents the device platform that the application is running on. + /// public readonly struct DevicePlatform : IEquatable { readonly string devicePlatform; - /// + /// + /// Gets an instance of that represents Android. + /// public static DevicePlatform Android { get; } = new DevicePlatform(nameof(Android)); - /// + /// + /// Gets an instance of that represents iOS. + /// public static DevicePlatform iOS { get; } = new DevicePlatform(nameof(iOS)); - /// + /// + /// Gets an instance of that represents macOS. + /// + /// Note, this is different than . public static DevicePlatform macOS { get; } = new DevicePlatform(nameof(macOS)); + /// + /// Gets an instance of that represents Mac Catalyst. + /// + /// Note, this is different than . public static DevicePlatform MacCatalyst { get; } = new DevicePlatform(nameof(MacCatalyst)); - /// + /// + /// Gets an instance of that represents Apple tvOS. + /// public static DevicePlatform tvOS { get; } = new DevicePlatform(nameof(tvOS)); - /// + /// + /// Gets an instance of that represents Samsung Tizen. + /// public static DevicePlatform Tizen { get; } = new DevicePlatform(nameof(Tizen)); - /// + /// + /// Gets an instance of that represents UWP. + /// [Obsolete("Use WinUI instead.")] public static DevicePlatform UWP { get; } = new DevicePlatform(nameof(WinUI)); + /// + /// Gets an instance of that represents WinUI. + /// public static DevicePlatform WinUI { get; } = new DevicePlatform(nameof(WinUI)); - /// + /// + /// Gets an instance of that represents Apple watchOS. + /// public static DevicePlatform watchOS { get; } = new DevicePlatform(nameof(watchOS)); - /// + /// + /// Gets an instance of that represents an unknown platform. This is used for when the current platform is unknown. + /// public static DevicePlatform Unknown { get; } = new DevicePlatform(nameof(Unknown)); DevicePlatform(string devicePlatform) @@ -47,22 +73,33 @@ namespace Microsoft.Maui.Devices this.devicePlatform = devicePlatform; } - /// + /// + /// Creates a new device platform instance. This can be used to define your custom platforms. + /// + /// The device platform identifier. + /// A new instance of with the specified platform identifier. public static DevicePlatform Create(string devicePlatform) => new DevicePlatform(devicePlatform); - /// + /// + /// Compares the underlying instances. + /// + /// object to compare with. + /// if they are equal, otherwise . public bool Equals(DevicePlatform other) => Equals(other.devicePlatform); internal bool Equals(string other) => string.Equals(devicePlatform, other, StringComparison.Ordinal); - /// + /// public override bool Equals(object obj) => obj is DevicePlatform && Equals((DevicePlatform)obj); - /// + /// + /// Gets the hash code for this platform instance. + /// + /// The computed hash code for this device platform or 0 when the device platform is . public override int GetHashCode() => devicePlatform == null ? 0 : devicePlatform.GetHashCode( #if !NETSTANDARD2_0 @@ -70,13 +107,28 @@ public override int GetHashCode() => #endif ); - /// + /// + /// Returns a string representation of the current value of . + /// + /// A string representation of this instance in the format of {device platform} or an empty string when no device platform is set. public override string ToString() => devicePlatform ?? string.Empty; + /// + /// Equality operator for equals. + /// + /// Left to compare. + /// Right to compare. + /// if objects are equal, otherwise . public static bool operator ==(DevicePlatform left, DevicePlatform right) => left.Equals(right); + /// + /// Inequality operator. + /// + /// Left to compare. + /// Right to compare. + /// if objects are not equal, otherwise . public static bool operator !=(DevicePlatform left, DevicePlatform right) => !left.Equals(right); } diff --git a/src/Essentials/src/Types/DisplayInfo.shared.cs b/src/Essentials/src/Types/DisplayInfo.shared.cs index 2a931a4ebfff..114d44e7f34a 100644 --- a/src/Essentials/src/Types/DisplayInfo.shared.cs +++ b/src/Essentials/src/Types/DisplayInfo.shared.cs @@ -3,10 +3,19 @@ namespace Microsoft.Maui.Devices { - /// + /// + /// Represents information about the device's screen. + /// public readonly struct DisplayInfo : IEquatable { - /// + /// + /// Initializes a new instance of the class. + /// + /// The width of the display. + /// The height of the display. + /// The screen density. + /// The current orientation. + /// The rotation of the device. public DisplayInfo(double width, double height, double density, DisplayOrientation orientation, DisplayRotation rotation) { Width = width; @@ -17,7 +26,15 @@ public DisplayInfo(double width, double height, double density, DisplayOrientati RefreshRate = 0; } - /// + /// + /// Initializes a new instance of the class. + /// + /// The width of the display. + /// The height of the display. + /// The screen density. + /// The current orientation. + /// The rotation of the device. + /// The refresh rate of the display. public DisplayInfo(double width, double height, double density, DisplayOrientation orientation, DisplayRotation rotation, float rate) { Width = width; @@ -28,35 +45,69 @@ public DisplayInfo(double width, double height, double density, DisplayOrientati RefreshRate = rate; } - /// + /// + /// Gets the width of the screen (in pixels) for the current . + /// public double Width { get; } - /// + /// + /// Gets the height of the screen (in pixels) for the current . + /// public double Height { get; } - /// + /// + /// Gets a value representing the screen density. + /// + /// + /// The density is the scaling or a factor that can be used to convert between physical pixels and scaled pixels. For example, on high resolution displays, the physical number of pixels increases, but the scaled pixels remain the same. + /// In a practical example for iOS, the Retina display will have a density of 2.0 or 3.0, but the units used to lay out a view does not change much. A view with a UI width of 100 may be 100 physical pixels (density = 1) on a non-Retina device, but be 200 physical pixels (density = 2) on a Retina device. + /// On Windows, the density works similarly, and may often relate to the scale used in the display. On some monitors, the scale is set to 100% (density = 1), but on other high resolution monitors, the scale may be set to 200% (density = 2) or even 250% (density = 2.5). + /// public double Density { get; } - /// + /// + /// Gets the orientation of the device's display. + /// public DisplayOrientation Orientation { get; } - /// + /// + /// Gets the orientation of the device's display. + /// public DisplayRotation Rotation { get; } - /// + /// + /// Gets the refresh rate (in Hertz) of the device's display. + /// public float RefreshRate { get; } + /// + /// Equality operator for equals. + /// + /// Left to compare. + /// Right to compare. + /// if objects are equal, otherwise . public static bool operator ==(DisplayInfo left, DisplayInfo right) => left.Equals(right); + /// + /// Inequality operator. + /// + /// Left to compare. + /// Right to compare. + /// if objects are not equal, otherwise . public static bool operator !=(DisplayInfo left, DisplayInfo right) => !left.Equals(right); - /// + /// public override bool Equals(object obj) => (obj is DisplayInfo metrics) && Equals(metrics); - /// + /// + /// Compares the underlying instances. + /// + /// object to compare with. + /// if they are equal, otherwise . + /// Equality is established by comparing if , , , and are all equal. public bool Equals(DisplayInfo other) => Width.Equals(other.Width) && Height.Equals(other.Height) && @@ -64,11 +115,18 @@ public bool Equals(DisplayInfo other) => Orientation.Equals(other.Orientation) && Rotation.Equals(other.Rotation); - /// + /// + /// Gets the hash code for this display info instance. + /// + /// The computed hash code for this device idiom or 0 when the device platform is . + /// The hash code is computed from , , , and . public override int GetHashCode() => (Height, Width, Density, Orientation, Rotation).GetHashCode(); - /// + /// + /// Returns a string representation of the current values of this display info instance. + /// + /// A string representation of this instance in the format of Height: {height}, Width: {width}, Density: {density}, Orientation: {orientation}, Rotation: {rotation}. public override string ToString() => $"{nameof(Height)}: {Height}, {nameof(Width)}: {Width}, " + $"{nameof(Density)}: {Density}, {nameof(Orientation)}: {Orientation}, " + diff --git a/src/Essentials/src/Types/DisplayOrientation.shared.cs b/src/Essentials/src/Types/DisplayOrientation.shared.cs index 6f34c0afa86d..4b812b545b5f 100644 --- a/src/Essentials/src/Types/DisplayOrientation.shared.cs +++ b/src/Essentials/src/Types/DisplayOrientation.shared.cs @@ -1,13 +1,17 @@ namespace Microsoft.Maui.Devices { - /// + /// + /// Represents the orientation a device display can have. + /// public enum DisplayOrientation { - /// + /// Unknown display orientation. Unknown = 0, - /// + + /// Device display is in portrait orientation. Portrait = 1, - /// + + /// Device display is in landscape orientation. Landscape = 2 } } diff --git a/src/Essentials/src/Types/DisplayRotation.shared.cs b/src/Essentials/src/Types/DisplayRotation.shared.cs index 1e7cf549a819..6905c10f5138 100644 --- a/src/Essentials/src/Types/DisplayRotation.shared.cs +++ b/src/Essentials/src/Types/DisplayRotation.shared.cs @@ -1,17 +1,23 @@ namespace Microsoft.Maui.Devices { - /// + /// + /// Represents the rotation a device display can have. + /// public enum DisplayRotation { - /// + /// Unknown display rotation. Unknown = 0, - /// + + /// The device display is rotated 0 degrees. Rotation0 = 1, - /// + + /// The device display is rotated 90 degrees. Rotation90 = 2, - /// + + /// The device display is rotated 180 degrees. Rotation180 = 3, - /// + + /// The device display is rotated 270 degrees. Rotation270 = 4 } } diff --git a/src/Essentials/src/Types/Location.shared.cs b/src/Essentials/src/Types/Location.shared.cs index 16a54d5a7121..efb282111e09 100644 --- a/src/Essentials/src/Types/Location.shared.cs +++ b/src/Essentials/src/Types/Location.shared.cs @@ -243,6 +243,7 @@ public override string ToString() => $"{nameof(Course)}: {Course}, " + $"{nameof(Timestamp)}: {Timestamp}"; + /// public override bool Equals(object obj) { if (ReferenceEquals(null, obj)) @@ -253,6 +254,7 @@ public override bool Equals(object obj) return Latitude == other.Latitude && Longitude == other.Longitude; } + /// public override int GetHashCode() { unchecked diff --git a/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs b/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs index cd3d118e2821..b00fdb9bf3bb 100644 --- a/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs +++ b/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs @@ -49,6 +49,9 @@ public static Task AuthenticateAsync(WebAuthenticatorOpt static IWebAuthenticator? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IWebAuthenticator Default => defaultImplementation ??= new WebAuthenticatorImplementation(); From ae52ef52548d05a13b3d44fb976a0cec44e738ca Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 15:06:39 +0100 Subject: [PATCH 02/12] Some more --- .../Xamarin.Essentials/LocationExtensions.xml | 119 ----------------- .../en/Xamarin.Essentials/NavigationMode.xml | 122 ------------------ .../src/Map/NavigationMode.shared.cs | 21 ++- .../src/Types/LocationExtensions.shared.cs | 12 +- 4 files changed, 21 insertions(+), 253 deletions(-) delete mode 100644 src/Essentials/docs/en/Xamarin.Essentials/LocationExtensions.xml delete mode 100644 src/Essentials/docs/en/Xamarin.Essentials/NavigationMode.xml diff --git a/src/Essentials/docs/en/Xamarin.Essentials/LocationExtensions.xml b/src/Essentials/docs/en/Xamarin.Essentials/LocationExtensions.xml deleted file mode 100644 index 971168e9d354..000000000000 --- a/src/Essentials/docs/en/Xamarin.Essentials/LocationExtensions.xml +++ /dev/null @@ -1,119 +0,0 @@ - - - - - - Xamarin.Essentials - 1.0.0.0 - - - System.Object - - - - Location Extensions - - - - - - - - Method - - 1.0.0.0 - Xamarin.Essentials - - - System.Double - - - - - - - - Start location to calculate from. - End location to calculate from. - Units to use during calculation. - Extension to calculate distance from location to another location. - Distance in units fro two locations. - - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - - - - Start location to calculate from. - End latitude to calculate from. - End longitude to calculate from. - Units to use. - Extension to calculate distance from location to another location. - Distance calculated. - - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - Location to open to. - Open maps to this location. - Task to wait. - - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - Location to open to. - Options to use. - Open maps to this location. - Task to wait. - - - - - diff --git a/src/Essentials/docs/en/Xamarin.Essentials/NavigationMode.xml b/src/Essentials/docs/en/Xamarin.Essentials/NavigationMode.xml deleted file mode 100644 index 10171bd08ac4..000000000000 --- a/src/Essentials/docs/en/Xamarin.Essentials/NavigationMode.xml +++ /dev/null @@ -1,122 +0,0 @@ - - - - - - Xamarin.Essentials - 1.0.0.0 - - - System.Enum - - - Represents various modes of navigation. - - Default is none. - - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.NavigationMode - - 2 - - Bicycle route mode. - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.NavigationMode - - 1 - - The default navigation mode on the platform. - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.NavigationMode - - 3 - - Car route mode. - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.NavigationMode - - 0 - - No navigation mode for map. - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.NavigationMode - - 4 - - Transit route mode. - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.NavigationMode - - 5 - - Walking route mode. - - - - diff --git a/src/Essentials/src/Map/NavigationMode.shared.cs b/src/Essentials/src/Map/NavigationMode.shared.cs index 85f66a937637..1a6665cc1598 100644 --- a/src/Essentials/src/Map/NavigationMode.shared.cs +++ b/src/Essentials/src/Map/NavigationMode.shared.cs @@ -1,19 +1,26 @@ namespace Microsoft.Maui.ApplicationModel { - /// + /// + /// Represents various modes of navigation that can be passed to the operating system's Maps app. + /// public enum NavigationMode { - /// + /// No navigation mode. None = 0, - /// + + /// The default navigation mode on the platform. Default = 1, - /// + + /// Bicycle route mode. Bicycling = 2, - /// + + /// Car route mode. Driving = 3, - /// + + /// Transit route mode. Transit = 4, - /// + + /// Walking route mode. Walking = 5, } } diff --git a/src/Essentials/src/Types/LocationExtensions.shared.cs b/src/Essentials/src/Types/LocationExtensions.shared.cs index 6cab479284d8..137ee87510c7 100644 --- a/src/Essentials/src/Types/LocationExtensions.shared.cs +++ b/src/Essentials/src/Types/LocationExtensions.shared.cs @@ -4,22 +4,24 @@ namespace Microsoft.Maui.Devices.Sensors { - /// + /// + /// This class contains static extension methods for use with objects. + /// public static partial class LocationExtensions { - /// + /// public static double CalculateDistance(this Location locationStart, double latitudeEnd, double longitudeEnd, DistanceUnits units) => Location.CalculateDistance(locationStart, latitudeEnd, longitudeEnd, units); - /// + /// public static double CalculateDistance(this Location locationStart, Location locationEnd, DistanceUnits units) => Location.CalculateDistance(locationStart, locationEnd, units); - /// + /// public static Task OpenMapsAsync(this Location location, MapLaunchOptions options) => Map.OpenAsync(location, options); - /// + /// public static Task OpenMapsAsync(this Location location) => Map.OpenAsync(location); } From 19a83a9cdedc32eab960bc51bdc2b8c6a820e11c Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 15:16:57 +0100 Subject: [PATCH 03/12] Placemark --- .../Microsoft.Maui.Essentials/Placemark.xml | 269 ------------------ .../src/Types/DisplayInfo.shared.cs | 2 +- src/Essentials/src/Types/Placemark.shared.cs | 63 +++- 3 files changed, 49 insertions(+), 285 deletions(-) delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/Placemark.xml diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/Placemark.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/Placemark.xml deleted file mode 100644 index b2a5e60d2fc3..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/Placemark.xml +++ /dev/null @@ -1,269 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Object - - - - User-friendly description of a geographic coordinate. This contains information such as the name of the place, its address, and other information. - - - - - - - - Constructor - - 1.0.0.0 - Microsoft.Maui.Essentials - - - - Default constructor for placemark. - - - - - - - - Constructor - - 1.0.0.0 - Microsoft.Maui.Essentials - - - - - - Placemark to copy. - Constructor to create a deep copy. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the administrative area name of the address, for example, "CA", or null if it is unknown. - The admin area. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the country ISO code. - The country ISO code. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the country name. - The country name. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the feature name. - The feature name. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the city or town. - The city or town of the locality. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - Microsoft.Maui.Essentials.Location - - - Gets or sets the location of the placemark. - The location of the placemark. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the postal code. - The postal code. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the sub-administrative area name of the address, for example, "Santa Clara County", or null if it is unknown. - The sub-admin area. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the sub locality. - The sub locality. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets optional info: sub street or region. - The sub thoroughfare. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets or sets the street name. - The street name. - - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.String - - - - A string representation of the placemark. - Returns a string representation of the placemark. - - - - - diff --git a/src/Essentials/src/Types/DisplayInfo.shared.cs b/src/Essentials/src/Types/DisplayInfo.shared.cs index 114d44e7f34a..27de695a543d 100644 --- a/src/Essentials/src/Types/DisplayInfo.shared.cs +++ b/src/Essentials/src/Types/DisplayInfo.shared.cs @@ -126,7 +126,7 @@ public override int GetHashCode() => /// /// Returns a string representation of the current values of this display info instance. /// - /// A string representation of this instance in the format of Height: {height}, Width: {width}, Density: {density}, Orientation: {orientation}, Rotation: {rotation}. + /// A string representation of this instance in the format of Height: {value}, Width: {value}, Density: {value}, Orientation: {value}, Rotation: {value}. public override string ToString() => $"{nameof(Height)}: {Height}, {nameof(Width)}: {Width}, " + $"{nameof(Density)}: {Density}, {nameof(Orientation)}: {Orientation}, " + diff --git a/src/Essentials/src/Types/Placemark.shared.cs b/src/Essentials/src/Types/Placemark.shared.cs index a01c8f0fa1b2..fbb71dcedcde 100644 --- a/src/Essentials/src/Types/Placemark.shared.cs +++ b/src/Essentials/src/Types/Placemark.shared.cs @@ -2,15 +2,23 @@ namespace Microsoft.Maui.Devices.Sensors { - /// + /// + /// Represents a user-friendly description of a geographic coordinate. This contains information such as the name of the place, its address, and other information. + /// public class Placemark { - /// + /// + /// Initializes a new instance of the class. + /// public Placemark() { } - /// + /// + /// Initializes a new instance of the class. + /// + /// An instance of that will be used to clone into this instance. + /// Thrown when is . public Placemark(Placemark placemark) { if (placemark == null) @@ -33,40 +41,65 @@ public Placemark(Placemark placemark) AdminArea = placemark.AdminArea; } - /// + /// + /// Gets or sets the location of the placemark. + /// public Location Location { get; set; } - /// + /// + /// Gets or sets the country ISO standard code. + /// public string CountryCode { get; set; } - /// + /// + /// Gets or sets the country name. + /// public string CountryName { get; set; } - /// + /// + /// Gets or sets the feature name. + /// public string FeatureName { get; set; } - /// + /// + /// Gets or sets the postal code. + /// public string PostalCode { get; set; } - /// + /// + /// Gets or sets the sub locality. + /// public string SubLocality { get; set; } - /// + /// + /// Gets or sets the street name. + /// public string Thoroughfare { get; set; } - /// + /// + /// Gets or sets optional info: sub street or region. + /// public string SubThoroughfare { get; set; } - /// + /// + /// Gets or sets the city or town. + /// public string Locality { get; set; } - /// + /// + /// Gets or sets the administrative area name of the address, for example, "CA", or if it is unknown. + /// public string AdminArea { get; set; } - /// + /// + /// Gets or sets the sub-administrative area name of the address, for example, "Santa Clara County", or if it is unknown. + /// public string SubAdminArea { get; set; } - /// + /// + /// Returns a string representation of the current values of . + /// + /// A string representation of this instance in the format of Location: {value}, CountryCode: {value}, CountryName: {value}, FeatureName: {value}, PostalCode: {value}, SubLocality: {value}, Thoroughfare: {value}, SubThoroughfare: {value}, Locality: {value}, AdminArea: {value}, SubAdminArea: {value}. public override string ToString() => $"{nameof(Location)}: {Location}, {nameof(CountryCode)}: {CountryCode}, " + $"{nameof(CountryName)}: {CountryName}, {nameof(FeatureName)}: {FeatureName}, " + From 0efbc13d55df5dc40c4765780522a448111c1635 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 15:18:39 +0100 Subject: [PATCH 04/12] PlacemarkExtensions --- .../PlacemarkExtensions.xml | 65 ------------------- .../src/Types/PlacemarkExtensions.shared.cs | 8 ++- 2 files changed, 5 insertions(+), 68 deletions(-) delete mode 100644 src/Essentials/docs/en/Xamarin.Essentials/PlacemarkExtensions.xml diff --git a/src/Essentials/docs/en/Xamarin.Essentials/PlacemarkExtensions.xml b/src/Essentials/docs/en/Xamarin.Essentials/PlacemarkExtensions.xml deleted file mode 100644 index 080157096ab7..000000000000 --- a/src/Essentials/docs/en/Xamarin.Essentials/PlacemarkExtensions.xml +++ /dev/null @@ -1,65 +0,0 @@ - - - - - - Xamarin.Essentials - 1.0.0.0 - - - System.Object - - - - Extensions for the placemark. - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - The placemark to open the map to. - Open the map to the placemark. - - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - A placemark to open the map to. - Options for opening the map. - Open the map to the placemark with options. - To be added. - To be added. - - - - diff --git a/src/Essentials/src/Types/PlacemarkExtensions.shared.cs b/src/Essentials/src/Types/PlacemarkExtensions.shared.cs index 3d37a7915295..a7e48ea312f6 100644 --- a/src/Essentials/src/Types/PlacemarkExtensions.shared.cs +++ b/src/Essentials/src/Types/PlacemarkExtensions.shared.cs @@ -4,14 +4,16 @@ namespace Microsoft.Maui.Devices.Sensors { - /// + /// + /// This class contains static extension methods for use with objects. + /// public static partial class PlacemarkExtensions { - /// + /// public static Task OpenMapsAsync(this Placemark placemark, MapLaunchOptions options) => Map.OpenAsync(placemark, options); - /// + /// public static Task OpenMapsAsync(this Placemark placemark) => Map.OpenAsync(placemark); From 43eee3e17b35fc9865c4976bf4df86fe1c1e0a7d Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 15:20:32 +0100 Subject: [PATCH 05/12] SensorSpeed --- .../Microsoft.Maui.Essentials/SensorSpeed.xml | 86 ------------------- .../src/Types/SensorSpeed.shared.cs | 15 ++-- 2 files changed, 10 insertions(+), 91 deletions(-) delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/SensorSpeed.xml diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/SensorSpeed.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/SensorSpeed.xml deleted file mode 100644 index 292e953f4a92..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/SensorSpeed.xml +++ /dev/null @@ -1,86 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Enum - - - Sensor speed to monitor for changes. - - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.SensorSpeed - - 0 - - The default sensor speed. - - - - - - - Field - - 1.0.0.0 - Microsoft.Maui.Essentials - - - Microsoft.Maui.Essentials.SensorSpeed - - 3 - - Get the sensor data as fast as possible. - - - - - - - Field - - 1.0.0.0 - Microsoft.Maui.Essentials - - - Microsoft.Maui.Essentials.SensorSpeed - - 2 - - Rate suitable for games. - - - - - - - Field - - 1.0.0.0 - Microsoft.Maui.Essentials - - - Microsoft.Maui.Essentials.SensorSpeed - - 1 - - Rate suitable for general user interface. - - - - diff --git a/src/Essentials/src/Types/SensorSpeed.shared.cs b/src/Essentials/src/Types/SensorSpeed.shared.cs index 46db52b4896c..051d09d09e4e 100644 --- a/src/Essentials/src/Types/SensorSpeed.shared.cs +++ b/src/Essentials/src/Types/SensorSpeed.shared.cs @@ -1,15 +1,20 @@ namespace Microsoft.Maui.Devices.Sensors { - /// + /// + /// Represents the sensor speed to monitor device sensors for changes. + /// public enum SensorSpeed { - /// + /// The device default sensor speed. Default = 0, - /// + + /// Rate suitable for general user interface. UI = 1, - /// + + /// Rate suitable for games. Game = 2, - /// + + /// Get the sensor data as fast as possible. Fastest = 3, } } From d322c82fc0bdbc72229c59aca55e6a45b1f3cafc Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 15:37:31 +0100 Subject: [PATCH 06/12] UnitConverters --- .../en/Xamarin.Essentials/SensorSpeed.xml | 86 --- .../en/Xamarin.Essentials/UnitConverters.xml | 713 ------------------ .../UnitConverters/UnitConverters.shared.cs | 172 ++++- 3 files changed, 144 insertions(+), 827 deletions(-) delete mode 100644 src/Essentials/docs/en/Xamarin.Essentials/SensorSpeed.xml delete mode 100644 src/Essentials/docs/en/Xamarin.Essentials/UnitConverters.xml diff --git a/src/Essentials/docs/en/Xamarin.Essentials/SensorSpeed.xml b/src/Essentials/docs/en/Xamarin.Essentials/SensorSpeed.xml deleted file mode 100644 index 1b8a6cc3ecef..000000000000 --- a/src/Essentials/docs/en/Xamarin.Essentials/SensorSpeed.xml +++ /dev/null @@ -1,86 +0,0 @@ - - - - - - Xamarin.Essentials - 1.0.0.0 - - - System.Enum - - - Sensor speed to monitor for changes. - - - - - - - - Field - - Xamarin.Essentials - 1.0.0.0 - - - Xamarin.Essentials.SensorSpeed - - 0 - - The default sensor speed. - - - - - - - Field - - 1.0.0.0 - Xamarin.Essentials - - - Xamarin.Essentials.SensorSpeed - - 3 - - Get the sensor data as fast as possible. - - - - - - - Field - - 1.0.0.0 - Xamarin.Essentials - - - Xamarin.Essentials.SensorSpeed - - 2 - - Rate suitable for games. - - - - - - - Field - - 1.0.0.0 - Xamarin.Essentials - - - Xamarin.Essentials.SensorSpeed - - 1 - - Rate suitable for general user interface. - - - - diff --git a/src/Essentials/docs/en/Xamarin.Essentials/UnitConverters.xml b/src/Essentials/docs/en/Xamarin.Essentials/UnitConverters.xml deleted file mode 100644 index 23d67077dc62..000000000000 --- a/src/Essentials/docs/en/Xamarin.Essentials/UnitConverters.xml +++ /dev/null @@ -1,713 +0,0 @@ - - - - - - Xamarin.Essentials - 1.0.0.0 - - - System.Object - - - - Built in unit converters - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - Atmospheres to convert - Atmospheres to Pascals - The pascals value - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The temperature in celsius to convert - Celsius to Fahrenheit - The temperature in fahrenheit - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The temperature in Celsius to convert - Celsius to Kelvin - The temperature in Kelvin - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - - - - First latitude - First longitude - Second latitude - Second longitude - Calulate the distance between two coordinate in kilometers - Distance in kilometers - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - - - - First latitude - First longitude - Second latitude - Second longitude - Calulate the distance between two coordinate in miles - Distance in miles - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The degrees to convert - Converte degrees per second to hertz - Value in hertz - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - Degrees to convert - Convert degrees per second to radians per second - Value in radians - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - Degrees to convert - Convert degrees to radian - The value in radians - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in fahrenheit to convert - Converter fahrenheit to celsius - The value in celsius - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - Hectopascals to convert - Convert hectopascals to kilopascals - The value in kilopascals - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value to convert in Hectopascals - Convert hectopascals to pascals - The value in pascals - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in hertz to convert - Convert hertz to degrees per second - The value in degrees per second - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in hertz to convert - Convert hertz to radians per second - The value in radians per second - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The feet to convert - Convert international feet to meters - The value in meters - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The kelvin value to convert - Convert kelvin to celsius - The value in celsius - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in kilograms to convert - Convert kilograms to pounds - The value in pounds. - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The kilometers to convert - Convert kilometers to miles - The value in miles. - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in kilopascals to convert - Convert kilopascals to hectopascals - The value in hectopascals - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in kilopascals to convert - Convert kilopascals to pascals - The value in pascals - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in meters to convert - Convert meters to international feet - The value in feet - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in meters to convert - Convert meters to US survey feet - The value in US survey feet - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in miles to convert - Convert miles to kilometers - The value in kilometers - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in miles to convert - Convert miles to meters - The value in meters - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in pascals to convert - Convert pascals to atmospheres - The value in atmospheres - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in pounds to convert - Convert pounds to kilograms - The value in kilograms - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in pounds to convert - Convert pounds to stones - The value in stones - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value of radians per second to convert - Convert radians per second to degrees per second - The value in degrees per second - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value of radians per second to convert - Convert radians per second to hertz - The value in hertz - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in radians to convert - Convert radians to degrees - The value in degrees - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in stones to convert - Convert stones to pounds - The value in pounds - To be added. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in US Survey Feet to convert - Convert US survey feet to meteres - The value in meters. - To be added. - - - - diff --git a/src/Essentials/src/UnitConverters/UnitConverters.shared.cs b/src/Essentials/src/UnitConverters/UnitConverters.shared.cs index 89b42e10ca24..9fb6eabd490e 100644 --- a/src/Essentials/src/UnitConverters/UnitConverters.shared.cs +++ b/src/Essentials/src/UnitConverters/UnitConverters.shared.cs @@ -2,7 +2,9 @@ namespace Microsoft.Maui.Media { - /// + /// + /// Static class with built-in unit converters. + /// public static class UnitConverters { const double twoPi = 2.0 * Math.PI; @@ -23,111 +25,225 @@ public static class UnitConverters const double internationalFootDefinition = 0.3048; const double usSurveyFootDefinition = 1200.0 / 3937; - /// + /// + /// Converts temperatures from Fahrenheit to Celsius. + /// + /// The value in Fahrenheit to convert. + /// The value from in degrees Celsius. public static double FahrenheitToCelsius(double fahrenheit) => (fahrenheit - 32.0) / 1.8; - /// + /// + /// Converts temperatures from Celsius to Fahrenheit. + /// + /// The value in Celcius to convert. + /// The value from in degrees Fahrenheit. public static double CelsiusToFahrenheit(double celsius) => celsius * 1.8 + 32.0; - /// + /// + /// Converts temperatures from Celsius to Kelvin. + /// + /// The value in Celcius to convert. + /// The value from in degrees Kelvin. public static double CelsiusToKelvin(double celsius) => celsius + celsiusToKelvin; - /// + /// + /// Converts temperatures from Kelvin to Celsius. + /// + /// The value in Kelvin to convert. + /// The value from in degrees Celcius. public static double KelvinToCelsius(double kelvin) => kelvin - celsiusToKelvin; - /// + /// + /// Converts distances from miles to meters. + /// + /// The value in miles to convert. + /// The value from in meters. public static double MilesToMeters(double miles) => miles * milesToMeters; - /// + /// + /// Converts distances from miles to kilometers. + /// + /// The value in miles to convert. + /// The value from in kilometers. public static double MilesToKilometers(double miles) => miles * milesToKilometers; - /// + /// + /// Converts distances from kilometers to miles. + /// + /// The value in kilometers to convert. + /// The value from in miles. public static double KilometersToMiles(double kilometers) => kilometers * kilometersToMiles; - /// + /// + /// Converts degrees to radian. + /// + /// The value in degrees to convert. + /// The value from in radian. public static double DegreesToRadians(double degrees) => degrees * degreesToRadians; - /// + /// + /// Converts radians to degrees. + /// + /// The value in radians to convert. + /// The value from in degrees. public static double RadiansToDegrees(double radians) => radians / degreesToRadians; - /// + /// + /// Converts pounds to kilograms. + /// + /// The value in pounds to convert. + /// The value from in kilograms. public static double PoundsToKilograms(double pounds) => pounds * poundsToKg; - /// + /// + /// Converts pounds to stones. + /// + /// The value in pounds to convert. + /// The value from in stones. public static double PoundsToStones(double pounds) => pounds * poundsToStones; - /// + /// + /// Converts stones to pounds. + /// + /// The value in stones to convert. + /// The value from in pounds. public static double StonesToPounds(double stones) => stones * stonesToPounds; - /// + /// + /// Converts kilograms to pounds. + /// + /// The value in kilograms to convert. + /// The value from in pounds. public static double KilogramsToPounds(double kilograms) => kilograms * kgToPounds; - /// + /// + /// Converts degrees per second to radians per second. + /// + /// The value in degrees per second to convert. + /// The value from in radians per second. public static double DegreesPerSecondToRadiansPerSecond(double degrees) => HertzToRadiansPerSecond(DegreesPerSecondToHertz(degrees)); - /// + /// + /// Converts radians per second to degrees per second. + /// + /// The value in radians per second to convert. + /// The value from in degrees per second. public static double RadiansPerSecondToDegreesPerSecond(double radians) => HertzToDegreesPerSecond(RadiansPerSecondToHertz(radians)); - /// + /// + /// Converts degrees per second to hertz. + /// + /// The value in degrees per second to convert. + /// The value from in hertz. public static double DegreesPerSecondToHertz(double degrees) => degrees / totalDegrees; - /// + /// + /// Converts radians per second to hertz. + /// + /// The value in radians per second to convert. + /// The value from in hertz. public static double RadiansPerSecondToHertz(double radians) => radians / twoPi; - /// + /// + /// Converts hertz to degrees per second. + /// + /// The value in degrees per second to convert. + /// The value from in degrees per second. public static double HertzToDegreesPerSecond(double hertz) => hertz * totalDegrees; - /// + /// + /// Converts hertz to radians per second. + /// + /// The value in radians per second to convert. + /// The value from in radians per second. public static double HertzToRadiansPerSecond(double hertz) => hertz * twoPi; - /// + /// + /// Converts Kilopascals to Hectopascals. + /// + /// The value in Kilopascals convert. + /// The value from in Hectopascals. public static double KilopascalsToHectopascals(double kpa) => kpa * 10.0; - /// + /// + /// Converts Kilopascals to Hectopascals. + /// + /// The value in Hectopascals convert. + /// The value from in Kilopascals. public static double HectopascalsToKilopascals(double hpa) => hpa / 10.0; - /// + /// + /// Converts Kilopascals to Pascals. + /// + /// The value in Kilopascals convert. + /// The value from in Pascals. public static double KilopascalsToPascals(double kpa) => kpa * 1000.0; - /// + /// + /// Converts Hectopascals to Pascals. + /// + /// The value in Hectopascals convert. + /// The value from in Pascals. public static double HectopascalsToPascals(double hpa) => hpa * 100.0; - /// + /// + /// Converts Atmospheres to Pascals. + /// + /// The value in Atmospheres convert. + /// The value from in Pascals. public static double AtmospheresToPascals(double atm) => atm * atmospherePascals; - /// + /// + /// Converts Pascals to Atmospheres. + /// + /// The value in Pascals convert. + /// The value from in Atmospheres. public static double PascalsToAtmospheres(double pascals) => pascals / atmospherePascals; - /// + /// + /// Calculates the distance between two coordinates in miles. + /// + /// First latitude. + /// First longitude. + /// Second latitude. + /// Second longitude. + /// The distance in miles. public static double CoordinatesToMiles(double lat1, double lon1, double lat2, double lon2) => KilometersToMiles(CoordinatesToKilometers(lat1, lon1, lat2, lon2)); - /// + /// + /// Calculates the distance between two coordinates in kilometers. + /// + /// First latitude. + /// First longitude. + /// Second latitude. + /// Second longitude. + /// The distance in kilometers. public static double CoordinatesToKilometers(double lat1, double lon1, double lat2, double lon2) { if (lat1 == lat2 && lon1 == lon2) From 07f03deaf9c19fa44e8832982abfc3c087265956 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 15:37:54 +0100 Subject: [PATCH 07/12] Delete UnitConverters.xml --- .../UnitConverters.xml | 713 ------------------ 1 file changed, 713 deletions(-) delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/UnitConverters.xml diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/UnitConverters.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/UnitConverters.xml deleted file mode 100644 index e8eeeaed8fbc..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/UnitConverters.xml +++ /dev/null @@ -1,713 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Object - - - - Built in unit converters - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - Atmospheres to convert - Atmospheres to Pascals - The pascals value - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The temperature in celsius to convert - Celsius to Fahrenheit - The temperature in fahrenheit - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The temperature in Celsius to convert - Celsius to Kelvin - The temperature in Kelvin - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - - - - First latitude - First longitude - Second latitude - Second longitude - Calulate the distance between two coordinate in kilometers - Distance in kilometers - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - - - - First latitude - First longitude - Second latitude - Second longitude - Calulate the distance between two coordinate in miles - Distance in miles - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The degrees to convert - Converte degrees per second to hertz - Value in hertz - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - Degrees to convert - Convert degrees per second to radians per second - Value in radians - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - Degrees to convert - Convert degrees to radian - The value in radians - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in fahrenheit to convert - Converter fahrenheit to celsius - The value in celsius - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - Hectopascals to convert - Convert hectopascals to kilopascals - The value in kilopascals - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value to convert in Hectopascals - Convert hectopascals to pascals - The value in pascals - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in hertz to convert - Convert hertz to degrees per second - The value in degrees per second - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in hertz to convert - Convert hertz to radians per second - The value in radians per second - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The feet to convert - Convert international feet to meters - The value in meters - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The kelvin value to convert - Convert kelvin to celsius - The value in celsius - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in kilograms to convert - Convert kilograms to pounds - The value in pounds. - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The kilometers to convert - Convert kilometers to miles - The value in miles. - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in kilopascals to convert - Convert kilopascals to hectopascals - The value in hectopascals - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in kilopascals to convert - Convert kilopascals to pascals - The value in pascals - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in meters to convert - Convert meters to international feet - The value in feet - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in meters to convert - Convert meters to US survey feet - The value in US survey feet - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in miles to convert - Convert miles to kilometers - The value in kilometers - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in miles to convert - Convert miles to meters - The value in meters - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in pascals to convert - Convert pascals to atmospheres - The value in atmospheres - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in pounds to convert - Convert pounds to kilograms - The value in kilograms - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in pounds to convert - Convert pounds to stones - The value in stones - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value of radians per second to convert - Convert radians per second to degrees per second - The value in degrees per second - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value of radians per second to convert - Convert radians per second to hertz - The value in hertz - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in radians to convert - Convert radians to degrees - The value in degrees - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in stones to convert - Convert stones to pounds - The value in pounds - To be added. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Double - - - - - - The value in US Survey Feet to convert - Convert US survey feet to meteres - The value in meters. - To be added. - - - - From da071c4c3d71d4a614bf3ca4f2c836071dded872 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 15:41:57 +0100 Subject: [PATCH 08/12] Apple Sign In --- .../AppleSignInAuthenticator+Options.xml | 70 ------------------- .../AppleSignInAuthenticator.xml | 41 ----------- .../AppleSignInAuthenticator.shared.cs | 31 +++++++- 3 files changed, 29 insertions(+), 113 deletions(-) delete mode 100644 src/Essentials/docs/en/Xamarin.Essentials/AppleSignInAuthenticator+Options.xml delete mode 100644 src/Essentials/docs/en/Xamarin.Essentials/AppleSignInAuthenticator.xml diff --git a/src/Essentials/docs/en/Xamarin.Essentials/AppleSignInAuthenticator+Options.xml b/src/Essentials/docs/en/Xamarin.Essentials/AppleSignInAuthenticator+Options.xml deleted file mode 100644 index 30791ffe77d6..000000000000 --- a/src/Essentials/docs/en/Xamarin.Essentials/AppleSignInAuthenticator+Options.xml +++ /dev/null @@ -1,70 +0,0 @@ - - - - - - Xamarin.Essentials - 1.0.0.0 - - - System.Object - - - - Options for Native Apple Sign In - - - - - - - - Constructor - - Xamarin.Essentials - 1.0.0.0 - - - - - To be added. - - - - - - - Property - - Xamarin.Essentials - 1.0.0.0 - - - System.Boolean - - - Include email scope. - - - - - - - - - Property - - Xamarin.Essentials - 1.0.0.0 - - - System.Boolean - - - Include full name scope. - - - - - - diff --git a/src/Essentials/docs/en/Xamarin.Essentials/AppleSignInAuthenticator.xml b/src/Essentials/docs/en/Xamarin.Essentials/AppleSignInAuthenticator.xml deleted file mode 100644 index d7421a0230a6..000000000000 --- a/src/Essentials/docs/en/Xamarin.Essentials/AppleSignInAuthenticator.xml +++ /dev/null @@ -1,41 +0,0 @@ - - - - - - Xamarin.Essentials - 1.0.0.0 - - - System.Object - - - - Native Apple Sign In authentication API. - This API is only supported on iOS 13.0+ and should not be called on other devices at runtime. - - - - - - - Method - - Xamarin.Essentials - 1.0.0.0 - - - System.Threading.Tasks.Task<Xamarin.Essentials.WebAuthenticatorResult> - - - - - - Additional Sign In options. - Performs a native Apple Sign In authentication request. - - - - - - diff --git a/src/Essentials/src/WebAuthenticator/AppleSignInAuthenticator.shared.cs b/src/Essentials/src/WebAuthenticator/AppleSignInAuthenticator.shared.cs index 52e684955635..b7af8286033c 100644 --- a/src/Essentials/src/WebAuthenticator/AppleSignInAuthenticator.shared.cs +++ b/src/Essentials/src/WebAuthenticator/AppleSignInAuthenticator.shared.cs @@ -3,30 +3,57 @@ namespace Microsoft.Maui.Authentication { + /// + /// Represents platform native Apple Sign In authentication APIs. + /// public interface IAppleSignInAuthenticator { + /// + /// Performs a native Apple Sign In authentication request. + /// + /// Additional Sign In options. + /// A object with the results of this operation. Task AuthenticateAsync(AppleSignInAuthenticator.Options? options = null); } - /// + /// + /// Represents platform native Apple Sign In authentication APIs. + /// + /// This API is only supported on iOS 13.0+ and should not be called on other devices at runtime. public static class AppleSignInAuthenticator { - /// + /// + /// Performs a native Apple Sign In authentication request. + /// + /// Additional Sign In options. + /// A object with the results of this operation. public static Task AuthenticateAsync(AppleSignInAuthenticator.Options? options = null) => Default.AuthenticateAsync(options ?? new AppleSignInAuthenticator.Options()); static IAppleSignInAuthenticator? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IAppleSignInAuthenticator Default => defaultImplementation ??= new AppleSignInAuthenticatorImplementation(); internal static void SetDefault(IAppleSignInAuthenticator? implementation) => defaultImplementation = implementation; + /// + /// Options for Apple Sign In. + /// public class Options { + /// + /// Gets or sets whether to request the full name scope during sign in. + /// public bool IncludeFullNameScope { get; set; } = false; + /// + /// Gets or sets whether to request the email scope during sign in. + /// public bool IncludeEmailScope { get; set; } = false; } } From 1600f300fc458fd6950d55f1eea2974387586267 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 16:20:42 +0100 Subject: [PATCH 09/12] WebAuthenticator --- .../src/Platform/Platform.shared.cs | 8 ++- .../AppleSignInAuthenticator.shared.cs | 2 +- .../WebAuthenticator.ios.tvos.cs | 1 + .../WebAuthenticator.shared.cs | 57 ++++++++++++++++--- 4 files changed, 59 insertions(+), 9 deletions(-) diff --git a/src/Essentials/src/Platform/Platform.shared.cs b/src/Essentials/src/Platform/Platform.shared.cs index e0e5c692b780..3d4e848a8086 100644 --- a/src/Essentials/src/Platform/Platform.shared.cs +++ b/src/Essentials/src/Platform/Platform.shared.cs @@ -69,7 +69,13 @@ public static void OnResume(Android.App.Activity? activity = null) => AppActions.Current.OnResume(activity?.Intent); #elif IOS || MACCATALYST - + /// + /// Opens the specified URI to start a authentication flow. + /// + /// This parameters is not used. + /// The URL to open that will start the authentication flow. + /// This parameters is not used. + /// when the URI has been opened, otherwise . public static bool OpenUrl(UIKit.UIApplication app, Foundation.NSUrl url, Foundation.NSDictionary options) => WebAuthenticator.Default.OpenUrl(app, url, options); diff --git a/src/Essentials/src/WebAuthenticator/AppleSignInAuthenticator.shared.cs b/src/Essentials/src/WebAuthenticator/AppleSignInAuthenticator.shared.cs index b7af8286033c..858c02fc400a 100644 --- a/src/Essentials/src/WebAuthenticator/AppleSignInAuthenticator.shared.cs +++ b/src/Essentials/src/WebAuthenticator/AppleSignInAuthenticator.shared.cs @@ -42,7 +42,7 @@ internal static void SetDefault(IAppleSignInAuthenticator? implementation) => defaultImplementation = implementation; /// - /// Options for Apple Sign In. + /// Represents additional options for Apple Sign In. /// public class Options { diff --git a/src/Essentials/src/WebAuthenticator/WebAuthenticator.ios.tvos.cs b/src/Essentials/src/WebAuthenticator/WebAuthenticator.ios.tvos.cs index 879f2ee719b5..81169504e050 100644 --- a/src/Essentials/src/WebAuthenticator/WebAuthenticator.ios.tvos.cs +++ b/src/Essentials/src/WebAuthenticator/WebAuthenticator.ios.tvos.cs @@ -174,6 +174,7 @@ public bool OpenUrlCallback(Uri uri) } catch (Exception ex) { + // TODO change this to ILogger? Console.WriteLine(ex); } return false; diff --git a/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs b/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs index b00fdb9bf3bb..2e7cb2017091 100644 --- a/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs +++ b/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs @@ -6,16 +6,37 @@ namespace Microsoft.Maui.Authentication { + /// + /// A web navigation API intended to be used for authentication with external web services such as OAuth. + /// public interface IWebAuthenticator { + /// + /// Begin an authentication flow by navigating to the specified URL and waiting for a callback/redirect to the callback URL scheme. + /// + /// A instance containing additional configuration for this authentication call. + /// A object with the results of this operation. Task AuthenticateAsync(WebAuthenticatorOptions webAuthenticatorOptions); } + /// + /// Provides abstractions for the platform web authenticator callbacks triggered when using . + /// public interface IPlatformWebAuthenticatorCallback { #if IOS || MACCATALYST || MACOS + /// + /// Opens the specified URI to start the authentication flow. + /// + /// The URI to open that will start the authentication flow. + /// when the URI has been opened, otherwise . bool OpenUrlCallback(Uri uri); #elif ANDROID + /// + /// The event that is triggered when an authentication flow calls back into the Android application. + /// + /// A object containing additional data about this resume operation. + /// when the callback can be processed, otherwise . bool OnResumeCallback(Android.Content.Intent intent); #endif } @@ -25,7 +46,9 @@ public interface IWebAuthenticatorResponseDecoder IDictionary? DecodeResponse(Uri uri); } - /// A web navigation API intended to be used for Authentication with external web services such as OAuth. + /// + /// A web navigation API intended to be used for Authentication with external web services such as OAuth. + /// /// /// This API helps with navigating to a start URL and waiting for a callback URL to the app. Your app must /// be registered to handle the callback scheme you provide in the call to authenticate. @@ -33,8 +56,8 @@ public interface IWebAuthenticatorResponseDecoder public static class WebAuthenticator { /// Begin an authentication flow by navigating to the specified url and waiting for a callback/redirect to the callbackUrl scheme. - /// Url to navigate to, beginning the authentication flow. - /// Expected callback url that the navigation flow will eventually redirect to. + /// Url to navigate to, beginning the authentication flow. + /// Expected callback url that the navigation flow will eventually redirect to. /// Returns a result parsed out from the callback url. public static Task AuthenticateAsync(Uri url, Uri callbackUrl) => Current.AuthenticateAsync(url, callbackUrl); @@ -59,6 +82,9 @@ internal static void SetDefault(IWebAuthenticator? implementation) => defaultImplementation = implementation; } + /// + /// This class contains static extension methods for use with . + /// public static class WebAuthenticatorExtensions { static IPlatformWebAuthenticatorCallback AsPlatformCallback(this IWebAuthenticator webAuthenticator) @@ -68,7 +94,9 @@ static IPlatformWebAuthenticatorCallback AsPlatformCallback(this IWebAuthenticat return platform; } - /// Begin an authentication flow by navigating to the specified url and waiting for a callback/redirect to the callbackUrl scheme. + /// + /// Begin an authentication flow by navigating to the specified url and waiting for a callback/redirect to the callbackUrl scheme. + /// /// The to use for the authentication flow. /// Url to navigate to, beginning the authentication flow. /// Expected callback url that the navigation flow will eventually redirect to. @@ -77,10 +105,11 @@ public static Task AuthenticateAsync(this IWebAuthentica webAuthenticator.AuthenticateAsync(new WebAuthenticatorOptions { Url = url, CallbackUrl = callbackUrl }); #if IOS || MACCATALYST || MACOS - + /// public static bool OpenUrl(this IWebAuthenticator webAuthenticator, Uri uri) => webAuthenticator.AsPlatformCallback().OpenUrlCallback(uri); + /// public static bool OpenUrl(this IWebAuthenticator webAuthenticator, UIKit.UIApplication app, Foundation.NSUrl url, Foundation.NSDictionary options) { if(url?.AbsoluteString != null) @@ -90,6 +119,7 @@ public static bool OpenUrl(this IWebAuthenticator webAuthenticator, UIKit.UIAppl return false; } + /// public static bool ContinueUserActivity(this IWebAuthenticator webAuthenticator, UIKit.UIApplication application, Foundation.NSUserActivity userActivity, UIKit.UIApplicationRestorationHandler completionHandler) { var uri = userActivity?.WebPageUrl?.AbsoluteString; @@ -100,19 +130,32 @@ public static bool ContinueUserActivity(this IWebAuthenticator webAuthenticator, } #elif ANDROID - + /// public static bool OnResume(this IWebAuthenticator webAuthenticator, Android.Content.Intent intent) => webAuthenticator.AsPlatformCallback().OnResumeCallback(intent); - #endif } + /// + /// Represents additional options for . + /// public class WebAuthenticatorOptions { + /// + /// Gets or sets the URL that will start the authentication flow. + /// public Uri? Url { get; set; } + /// + /// Gets or sets the callback URL that should be called when authentication completes. + /// public Uri? CallbackUrl { get; set; } + /// + /// Gets or sets whether the browser used for the authentication flow is short-lived. + /// This means it will not share session nor cookies with the regular browser on this device if set the . + /// + /// This setting only has effect on iOS. public bool PrefersEphemeralWebBrowserSession { get; set; } public IWebAuthenticatorResponseDecoder? ResponseDecoder { get; set; } From 1c6cafaee83e4f970e5140ac364aa550b87ace4a Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 30 Jan 2023 20:00:39 +0100 Subject: [PATCH 10/12] Some more --- .../Platform/ActivityStateManager.android.cs | 51 +++++++++++++++++++ .../src/Platform/Platform.shared.cs | 50 +++++++++++++++--- 2 files changed, 95 insertions(+), 6 deletions(-) diff --git a/src/Essentials/src/Platform/ActivityStateManager.android.cs b/src/Essentials/src/Platform/ActivityStateManager.android.cs index 882b38391d0a..f90d127ce57c 100644 --- a/src/Essentials/src/Platform/ActivityStateManager.android.cs +++ b/src/Essentials/src/Platform/ActivityStateManager.android.cs @@ -8,23 +8,52 @@ namespace Microsoft.Maui.ApplicationModel { + /// + /// Represents a manager object that can handle states. + /// public interface IActivityStateManager { + /// + /// Initializes the for the given . + /// + /// The to use for initialization. void Init(Application application); + /// + /// Initializes the for the given and . + /// + /// The to use for initialization. + /// The to use for initialization. void Init(Activity activity, Bundle? bundle); + /// + /// Gets the object that represents the application's current activity. + /// Activity? GetCurrentActivity(); + /// + /// Occurs when the state of an activity of this application changes. + /// event EventHandler ActivityStateChanged; + /// + /// Waits for a to be created or resumed. + /// + /// A token that can be used for cancelling the operation. + /// The application's current or the that has been created or resumed. Task WaitForActivityAsync(CancellationToken cancelToken = default); } + /// + /// Represents a manager object that can handle states. + /// public static class ActivityStateManager { static IActivityStateManager? defaultImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IActivityStateManager Default => defaultImplementation ??= new ActivityStateManagerImplementation(); @@ -88,6 +117,12 @@ void OnActivityStateChanged(Activity activity, ActivityState ev) static class ActivityStateManagerExtensions { + /// + /// Gets the object that represents the application's current activity. + /// + /// The object to invoke this method on. + /// Throws an exception if no current can be found and this value is set to , otherwise this method returns . + /// Thrown if no current can be found and is set to . public static Activity? GetCurrentActivity(this IActivityStateManager manager, bool throwOnNull) { var activity = manager.GetCurrentActivity(); @@ -98,14 +133,30 @@ static class ActivityStateManagerExtensions } } + /// + /// Represents states that a can have. + /// public enum ActivityState { + /// The activity is created. Created, + + /// The activity is resumed. Resumed, + + /// The activity is paused. Paused, + + /// The activity is destroyed. Destroyed, + + /// The activity saving the instance state. SaveInstanceState, + + /// The activity is started. Started, + + /// The activity is stopped. Stopped } diff --git a/src/Essentials/src/Platform/Platform.shared.cs b/src/Essentials/src/Platform/Platform.shared.cs index 3d4e848a8086..6ef20cb0544d 100644 --- a/src/Essentials/src/Platform/Platform.shared.cs +++ b/src/Essentials/src/Platform/Platform.shared.cs @@ -31,40 +31,54 @@ public static class Intent // ActivityStateManager - /// - /// Gets the object that represents the application's current activity. - /// + /// public static Android.App.Activity? CurrentActivity => ActivityStateManager.Default.GetCurrentActivity(); - /// - /// Occurs when the state of an activity of this application changes. - /// + + /// public static event EventHandler? ActivityStateChanged { add => ActivityStateManager.Default.ActivityStateChanged += value; remove => ActivityStateManager.Default.ActivityStateChanged -= value; } + /// public static Task WaitForActivityAsync(CancellationToken cancelToken = default) => ActivityStateManager.Default.WaitForActivityAsync(cancelToken); + /// public static void Init(Android.App.Application application) => ActivityStateManager.Default.Init(application); + /// public static void Init(Android.App.Activity activity, Android.OS.Bundle? bundle) => ActivityStateManager.Default.Init(activity, bundle); // Permissions + /// + /// Pass permission request results from an activity's overridden method to the library for handling internal permission requests. + /// + /// The requestCode from the corresponding overridden method in an activity. + /// The permissions from the corresponding overridden method in an activity. + /// The grantResults from the corresponding overridden method in an activity. public static void OnRequestPermissionsResult(int requestCode, string[] permissions, Android.Content.PM.Permission[] grantResults) => Permissions.OnRequestPermissionsResult(requestCode, permissions, grantResults); // AppActions + /// + /// Called when a new was created as part of invoking an app action. + /// + /// The that is created. public static void OnNewIntent(Android.Content.Intent? intent) => AppActions.Current.OnNewIntent(intent); + /// + /// Called when a is resumed as part of invoking an app action. + /// + /// The that is resumed. public static void OnResume(Android.App.Activity? activity = null) => AppActions.Current.OnResume(activity?.Intent); @@ -79,15 +93,37 @@ public static void OnResume(Android.App.Activity? activity = null) => public static bool OpenUrl(UIKit.UIApplication app, Foundation.NSUrl url, Foundation.NSDictionary options) => WebAuthenticator.Default.OpenUrl(app, url, options); + /// + /// Informs the app that there is data associated with continuing a task specified as a object, and then returns whether the app continued the activity. + /// + /// The application this action is invoked on. + /// The user activity identifier. + /// The action that is invoked when the operation is completed. + /// if the app handled the user activity, otherwise . public static bool ContinueUserActivity(UIKit.UIApplication application, Foundation.NSUserActivity userActivity, UIKit.UIApplicationRestorationHandler completionHandler) => WebAuthenticator.Default.ContinueUserActivity(application, userActivity, completionHandler); + /// + /// Invokes the action that corresponds to the chosen by the user. + /// + /// The application this action is invoked on. + /// The shortcut item that was chosen by the user. + /// The action that is invoked when the operation is completed. public static void PerformActionForShortcutItem(UIKit.UIApplication application, UIKit.UIApplicationShortcutItem shortcutItem, UIKit.UIOperationHandler completionHandler) => AppActions.Current.PerformActionForShortcutItem(application, shortcutItem, completionHandler); + /// + /// Initializes the for the given . + /// + /// The to use for initialization. public static void Init(Func? getCurrentUIViewController) => WindowStateManager.Default.Init(getCurrentUIViewController); + /// + /// Gets the current view controller through the . + /// + /// The object that is currently presented. + /// Thrown if no current can be found. public static UIKit.UIViewController? GetCurrentUIViewController() => WindowStateManager.Default.GetCurrentUIViewController(true); @@ -101,9 +137,11 @@ public static string? MapServiceToken set => Geocoding.Default.SetMapServiceToken(value); } + /// public static void OnLaunched(UI.Xaml.LaunchActivatedEventArgs e) => AppActions.Current.OnLaunched(e); + /// public static void OnActivated(UI.Xaml.Window window, UI.Xaml.WindowActivatedEventArgs args) => WindowStateManager.Default.OnActivated(window, args); From edd97565de46a17f8334eee80c7d5e83718fc4f7 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Thu, 2 Feb 2023 10:46:50 +0100 Subject: [PATCH 11/12] Update src/Essentials/src/FileSystem/FileSystem.shared.cs Co-authored-by: Matthew Leibowitz --- src/Essentials/src/FileSystem/FileSystem.shared.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Essentials/src/FileSystem/FileSystem.shared.cs b/src/Essentials/src/FileSystem/FileSystem.shared.cs index 7e41e78edc24..6461323cd3be 100644 --- a/src/Essentials/src/FileSystem/FileSystem.shared.cs +++ b/src/Essentials/src/FileSystem/FileSystem.shared.cs @@ -67,7 +67,7 @@ public static Task OpenAppPackageFileAsync(string filename) /// /// Determines whether or not a file exists in the app package. /// - /// The name of the file (excluding the path) to check for existence + /// The path of the file (relative to the app package) to check the existence of. /// when the specified file exists in the app package, otherwise . public static Task AppPackageFileExistsAsync(string filename) => Current.AppPackageFileExistsAsync(filename); From 1b8f3ea16641050db109556d7deee1aaeac0ffb1 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 13 Feb 2023 09:12:51 +0100 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: Matthew Leibowitz --- src/Essentials/src/Types/DisplayInfo.shared.cs | 10 +++++----- .../src/UnitConverters/UnitConverters.shared.cs | 10 +++++----- .../src/WebAuthenticator/WebAuthenticator.shared.cs | 2 +- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/Essentials/src/Types/DisplayInfo.shared.cs b/src/Essentials/src/Types/DisplayInfo.shared.cs index 27de695a543d..2cfa915f7c01 100644 --- a/src/Essentials/src/Types/DisplayInfo.shared.cs +++ b/src/Essentials/src/Types/DisplayInfo.shared.cs @@ -59,10 +59,10 @@ public DisplayInfo(double width, double height, double density, DisplayOrientati /// Gets a value representing the screen density. /// /// - /// The density is the scaling or a factor that can be used to convert between physical pixels and scaled pixels. For example, on high resolution displays, the physical number of pixels increases, but the scaled pixels remain the same. - /// In a practical example for iOS, the Retina display will have a density of 2.0 or 3.0, but the units used to lay out a view does not change much. A view with a UI width of 100 may be 100 physical pixels (density = 1) on a non-Retina device, but be 200 physical pixels (density = 2) on a Retina device. - /// On Windows, the density works similarly, and may often relate to the scale used in the display. On some monitors, the scale is set to 100% (density = 1), but on other high resolution monitors, the scale may be set to 200% (density = 2) or even 250% (density = 2.5). - /// + /// The density is the scaling or a factor that can be used to convert between physical pixels and scaled pixels. For example, on high resolution displays, the physical number of pixels increases, but the scaled pixels remain the same. + /// In a practical example for iOS, the Retina display will have a density of 2.0 or 3.0, but the units used to lay out a view does not change much. A view with a UI width of 100 may be 100 physical pixels (density = 1) on a non-Retina device, but be 200 physical pixels (density = 2) on a Retina device. + /// On Windows, the density works similarly, and may often relate to the scale used in the display. On some monitors, the scale is set to 100% (density = 1), but on other high resolution monitors, the scale may be set to 200% (density = 2) or even 250% (density = 2.5). + /// public double Density { get; } /// @@ -81,7 +81,7 @@ public DisplayInfo(double width, double height, double density, DisplayOrientati public float RefreshRate { get; } /// - /// Equality operator for equals. + /// Equality operator for equals. /// /// Left to compare. /// Right to compare. diff --git a/src/Essentials/src/UnitConverters/UnitConverters.shared.cs b/src/Essentials/src/UnitConverters/UnitConverters.shared.cs index 9fb6eabd490e..d042d39069a0 100644 --- a/src/Essentials/src/UnitConverters/UnitConverters.shared.cs +++ b/src/Essentials/src/UnitConverters/UnitConverters.shared.cs @@ -226,18 +226,18 @@ public static double PascalsToAtmospheres(double pascals) => pascals / atmospherePascals; /// - /// Calculates the distance between two coordinates in miles. + /// Calculates the distance between two coordinates in miles. /// /// First latitude. - /// First longitude. - /// Second latitude. - /// Second longitude. + /// First longitude. + /// Second latitude. + /// Second longitude. /// The distance in miles. public static double CoordinatesToMiles(double lat1, double lon1, double lat2, double lon2) => KilometersToMiles(CoordinatesToKilometers(lat1, lon1, lat2, lon2)); /// - /// Calculates the distance between two coordinates in kilometers. + /// Calculates the distance between two coordinates in kilometers. /// /// First latitude. /// First longitude. diff --git a/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs b/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs index 2e7cb2017091..2af4a1979925 100644 --- a/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs +++ b/src/Essentials/src/WebAuthenticator/WebAuthenticator.shared.cs @@ -35,7 +35,7 @@ public interface IPlatformWebAuthenticatorCallback /// /// The event that is triggered when an authentication flow calls back into the Android application. /// - /// A object containing additional data about this resume operation. + /// An object containing additional data about this resume operation. /// when the callback can be processed, otherwise . bool OnResumeCallback(Android.Content.Intent intent); #endif