Merge pull request #80 from dotnet/adegeo-essentials-2

davidbritch · web-flow · commit e90285caa59a · 2021-08-05T13:12:14.000+01:00
[essentials] Clean up include files
diff --git a/docs/essentials/app-information.md b/docs/essentials/app-information.md
@@ -88,9 +88,3 @@ App information is taken from the `Package.appxmanifest` for the following field
 
 - [AppInfo source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/AppInfo)
 - [AppInfo API documentation](xref:Xamarin.Essentials.AppInfo)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/App-Information-Essential-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/app-theme.md b/docs/essentials/app-theme.md
@@ -70,9 +70,3 @@ You can read more on the [UWP Requested Theme Documentation](/uwp/api/windows.ui
 
 - [AppInfo source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/AppInfo)
 - [AppInfo API documentation](xref:Xamarin.Essentials.AppInfo)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Theme-Detection-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/battery.md b/docs/essentials/battery.md
@@ -179,9 +179,3 @@ No platform differences.
 
 - [Battery source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Battery)
 - [Battery API documentation](xref:Xamarin.Essentials.Battery)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Battery-Essential-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/clipboard.md b/docs/essentials/clipboard.md
@@ -67,9 +67,3 @@ public class ClipboardTest
 
 - [Clipboard source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Clipboard)
 - [Clipboard API documentation](xref:Xamarin.Essentials.Clipboard)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Clipboard-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/color-converters.md b/docs/essentials/color-converters.md
@@ -79,9 +79,3 @@ The `ToSystemColor` method applies to Android.Graphics.Color, UIKit.UIColor, and
 - [Color Converters API documentation](xref:Xamarin.Essentials.ColorConverters)
 - [Color Extensions source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Types/ColorConverters.shared.cs)
 - [Color Extensions API documentation](xref:Xamarin.Essentials.ColorExtensions)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Color-Converters-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/compass.md b/docs/essentials/compass.md
@@ -94,9 +94,3 @@ This is only applied on the Android platform, and the parameter is ignored on iO
 
 - [Compass source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Compass)
 - [Compass API documentation](xref:Xamarin.Essentials.Compass)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Compass-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/connectivity.md b/docs/essentials/connectivity.md
@@ -112,9 +112,3 @@ It is important to note that it is possible that `Internet` is reported by `Netw
 
 * [Connectivity source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Connectivity)
 * [Connectivity API documentation](xref:Xamarin.Essentials.Connectivity)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Connectivity-Essential-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/detect-shake.md b/docs/essentials/detect-shake.md
@@ -75,9 +75,3 @@ The detect shake API uses raw readings from the accelerometer to calculate accel
 
 - [Accelerometer source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Accelerometer)
 - [Accelerometer API documentation](xref:Xamarin.Essentials.Accelerometer)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Detect-Shake-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/device-display.md b/docs/essentials/device-display.md
@@ -101,9 +101,3 @@ No differences.
 
 - [DeviceDisplay source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/DeviceDisplay)
 - [DeviceDisplay API documentation](xref:Xamarin.Essentials.DeviceDisplay)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Device-Display-Information-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/device-information.md b/docs/essentials/device-information.md
@@ -85,9 +85,3 @@ iOS does not expose an API for developers to get the model of the specific iOS d
 
 - [DeviceInfo source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/DeviceInfo)
 - [DeviceInfo API documentation](xref:Xamarin.Essentials.DeviceInfo)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Device-Information-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/email.md b/docs/essentials/email.md
@@ -136,9 +136,3 @@ Not all email clients support sending attachments. See [documentation](/windows/
 
 - [Email source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Email)
 - [Email API documentation](xref:Xamarin.Essentials.Email)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Email-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/file-system-helpers.md b/docs/essentials/file-system-helpers.md
@@ -80,9 +80,3 @@ Add any file into the root in the UWP project and mark the Build Action as **Con
 
 - [File System Helpers source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/FileSystem)
 - [File System API documentation](xref:Xamarin.Essentials.FileSystem)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/File-System-Helpers-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/flashlight.md b/docs/essentials/flashlight.md
@@ -120,9 +120,3 @@ A camera surface texture is created to turn on or off the `FlashMode` of the cam
 
 - [Flashlight source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Flashlight)
 - [Flashlight API documentation](xref:Xamarin.Essentials.Flashlight)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Flashlight-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/geocoding.md b/docs/essentials/geocoding.md
@@ -120,9 +120,3 @@ The [`Location`](xref:Xamarin.Essentials.Location) and [`LocationExtensions`](xr
 
 - [Geocoding source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Geocoding)
 - [Geocoding API documentation](xref:Xamarin.Essentials.Geocoding)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Geocoding-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/geolocation.md b/docs/essentials/geolocation.md
@@ -265,9 +265,3 @@ On UWP, altitude is returned in meters. See the [AltitudeReferenceSystem](/uwp/a
 
 - [Geolocation source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Geolocation)
 - [Geolocation API documentation](xref:Xamarin.Essentials.Geolocation)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Geolocation-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/includes/android-permissions.md b/docs/essentials/includes/android-permissions.md
@@ -1,29 +1,28 @@
 ---
 ms.topic: include
-author: jamesmontemagno
-ms.author: jamont
-ms.date: 05/11/2020
+ms.date: 08/04/2021
 ---
-This API uses runtime permissions on Android. Please ensure that Xamarin.Essentials is fully initialized and permission handling is setup in your app.
 
-In the Android project's `MainLauncher` or any `Activity` that is launched Xamarin.Essentials must be initialized in the `OnCreate` method:
+This API uses runtime permissions on Android. Please ensure that .NET MAUI Essentials is fully initialized and permission handling is setup in your app. For more information, see [Get Started with .NET MAUI Essentials](../get-started.md).
+
+In the Android project's `MainLauncher` or any `Activity` that is launched, .NET MAUI Essentials must be initialized in the `OnCreate` method:
 
 ```csharp
 protected override void OnCreate(Bundle savedInstanceState) 
 {
     //...
     base.OnCreate(savedInstanceState);
-    Xamarin.Essentials.Platform.Init(this, savedInstanceState); // add this line to your code, it may also be called: bundle
+    Microsoft.Maui.Essentials.Platform.Init(this, savedInstanceState); // add this line to your code, it may also be called: bundle
     //...
 }    
 ```
 
-To handle runtime permissions on Android, Xamarin.Essentials must receive any `OnRequestPermissionsResult`. Add the following code to all `Activity` classes:
+To handle runtime permissions on Android, .NET MAUI Essentials must receive any `OnRequestPermissionsResult`. Add the following code to all `Activity` classes:
 
 ```csharp
 public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Android.Content.PM.Permission[] grantResults)
 {
-    Xamarin.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);
+    Microsoft.Maui.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);
 
     base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
 }
