Add essentials content

.gitignore

@@ -1,9 +1,11 @@
 log/
+bin/
 obj/
 _site/
 .optemp/
 _themes*/
 _repo.*/
+.vs/
 
 .openpublishing.buildcore.ps1
 .DS_Store

docs/TOC.yml

@@ -413,6 +413,84 @@
           href: user-interface/visual-states.md
     - name: Platform integration
       items:
+        - name: Application model
+          items:
+          - name: App actions
+            href: platform-integration/appmodel/app-actions.md
+          - name: App information
+            href: platform-integration/appmodel/app-information.md
+          - name: Browser
+            href: platform-integration/appmodel/open-browser.md
+          - name: Launcher
+            href: platform-integration/appmodel/launcher.md
+          - name: Main thread
+            href: platform-integration/appmodel/main-thread.md
+          - name: Maps
+            href: platform-integration/appmodel/maps.md
+          - name: Permissions
+            href: platform-integration/appmodel/permissions.md
+          - name: Version tracking
+            href: platform-integration/appmodel/version-tracking.md
+        - name: Communication
+          items:
+          - name: Contacts
+            href: platform-integration/communication/contacts.md
+          - name: Email
+            href: platform-integration/communication/email.md
+          - name: Networking
+            href: platform-integration/communication/networking.md
+          - name: Phone dialer
+            href: platform-integration/communication/phone-dialer.md
+          - name: SMS (messaging)
+            href: platform-integration/communication/sms.md
+          - name: Web authentication
+            href: platform-integration/communication/authentication.md
+        - name: Device features
+          items:
+          - name: Battery
+            href: platform-integration/device/battery.md
+          - name: Device display
+            href: platform-integration/device/display.md
+          - name: Device information
+            href: platform-integration/device/information.md
+          - name: Device sensors
+            href: platform-integration/device/sensors.md
+          - name: Flashlight
+            href: platform-integration/device/flashlight.md
+          - name: Geocoding
+            href: platform-integration/device/geocoding.md
+          - name: Geolocation
+            href: platform-integration/device/geolocation.md
+          - name: Haptic feedback
+            href: platform-integration/device/haptic-feedback.md
+          - name: Vibration
+            href: platform-integration/device/vibrate.md
+        - name: Media
+          items:
+          - name: Photo picker
+            href: platform-integration/device-media/picker.md
+          - name: Screenshot
+            href: platform-integration/device-media/screenshot.md
+          - name: Text-to-speech
+            href: platform-integration/device-media/text-to-speech.md
+          - name: Unit converters
+            href: platform-integration/device-media/unit-converters.md
+        - name: Sharing
+          items:
+          - name: Clipboard
+            href: platform-integration/data/clipboard.md
+          - name: Share files and text
+            href: platform-integration/data/share.md
+        - name: Storage
+          items:
+          - name: File picker
+            href: platform-integration/storage/file-picker.md
+          - name: File system helpers
+            href: platform-integration/storage/file-system-helpers.md
+          - name: Preferences
+            href: platform-integration/storage/preferences.md
+          - name: Secure storage
+            href: platform-integration/storage/secure-storage.md
         - name: Configure multi-targeting
           href: platform-integration/configure-multi-targeting.md
         - name: Invoke platform code

docs/fundamentals/accessibility.md

@@ -176,13 +176,17 @@ label.SetSemanticFocus();
 
 ## Semantic screen reader
 
-.NET MAUI Essentials includes a `SemanticScreenReader` class that enables you to instruct a screen reader to announce specified text. This can be achieved by calling the `SemanticScreenReader.Announce` method, passing a `string` argument that represents the text:
+.NET Maui provides the `ISemanticScreenReader` interface, with which you can instruct a screen reader to announce text to the user. The interface is exposed through the `SemanticScreenReader.Default` property, and is available in the `Microsoft.Maui.Accessability` namespace.
+
+To instruct a screen reader to announce text, use the `Announce` method, passing a `string` argument that represents the text. The following example demonstrates using this method:
 
 ```csharp
-SemanticScreenReader.Announce("This is the announcement text.");
+SemanticScreenReader.Default.Announce("This is the announcement text.");
 ```
 
-<!-- For more information, see [SemanticScreenReader]().-->
+### Limitations
+
+The default platform screen reader must be enabled for text to be read aloud.
 
 <!--
 ### Semantic effects

