Merge pull request #1667 from MicrosoftDocs/master

Publish: add topic about the App object, including ConfirmExit

Author: AFTOwen

powerapps-docs/maker/TOC.yml

@@ -350,7 +350,7 @@
           - name: And
             href: ./canvas-apps/functions/function-logicals.md
           - name: App
-            href: ./canvas-apps/functions/signals.md
+            href: ./canvas-apps/functions/object-app.md
           - name: Asin
             href: ./canvas-apps/functions/function-trig.md
           - name: AsType

powerapps-docs/maker/canvas-apps/formula-reference.md

@@ -41,7 +41,7 @@ Other elements include:
 
 **[And](functions/function-logicals.md)** – Boolean logic AND.  Returns **true** if all arguments are **true**.  You can also use the [**&&** operator](functions/operators.md).
 
-**[App](functions/signals.md)** – Returns information about the currently running app, such as which screen is currently displayed.
+**[App](functions/object-app.md)** – Provides information about the currently running app and control over the app's behavior.
 
 **[Asin](functions/function-trig.md)** – Returns the arcsine of a number, in radians.
 

powerapps-docs/maker/canvas-apps/functions/media/appobject-runonstart.png

@@ -0,0 +1,119 @@
+---
+title: App object | Microsoft Docs
+description: Reference information, including syntax and examples, for the App object in PowerApps
+author: gregli-msft
+manager: kvivek
+ms.service: powerapps
+ms.topic: reference
+ms.custom: canvas
+ms.reviewer: anneta
+ms.date: 05/29/2019
+ms.author: gregli
+search.audienceType: 
+  - maker
+search.app: 
+  - PowerApps
+---
+# App object in PowerApps
+
+Provides information about the currently running app and control over the app's behavior.
+
+## Description
+
+Like a control, the **App** object provides properties that identify which screen is showing and that prompt the user to save changes so that they're not lost. Every app has an **App** object.
+
+You can write formulas for some properties of the **App** object. At the top of the **Tree view** pane, select the **App** object as you would any other control or screen. View and edit one of the object's properties by selecting it in the drop-down list to the left of the formula bar.
+
+> [!div class="mx-imgBorder"]
+> ![The App object in the Tree view pane](media/object-app/appobject.png)
+
+## ActiveScreen property
+
+The **ActiveScreen** property identifies the screen that's showing.
+
+This property returns a screen object, which you can use to reference properties of the screen or compare to another screen to determine which screen is showing. You can also use the expression **App.ActiveScreen.Name** to retrieve the name of the screen that's showing.
+
+Use the **[Back](function-navigate.md)** or **[Navigate](function-navigate.md)** function to change the screen that's showing.
+
+## OnStart property
+
+The **OnStart** property runs when the user starts the app. App makers often use this property to perform these tasks:
+
+- Retrieve and cache data into collections by using the **[Collect](function-clear-collect-clearcollect.md)** function.
+- Set up global variables by using the **[Set](function-set.md)** function.
+- Navigate to an initial screen by using the **[Navigate](function-navigate.md)** function.
+
+This formula is evaluated before the first screen appears. No screen is loaded, so you can't set context variables with the **[UpdateContext](function-updatecontext.md)** function. However, you can pass context variables with the **Navigate** function.
+
+After you change the **OnStart** property, test it by hovering over the **App** object in the **Tree view** pane, selecting the ellipsis (...) that appears, and then selecting **Run OnStart**. Unlike when the app is loaded for the first time, existing collections and variables will already be set. To start with empty collections, use the **[ClearCollect](function-clear-collect-clearcollect.md)** function instead of the **Collect** function.
+
+> [!div class="mx-imgBorder"]
+> ![App-item shortcut menu for Run OnStart](media/object-app/appobject-runonstart.png)
+
+## ConfirmExit properties
+
+Nobody wants to lose unsaved changes. Use the **ConfirmExit** and **ConfirmExitMessage** properties to warn the user before they close your app.
+
+> [!NOTE]
+> **ConfirmExit** doesn't work in apps that are embedded in, for example, Power BI and SharePoint.
+
+> [!NOTE]
+> At present, these properties can reference controls on only the first screen if the **Delayed load** preview feature is enabled (which it is by default for new apps). If references are made, PowerApps Studio doesn't show an error, but the resulting published app doesn't open in PowerApps Mobile or a browser. We're actively working to lift this limitation. In the meantime, you can turn off **Delayed load** in **File** > **App settings** > **Advanced settings** (under **Preview features**).
+
+### ConfirmExit
+
+**ConfirmExit** is a Boolean property that, when *true*, opens a confirmation dialog box before the app is closed. By default, this property is *false*, and no dialog box appears.
+
+Use this property to show a confirmation dialog box if the user has made changes but not saved them. Use a formula that can check variables and control properties (for example, the **Unsaved** property of the [**Edit form**](../controls/control-form-detail.md) control).
+
+The confirmation dialog box appears in any situation where data could be lost, as in these examples:
+
+- Running the [**Exit**](function-exit.md) function.
+- If the app is running in a browser:
+  - Closing the browser or the browser tab in which the app is running.
+  - Selecting the browser's back button.
+- If the app is running in PowerApps Mobile (iOS or Android):
+  - Running the [**Launch**](function-param.md) function.<br>The **Launch** function doesn't trigger the dialog box in a browser because another tab opens so that data isn't lost.
+  - Swiping to switch to a different app in PowerApps Mobile.
+  - Selecting the back button on an Android device.
+
+The exact look of the confirmation dialog box might vary across devices and versions of PowerApps.
+
+The confirmation dialog box doesn't appear in PowerApps Studio.
+
+### ConfirmExitMessage
+
+By default, the confirmation dialog box shows a generic message, such as **"You may have unsaved changes."** in the user's language.
+
+Use **ConfirmExitMessage** to provide a custom message in the confirmation dialog box. If this property is *blank*, the default value is used. Custom messages are truncated as necessary to fit within the confirmation dialog box, so keep the message to a few lines at most.
+
+In a browser, the confirmation dialog box might appear with a generic message from the browser.
+
+### Example
+
+1. Create an app that contains two form controls, **AccountForm** and **ContactForm**.
+
+1. Set the **App** object's **ConfirmExit** property to this expression:
+
+    ```powerapps-dot
+    AccountForm.Unsaved Or ContactForm.Unsaved
+    ```
+
+    This dialog box appears if the user changes data in either form and then tries to close the app without saving those changes.
+
+    > [!div class="mx-imgBorder"]
+    > ![Generic confirmation dialog box](media/object-app/confirm-native.png)
+
+1. Set the **App** object's **ConfirmExitMessage** property to this formula:
+
+    ```powerapps-dot
+    If( AccountsForm.Unsaved,
+        "Accounts form has unsaved changes.",
+        "Contacts form has unsaved changes."
+    )
+    ```
+
+    This dialog box appears if the user changes data in the Account form and then tries to close the app without saving those changes.
+
+    > [!div class="mx-imgBorder"]
+    > ![Form-specific confirmation dialog box](media/object-app/confirm-native-custom.png)

