diff options
Diffstat (limited to 'examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc')
| -rw-r--r-- | examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc | 77 |
1 files changed, 36 insertions, 41 deletions
diff --git a/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc b/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc index 0702fe5a..2f819c32 100644 --- a/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc +++ b/examples/applicationmanager/custom-appman/doc/src/custom-appman.qdoc @@ -29,77 +29,72 @@ /*! \example applicationmanager/custom-appman -\title Implementing a Custom Application-Manager Example +\title Implement a Custom Application Manager Example \image custom-appman.png Screenshot -\brief Basic structure and starting point for a custom application-manager executable. +\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 it may still -be necessary to implement a custom application-manager executable to have more influence over the -startup behavior. +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 Please note however, that all C++ classes in the application-manager modules are considered private -API at the moment, so there are no compatibility guarantees at all. +\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 desire to go down that road however, this example will provide you with an starting -point to build your custom implementation upon. +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. -Keep in mind though, that this custom application-manager executable will need a System-UI to -display something on the screen, just as the standard \c appman executable. - -\section1 Walkthrough - -Following is a breakdown of the minimal code needed for such a custom implementation: +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/libraries. These includes will -pull in the basic set of classes needed. -In order to avoid possible clashes with QML plugins, all of the application-manager's symbols are -namespaced - \c QT_USE_NAMESPACE_AM will expand to the matching \c using statement. +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 -Not application-manager specific, but having an application name and version set is generally -a good idea. +Generally, it's a good idea to set an application name and version. \printline Logging::init -We want the logging part of the application-manager initialized as early as possible, especially -when dealing with DLT logging. +We want the application manager's logging part to be initialized as early as possible, especially +when we are dealing with DLT logging. \printline Package::ensure -If you are using the installer part of the application-manager, this function needs to be called -\e before the QApplication constructor to make sure your C locale is an UTF-8 variant (this is a -requirement in order to get deterministic results when using \c libarchive with non-ASCII filenames). +If you are using the application manager's installer part, this function needs to be called +\e before the QApplication constructor to make sure that your C locale is a UTF-8 variant. This is +a requirement, to get deterministic results when using \c libarchive with non-ASCII filenames. \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 of a child -process which keeps the root privileges while the main process permanently drop them. +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 -(which is a class derived from QGuiApplication) object plus a suitable configuration object: in -this simple case we just use the application-manager's default YAML parsing, so we instantiate -a \c DefaultConfiguration object. -The rest of the function consists of parsing the configuration and then calling the relevant -setup routines on the \c Main object. -Since \c Main can be derived differently depending on your application-manager configuration -(headless, with widgets or standard), you would need to know the correct base-class for the exec() -call - the \c MainBase typedef will circumvent that problem though. - -Keep in mind that most functions in the application-manager will throw exceptions that are -derived from \c std::exception, so a \c catch handler is a must. +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: headless, 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. */ |