docs/index.yml

@@ -16,8 +16,6 @@ landingContent:
         links:
           - text: What is .NET Multi-platform App UI?
             url: what-is-maui.md
-          - text: Supported platforms
-            url: supported-platforms.md
   - title: Get started
     linkLists:
       - linkListType: how-to-guide

docs/platform-integration/appmodel/app-actions.md

@@ -0,0 +1,88 @@
+---
+title: "App actions (shortcuts)"
+description: "Describes the IAppActions interface in the Microsoft.Maui.ApplicationModel namespace, which lets you create and respond to app shortcuts from the app icon."
+ms.date: 05/23/2022
+no-loc: ["Microsoft.Maui", "Microsoft.Maui.ApplicationModel", "AppDelegate.cs", "AppActions", "Platforms/Android/MainActivity.cs", "Platforms/iOS/AppDelegate.cs", "Platforms/Windows/App.xaml.cs", "Id", "Title", "Subtitle", "Icon"]
+---
+
+# App actions
+
+This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) `IAppActions` interface, which lets you create and respond to app shortcuts. App shortcuts are helpful to users because they allow you, as the app developer, to present them with extra 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.
+
+[!INCLUDE [docs under construction](~/includes/preview-note.md)]
+
+The `IAppActions` interface is exposed through the `AppActions.Current` property, and is available in the `Microsoft.Maui.ApplicationModel` namespace.
+
+## Get started
+
+To access the `AppActions` functionality, the following platform specific setup is required.
+
+<!-- markdownlint-disable MD025 -->
+
+# [Android](#tab/android)
+
+In the _Platforms/Android/MainActivity.cs_ file, add the following `IntentFilter` attribute to the `MainActivity` class:
+
+:::code language="csharp" source="../snippets/shared_2/Platforms/Android/MainActivity.cs" id="intent_filter_1":::
+
+# [iOS](#tab/ios)
+
+No setup is required.
+
+# [Windows](#tab/windows)
+
+No setup is required.
+
+-----
+
+<!-- markdownlint-enable MD025 -->
+
+## Create actions
+
+App actions can be created at any time, but are often created when an app starts. To configure app actions, add the `ConfigureEssentials` step to the `CreateMauiApp` bootstrap code. The app startup code is configured in the _MauiProgram.cs_ file. There are two methods you must call to enable an app action:
+
+01. `AddAppAction`
+
+    This method creates an action. It takes an `id` string to uniquely identify the action, and a `title` string that's displayed to the user. You can optionally provide a subtitle and an icon.
+
+01. `OnAppAction`
+
+    The delegate passed to this method is called when the user invokes an app action, provided the app action instance. Check the `Id` property of the action to determine which app action was started by the user.
+
+The following code demonstrates how to configure the app actions at app startup:
+
+:::code language="csharp" source="../snippets/shared_1/MauiProgram.cs" id="bootstrap_appaction" highlight="12-18":::
+
+## Responding to actions
+
+After app actions [have been configured](#create-actions), the `OnAppAction` method is called for all app actions invoked by the user. Use the `Id` property to differentiate them. The following code demonstrates handling an app action:
+
+:::code language="csharp" source="../snippets/shared_1/App.xaml.cs" id="appaction_handle":::
+
+### Check if app actions are supported
+
+When you create an app action, either at app startup or while the app is being used, check to see if app actions are supported by reading the `AppActions.Current.IsSupported` property.
+
+### Create an app action outside of the startup bootstrap
+
+To create app actions, call the `SetAsync` method:
+
+:::code language="csharp" source="../snippets/shared_2/MainPage.xaml.cs" id="app_actions":::
+
+### More information about app actions
+
+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 subtitle to display under the title.
+- **Icon**: Must match icons in the corresponding resources directory on each platform.
+
+<!-- TODO icon in image needs update -->
+:::image type="content" source="media/app-actions/appactions.png" alt-text="App actions on home screen.":::
+
+## Get actions
+
+You can get the current list of app actions by calling `AppActions.Current.GetAsync()`.

docs/platform-integration/appmodel/app-information.md

@@ -0,0 +1,104 @@
+---
+title: "App Information"
+description: "Describes the IAppInfo interface in the Microsoft.Maui.ApplicationModel namespace, which provides information about your application. For example, it exposes the app name and version."
+ms.date: 05/23/2022
+no-loc: ["Microsoft.Maui", "Microsoft.Maui.ApplicationModel"]
+---
+
+# App information
+
+This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) `IAppInfo` interface, which provides information about your application. The `IAppInfo` interface is exposed through the `AppInfo.Current` property.
+
+[!INCLUDE [docs under construction](~/includes/preview-note.md)]
+
+The `AppInfo` and `IAppInfo` types are available in the `Microsoft.Maui.ApplicationModel` namespace.
+
+## Read the app information
+
+There are four properties exposed by the `IAppInfo` interface:
+
+- `IAppInfo.Name` — The application name
+- `IAppInfo.PackageName` — The package name or application identifier, such as `com.microsoft.myapp`.
+- `IAppInfo.VersionString` — The application version, such as `1.0.0`.
+- `IAppInfo.BuildString` — The build number of the version, such as `1000`.
+
+The following code example demonstrates accessing these properties:
+
+:::code language="csharp" source="../snippets/shared_1/AppModelPage.xaml.cs" id="read_info":::
+
+## Read the current theme
+
+The `RequestedTheme` property provides the current requested theme by the system for your application. One of the following values is returned:
+
+- `Unspecified`
+- `Light`
+- `Dark`
+
+`Unspecified` is returned when the operating system doesn't have a specific user interface style. An example of this is on devices running versions of iOS older than 13.0.
+
+The following code example demonstrates reading the theme:
+
+:::code language="csharp" source="../snippets/shared_1/AppModelPage.xaml.cs" id="read_theme":::
+
+## Display app settings
+
+The `IAppInfo` class can also display a page of settings maintained by the operating system for the application:
+
+:::code language="csharp" source="../snippets/shared_1/AppModelPage.xaml.cs" id="show_settings":::
+
+This settings page allows the user to change application permissions and perform other platform-specific tasks.
+
+## Platform implementation specifics
+
+This section describes platform-specific implementation details related to the `IAppInfo` interface.
+
+<!-- markdownlint-disable MD025 -->
+
+# [Android](#tab/android)
+
+App information is taken from the _AndroidManifest.xml_ for the following fields:
+
+- **Build** &mdash; `android:versionCode` in `manifest` node
+- **Name** &mdash; `android:label` in the `application` node
+- **PackageName** &mdash; `package` in the `manifest` node
+- **VersionString** &mdash; `android:versionName` in the `application` node
+
+### Requested theme
+
+Android uses configuration modes to specify the type of theme to request from the user. Based on the version of Android, it can be changed by the user or may be changed when battery saver mode is enabled.
+
+You can read more on the official [Android documentation for Dark Theme](https://developer.android.com/guide/topics/ui/look-and-feel/darktheme).
+
+# [iOS](#tab/ios)
+
+App information is taken from the _Info.plist_ for the following fields:
+
+- **Build** &mdash; `CFBundleVersion`
+- **Name** &mdash; `CFBundleDisplayName` if set, else `CFBundleName`
+- **PackageName** &mdash; `CFBundleIdentifier`
+- **VersionString** &mdash; `CFBundleShortVersionString`
+
+### Requested theme
+
+_Unspecified_ is always returned on versions of iOS older than 13.0
+
+# [Windows](#tab/windows)
+
+App information is taken from the _Package.appxmanifest_ for the following fields:
+
+- **Build** &mdash; Uses the `Build` from the `Version` on the `Identity` node
+- **Name** &mdash; `DisplayName` on the `Properties` node
+- **PackageName** &mdash; `Name` on the `Identity` node
+- **VersionString** &mdash; `Version` on the `Identity` node
+
+### Requested theme
+
+Code that accesses the `IAppInfo.RequestedTheme` property must be called on the UI thread or an exception will be thrown.
+
+Windows applications respect the `RequestedTheme` property setting in the Windows _App.xaml_. If it's set to a specific theme, this API always returns this setting. To use the dynamic theme of the OS, remove this property from your application. When your app is run, it returns the theme set by the user in Windows settings: **Settings** > **Personalization** > **Colors** > **Choose your default app mode**.
+
+<!-- TODO: You can read more on the [Windows Requested Theme Documentation](/uwp/api/windows.ui.xaml.application.requestedtheme). -->
+
+--------------
+
+<!-- markdownlint-enable MD025 -->