powerapps-docs/maker/canvas-apps/functions/media/object-app/appobject-runonstart.png

@@ -7,23 +7,28 @@ ms.service: powerapps
 ms.topic: reference
 ms.custom: canvas
 ms.reviewer: anneta
-ms.date: 11/07/2015
+ms.date: 05/29/2019
 ms.author: gregli
 search.audienceType: 
   - maker
 search.app: 
   - PowerApps
 ---
 # Acceleration, App, Compass, Connection, and Location signals in PowerApps
-Returns information about the app's environment, such as where the user is located in the world and which screen is displayed.  
+
+Returns information about the app's environment, such as where the user is located in the world and which screen is displayed.
 
 ## Description and syntax
-All signals return a [record](../working-with-tables.md#records) of information. You can use and store this information as a record, or you can extract individual properties by using the **.** [operator](operators.md).
+
+Signals are values that can change at any time, independent of how the user may be interacting with the app. Formulas that are based on signals automatically recalculate as these values change.
+
+Signals typically return a [record](../working-with-tables.md#records) of information. You can use and store this information as a record, or you can extract individual properties by using the **.** [operator](operators.md).
 
 > [!NOTE]
 > The **Acceleration** and **Compass** functions return accurate values in a native player such as on iOS or Android, but those functions return zero values as you create or modify an app in the browser.
 
 ### Acceleration
+
 The **Acceleration** signal returns the device's acceleration in three dimensions relative to the device's screen. Acceleration is measured in *g* units of 9.81 m/second<sup>2</sup> or 32.2 ft/second<sup>2</sup> (the acceleration that the Earth imparts to objects at its surface due to gravity).
 
 | Property | Description |
@@ -33,28 +38,14 @@ The **Acceleration** signal returns the device's acceleration in three dimension
 | **Acceleration.Z** |Up and down.  Up is a positive number. |
 
 ### App
-The **App** signal returns information about the running app.
-
-| Property | Description |
-| --- | --- |
-| **App.ActiveScreen** | Screen that's displayed. Returns a screen object, which you can use to reference properties of the screen or compare to another screen to determine which screen is displayed. To change the displayed screen, use the **[Back](function-navigate.md)** or **[Navigate](function-navigate.md)** function. |
-| **App.Width** | Returns the width of the window in which the app is running. You can use this property in a formula when you set the **Width** property of the screen to build a responsive app.  |
-| **App.Height** | Returns the height of the window in which the app is running. You can use this property in a formula when you set the **Height** property of the screen to build a responsive app. |
-| **App.DesignWidth** | Returns the width of the app in PowerApps Studio. You can use this property in a formula when you set the **Width** property of the screen to ensure a minimum width in a responsive app.  |
-| **App.DesignHeight** | Returns the height of the app in PowerApps Studio. You can use this property in a formula when you set the **Height** property of the screen to ensure a minimum height in a responsive app.  |
-| **App.SizeBreakpoints** | A single-column table of numbers that delimit the screen-size ranges that the [**Screen.Size**](../controls/control-screen.md) property returns. The values in this table may be changed to customize the breakpoints that all of the app's screens use.
 
-The **App** object also has a [behavior formula](../working-with-formulas-in-depth.md) that you can set.
+Among other properties, the **App** object includes a signal that indicates which screen is showing.
 
-| Property  | Description |
+| Property | Description |
 | --- | --- |
-| **App.OnStart** | The behavior of the app when the user starts it. Makers often use this property to retrieve and cache data into collections with the **[Collect](function-clear-collect-clearcollect.md)** function, set up variables with the **[Set](function-set.md)** function, and navigate to an initial screen with the **[Navigate](function-navigate.md)** function. This formula is evaluated before the first screen appears. No screen is loaded, so you can't set context variables with the **[UpdateContext](function-updatecontext.md)** function. However, you can pass context variables with the **Navigate** function. |
-
-The **App** object appears at the top of the hierarchical list of controls in the left navigation pane, and you can select this object like a control on a screen. After you select the object, you can view and edit one of its properties if you select that property in the drop-down list to the left of the formula bar.  
-
-After you change the **OnStart** property, you can test it by hovering over the **App** object in the left navigation pane, selecting the ellipsis (...) that appears, and then selecting **Run OnStart**. Unlike when the app is loaded for the first time, existing collections and variables will already be set. Use the **[ClearCollect](function-clear-collect-clearcollect.md)** function instead of the **Collect** function to start with empty collections.
+| **App.ActiveScreen** |Screen that's showing. Returns a screen object, which you can use to reference properties of the screen or compare to another screen to determine which screen is showing. You can use the **[Back](function-navigate.md)** or **[Navigate](function-navigate.md)** function to change the screen that's showing. |
 
- ![App item context menu with Run OnStart](media/appobject-runonstart.png)
+More information: [**App** object](object-app.md) documentation.
 
 ### Compass
 The **Compass** signal returns the compass heading of the top of the screen. The heading is based on magnetic north.