Review of the "Essentials" interface API

src/Compatibility/Core/src/Essentials/Accelerometer.cs

@@ -0,0 +1,33 @@
+#nullable enable
+using System;
+using Microsoft.Maui.Devices.Sensors;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/Accelerometer.xml" path="Type[@FullName='Microsoft.Maui.Essentials.Accelerometer']/Docs" />
+	public static partial class Accelerometer
+	{
+		public static event EventHandler<AccelerometerChangedEventArgs> ReadingChanged
+		{
+			add => Current.ReadingChanged += value;
+			remove => Current.ReadingChanged -= value;
+		}
+
+		public static event EventHandler ShakeDetected
+		{
+			add => Current.ShakeDetected += value;
+			remove => Current.ShakeDetected -= value;
+		}
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Accelerometer.xml" path="//Member[@MemberName='IsMonitoring']/Docs" />
+		public static bool IsMonitoring => Current.IsMonitoring;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Accelerometer.xml" path="//Member[@MemberName='Start']/Docs" />
+		public static void Start(SensorSpeed sensorSpeed) => Current.Start(sensorSpeed);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Accelerometer.xml" path="//Member[@MemberName='Stop']/Docs" />
+		public static void Stop() => Current.Stop();
+
+		static IAccelerometer Current => Devices.Sensors.Accelerometer.Default;
+	}
+}

src/Compatibility/Core/src/Essentials/AppActions.cs

@@ -0,0 +1,33 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Microsoft.Maui.ApplicationModel;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentialssss/AppActions.xml" path="Type[@FullName='Microsoft.Maui.Essentialssss.AppActions']/Docs" />
+	public static partial class AppActions
+	{
+		/// <include file="../../docs/Microsoft.Maui.Essentialssss/AppActions.xml" path="//Member[@MemberName='GetAsync']/Docs" />
+		public static Task<IEnumerable<AppAction>> GetAsync()
+			=> Current.GetAsync();
+
+		/// <include file="../../docs/Microsoft.Maui.Essentialssss/AppActions.xml" path="//Member[@MemberName='SetAsync'][1]/Docs" />
+		public static Task SetAsync(params AppAction[] actions)
+			=> Current.SetAsync(actions);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentialssss/AppActions.xml" path="//Member[@MemberName='SetAsync'][2]/Docs" />
+		public static Task SetAsync(IEnumerable<AppAction> actions)
+			=> Current.SetAsync(actions);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentialssss/AppActions.xml" path="//Member[@MemberName='OnAppAction'][2]/Docs" />
+		public static event EventHandler<AppActionEventArgs>? OnAppAction
+		{
+			add => Current.AppActionActivated += value;
+			remove => Current.AppActionActivated -= value;
+		}
+
+		static IAppActions Current => ApplicationModel.AppActions.Current;
+	}
+}

src/Compatibility/Core/src/Essentials/AppInfo.cs

@@ -0,0 +1,37 @@
+#nullable enable
+using System;
+using Microsoft.Maui.ApplicationModel;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/AppInfo.xml" path="Type[@FullName='Microsoft.Maui.Essentials.AppInfo']/Docs" />
+	public static class AppInfo
+	{
+		/// <include file="../../docs/Microsoft.Maui.Essentials/AppInfo.xml" path="//Member[@MemberName='PackageName']/Docs" />
+		public static string PackageName => Current.PackageName;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/AppInfo.xml" path="//Member[@MemberName='Name']/Docs" />
+		public static string Name => Current.Name;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/AppInfo.xml" path="//Member[@MemberName='VersionString']/Docs" />
+		public static string VersionString => Current.VersionString;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/AppInfo.xml" path="//Member[@MemberName='Version']/Docs" />
+		public static Version Version => Current.Version;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/AppInfo.xml" path="//Member[@MemberName='BuildString']/Docs" />
+		public static string BuildString => Current.BuildString;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/AppInfo.xml" path="//Member[@MemberName='ShowSettingsUI']/Docs" />
+		public static void ShowSettingsUI() => Current.ShowSettingsUI();
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/AppInfo.xml" path="//Member[@MemberName='RequestedTheme']/Docs" />
+		public static AppTheme RequestedTheme => Current.RequestedTheme;
+
+		public static AppPackagingModel PackagingModel => Current.PackagingModel;
+
+		public static LayoutDirection RequestedLayoutDirection => Current.RequestedLayoutDirection;
+
+		static IAppInfo Current => ApplicationModel.AppInfo.Current;
+	}
+}

