Qt Quick Android 클래스 보기

QtQuickView 클래스를 사용하면 안드로이드 앱에 QML 콘텐츠를 뷰로 쉽게 추가할 수 있습니다.

상세 설명

QtQuickView 클래스를 사용하면 QML 컨텐츠를 안드로이드 앱에 뷰로 쉽게 추가할 수 있습니다. QtQuickView 는 지정된 QML 컴포넌트 소스(로컬 또는 네트워크 파일)로 QQuickView 를 인스턴스화하여 그 자체에 임베드합니다. 다른 뷰와 마찬가지로 안드로이드 앱의 레이아웃에 추가할 수 있습니다. QtQuickView 는 Qt가 아닌 안드로이드 앱을 QML 콘텐츠로 확장하고 싶지만 전체 앱을 Qt 프레임워크로 만들고 싶지 않을 때 좋은 선택입니다. Qt Quick 의 강력한 기능을 Android 앱에 도입하여 다양한 Qt Quick API를 Android 앱에서 사용할 수 있습니다.

이 클래스의 일반적인 사용 예시입니다:

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 애플리케이션과 비교하여 main.cpp에서 필요한 변경 사항

QtQuickView는 앱의 창 생성 및 QML 콘텐츠 로드를 처리합니다. 안드로이드 프로젝트에 임베드하는 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 을 참조하세요.

알려진 문제

다음은 이 API와 관련된 알려진 문제입니다. 이러한 문제는 패치 릴리스에서 해결 및 제거될 수 있습니다.

활동 재생성으로 인해 애플리케이션 충돌이 발생함

방향 및 기타 구성을 변경하면 활동이 다시 만들어집니다.

자세한 내용은 {https://bugreports.qt.io/browse/QTBUG-123711}{QTBUG-123711}을 참조하세요.

액티비티를 다시 만들지 않고 애플리케이션 내에서 회전을 수동으로 처리하는 방법에 대한 예는 안드로이드 스튜디오 프로젝트용Qt Quick 을 참조하십시오.

안드로이드 서비스에서의 QtQuickView

안드로이드 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

한 번에 여러 QtQuickView를 인스턴스화하는 것도 가능합니다:

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(컨텍스트 부모, 문자열 qmlUri, 문자열 appName)

QML 컴퍼넌트를 로드, 렌더링 하는 QtQuickView를 작성합니다. QtQuickView를 인스턴스화하면 appName에 지정된 앱 라이브러리를 포함한 Qt 라이브러리가 로드됩니다. 그런 다음 qmlUri로 지정된 QML 소스를 로드하는 QQuickView 를 생성합니다.

파라미터

• context: 상위 컨텍스트입니다.
• qmlUri: 메인 QML 파일의 URI.
• appName: 로드하고 시작할 Qt 앱 라이브러리의 이름입니다. 이는 Qt 앱의 CMakeLists.txt에 설정된 대상 이름에 해당합니다.

Throws

파라미터가 유효하지 않은 경우 InvalidParameterException을 던집니다.

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

QML 컴퍼넌트를 로드하고 보기 위한 QtQuickView를 작성합니다. QtQuickView를 인스턴스화하면 appName으로 지정된 앱 라이브러리를 포함한 Qt 라이브러리가 로드됩니다. 그런 다음 qmlUri로 지정된 QML 소스를 로드하는 QQuickView 을 생성합니다. 이 오버로드는 QML 애플리케이션이 사용자 정의 경로에서 QML 모듈을 로드해야 하는 경우 문자열 배열 qmlImportPaths를 받아들입니다.

파라미터

• context: 상위 컨텍스트입니다.
• qmlUri: 기본 QML 파일의 URI입니다.
• appName: 로드하고 시작할 Qt 앱 라이브러리의 이름입니다. 이는 Qt 앱의 CMakeLists.txt에 설정된 대상 이름에 해당합니다.
• qmlImportPaths: 전달할 추가 가져오기 경로에 대한 문자열 배열입니다.

Throws

파라미터가 유효하지 않은 경우 InvalidParameterException을 던집니다.

인터페이스

공용 인터페이스 SignalListener<T>

신호가 방출되었을 때 안드로이드 UI 스레드에서 호출됩니다.

파라미터

• signalName: 리터럴 신호 이름
• value: 신호가 전달한 값 또는 매개변수가 없는 신호인 경우 null입니다.

공용 인터페이스 StatusChangeListener

QML 컴포넌트 상태가 변경되었을 때 안드로이드 UI 스레드에서 호출됩니다.

파라미터

• status: 현재 상태입니다.

필드

상태 값

상태는 상태_null, 상태_준비, 상태_로드 중 또는 상태_오류일 수 있습니다. 자세한 내용은 QQuickView::Status 을 참조하세요.

메소드

public void setProperty(String propertyName, Object value)

QML 루트 객체의 기존 프로퍼티의 값을 설정합니다. 지원되는 타입은 Integer, Double, Float, Boolean, String 입니다. 이러한 유형은 해당 QML 유형인 int, double/float, bool 및 string으로 변환됩니다. 이 함수는 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을 반환합니다.

Throws

형 변환에 실패하면 ClassCastException을 던집니다.

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

시그널 리스너를 QML 루트 객체의 신호에 연관시킵니다.

파라미터

• signalName: 루트 객체 신호의 이름입니다.
• argType: 신호 인자의 클래스 유형.
• listener: SignalListener 인터페이스의 인스턴스.

반환값

신호와 리스너 사이의 Connection ID 또는 동일한 신호와 리스너 사이에 기존 연결이 있는 경우 기존 연결 ID를 반환합니다. 신호가 QML 루트 객체에 존재하지 않으면 음수 값을 반환합니다.

public boolean removeSignalListener(int signalListenerId)

추가 시그널 리스너() 호출로부터 취득한 지정된 ID의 시그널 리스너의 신호의 수신을 중지합니다.

파라미터

• signalListenerId: 연결 ID.

반환값

연결 ID가 유효하고 성공적으로 제거되면참을 반환하고, 그렇지 않으면 거짓을 반환합니다.

public int getStatus()

QML 컴퍼넌트의 상태를 리턴합니다.

리턴

QML이 준비되면STATUS_READY를 반환합니다. setProperty(), getProperty(), addSignalListener() 등 QML 루트 객체에서 작동하는 메서드를 호출하면 현재 상태가 STATUS_READY 인 경우에만 성공합니다. 또한 기본 QQuickView 인스턴스의 상태를 나타내는 다른 상태 값을 반환할 수도 있습니다.

public void setStatusChangeListener(StatusChangeListener listener)

상태 변경을 리스닝할 스테이터스 체인지 리스너를 설정합니다.

파라미터

• listener: StatusChangeListener 인터페이스의 인스턴스.