从 5.11 迁移代码到 5.12

Qt 应用程序管理器 5.12 版本与 5.11 版本的 API 不兼容。本文档将介绍主要的 API 打破，以及如何将受影响的 5.11 代码移植到新 5.12 API。这些 API 打破主要在系统 UI 方面，因此应用程序代码保持不变。

也有这样的情况，没有 API 打破，但是在 5.12 中有新的、更好的 API 来实现相同的结果。本文档还将涵盖这些情况的一些。

导入语句

QtApplicationManager QML 模块的大部分内容已转移到两个新模块：QtApplicationManager.SystemUI 和 QtApplicationManager.Application。以下表格简要说明每个模块的内容

QML 模块名称	内容
QtApplicationManager	应用程序和系统 UI 中的通用组件和类型。系统 UI 和应用程序代码都可以导入此模块。
QtApplicationManager.SystemUI	系统 UI 可以使用的组件和类型。应用程序不应导入此模块。
QtApplicationManager.Application	应用程序可以使用的组件和类型。系统 UI 代码不应导入此模块。

为了避免与旧代码的兼容性问题，期望旧的 API，所有导入都已升级到版本 2.0。导入 1.0 版本将仅产生一个 QML 错误。

应用程序管理器和应用程序

重构应用程序对象

在 5.11 中，代表应用程序的对象类型命名为 Application。但由于 Qt 也具有相同名称的对象类型，为了能够引用在它中定义的枚举，必须在一个单独的作用域中导入 QtApplicationManager。在 5.12 中，该对象类型被重命名为 ApplicationObject 并且因此它不再与 Qt 的自身 Application 类型冲突。

例如，如果您有如下代码

import QtApplicationManager 1.0 as AppMan
...
if (application.state === AppMan.Application.Installed) {
    ...
}

则可重写为

import QtApplicationManager.SystemUI 2.0
...
if (application.state === ApplicationObject.Installed) {
    ...
}

启动和停止应用程序

现在 ApplicationObject 更智能，它从主要是一个传统的数据结构转变为也包含与当前应用程序相关的所有操作，从而使得 API 更具有面向对象的特点。这在 5.12 中启动和停止应用程序的方式中得到了体现。

例如，如果您有如下代码

import QtApplicationManager 1.0
...
var application = ApplicationManager.fromId("com.example.music");
...
ApplicationManager.startApplication(application.id);

则可重写为

import QtApplicationManager.SystemUI 2.0
...
var application = ApplicationManager.fromId("com.example.music");
...
application.start();

窗口管理器和窗口

现在窗口用 WindowObject 类型的实例表示，而不是用 Item 实例表示。WindowObjects 不能直接显示，必须分配给一个 WindowItem 才能在屏幕上渲染。

这也在 WindowManager 模型角色中得到了体现，这些角色现在更少且不同。已用 window 角色替换了 windowItem 角色。已删除 isFullscreen 角色，没有替代品。isMapped 和 isClosing 被替换为单个名为 contentState 的角色。

例如，如果您有如下代码

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
    ...
}

则可重写为

import QtApplicationManager.SystemUI 2.0
...
Connections {
    target: WindowManager
    onWindowAdded: {
        windowItem.window = window;
    }
    ...
}
...
WindowItem {
    id: windowItem
    ...
}

请参阅新的 Hello World 和动画窗口示例，进一步了解在系统 UI 中以新方式操作窗口的方法。

窗口管理器信号

与窗口生命周期相关的窗口管理器信号均有所更改。windowReady是唯一在新的API中有等价信号的信号，如在之前的代码片段中所示。对于其他信号，没有精确匹配，尽管新的API有类似的信号。

例如，如果您有如下代码

import QtApplicationManager 1.0
...
Connections {
    target: WindowManager
    onWindowClosing: {
        ...
    }
    onWindowLost: {
        ...
    }
    ...
}

则可重写为

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
            ...
        }
    }
    ...
}

您还可以从其WindowObject.contentState属性检查和跟踪窗口的内容状态。

释放窗口

在新的API中，不再存在释放窗口的概念。因此，信号WindowManager.windowReleased和方法WindowManager.releaseWindow()已被删除。取而代之的是，当WindowObject没有支持表面（也就是其WindowObject.NoSurface内容状态）并且未分配给任何WindowItem时，它会被销毁。

窗口属性

现在，您可以从其WindowObject设置、查询和跟踪特定窗口的窗口属性；在WindowManager单例中对应的，旧的API已被删除。这样代码变得更加易于阅读和模块化

例如，如果您有如下代码

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);
        }
    }
}

则可重写为

import QtApplicationManager.SystemUI 2.0
...
window.setWindowProperty("type", "dialog");
...
Connections {
    target: fooWindow
    onWindowPropertyChanged: {
        console.log("fooWindow's property " + name + " is now " + value);
    }
}

注册合成器视图

在新的API中，在系统UI方面，不再需要显式调用WindowManager.registerCompositorView来将窗口与客户端应用程序表面进行合成（即在WindowItems上渲染WindowObject）。现在这由内部自动处理，因此已从Qt应用程序管理器API中删除了此函数。

例如，如果您有如下代码

import QtApplicationManager 1.0
...
QtObject {
    Window {
        id: someSysUIWindow
        visible: true
        ...
        Component.onCompleted: {
            WindowManager.registerCompositorView(someSysUIWindow);
        }
    }
}

则可重写为

import QtApplicationManager.SystemUI 2.0
...
QtObject {
    Window {
        id: someSysUIWindow
        visible: true
        ...
    }
}

系统监控器

系统监控器单例不再存在。它提供的功能被分割到多个新组件中，包括：MonitorModel、CpuStatus、GpuStatus、MemoryStatus、FrameTimer和IoStatus。

例如，如果您有如下代码

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
        ...
    }
}

则可重写为

import QtApplicationManager 2.0
...
Item {
    id: root
    ...
    // Draw a graph of CPU usage
    ListView {
        model: MonitorModel {
            interval: 1500
            running: root.visible
            maximumCount: 20
            CpuStatus {}
        }
        ...
    }
}

进程监控器

进程监控器组件不再存在。它提供的功能被分割成几个新组件，包括：ProcessStatus、MonitorModel和FrameTimer。

例如，如果您有如下代码

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"
        }
        ...
    }
}

则可重写为

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"
            }
        }
        ...
    }
}