src/Compatibility/Core/src/Essentials/Barometer.cs

@@ -0,0 +1,32 @@
+#nullable enable
+using System;
+using Microsoft.Maui.Devices.Sensors;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/Barometer.xml" path="Type[@FullName='Microsoft.Maui.Essentials.Barometer']/Docs" />
+	public static class Barometer
+	{
+		public static event EventHandler<BarometerChangedEventArgs> ReadingChanged
+		{
+			add => Current.ReadingChanged += value;
+			remove => Current.ReadingChanged -= value;
+		}
+
+		public static bool IsSupported => Current.IsSupported;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Barometer.xml" path="//Member[@MemberName='IsMonitoring']/Docs" />
+		public static bool IsMonitoring
+			=> Current.IsMonitoring;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Barometer.xml" path="//Member[@MemberName='Start']/Docs" />
+		public static void Start(SensorSpeed sensorSpeed)
+			=> Current.Start(sensorSpeed);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Barometer.xml" path="//Member[@MemberName='Stop']/Docs" />
+		public static void Stop()
+			=> Current.Stop();
+
+		static IBarometer Current => Devices.Sensors.Barometer.Default;
+	}
+}

src/Compatibility/Core/src/Essentials/Battery.cs

@@ -0,0 +1,38 @@
+#nullable enable
+using System;
+using Microsoft.Maui.Devices;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/Battery.xml" path="Type[@FullName='Microsoft.Maui.Essentials.Battery']/Docs" />
+	public static partial class Battery
+	{
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Battery.xml" path="//Member[@MemberName='ChargeLevel']/Docs" />
+		public static double ChargeLevel => Current.ChargeLevel;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Battery.xml" path="//Member[@MemberName='State']/Docs" />
+		public static BatteryState State => Current.State;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Battery.xml" path="//Member[@MemberName='PowerSource']/Docs" />
+		public static BatteryPowerSource PowerSource => Current.PowerSource;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Battery.xml" path="//Member[@MemberName='EnergySaverStatus']/Docs" />
+		public static EnergySaverStatus EnergySaverStatus => Current.EnergySaverStatus;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Battery.xml" path="//Member[@MemberName='BatteryInfoChanged']/Docs" />
+		public static event EventHandler<BatteryInfoChangedEventArgs> BatteryInfoChanged
+		{
+			add => Current.BatteryInfoChanged += value;
+			remove => Current.BatteryInfoChanged -= value;
+		}
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Battery.xml" path="//Member[@MemberName='EnergySaverStatusChanged']/Docs" />
+		public static event EventHandler<EnergySaverStatusChangedEventArgs> EnergySaverStatusChanged
+		{
+			add => Current.EnergySaverStatusChanged += value;
+			remove => Current.EnergySaverStatusChanged -= value;
+		}
+
+		static IBattery Current => Devices.Battery.Default;
+	}
+}

src/Compatibility/Core/src/Essentials/Browser.cs

