Qt Quick 查看 Android 类

QtQuickView 类可让您轻松地将 QML 内容作为视图添加到 Android 应用程序中。

详细描述

QtQuickView 类可让您轻松地将 QML 内容作为View 添加到您的 Android 应用程序中。QtQuickView 使用给定的 QML 组件源（本地或网络文件）实例化QQuickView 并将其嵌入到自身中。您可以像使用其他View 一样将其添加到您的 Android 应用程序布局中。当您想用 QML 内容扩展您的非 Qt Android 应用程序，但又不想使用 Qt 框架制作整个应用程序时，QtQuickView 是一个不错的选择。它将Qt Quick 的强大功能引入 Android 应用程序，使在 Android 应用程序中使用各种Qt Quick API 成为可能。

该类的典型用法：

import org.qtproject.qt.qml.target.Main;
...

private Main m_mainQmlContent;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    ...
    m_mainQmlContent = new Main();
    QtQuickView qmlView = new QtQuickView(this);

    layout.addView(qmlView, params);

    qmlView.loadContent(m_mainQmlContent);
    ...
}

与 Qt for Android 应用程序相比，main.cpp 中需要进行的修改

QtQuickView 将处理应用程序窗口的创建和 QML 内容的加载。嵌入到 Android 项目中的 QML 项目的主函数不需要做这两件事。创建QGuiApplication 和starting the event loop 即可。以下是 QML 项目所需的最低main.cpp 。

#include <QGuiApplication>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    return app.exec();
}

有关更详细的示例，请参阅Qt Quick for Android Studio Projects。

已知问题

以下是此 API 的已知问题。这些问题可能会在补丁发布时得到解决并删除。

活动重现导致应用程序崩溃

方向和其他配置更改将重新创建活动。

有关详细信息，请参阅QTBUG-123711。

有关如何在应用程序内手动处理旋转而无需重新创建 Activity 的示例，请参见Qt Quick for Android Studio Projects。

Android 服务中的 QtQuickView

通过使用 Android WindowManager 接口，也可以在服务上下文中添加 QtQuickView：

import org.qtproject.qt.qml.target.Main;
...
private Main m_mainQmlContent;
@Override
public void onCreate() {
    m_windowManager = getSystemService(WindowManager.class);

    m_mainQmlContent = new Main();
    QtQuickView qmlView = new QtQuickView(this)

    WindowManager.LayoutParams layoutParams = new WindowManager.LayoutParams(
            640, 320,
            WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY,
            WindowManager.LayoutParams.FLAG_LAYOUT_NO_LIMITS,
            PixelFormat.TRANSLUCENT);

    m_windowManager.addView(m_qtView, layoutParams);

    qmlView.loadContent(m_mainQmlContent);
}

要清理 QtQuickView 和 Qt 库，可以使用 onDestroy() 生命周期函数：

@Override
public void onDestroy() {
    super.onDestroy();
    m_windowManager.removeView(m_qtView);
    m_qtView = null;
}

一个活动中的多个 QtQuickViews

同时实例化多个 QtQuickViews 也是可能的：

import org.qtproject.qt.qml.target.Main;
import org.qtproject.qt.qml.target.Second;
...

private Main m_mainQmlContent;
private Second m_secondQmlContent;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    ...

    m_mainQmlContent = new Main();
    m_secondQmlContent = new Second();

    QtQuickView qmlView = new QtQuickView(this);
    QtQuickView secondQmlView = new QtQuickView(this);

    layout.addView(qmlView, params);
    layout.addView(secondQmlView, secondParams);

    qmlView.loadContent(m_mainQmlContent);
    secondQmlView.loadContent(m_secondQmlContent);
    ...
}

构造函数

public QtQuickView(Context parent, String qmlUri, String appName)

创建 QtQuickView 以加载并渲染 QML 组件。实例化 QtQuickView 将加载 Qt 库，包括appName 指定的应用程序库。然后，它会创建一个QQuickView ，加载由qmlUri 指定的 QML 源。

参数

• context：父上下文。
• qmlUri：主 QML 文件的 URI。
• appName：要加载和启动的 Qt 应用程序库的名称。这与 Qt 应用程序的 CMakeLists.txt 中设置的目标名称一致。

抛出

如果参数无效，则抛出InvalidParameterException 异常。

public QtQuickView(Context context, String qmlUri, String appName, String[] qmlImportPaths)

创建一个 QtQuickView 来加载和查看 QML 组件。实例化 QtQuickView 将加载 Qt 库，包括appName 指定的应用程序库。然后，它会创建一个QQuickView ，加载由qmlUri 指定的 QML 源。如果 QML 应用程序要从自定义路径加载 QML 模块，该重载会接受qmlImportPaths字符串数组。

参数

• context：父 Context。
• qmlUri：主 QML 文件的 URI。
• appName：要加载和启动的 Qt 应用程序库的名称。这与 Qt 应用程序的 CMakeLists.txt 中设置的目标名称一致。
• qmlImportPaths：字符串数组，用于传递其他导入路径。

抛出

如果参数无效，则抛出InvalidParameterException 异常。

接口

公共接口 SignalListener<T>

当信号发出时在 Android UI 线程上调用。

参数

• signalName：字面信号名
• value：信号传递的值，如果信号没有参数，则为空。

公共接口 StatusChangeListener

当 QML 组件状态发生变化时，在 Android UI 线程上调用。

参数

• 状态：当前状态。

字段

状态值

状态可以是NULL、READY、LOADING或ERROR。更多信息，请参阅QQuickView::Status 。

方法

public void setProperty(String propertyName, Object value)

设置 QML 根对象上现有属性的值。支持的类型有Integer,Double,Float,Boolean, 和String 。这些类型会被转换成相应的 QML 类型 int、double/float、bool 和 string。如果 QML 根对象不存在属性，该函数不会将其添加到 QML 根对象中。

参数

• propertyName：要设置值的现有根对象属性的名称
• value：属性值

public <T extends Object> T getProperty(String propertyName)

获取 QML 根对象现有属性的值。支持的返回类型有整数（Integer）、双（Double）、浮点数（Float）、布尔（Boolean）和字符串（String）。这些类型由相应的 QML 类型 int、double/float、bool 和 string 转换而来。

参数

• propertyName：现有根对象属性的名称。

返回值

如果属性不存在或 QML 组件的状态不是STATUS_READY，此函数将返回 null。

抛出

如果类型转换失败，则抛出ClassCastException。

public <T> int addSignalListener(String signalName, Class<T> argType, SignalListener<T> listener)

将一个SignalListener与 QML 根对象的信号关联。

参数

• signalName：根对象信号的名称。
• argType：信号参数的类类型。
• listener：SignalListener 接口的实例。

返回值

信号和监听器之间的Connection ID 或现有连接 ID（如果同一信号和监听器之间存在现有连接）。如果 QML 根对象上不存在信号，则返回负值。

public boolean removeSignalListener(int signalListenerId)

使用从addSignalListener()调用中获得的给定 id 停止信号监听器 监听信号。

参数

• signalListenerId：连接 ID。

返回值

如果连接 ID 有效且已成功移除，则返回true，否则返回 false。

公共 int getStatus()

获取 QML 组件的状态。

返回值

当 QML 已准备就绪时，返回STATUS_READY。只有在当前状态为STATUS_READY 时，调用操作 QML 根对象的方法（如setProperty()、getProperty () 和addSignalListener()） 才会成功。它还可以返回其他状态值，代表底层QQuickView 实例的状态。

public void setStatusChangeListener(StatusChangeListener listener)

设置StatusChangeListener以监听状态变化。

参数

• listener：StatusChangeListener接口的实例。