From 1efa4385ea9d73a747e02b136d9d2721b14413a8 Mon Sep 17 00:00:00 2001 From: Andy De George Date: Tue, 3 Aug 2021 16:55:16 -0700 Subject: [PATCH 1/2] First two articles ported --- docs/essentials/accelerometer.md | 44 ++++++--------- docs/essentials/app-actions.md | 71 ++++++++++++------------ docs/essentials/includes/get-started.md | 6 +- docs/essentials/includes/sensor-speed.md | 5 +- 4 files changed, 58 insertions(+), 68 deletions(-) diff --git a/docs/essentials/accelerometer.md b/docs/essentials/accelerometer.md index 99431b65e..474b922a9 100644 --- a/docs/essentials/accelerometer.md +++ b/docs/essentials/accelerometer.md @@ -1,16 +1,13 @@ --- -title: "Xamarin.Essentials: Accelerometer" -description: "The Accelerometer class in Xamarin.Essentials lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in three dimensional space." -author: jamesmontemagno -ms.author: jamont -ms.date: 04/02/2019 -ms.custom: video -no-loc: [Xamarin.Forms, Xamarin.Essentials] +title: "Essentials: Accelerometer" +description: "The Accelerometer class in Microsoft.Maui.Essentials lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in 3D space." +ms.date: 08/02/2021 +no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials", "A", "G", "X", "Y", "Z"] --- -# Xamarin.Essentials: Accelerometer +# Accelerometer -The **Accelerometer** class lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in three-dimensional space. +The class lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in 3D space. The `Accelerometer` class is part of the .NET MAUI Essentials library that is included with the .NET MAUI Workload. ## Get started @@ -18,16 +15,15 @@ The **Accelerometer** class lets you monitor the device's accelerometer sensor, ## Using Accelerometer -Add a reference to Xamarin.Essentials in your class: +Add a reference to the `Microsoft.Maui.Essentials` namespace in your class: ```csharp -using Xamarin.Essentials; +using Microsoft.Maui.Essentials; ``` -The Accelerometer functionality works by calling the `Start` and `Stop` methods to listen for changes to the acceleration. Any changes are sent back through the `ReadingChanged` event. Here is sample usage: +The accelerometer functionality works by calling the and methods to listen for changes to the acceleration. Any changes are sent back through the event. Here's a sample of using the accelerometer: ```csharp - public class AccelerometerTest { // Set speed delay for monitoring changes. @@ -67,29 +63,23 @@ public class AccelerometerTest } ``` -Accelerometer readings are reported back in G. A G is a unit of gravitation force equal to that exerted by the earth's gravitational field (9.81 m/s^2). +Accelerometer readings are reported back in **G**. A **G** is a unit of gravitation force equal to the gravity exerted by the earth's gravitational field $(9.81 m/s^2)$. -The coordinate-system is defined relative to the screen of the phone in its default orientation. The axes are not swapped when the device's screen orientation changes. +The coordinate-system is defined relative to the screen of the device in its default orientation. The axes aren't swapped when the device's screen orientation changes. -The X axis is horizontal and points to the right, the Y axis is vertical and points up and the Z axis points towards the outside of the front face of the screen. In this system, coordinates behind the screen have negative Z values. +The **X** axis is horizontal and points to the right, the **Y** axis is vertical and points up and the **Z** axis points towards the outside of the front face of the screen. In this system, coordinates behind the screen have negative **Z** values. Examples: -- When the device lies flat on a table and is pushed on its left side toward the right, the x acceleration value is positive. +- When the device lies flat on a table and is pushed on its left side toward the right, the **X** acceleration value is positive. -- When the device lies flat on a table, the acceleration value is +1.00 G or (+9.81 m/s^2), which correspond to the acceleration of the device (0 m/s^2) minus the force of gravity (-9.81 m/s^2) and normalized as in G. +- When the device lies flat on a table, the acceleration value is +1.00 G or $(+9.81 m/s^2)$, which correspond to the acceleration of the device $(0 m/s^2)$ minus the force of gravity $(-9.81 m/s^2)$ and normalized as in G. -- When the device lies flat on a table and is pushed toward the sky with an acceleration of A m/s^2, the acceleration value is equal to A+9.81 which corresponds to the acceleration of the device (+A m/s^2) minus the force of gravity (-9.81 m/s^2) and normalized in G. +- When the device lies flat on a table and is pushed toward the sky with an acceleration of **A** $m/s^2$, the acceleration value is equal to $A+9.81$ which corresponds to the acceleration of the device $(+A m/s^2)$ minus the force of gravity $(-9.81 m/s^2)$ and normalized in **G**. [!INCLUDE [sensor-speed](includes/sensor-speed.md)] ## API -- [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/Accelerometer-XamarinEssentials-API-of-the-Week/player] - -[!INCLUDE [xamarin-show-essentials](includes/xamarin-show-essentials.md)] +- [Accelerometer source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/Accelerometer) +- [Accelerometer API documentation](xref:Microsoft.Maui.Essentials.Accelerometer) diff --git a/docs/essentials/app-actions.md b/docs/essentials/app-actions.md index 67a5438d4..354ac6f2f 100644 --- a/docs/essentials/app-actions.md +++ b/docs/essentials/app-actions.md @@ -1,33 +1,32 @@ --- -title: "Xamarin.Essentials: App Actions" -description: "The Accelerometer class in Xamarin.Essentials lets you create and respond to app shortcuts from the app icon." -author: jamesmontemagno -ms.author: jamont -ms.date: 01/04/2021 -no-loc: [Xamarin.Forms, Xamarin.Essentials] +title: "Essentials: App Actions" +description: "The AppActions class in Microsoft.Maui.Essentials lets you create and respond to app shortcuts from the app icon." +ms.date: 08/02/2021 +no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials", "AppDelegate.cs", "AppActions"] --- -# Xamarin.Essentials: App Actions +# App Actions -The **AppActions** class lets you create and respond to app shortcuts from the app icon. +The class lets you create and respond to app shortcuts from the app icon. App shortcuts are helpful to users because they allow you, as the app developer, to present them with additional ways of starting your app. For example, if you were developing an email and calendar app, you could present two different app actions, one to open the app directly to the current day of the calendar, and another to open to the email inbox folder. ## Get started [!INCLUDE [get-started](includes/get-started.md)] -To access the **AppActions** functionality the following platform specific setup is required. +To access the `AppActions` functionality the following platform specific setup is required. # [Android](#tab/android) Add the intent filter to your `MainActivity` class: ```csharp -[IntentFilter( - new[] { Xamarin.Essentials.Platform.Intent.ActionAppAction }, - Categories = new[] { Android.Content.Intent.CategoryDefault })] -public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity +[IntentFilter(new[] { Microsoft.Maui.Essentials.Platform.Intent.ActionAppAction }, + Categories = new[] { Android.Content.Intent.CategoryDefault })] +[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize)] +public class MainActivity : MauiAppCompatActivity { ... +} ``` Then add the following logic to handle actions: @@ -37,24 +36,24 @@ protected override void OnResume() { base.OnResume(); - Xamarin.Essentials.Platform.OnResume(this); + Microsoft.Maui.Essentials.Essentials.Platform.OnResume(this); } protected override void OnNewIntent(Android.Content.Intent intent) { base.OnNewIntent(intent); - Xamarin.Essentials.Platform.OnNewIntent(intent); + Microsoft.Maui.Essentials.Platform.OnNewIntent(intent); } ``` # [iOS](#tab/ios) -In the `AppDelegate.cs` add the following logic to handle actions: +In the _AppDelegate.cs_ add the following logic to handle actions: ```csharp public override void PerformActionForShortcutItem(UIApplication application, UIApplicationShortcutItem shortcutItem, UIOperationHandler completionHandler) - => Xamarin.Essentials.Platform.PerformActionForShortcutItem(application, shortcutItem, completionHandler); + => Microsoft.Maui.Essentials.Platform.PerformActionForShortcutItem(application, shortcutItem, completionHandler); ``` # [UWP](#tab/uwp) @@ -62,20 +61,25 @@ public override void PerformActionForShortcutItem(UIApplication application, UIA In the `App.xaml.cs` file in the `OnLaunched` method add the following logic at the bottom of the method: ```csharp -Xamarin.Essentials.Platform.OnLaunched(e); +protected override void OnLaunched(LaunchActivatedEventArgs args) +{ + // ... other code + + Microsoft.Maui.Essentials.Platform.OnLaunched(args); +} ``` ----- -## Create Actions +## Create actions -Add a reference to Xamarin.Essentials in your class: +Add a reference to the `Microsoft.Maui.Essentials` namespace in your class: ```csharp -using Xamarin.Essentials; +using Microsoft.Maui.Essentials; ``` -App Actions can be created at any time, but are often created when an application starts. Call the `SetAsync` method to create the list of actions for your app. +App Actions can be created at any time, but are often created when an application starts. Call the `SetAsync` method to create the list of actions for your app. ```csharp try @@ -90,18 +94,18 @@ catch (FeatureNotSupportedException ex) } ``` -If App Actions are not supported on the specific version of the operating system a `FeatureNotSupportedException` will be thrown. +If App Actions aren't supported on the specific version of the operating system a `FeatureNotSupportedException` will be thrown. The following properties can be set on an `AppAction`: -* Id: A unique identifier used to respond to the action tap. -* Title: the visible title to display. -* Subtitle: If supported a sub-title to display under the title. -* Icon: Must match icons in the corresponding resources directory on each platform. +- **Id**: A unique identifier used to respond to the action tap. +- **Title**: the visible title to display. +- **Subtitle**: If supported a sub-title to display under the title. +- **Icon**: Must match icons in the corresponding resources directory on each platform. -![App Actions on Homescreen.](images/appactions.png) +:::image type="content" source="images/appactions.png" alt-text="App actions on home screen"::: -## Responding To Actions +## Responding to actions When your application starts register for the `OnAppAction` event. When an app action is selected the event will be sent with information as to which action was selected. @@ -129,13 +133,10 @@ void AppActions_OnAppAction(object sender, AppActionEventArgs e) ``` ## GetActions + You can get the current list of App Actions by calling `AppActions.GetAsync()`. ## API -- [AppActions source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/AppActions) -- [AppActions API documentation](xref:Xamarin.Essentials.AppActions) - -## Related Video - -> [!Video https://channel9.msdn.com/Shows/XamarinShow/App-Actions-XamarinEssentials-API-of-the-Week/player] \ No newline at end of file +- [AppActions source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/AppActions) +- [AppActions API documentation](xref:Microsft.Maui.Essentials.AppActions) diff --git a/docs/essentials/includes/get-started.md b/docs/essentials/includes/get-started.md index f8372a99d..2fff8faf6 100644 --- a/docs/essentials/includes/get-started.md +++ b/docs/essentials/includes/get-started.md @@ -1,7 +1,5 @@ --- ms.topic: include -author: jamesmontemagno -ms.author: jamont -ms.date: 10/31/2018 +ms.date: 08/02/2021 --- -To start using this API, read the [getting started](~/essentials/get-started.md) guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects. +To start using this API, read the [getting started](../get-started.md) guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects. diff --git a/docs/essentials/includes/sensor-speed.md b/docs/essentials/includes/sensor-speed.md index 638dd9f83..cf642bfa8 100644 --- a/docs/essentials/includes/sensor-speed.md +++ b/docs/essentials/includes/sensor-speed.md @@ -1,11 +1,12 @@ --- ms.topic: include +ms.date: 08/02/2021 --- -## [Sensor Speed](xref:Xamarin.Essentials.SensorSpeed) +## [Sensor Speed](xref:Microsoft.Maui.Essentials.SensorSpeed) - **Fastest** – Get the sensor data as fast as possible (not guaranteed to return on UI thread). - **Game** – Rate suitable for games (not guaranteed to return on UI thread). - **Default** – Default rate suitable for screen orientation changes. - **UI** – Rate suitable for general user interface. -If your event handler is not guaranteed to run on the UI thread, and if the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](~/essentials/main-thread.md) method to run that code on the UI thread. +If your event handler is not guaranteed to run on the UI thread, and if the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](../main-thread.md) method to run that code on the UI thread. From 00657562bce45d77421d2b63104c5bd10bebe23b Mon Sep 17 00:00:00 2001 From: Andy De George Date: Wed, 4 Aug 2021 13:01:14 -0700 Subject: [PATCH 2/2] Feedback --- docs/essentials/accelerometer.md | 6 +++--- docs/essentials/app-actions.md | 15 +++++++++------ docs/essentials/includes/get-started.md | 3 ++- docs/essentials/includes/sensor-speed.md | 3 ++- 4 files changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/essentials/accelerometer.md b/docs/essentials/accelerometer.md index 474b922a9..07aea0f4d 100644 --- a/docs/essentials/accelerometer.md +++ b/docs/essentials/accelerometer.md @@ -7,7 +7,7 @@ no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials", "A", "G", "X", "Y", "Z"] # Accelerometer -The class lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in 3D space. The `Accelerometer` class is part of the .NET MAUI Essentials library that is included with the .NET MAUI Workload. +The `Microsoft.Maui.Essentials.Accelerometer` class lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in 3D space. ## Get started @@ -21,7 +21,7 @@ Add a reference to the `Microsoft.Maui.Essentials` namespace in your class: using Microsoft.Maui.Essentials; ``` -The accelerometer functionality works by calling the and methods to listen for changes to the acceleration. Any changes are sent back through the event. Here's a sample of using the accelerometer: +The accelerometer functionality works by calling the `Start` and `Stop` methods to listen for changes to the acceleration. Any changes are sent back through the `ReadingChanged` event. Here's a sample of using the accelerometer: ```csharp public class AccelerometerTest @@ -82,4 +82,4 @@ Examples: ## API - [Accelerometer source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/Accelerometer) -- [Accelerometer API documentation](xref:Microsoft.Maui.Essentials.Accelerometer) + diff --git a/docs/essentials/app-actions.md b/docs/essentials/app-actions.md index 354ac6f2f..3ba70210a 100644 --- a/docs/essentials/app-actions.md +++ b/docs/essentials/app-actions.md @@ -7,7 +7,7 @@ no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials", "AppDelegate.cs", "AppAc # App Actions -The class lets you create and respond to app shortcuts from the app icon. App shortcuts are helpful to users because they allow you, as the app developer, to present them with additional ways of starting your app. For example, if you were developing an email and calendar app, you could present two different app actions, one to open the app directly to the current day of the calendar, and another to open to the email inbox folder. +The `Microsoft.Maui.Essentials.AppActions` class lets you create and respond to app shortcuts from the app icon. App shortcuts are helpful to users because they allow you, as the app developer, to present them with additional ways of starting your app. For example, if you were developing an email and calendar app, you could present two different app actions, one to open the app directly to the current day of the calendar, and another to open to the email inbox folder. ## Get started @@ -15,6 +15,8 @@ The class lets you create and respon To access the `AppActions` functionality the following platform specific setup is required. + + # [Android](#tab/android) Add the intent filter to your `MainActivity` class: @@ -22,7 +24,6 @@ Add the intent filter to your `MainActivity` class: ```csharp [IntentFilter(new[] { Microsoft.Maui.Essentials.Platform.Intent.ActionAppAction }, Categories = new[] { Android.Content.Intent.CategoryDefault })] -[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize)] public class MainActivity : MauiAppCompatActivity { ... @@ -36,7 +37,7 @@ protected override void OnResume() { base.OnResume(); - Microsoft.Maui.Essentials.Essentials.Platform.OnResume(this); + Microsoft.Maui.Essentials.Platform.OnResume(this); } protected override void OnNewIntent(Android.Content.Intent intent) @@ -56,7 +57,7 @@ public override void PerformActionForShortcutItem(UIApplication application, UIA => Microsoft.Maui.Essentials.Platform.PerformActionForShortcutItem(application, shortcutItem, completionHandler); ``` -# [UWP](#tab/uwp) +# [Windows](#tab/windows) In the `App.xaml.cs` file in the `OnLaunched` method add the following logic at the bottom of the method: @@ -71,6 +72,8 @@ protected override void OnLaunched(LaunchActivatedEventArgs args) ----- + + ## Create actions Add a reference to the `Microsoft.Maui.Essentials` namespace in your class: @@ -103,7 +106,7 @@ The following properties can be set on an `AppAction`: - **Subtitle**: If supported a sub-title to display under the title. - **Icon**: Must match icons in the corresponding resources directory on each platform. -:::image type="content" source="images/appactions.png" alt-text="App actions on home screen"::: +:::image type="content" source="images/appactions.png" alt-text="App actions on home screen."::: ## Responding to actions @@ -139,4 +142,4 @@ You can get the current list of App Actions by calling `AppActions.GetAsync()`. ## API - [AppActions source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/AppActions) -- [AppActions API documentation](xref:Microsft.Maui.Essentials.AppActions) + diff --git a/docs/essentials/includes/get-started.md b/docs/essentials/includes/get-started.md index 2fff8faf6..656ba8586 100644 --- a/docs/essentials/includes/get-started.md +++ b/docs/essentials/includes/get-started.md @@ -2,4 +2,5 @@ ms.topic: include ms.date: 08/02/2021 --- -To start using this API, read the [getting started](../get-started.md) guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects. + +To start using this API, read the [getting started](../get-started.md) guide for .NET MAUI Essentials to make sure it's correctly configured for your target platform. diff --git a/docs/essentials/includes/sensor-speed.md b/docs/essentials/includes/sensor-speed.md index cf642bfa8..d27feda96 100644 --- a/docs/essentials/includes/sensor-speed.md +++ b/docs/essentials/includes/sensor-speed.md @@ -2,7 +2,8 @@ ms.topic: include ms.date: 08/02/2021 --- -## [Sensor Speed](xref:Microsoft.Maui.Essentials.SensorSpeed) + +## Sensor Speed - **Fastest** – Get the sensor data as fast as possible (not guaranteed to return on UI thread). - **Game** – Rate suitable for games (not guaranteed to return on UI thread).