@@ -0,0 +1,31 @@
+#nullable enable
+using System;
+using System.Threading.Tasks;
+using Microsoft.Maui.ApplicationModel;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/Browser.xml" path="Type[@FullName='Microsoft.Maui.Essentials.Browser']/Docs" />
+	public static partial class Browser
+	{
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Browser.xml" path="//Member[@MemberName='OpenAsync'][1]/Docs" />
+		public static Task<bool> OpenAsync(string uri) => Current.OpenAsync(uri);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Browser.xml" path="//Member[@MemberName='OpenAsync'][3]/Docs" />
+		public static Task<bool> OpenAsync(string uri, BrowserLaunchMode launchMode) => Current.OpenAsync(uri, launchMode);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Browser.xml" path="//Member[@MemberName='OpenAsync'][4]/Docs" />
+		public static Task<bool> OpenAsync(string uri, BrowserLaunchOptions options) => Current.OpenAsync(uri, options);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Browser.xml" path="//Member[@MemberName='OpenAsync'][2]/Docs" />
+		public static Task<bool> OpenAsync(Uri uri) => Current.OpenAsync(uri);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Browser.xml" path="//Member[@MemberName='OpenAsync'][5]/Docs" />
+		public static Task<bool> OpenAsync(Uri uri, BrowserLaunchMode launchMode) => Current.OpenAsync(uri, launchMode);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Browser.xml" path="//Member[@MemberName='OpenAsync'][6]/Docs" />
+		public static Task<bool> OpenAsync(Uri uri, BrowserLaunchOptions options) => Current.OpenAsync(uri, options);
+
+		public static IBrowser Current => ApplicationModel.Browser.Default;
+	}
+}

src/Compatibility/Core/src/Essentials/Clipboard.cs

@@ -0,0 +1,32 @@
+#nullable enable
+using System;
+using System.Threading.Tasks;
+using Microsoft.Maui.ApplicationModel.DataTransfer;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/Clipboard.xml" path="Type[@FullName='Microsoft.Maui.Essentials.Clipboard']/Docs" />
+	public static partial class Clipboard
+	{
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Clipboard.xml" path="//Member[@MemberName='SetTextAsync']/Docs" />
+		public static Task SetTextAsync(string? text)
+			=> Current.SetTextAsync(text ?? string.Empty);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Clipboard.xml" path="//Member[@MemberName='HasText']/Docs" />
+		public static bool HasText
+			=> Current.HasText;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Clipboard.xml" path="//Member[@MemberName='GetTextAsync']/Docs" />
+		public static Task<string?> GetTextAsync()
+			=> Current.GetTextAsync();
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Clipboard.xml" path="//Member[@MemberName='ClipboardContentChanged']/Docs" />
+		public static event EventHandler<EventArgs> ClipboardContentChanged
+		{
+			add => Current.ClipboardContentChanged += value;
+			remove => Current.ClipboardContentChanged -= value;
+		}
+
+		static IClipboard Current => ApplicationModel.DataTransfer.Clipboard.Default;
+	}
+}

src/Compatibility/Core/src/Essentials/Compass.cs

@@ -0,0 +1,54 @@
+#nullable enable
+using System;
+using Microsoft.Maui.Devices.Sensors;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/Compass.xml" path="Type[@FullName='Microsoft.Maui.Essentials.Compass']/Docs" />
+	public static partial class Compass
+	{
+		public static event EventHandler<CompassChangedEventArgs> ReadingChanged
+		{
+			add => Current.ReadingChanged += value;
+			remove => Current.ReadingChanged -= value;
+		}
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Compass.xml" path="//Member[@MemberName='IsMonitoring']/Docs" />
+		public static bool IsSupported
+			=> Current.IsSupported;
+
+		public static bool IsMonitoring
+			=> Current.IsMonitoring;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Compass.xml" path="//Member[@MemberName='Start'][1]/Docs" />
+		public static void Start(SensorSpeed sensorSpeed)
+			=> Start(sensorSpeed, true);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Compass.xml" path="//Member[@MemberName='Start'][2]/Docs" />
+		public static void Start(SensorSpeed sensorSpeed, bool applyLowPassFilter)
+			=> Current.Start(sensorSpeed, applyLowPassFilter);
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Compass.xml" path="//Member[@MemberName='Stop'][1]/Docs" />
+		public static void Stop()
+			=> Current.Stop();
+
+#if IOS || MACCATALYST
+		public static bool ShouldDisplayHeadingCalibration
+		{
+			get
+			{
+				if (Current is IPlatformCompass c)
+					return c.ShouldDisplayHeadingCalibration;
+				return false;
+			}
+			set
+			{
+				if (Current is IPlatformCompass c)
+					c.ShouldDisplayHeadingCalibration = value;
+			}
+		}
+#endif
+
+		static ICompass Current => Devices.Sensors.Compass.Default;
+	}
+}

