/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** 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$
**
****************************************************************************/

/*!

\example applicationmanager/custom-appman
\title Implement a Custom Application Manager Example
\image custom-appman.png Screenshot
\brief Provides the basic structure and starting point for a custom application manager executable.
\ingroup applicationmanager-examples

\section1 Introduction

The application manager is compiled as a self-contained executable that can be configured in large
parts through the YAML-based config file system and startup plugins. However, if you need to have
more control over the application's startup behavior, it may be necessary to implement a custom
application manager executable.

\note Currently, all C++ classes in the application manager modules are considered private API, so
there are no compatibility guarantees at all.

If you still require this behavior, this example provides a starting point that you can build your
custom implementation upon. Keep in mind, that this custom application manager executable needs a
System UI to display something on the screen, just like the standard \c appman executable.

The following is a breakdown of the minimal code necessary:

\quotefromfile applicationmanager/custom-appman/custom-appman.cpp
\skipto #include
\printuntil QT_USE_NAMESPACE_AM

The application manager is split into functional building blocks. These include statements
pull in the basic set of classes that you need. To avoid possible clashes with QML plugins, all of
the application manager's symbols are namespaced - \c QT_USE_NAMESPACE_AM expands to the equivalent
\c using statement.

\skipto QCoreApplication::setApplicationName
\printuntil QCoreApplication::setApplicationVersion

Generally, it's a good idea to set an application name and version.

\printline Logging::init

We want the application manager's logging part to be initialized as early as possible, especially
when we are dealing with DLT logging.

\printline Sudo::forkServer

Again, for the installer part only, an additional setup step is necessary before running the
QApplication constructor: if the executable is setuid-root, this call will \c fork off a child
process which keeps the root privileges while the main process permanently drops them.

\printuntil return 2
\printline }

This \c try block is the heart of the custom application manager. You need to create a \c Main
object, which is a class derived from QGuiApplication, plus a suitable configuration object. In
this simple case, we use the application manager's default YAML parsing, so we instantiate a
\c DefaultConfiguration object. The rest of the function involves parsing the configuration and
then calling the relevant setup routines on the \c Main object.

Depending on your application manager's configuration, the \c Main object can be derived
differently: with widgets, or standard. So, you need to know the correct base class for
the exec() call. However, the \c MainBase typedef circumvents this problem.

Most functions in the application manager throw exceptions that are derived from \c std::exception,
so a \c catch handler is compulsory.

*/