Merge pull request #8902 from MicrosoftDocs/u/anuitz/mobilenative

Optimize for devices documentation

Author: sericks007

powerapps-docs/maker/TOC.yml

@@ -1785,6 +1785,12 @@
     href: ../mobile/scan-QR-code.md
   - name: Switch to a different directory in the Power Apps mobile app
     href: ../mobile/tenant-switcher.md
+  - name: Optimize canvas app screens for devices
+    items:
+    - name: Optimize for devices overview (preview)
+      href: ../mobile/optimize-for-devices-overview.md
+    - name: Optimize for devices controls (preview)
+      href: ../mobile/optimize-for-devices-controls.md
   - name: Mobile offline for model-driven apps
     items:
     - name: Mobile offline overview
@@ -2641,4 +2647,4 @@
   - name: Troubleshoot Power Query
     href: /troubleshoot/power-platform/power-apps/troubleshoot-power-query-issues
   - name: Support
-    href: https://powerapps.microsoft.com/support/
+    href: https://powerapps.microsoft.com/support/

powerapps-docs/mobile/media/optimized-for-devices-app-setting.PNG

@@ -0,0 +1,89 @@
+---
+title: Optimize for devices controls (preview)
+description: Learn which controls and properties are supported for device-optimized screens.
+author: anuitz
+ms.topic: conceptual
+ms.custom: canvas
+ms.reviewer: sericks
+ms.date: 11/14/2023
+ms.subservice: canvas-maker
+ms.author: anuitz
+search.audienceType: 
+  - maker
+contributors:
+  - sericks
+  - anuitz
+---
+
+# Optimize for devices controls (preview)
+[This article is prerelease documentation and is subject to change.]
+
+For a screen to be optimized for devices, it must use controls that are supported natively. You can filter the control **Insert** pane to only show device-optimized controls. 
+
+:::image type="content" source="media/optimized-for-devices-control-filter.png" alt-text="The Insert pane is filtered to only show controls that are device-optimized.":::
+
+> [!Important]
+> - This is a preview feature.
+> - Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.
+
+## Device-optimized controls
+The following controls are available for screens that are optimized for devices. All other controls are currently unsupported.
+
+[**Modern controls**](../maker/canvas-apps/controls/modern-controls/modern-controls-reference.md)
+ - Button
+ - Checkbox
+ - Date picker
+ - Form
+ - Text
+ - Text input
+ - Toggle
+
+ [**Controls**](../maker/canvas-apps/reference-properties.md)
+ - Add picture
+ - Barcode reader
+ - Button
+ - Camera
+ - Check box
+ - Circle
+ - Container (horizontal and vertical included)
+ - Form (edit and display)
+ - Gallery (vertical, horizontal, flexible height)
+ - Icon (all icons supported)
+ - Image
+ - Radio
+ - Rectangle
+ - Text input
+ - Text label
+ - Timer
+
+## Unsupported controls
+
+If a screen is set to be optimized for devices, but has an unsupported control, an error message in a box is displayed. 
+
+:::image type="content" source="media/optimized-for-devices-control-error.png" alt-text="The error that shows when an unsupported control is on a screen set to optimize for devices.":::
+
+## Device-optimized properties
+
+Some properties must be specifically configured to be optimized for devices. For example, consider the [barcode reader](../maker/canvas-apps/controls/control-barcodereader.md) control. The maker can select **Scan Inline** for the **Scanning mode** property. In Power Apps Studio, when this mode is selected, the control displays as a warning box indicating the control only works on mobile devices. On a device, in a screen optimized for devices, the control displays a camera feed to enable barcode scanning.
+
+## Known limitations
+
+Note the following limitations with the optimize for devices feature.
+
+ - Only the **Segoe UI** font is supported. If a control is using another font, it displays the Segoe UI font, instead. Due to the differences in fonts, this can result in the control taking up more or less space than expected. We recommend that you use the Segoe UI font for device-optimized screens.
+ - The **Image** control, when showing an SVG, only supports the fit and stretch image position options. Its default behavior is to fit, if another option is selected. All other image types work as expected for all image positions. 
+ - In the **modern Text** control, the **Semi-bold** and **Medium** font weights aren't supported on Android devices. It displays a regular font weight, instead.
+ - In the **modern Text input** control, the **Value** property, when set to a Power Fx variable, isn't displayed at first navigation. Instead, it shows the placeholder value until the user navigates away and back to the screen with the **modern Text input** control.
+ - In the **modern Text input** control, the **OnChange** property is called twice when the control is exited, and then blurred.
+ - In the **modern Text input** control, the **Validate state** property doesn't display a red border around the control. 
+ - In the **Image** control, the **Image rotation** property isn't supported. The image isn't rotated.
+ - In the **Dropdown** and **Radio** control, the **Items** property doesn't support references to other controls. Items aren't shown if they're complex values, like references. 
+ - In the **modern Date picker** control, tapping on the control opens a modal with a calendar, instead of allowing users to type into the control directly. 
+ - In the **modern Date picker** control, the **Base palette color** and modern theme aren't applied on Android devices. Instead, it displays as the device's theme color.
+ - In the **Button**, **Image**, **Label**, and **Icon** controls, the **SetFocus** Power Fx function doesn't support keyboard focus, only accessibility focus (for example, screen reader).
+ - In **Horizontal and vertical containers**, the **Drop shadow** property isn't supported. Instead, containers display without drop shadow. 
+ - In **Horizontal and vertical containers**, the **Scroll** option only works for a single direction, depending on the **Wrap** property. If **Wrap** is off, the container is scrollable in the primary direction, otherwise it's scrollable in the secondary direction. 
+ - Multiple **Barcode reader** controls on a single screen aren't supported.
+ - Multiple **Camera** controls on a single screen isn't supported. 
+ - In the **Camera** control, the **Display mode** property of the parent control isn't supported. For example, if the camera control is part of a form that is set to view mode, the camera might still be in edit mode. 
+ - On **Screen**, the **Background image** property isn't supported.