src/Compatibility/Core/src/Essentials/Connectivity.cs

@@ -0,0 +1,27 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.Maui.Networking;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/Connectivity.xml" path="Type[@FullName='Microsoft.Maui.Essentials.Connectivity']/Docs" />
+	public static partial class Connectivity
+	{
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Connectivity.xml" path="//Member[@MemberName='NetworkAccess']/Docs" />
+		public static NetworkAccess NetworkAccess => Current.NetworkAccess;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Connectivity.xml" path="//Member[@MemberName='ConnectionProfiles']/Docs" />
+		public static IEnumerable<ConnectionProfile> ConnectionProfiles => Current.ConnectionProfiles.Distinct();
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Connectivity.xml" path="//Member[@MemberName='ConnectivityChanged']/Docs" />
+		public static event EventHandler<ConnectivityChangedEventArgs> ConnectivityChanged
+		{
+			add => Current.ConnectivityChanged += value;
+			remove => Current.ConnectivityChanged -= value;
+		}
+
+		static IConnectivity Current => Networking.Connectivity.Current;
+	}
+}

src/Compatibility/Core/src/Essentials/Contacts.cs

@@ -0,0 +1,29 @@
+#nullable enable
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Maui.ApplicationModel.Communication;
+using Microsoft.Maui.Devices;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/Contacts.xml" path="Type[@FullName='Microsoft.Maui.Essentials.Contacts']/Docs" />
+	public static class Contacts
+	{
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Contacts.xml" path="//Member[@MemberName='PickContactAsync']/Docs" />
+		public static async Task<Contact?> PickContactAsync()
+		{
+			// iOS does not require permissions for the picker
+			if (DeviceInfo.Platform != DevicePlatform.iOS)
+				await Permissions.EnsureGrantedAsync<Permissions.ContactsRead>();
+
+			return await Current.PickContactAsync();
+		}
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/Contacts.xml" path="//Member[@MemberName='GetAllAsync']/Docs" />
+		public static Task<IEnumerable<Contact>> GetAllAsync(CancellationToken cancellationToken = default)
+			=> Current.GetAllAsync(cancellationToken);
+
+		static IContacts Current => ApplicationModel.Communication.Contacts.Current;
+	}
+}

src/Compatibility/Core/src/Essentials/DeviceDisplay.cs

@@ -0,0 +1,29 @@
+#nullable enable
+using System;
+using Microsoft.Maui.Devices;
+
+namespace Microsoft.Maui.Essentials
+{
+	/// <include file="../../docs/Microsoft.Maui.Essentials/DeviceDisplay.xml" path="Type[@FullName='Microsoft.Maui.Essentials.DeviceDisplay']/Docs" />
+	public static class DeviceDisplay
+	{
+		static IDeviceDisplay Current => Devices.DeviceDisplay.Current;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/DeviceDisplay.xml" path="//Member[@MemberName='KeepScreenOn']/Docs" />
+		public static bool KeepScreenOn
+		{
+			get => Current.KeepScreenOn;
+			set => Current.KeepScreenOn = value;
+		}
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/DeviceDisplay.xml" path="//Member[@MemberName='MainDisplayInfo']/Docs" />
+		public static DisplayInfo MainDisplayInfo => Current.MainDisplayInfo;
+
+		/// <include file="../../docs/Microsoft.Maui.Essentials/DeviceDisplay.xml" path="//Member[@MemberName='MainDisplayInfoChanged']/Docs" />
+		public static event EventHandler<DisplayInfoChangedEventArgs> MainDisplayInfoChanged
+		{
+			add => Current.MainDisplayInfoChanged += value;
+			remove => Current.MainDisplayInfoChanged -= value;
+		}
+	}
+}