Doc: Describe Android run settings

Users can apply Android Activity manager (am) start options
and run shell commands before and after starting applications
on Android devices.

Change-Id: I9ffcfce8a26b8e7d965a1a2327eeedf38bf81a31
Reviewed-by: Vikas Pachdha <vikas.pachdha@qt.io>

doc/src/android/creator-projects-settings-run-android.qdocinc

@@ -0,0 +1,64 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+/*!
+//! [run settings android]
+
+    \section2 Specifying Run Settings for Android Devices
+
+    To run and debug an application on an Android device, you must create
+    connections from the development host to the device, as instructed in
+    \l {Connecting Android Devices}.
+
+    A default set of Android Activity manager (am) start options is applied when
+    starting applications. You can specify additional start options in the
+    \uicontrol {Activity manager start options} field. However, if the default
+    options conflict with the added options, the application might not start.
+
+    For example, to run the application as a particular user, enter the start
+    option \c {--user 10}, where \c 10 is the user ID of the user account.
+
+    \image qtcreator-android-run-settings.png
+
+    You can specify shell commands to run before the application is started and
+    after it is quit. For example, enter the following commands to unlock the
+    screen and to switch to the user account \c 10 on the device before running
+    the application:
+
+    \code
+    input keyevent 82
+    am switch-user 10
+    \endcode
+
+    Enter the following commands to switch back to the default user, \c 0, and
+    to unlock the screen after the application is quit:
+
+    \code
+    am switch-user 0
+    input keyevent 82
+    \endcode
+
+//! [run settings android]
+*/

doc/src/android/deploying-android.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -55,6 +55,9 @@
     To specify settings for application packages, select \uicontrol Projects >
     \uicontrol {Build Android APK} > \uicontrol Details.
 
+    For more information about options that you have for running applications,
+    see \l {Specifying Run Settings for Android Devices}.
+
     \section1 Creating Distributable APK Packages
 
     To copy Qt libraries and files to the project directory and to bundle them

doc/src/projects/creator-projects-settings-run.qdoc

@@ -65,6 +65,7 @@
     \include projects/creator-projects-settings-run-desktop.qdocinc run settings desktop
     \include projects/creator-projects-settings-run-analyze.qdocinc settings valgrind
     \include projects/creator-projects-settings-run-debug.qdocinc run settings debugger
+    \include android/creator-projects-settings-run-android.qdocinc run settings android
     \include linux-mobile/creator-projects-settings-run-linux.qdocinc run settings linux
     \include qnx/creator-projects-settings-run-qnx.qdocinc run settings qnx
     \include linux-mobile/creator-projects-settings-run-b2qt.qdocinc run settings embedded