powerapps-docs/mobile/media/optimized-for-devices-control-error.PNG

@@ -0,0 +1,55 @@
+---
+title: Optimize for devices overview (preview)
+description: Learn how to make your canvas app screens optimized for devices. 
+author: anuitz
+ms.topic: conceptual
+ms.custom: canvas
+ms.reviewer: sericks
+ms.date: 11/14/2023
+ms.subservice: canvas-maker
+ms.author: anuitz
+search.audienceType: 
+  - maker
+contributors:
+  - sericks
+  - anuitz
+---
+
+# Optimize for devices overview (preview)
+[This article is prerelease documentation and is subject to change.]
+
+_Optimize for devices_ is a feature that changes the way canvas app screens are loaded and displayed for Android and iOS devices to use native UI. This lets makers build stunning native apps for mobile users with device-optimized screens that use native UI elements instead of rendering inside of web view. This feature provides the following benefits:
+
+ - Brings modern mobile user experiences and interaction patterns
+ - Improves performance and reliability
+ - Integrates device capabilities with maker defined UI
+
+There's no need to rebuild apps as makers can use all the familiar app building elements to create device-optimized experiences, though there are some limitations around which [controls are supported natively today](./optimize-for-devices-controls.md). Apps that are optimized for device work with other mobile features like [offline](./canvas-mobile-offline-overview.md), [push notifications](./power-apps-mobile-notification.md), and [wrap](../maker/common/wrap/overview.md).
+
+> [!Important]
+> - This is a preview feature.
+> - Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.
+
+## How screens are optimized for devices
+
+For a canvas app running on Power Apps mobile, there are UI elements, their current state, and the related business logic. For example, on screen you might have a button that is currently at position 0, with a width and height of 200 and 40 respectively, and is fill color blue on top of having business logic defined on select with Power Fx that navigates the user to a different screen.
+
+If optimize for devices is off for that screen, the screen loads and the displays in a web view, running similarly to how it would in a desktop's web browser. When optimized for devices is on, each element's current state is passed over to the device where it renders that same element, but using native UI. So now we have a natively rendered, long blue button in the top-left corner. Business logic modifies state or takes actions, which run the same way it did before, meaning when that now natively rendered button is clicked on, the device runs Power Fx and the user is navigated to the specified screen.
+
+What this means is that each [control needs a device-optimized](./optimize-for-devices-controls.md), native equivalent that supports the same properties so it can render the way a maker expects. During preview, there are some [limitations](optimize-for-devices-controls.md#known-limitations) to which controls and properties are supported. This is independent of whether a control is classic or modern, but rather a filter on the list of controls to ones that are device-optimized. 
+
+## Enable screens to be device-optimized
+
+There are two steps to enabling a screen to be optimized for devices.
+
+1. The **Optimize for devices** experimental app setting must be turned on.
+
+    The setting can be found in **Settings** > **Upcoming features** > **Experimental** tab. Turning on the **Optimize for devices** app setting shows the **Optimize for devices** property on screens.
+
+    :::image type="content" source="media/optimized-for-devices-app-setting.png" alt-text="Shows the app setting that enables Optimize for devices.":::
+
+2. On each screen, the **Optimize for devices** property must be set to **On**.
+
+    A maker can open the tree view in the left-hand pane and select a screen where the **Optimize for devices** property will be. By setting this property to **On**, the screen will be rendered natively when running on Power Apps mobile in iOS and Android devices. 
+
+    :::image type="content" source="media/optimized-for-devices-screen-setting.png" alt-text="Shows the screen setting that sets that screen to display natively.":::