diff --git a/docs/essentials/includes/ios-PresentationSourceBounds.md b/docs/essentials/includes/ios-PresentationSourceBounds.md
@@ -1,41 +1,41 @@
 ---
 ms.topic: include
-author: jamont
-ms.author: jamont
-ms.date: 01/16/2020
+ms.date: 08/04/2021
 ---
 
-When requesting a share or opening launcher on iPadOS you have the ability to present in a pop over control. This specifies where the pop over will appear and point an arrow directly to. This location is often the control that launched the action. You can specify the location using the `PresentationSourceBounds` property:
+When requesting a share or opening launcher on iPadOS, you can present in a popover. This specifies where the pop over will appear and point an arrow directly to. This location is often the control that launched the action. You can specify the location using the `PresentationSourceBounds` property:
 
 ```csharp
 await Share.RequestAsync(new ShareFileRequest
-{
-    Title = Title,
-    File = new ShareFile(file),
-    PresentationSourceBounds = DeviceInfo.Platform== DevicePlatform.iOS && DeviceInfo.Idiom == DeviceIdiom.Tablet
-                            ? new System.Drawing.Rectangle(0, 20, 0, 0)
-                            : System.Drawing.Rectangle.Empty
-});
+    {
+        Title = Title,
+        File = new ShareFile(file),
+        PresentationSourceBounds = DeviceInfo.Platform== DevicePlatform.iOS && DeviceInfo.Idiom == DeviceIdiom.Tablet
+                                ? new System.Drawing.Rectangle(0, 20, 0, 0)
+                                : System.Drawing.Rectangle.Empty
+    });
 ```
 
 ```csharp
 await Launcher.OpenAsync(new OpenFileRequest
-{
-    File = new ReadOnlyFile(file),
-    PresentationSourceBounds = DeviceInfo.Platform== DevicePlatform.iOS && DeviceInfo.Idiom == DeviceIdiom.Tablet
-                            ? new System.Drawing.Rectangle(0, 20, 0, 0)
-                            : System.Drawing.Rectangle.Empty
-});
+    {
+        File = new ReadOnlyFile(file),
+        PresentationSourceBounds = DeviceInfo.Platform== DevicePlatform.iOS && DeviceInfo.Idiom == DeviceIdiom.Tablet
+                                ? new System.Drawing.Rectangle(0, 20, 0, 0)
+                                : System.Drawing.Rectangle.Empty
+    });
 ```
 
+<!-- TODO: Is this stuff Apple specific? It seems generic. I know the previous section is because it references iOS, but that's done in this code -->
+
 Everything described here works equally for `Share` and `Launcher`.
 
-If you are using Xamarin.Forms you are able to pass in a `View` and calculate the bounds:
+Here are some extension methods that help calculate the bounds of a view:
 
 ```csharp
 public static class ViewHelpers
 {
-    public static Rectangle GetAbsoluteBounds(this Xamarin.Forms.View element)
+    public static Rectangle GetAbsoluteBounds(this Microsoft.Maui.Controls.View element)
     {
         Element looper = element;
 
@@ -47,7 +47,7 @@ public static class ViewHelpers
         while (looper.Parent != null)
         {
             looper = looper.Parent;
-            if (looper is Xamarin.Forms.View v)
+            if (looper is Microsoft.Maui.Controls.View v)
             {
                 absoluteX += v.X + v.Margin.Top;
                 absoluteY += v.Y + v.Margin.Left;
@@ -64,9 +64,12 @@ public static class ViewHelpers
 
 This can then be used when calling `RequstAsync`:
 
+<!-- TODO: I don't think this code works. I can't resolve Share.RequestAsync and there is a type mismatch on bounds.ToSystemRectangle and what is Analytics for? Is that normal to put in these examples? odd -->
+
 ```csharp
