/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page winrt_support.html
    \title Qt for UWP
    \brief Running Qt applications on devices supporting the
    Universal Windows Platform (UWP).
    \ingroup supportedplatform

    Qt for UWP allows you to run Qt applications on devices supporting the
    Universal Windows Platform (UWP). Microsoft Windows 10 introduced UWP, which
    provides a common application platform on every device that runs Windows 10,
    as a successor to Windows Runtime (WinRT) introduced by Windows 8. The UWP
    core APIs are the same on all Windows devices, and therefore applications
    that only use the core APIs will run on any Windows 10 device, such as a
    desktop PC, or Xbox One.

    The Qt port was originally written for WinRT and updated to support UWP. The
    port uses the C++ capabilities. While UWP supports the component
    extensions internally, they are not used inside Qt and you do not need to
    use them. UWP applications run in a sandboxed environment for security
    reasons and support different architectures, such as ARM and x86.

    \target winrt-supported-configurations
    \section1 Supported Configurations

    The following configurations are supported.

    \include supported-platforms.qdocinc winrt

    \section1 Requirements

    Development for UWP requires a Microsoft Windows development host.
    The minimum version supported is Windows 10.

    Qt supports UWP apps running on any variant of Windows 10 or later on the
    desktop PC, IoT, Xbox One, and so on.

    If you are targeting a remote device, follow the instructions by
    Visual Studio to set it up correctly.

    \section1 Getting Started

    \section2 Notes to Desktop Users

    As UWP applications run in a sandboxed environment, some restrictions should be taken
    into account when considering porting or writing cross-platform applications:

    \list
        \li The class QProcess is not implemented (indicated by the macro \c QT_NO_PROCESS
            being defined) as no subprocesses can be launched.
        \li Some paths returned by QStandardPaths::writableLocation() may be empty.
        \li A UWP application may not do socket-based communication with another application
            running on the same host (as this would violate the sandboxing).
        \li Applications run in fullscreen mode only (see QStyleHints). On desktop,
            the screen size varies as the application is resized.
        \li There are no environment variables. Qt emulates the functionality
            by maintaining the values locally, so that qputenv() and related
            functions continue to work. All known variables influencing Qt can
            be set in source code.
        \li UWP applications are UI applications by nature. This implies that
            console type applications will have a window created internally,
            which is always visible.
        \li Applications should not exit programmatically. In particular, calling
            exit() before the UI is shown causes a crash.
        \li The UWP clipboard is local to the application; it cannot be retrieved
            by a desktop application.
    \endlist

    \section2 Building Applications

    You can develop applications for UWP just as any other Qt applications.
    Use your favorite editor or IDE (such as Qt Creator) and create your
    application or load a Qt example. Then run \c qmake and \c {nmake/jom} to
    build your application.

    \section3 Building Applications with Visual Studio

    To launch your project with Visual Studio a corresponding project needs to
    be created. \c qmake supports converting a \c .pro project into Visual
    Studio format by passing the parameters \c -tp vc.

    \code
      qmake -tp vc <your project>.pro
    \endcode

    Be aware of using the correct match of \c qmake and Visual Studio. As the
    Visual Studio format is generic, it does not return an immediate error if
    for instance you open a Windows Phone project inside Visual Studio
    for Windows.

    This creates a project which supports building applications and running them
    with Visual Studio. It does not embed Qt libraries into the package and
    requires you to add them manually. For this purpose, the command line
    tool \l{The Windows Deployment Tool}{windeployqt} has been included in the installed package. To
    enable automatic parsing of dependencies and adding the libraries and
    dependencies into the application package, create the project with the
    following options:

    \code
      qmake -tp vc <your project>.pro "CONFIG+=windeployqt"
    \endcode

    \section3 Building Applications with Qt Creator

    You will not need to do any conversion to open your project in Qt Creator.
    Please follow the generic instructions on how to open and build a project.

    Qt Creator deploys your application on the UWP device, if the
    device is detected by the PC.

    \note Remote PCs, such as the Surface, are not yet supported for deployment by Creator.

    \section1 Building from Source

    We assume that you have cloned the Qt 5 repositories (or obtained
    the Qt sources elsewhere) and followed the platform-independent
    requirements for building Qt. The process of building Qt is found
    in the \l{Building Qt Sources} page.

    Qt for UWP is always built as a cross-build, because tools, such as qmake,
    are built as desktop applications. For compiling those, a desktop development
    environment is required. If you have installed Visual Studio for Windows,
    this will only create binaries for UWP. You will need Visual Studio for
    Windows Desktop as well to create those desktop tools.

    Please make sure to use an x86 command prompt (either use the \e {VS x86 Native
    Tools Command Prompt} or call \e vcvarsall.bat without any parameter or with \c x86)
    for every UWP build. While the toolchain which is used for the
    target is set automatically, the command prompt decides what will be used for the
    host tools like \e qmake or \e moc. Building these tools might fail if another
    command prompt is used.

    The UWP mkspec format is \c {<platform>-<architecture>-<toolchain>}
    where architecture can be \c arm, \c x86, or \c x64. The following is an
    example of building qtbase for UWP:
    \code
        > ./configure -xplatform winrt-x64-msvc2017 -release
        > nmake/jom
    \endcode

    \section1 Running Applications from Command Line

    UWP applications must be packaged (including all dependencies) and
    installed or registered with the application service in order to be
    launched. \l{winrtrunner}{The WinRT Runner Tool} can be used to
    launch these applications from the command line.

    \section2 Package Content
    Package content
    consists of the application executable and its dependencies, as for every
    Windows application. The dependencies are the needed (Qt)
    libraries and plugins. Note that Qt plugins have to be put into a folder
    named after their category (platforms, imageformats, and so on) without
    using a \c plugins folder as root. For more information, see
    \l{Qt for Windows - Deployment}.

    As UWP applications are run in a sandboxed environment, setting
    the path variable to point to the files required will not work.

    The \l{The Windows Deployment Tool}{windeployqt} convenience tool looks up
    the application's dependencies
    and copies Qt libraries and plugins to the appropriate directories, as
    necessary.

    Because all resources are placed to one directory, you can register the
    directory using an XML file (AppxManifest.xml) and Windows Powershell. The reference
    for these manifest files can be found
    \l{http://msdn.microsoft.com/en-us/library/windows/apps/br211473.aspx}{here}.
    The target processor architecture must be specified (as opposed to the default,
    'neutral').
    As soon as these requirements are met, change into your \e packaged directory in
    PowerShell and call:
    \code
        > Add-AppxPackage -Register AppxManifest.xml
    \endcode
    \note \l{winrtrunner}{The WinRT Runner Tool} can perform the same operation with the --install option.

    If that worked, you should be able to find your application in Windows'
    start screen. To remove your application, use Windows' built-in way to
    uninstall applications (right-click or tap and hold the application and
    choose \c{Uninstall}).
    \note \l{winrtrunner}{The WinRT Runner Tool} can perform the same operation with the --remove option.

    \section2 WinRT Runner Tool
    \target winrtrunner
    The WinRT Runner Tool can be found in QTDIR/bin/winrtrunner. It is
    intended to aid in the deployment, launching, and debugging of Qt for WinRT
    applications. It can be used from the command line, or invoked by the IDE.

    \badcode
    Usage: winrtrunner [options] package [arguments]
    winrtrunner installs, runs, and collects test results for packages made with Qt.

    Options:
      --test                            Install, start, collect output, stop (if
                                        needed), and uninstall the package. This is
                                        the default action of winrtrunner.
      --start                           Start the package. The package is installed
                                        if it is not already installed. Pass
                                        --install to force reinstallation.
      --debug <debugger>                Start the package with the debugger
                                        attached. The package is installed if it is
                                        not already installed. Pass --install to
                                        force reinstallation.
      --debugger-arguments <arguments>  Arguments that are passed to the debugger
                                        when --debug is used. If no debugger was
                                        provided this option is ignored.
      --suspend                         Suspend a running package. When combined
                                        with --stop or --test, the app will be
                                        suspended before being terminated.
      --stop                            Terminate a running package. Can be be
                                        combined with --start and --suspend.
      --wait <seconds>                  If the package is running, waits the given
                                        number of seconds before continuing to the
                                        next task. Passing 0 causes the runner to
                                        wait indefinitely.
      --install                         (Re)installs the package.
      --remove                          Uninstalls the package.
      --device <name|index>             Specifies the device to target as a device
                                        name or index. Use --list-devices to find
                                        available devices. The default device is the
                                        first device found for the active run
                                        profile.
      --profile <name>                  Force a particular run profile.
      --list-devices                    List the available devices (for use with
                                        --device).
      --verbose <level>                 The verbosity level of the message output
                                        (0 - silent, 1 - info, 2 - debug). Defaults
                                        to 1.
      --ignore-errors                   Always exit with code 0, regardless of the
                                        error state.
      --loopbackexempt <mode>           Enables localhost communication for
                                        clients,servers or both. Adding this
                                        possibility for servers needs elevated
                                        rights and might ask for these in a
                                        dialog.Possible values: client, server,
                                        clientserver
      -?, -h, --help                    Displays this help.

    Arguments:
      package [arguments]               The executable or package manifest to act
                                        upon. Arguments after the package name will
                                        be passed to the application when it starts.
    \endcode
*/