diff options
author | Robert Griebl <robert.griebl@qt.io> | 2022-06-29 15:35:26 +0200 |
---|---|---|
committer | Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> | 2022-06-30 20:52:48 +0000 |
commit | 9a41317657da25661c96da1a65d3bff34200a07f (patch) | |
tree | e5f73703fa458274d1b7c191447005b0fb035f36 | |
parent | 729b750f5fd6d7edaafd7e79327b7fabdafbe371 (diff) | |
download | qtapplicationmanager-9a41317657da25661c96da1a65d3bff34200a07f.tar.gz |
Remove pre-5.15 migration guides
Change-Id: I52f7f963ea1a10bf4080aa025a49136c1ab1791e
Reviewed-by: Dominik Holland <dominik.holland@qt.io>
(cherry picked from commit 49fdff8cda7258faab493e935bf911de4b874371)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
-rw-r--r-- | doc/migration-guide-5.12.qdoc | 334 | ||||
-rw-r--r-- | doc/migration-guide-5.14.qdoc | 87 |
2 files changed, 0 insertions, 421 deletions
diff --git a/doc/migration-guide-5.12.qdoc b/doc/migration-guide-5.12.qdoc deleted file mode 100644 index 47449de9..00000000 --- a/doc/migration-guide-5.12.qdoc +++ /dev/null @@ -1,334 +0,0 @@ -// Copyright (C) 2021 The Qt Company Ltd. -// Copyright (C) 2019 Luxoft Sweden AB -// Copyright (C) 2018 Pelagicore AG -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - -\page migration-guide-5.12.html -\title Migrating code from 5.11 to 5.12 - -Qt Application Manager 5.12 is not API compatible with the 5.11 release. In this document we go through -the main API breaks and how to port affected code from the 5.11 to the new 5.12 API. The API breaks lie -solely on the System UI side, therefore application code remains unchanged. - -There are also cases where there's no API break but instead new, better, APIs for achieving the same -result in 5.12. This document also covers some of such situations. - -\section1 Import statements - -Most of the content of the QtApplicationManager QML module was moved into two new modules: -\l{QtApplicationManager.SystemUI QML module}{QtApplicationManager.SystemUI} -and \l{QtApplicationManager.Application QML module}{QtApplicationManager.Application}. The following -table briefly explains each of them: - -\table -\header - \li QML Module Name - \li Content -\row - \li \l{QtApplicationManager QML module}{QtApplicationManager} - \li Components and types in common to applications and System UI. Both - System UI and application code can import this module. -\row - \li \l{QtApplicationManager.SystemUI QML module}{QtApplicationManager.SystemUI} - \li Components and types that a System UI can use. Applications should - not import this module. -\row - \li \l{QtApplicationManager.Application QML module}{QtApplicationManager.Application} - \li Components and types that an application can use. System UI code should - not import this module. -\endtable - -In order to avoid compatibility problems with old code expecting the old APIs, \b all imports have -been bumped up to version \c 2.0. Importing the \c 1.0 versions will just yield a QML error. - - -\section1 ApplicationManager and applications - -\section2 Refactored ApplicationObject - -In 5.11, the object type representing an application was named \c Application. But since Qt also has -an object type with the same name, in order to be able to reference enumerations defined in it you -had to import QtApplicationManager in a separate namespace. In 5.12, that object type was renamed to -ApplicationObject and thus it no longer clashes with Qt's own \c Application type. - -\oldcode -import QtApplicationManager 1.0 as AppMan -... -if (application.state === AppMan.Application.Installed) { - ... -} -\newcode -import QtApplicationManager.SystemUI 2.0 -... -if (application.state === ApplicationObject.Installed) { - ... -} -\endcode - -\section2 Starting and stopping applications - -The ApplicationObject is smarter now, moving away from being mostly a plain-old-data structure to also -contain all actions pertaining to the application at hand, making for a more object oriented API. This -is reflected in the way you can start and stop applications in 5.12. - -\oldcode -import QtApplicationManager 1.0 -... -var application = ApplicationManager.fromId("com.example.music"); -... -ApplicationManager.startApplication(application.id); -\newcode -import QtApplicationManager.SystemUI 2.0 -... -var application = ApplicationManager.fromId("com.example.music"); -... -application.start(); -\endcode - -\section1 WindowManager and windows - -Windows are now represented by instances of the WindowObject type instead of being Item instances. WindowObjects -cannot be displayed directly and have to be assigned to a WindowItem to be rendered on the screen. - -This is also reflected in WindowManager model roles, which are now fewer and different. The \c windowItem role -has been replaced with the \l{windowmanager-window-role}{window} role. The \c isFullscreen role has been removed -and there's no replacement for it. \c isMapped and \c isClosing were replaced with a single role named -\l{windowmanager-contentState-role}{contentState}. - -\oldcode -import QtApplicationManager 1.0 -... -Connections { - target: WindowManager - onWindowReady: { - window.parent = windowContainer; - window.width = Qt.binding(function() { return windowContainer.width; }); - window.height = Qt.binding(function() { return windowContainer.height; }); - } - ... -} -... -Item { - id: windowContainer - ... -} -\newcode -import QtApplicationManager.SystemUI 2.0 -... -Connections { - target: WindowManager - onWindowAdded: { - windowItem.window = window; - } - ... -} -... -WindowItem { - id: windowItem - ... -} -\endcode - -See the new \l{System UI Example: "Hello World!"}{Hello World} and \l{Animated Windows System UI Example}{Animated Windows} -examples for further explanations on the new way of manipulating windows in your System UI. - -\section2 WindowManager signals - -Signals in WindowManager related to the window lifecycle have all changed. \c windowReady is the only signal thas has an -equivalent in the new API, as seen in the previous code snippet. For others there's no exact match, although the new API -has similar signals. - -\oldcode -import QtApplicationManager 1.0 -... -Connections { - target: WindowManager - onWindowClosing: { - ... - } - onWindowLost: { - ... - } - ... -} -\newcode -import QtApplicationManager.SystemUI 2.0 -... -Connections { - target: WindowManager - onWindowContentStateChanged: { - if (window.contentState === WindowObject.SurfaceNoContent) { - // code from onWindowClosing - ... - } else if (window.contentState === WindowObject.NoSurface) { - // code from onWindowLost - ... - } - } - ... -} -\endcode - -You can also check and track the content state of a window from its \l{WindowObject::contentState}{WindowObject.contentState} -property. - -\section2 Releasing windows - -In the new API there's no longer the concept of releasing windows. Thus the signal \c WindowManager.windowReleased and the -method \c WindowManager.releaseWindow() have been removed. Instead, a WindowObject is destroyed once it no longer has a -backing surface (ie, its contentState is \l{windowobject-nosurface}{WindowObject.NoSurface}) and it is not assigned to any -WindowItem. - -\section2 Window properties - -The window properties of a given window are now set, queried and tracked from its WindowObject; the -corresponding, old API in the WindowManager singleton has been removed. The code becomes more -readable and modular this way: - -\oldcode -import QtApplicationManager 1.0 -... -WindowManager.setWindowProperty(window, "type", "dialog"); -... -Connections { - target: WindowManager - onWindowPropertyChanged: { - if (window === fooWindow) { - console.log("fooWindow's property " + name + " is now " + value); - } - } -} -\newcode -import QtApplicationManager.SystemUI 2.0 -... -window.setWindowProperty("type", "dialog"); -... -Connections { - target: fooWindow - onWindowPropertyChanged: { - console.log("fooWindow's property " + name + " is now " + value); - } -} -\endcode - -\section2 Registering compositor views - -In the new API, on the System UI side, there's no longer a need to explicitly call WindowManager.registerCompositorView -on a Window to be able to composite client application surfaces on them (ie. have WindowItems rendering WindowObjects). -This is now handled internally automatically and thus this function has been removed from the Qt Application Manager API. - -\oldcode -import QtApplicationManager 1.0 -... -QtObject { - Window { - id: someSysUIWindow - visible: true - ... - Component.onCompleted: { - WindowManager.registerCompositorView(someSysUIWindow); - } - } -} -\newcode -import QtApplicationManager.SystemUI 2.0 -... -QtObject { - Window { - id: someSysUIWindow - visible: true - ... - } -} -\endcode - -\section1 SystemMonitor - -The SystemMonitor singleton no longer exists. The functionality that it provided has been split into -several new components, namely: MonitorModel, CpuStatus, GpuStatus, MemoryStatus, FrameTimer and -IoStatus. - -\oldcode -import QtApplicationManager 1.0 -... -Item { - id: root - ... - Component.onCompleted: { - SystemMonitor.reportingInterval = 1500; - SystemMonitor.count = 20; - } - Binding { target: SystemMonitor; property: "cpuLoadReportingEnabled"; value: root.visible } - - // Draw a graph of CPU usage - ListView { - model: SystemMonitor - ... - } -} -\newcode -import QtApplicationManager 2.0 -... -Item { - id: root - ... - // Draw a graph of CPU usage - ListView { - model: MonitorModel { - interval: 1500 - running: root.visible - maximumCount: 20 - CpuStatus {} - } - ... - } -} -\endcode - -\section1 ProcessMonitor - -The ProcessMonitor component no longer exists. The functionality that it provided has been split into a -couple of new components, namely: ProcessStatus, MonitorModel and FrameTimer. - -\oldcode -import QtApplicationManager 1.0 -... -Item { - id: root - ... - // Draw a graph of CPU usage - ListView { - model: ProcessMonitor { - count: 20 - cpuReportingEnabled: root.visible - reportingInterval: 1500 - applicationId: "foo.app" - } - ... - } -} -\newcode -import QtApplicationManager 2.0 -import QtApplicationManager.SystemUI 2.0 -... -Item { - id: root - ... - // Draw a graph of CPU usage - ListView { - model: MonitorModel { - maximumCount: 20 - running: root.visible - interval: 1500 - ProcessStatus { - applicationId: "foo.app" - } - } - ... - } -} -\endcode - -*/ diff --git a/doc/migration-guide-5.14.qdoc b/doc/migration-guide-5.14.qdoc deleted file mode 100644 index 08678f84..00000000 --- a/doc/migration-guide-5.14.qdoc +++ /dev/null @@ -1,87 +0,0 @@ -// Copyright (C) 2021 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - -\page migration-guide-5.14.html -\title Migrating code from 5.13 to 5.14 - -Qt Application Manager 5.14 added a new \l{Intents} IPC mechanism and added support for application -packages shipping multiple executables. In this document we go through the main API breaks and how -to port affected code and meta-data from the 5.13 to the new 5.14 API. - -\section1 Application Aliases and the documentUrl - -If you wanted to have a single application, but have it show up with multiple different entries in -the launcher, you would use \l{Alias Manifests}. To disambiguate which application was actually -activated, you would supply different \c documentUrl parameters in each of the alias manifests and -watch for these in a signal handler for ApplicationInterface::openDocument. -This mechanism only worked for built-in applications though and it was not possible to extend it in -a clean way to support the new multiple executables alternative that is possible with 5.14. - -Because of this, support for alias manifests is completely removed in 5.14. - -The \c documentUrl field is not supported in the newer manifest versions anymore, but continues to -work as expected when specified in a legacy manifest. - -The \c documentUrl parameter in the ApplicationObject::start() and -ApplicationManager::startApplication() calls is still fully supported. This also ties into the -open-URL handling via ApplicationManager::openUrl() and Qt::openUrlExternally(), which use the \c -documentUrl parameter to communicate the URL to open towards the application. Although there are no -plans to retire this API, you still might want to switch over to the more versatile intent -framework, depending on your use-case. - -There is an example explaining how to use this new mechanism as a direct replacement for the old -alias manifests: \l{Launch Applications Using Intents System UI Example} - - -\section1 The PackageManager and the PackageObject - -Installable applications were already referred to as "packages", but were just represented by an -ApplicationObject handle within the the application manager. Now that 5.14 added support for -multiple applications within a single package, all packages - even built-in ones - are represented -by a PackageObject handle, which in turn holds references to all the contained applications. For -legacy applications, this results in the PackageObject referring to just a single application. - -A new PackageManager singleton was added, which acts as an item model for all PackageObjects in the -same way the ApplicationManager does for ApplicationObjects. Since everything is a package now, the -ApplicationInstaller singleton functionality was moved to the PackageManager singleton and the API -was adapted slightly to reflect the distinction between packages and applications. -The old ApplicationInstaller singleton is deprecated, but still available as a light-weight wrapper -around the new PackageManager. -In the same vein, using the PackageManager singleton is completely optional, if the information you -are getting from the ApplicationManager singleton is sufficient for your use-case. - - -\section1 Multiple Installation Locations - -The possibility to specify multiple installation locations for installing third-party applications -has been removed in 5.14. This feature complicated the ApplicationInstaller API use, added a lot of -hard to test complexity to the installer code base and the originally intended use-case (removable -SD-Cards) was not fully implemented at all. - -A replacement for this functionality should be implemented on a system level and depend on the -intended use-case: candidates would be e.g. -\l{https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html}{\c overlayfs}, -\l{https://www.tldp.org/HOWTO/LVM-HOWTO/index.html}{\c lvm2}, or -\l {https://www.kernel.org/doc/html/latest/filesystems/btrfs.html}{\c btrfs} - -Although you should use the new \c --installation-dir option or the \c applications/installationDir -key in the configuration file to set the installation directory in 5.14, the old syntax using a -list of \c installationLocations in the configuration file is still supported - as long as there is -exactly one location defined in this list. - -\section1 Application Database Internals - -The internal application database - a cache of the known application manifest files - was -completely re-done in 5.14. All manifest files are now scanned on startup, so the \c -r / \c ---recreate-database command line option is not needed anymore. Along the same lines the \c --database -option and the \c applications/database configuration key are not needed anymore, because the new -application database is just treated as a standard cache file and is stored in the appropriate -system directories (see also QStandardPaths::CacheLocation). - -Although both the configuration and application caches are versioned and keyed to the checksum -of the respective source files, you can still force the application manager to either clear them via -the \c --clear-cache option or not use caches at all via the \c --no-cache option. - -*/ |