-public Command<Xamarin.Forms.View> ShareCommand { get; } = new Command<Xamarin.Forms.View>(Share);
-async void Share(Xamarin.Forms.View element)
+public Command<Microsoft.Maui.Controls.View> ShareCommand { get; } = new Command<Microsoft.Maui.Controls.View>(Share);
+
+async void Share(Microsoft.Maui.Controls.View element)
 {
     try
     {
diff --git a/docs/essentials/includes/tip-file-result.md b/docs/essentials/includes/tip-file-result.md
@@ -1,9 +1,7 @@
 ---
 ms.topic: include
-author: dimonovdd
-ms.author: jamont
-ms.date: 04/16/2020
+ms.date: 08/04/2021
 ---
 
 > [!TIP]
-> The `FullPath` property does not always return the physical path to the file. To get the file, use the `OpenReadAsync` method.
+> The `FullPath` property doesn't always return the physical path to the file. To get the file, use the `OpenReadAsync` method.
diff --git a/docs/essentials/includes/xamarin-show-essentials.md b/docs/essentials/includes/xamarin-show-essentials.md
diff --git a/docs/essentials/launcher.md b/docs/essentials/launcher.md
@@ -119,9 +119,3 @@ No platform differences.
 
 - [Launcher source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Launcher)
 - [Launcher API documentation](xref:Xamarin.Essentials.Launcher)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Launcher-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/main-thread.md b/docs/essentials/main-thread.md
@@ -111,9 +111,3 @@ The `MainThread` class includes the following additional `static` methods that c
 
 - [MainThread source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/MainThread)
 - [MainThread API documentation](xref:Xamarin.Essentials.MainThread)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Main-Thread-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/maps.md b/docs/essentials/maps.md
@@ -153,9 +153,3 @@ No platform-specific implementation details.
 
 - [Map source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Map)
 - [Map API documentation](xref:Xamarin.Essentials.Map)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Maps-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/open-browser.md b/docs/essentials/open-browser.md
@@ -129,9 +129,3 @@ The user's default browser will always be launched regardless of the `BrowserLau
 
 - [Browser source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Browser)
 - [Browser API documentation](xref:Xamarin.Essentials.Browser)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Open-Browser-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/permissions.md b/docs/essentials/permissions.md
@@ -266,10 +266,3 @@ Read more on the [App Capability Declaration](/windows/uwp/packaging/app-capabil
 
 - [Permissions source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Permissions)
 - [Permissions API documentation](xref:Xamarin.Essentials.Permissions)
-
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Permissions-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/phone-dialer.md b/docs/essentials/phone-dialer.md
@@ -80,9 +80,3 @@ public class PhoneDialerTest
 
 - [Phone Dialer source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/PhoneDialer)
 - [Phone Dialer API documentation](xref:Xamarin.Essentials.PhoneDialer)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Phone-Dialer-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/preferences.md b/docs/essentials/preferences.md
@@ -112,9 +112,3 @@ When storing a string, this API is intended to store small amounts of text. Perf
 
 - [Preferences source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Preferences)
 - [Preferences API documentation](xref:Xamarin.Essentials.Preferences)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Preferences-Essential-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/secure-storage.md b/docs/essentials/secure-storage.md
@@ -166,9 +166,3 @@ This API is intended to store small amounts of text.  Performance may be slow if
 
 - [SecureStorage source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/SecureStorage)
 - [SecureStorage API documentation](xref:Xamarin.Essentials.SecureStorage)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Secure-Storage-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/share.md b/docs/essentials/share.md
@@ -138,9 +138,3 @@ await Share.RequestAsync(new ShareMultipleFilesRequest
 
 - [Share source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Share)
 - [Share API documentation](xref:Xamarin.Essentials.Share)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/Share-Essential-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/sms.md b/docs/essentials/sms.md
@@ -103,9 +103,3 @@ public class SmsTest
 
 - [Sms source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Sms)
 - [Sms API documentation](xref:Xamarin.Essentials.Sms)
-
-## Related Video
-
-> [!Video https://channel9.msdn.com/Shows/XamarinShow/SMS-XamarinEssentials-API-of-the-Week/player]
-
-[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)]
diff --git a/docs/essentials/text-to-speech.md b/docs/essentials/text-to-speech.md
diff --git a/docs/essentials/unit-converters.md b/docs/essentials/unit-converters.md
diff --git a/docs/essentials/version-tracking.md b/docs/essentials/version-tracking.md
diff --git a/docs/essentials/vibrate.md b/docs/essentials/vibrate.md
