qiurui
/
qtdeclarative
mirror of https://github.com/qt/qtdeclarative.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs: Update existing and add missing links to online Java docs 

-Updated QtQuickView and QtQuickViewContent links to new pages.
-Added links to QtQmlStatus Enum and QtQmlStatusChangeListener interface
classes.
-Removed the qdoc QtQuickView file.
-Updated links in examples and the main Qt Quick for Android page.

Task-number: QTBUG-127747
Fixes: QTBUG-138917
Fixes: QTBUG-123106
Fixes: QTBUG-135474
Pick-to: 6.10 6.10.0 6.9 6.8
Change-Id: I61a64c8637c222290e4c630d75d579f6bb23886c
Reviewed-by: Ville Voutilainen <ville.voutilainen@qt.io>
This commit is contained in:
Nicholas Bennett 2025-09-01 13:15:10 +03:00
parent 47d331a831
commit ba9f204e12
6 changed files with 46 additions and 395 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
examples/platforms/android/doc/src/qtabstractitemmodel_in_android_studio_projects.qdoc
View File

@ -20,7 +20,7 @@
You can import the QML project into an Android project.
The example shows how to handle complex data types between Java and QML.
It demonstrates how to use the \c QtAbstractItemModel and \c QtModelIndex
It demonstrates how to use the \l QtAbstractItemModel and \l QtModelIndex
Java API classes. In QML, the data usage is demonstrated with the TableView item.
In Java, data usage is demonstrated with a model of nested ArrayList items
for rows and columns. For more information on how QML works, see \l {Qt Qml}.
@ -70,7 +70,7 @@
\section2 Data Model
The data model, \c MyDataModel, extends \c QtAbstractItemModel class.
The data model, \c MyDataModel, extends \l QtAbstractItemModel class.
The \c QtAbstractItemModel is a wrapper for \l {QAbstractItemModel}.
As the methods of \c MyDataModel class are called from both, QML and Android sides, the
@ -83,7 +83,7 @@
\snippet android/models/qtabstractitemmodel_java/app/src/main/java/com/example/qtabstractitemmodel_java/MyDataModel.java 1
The example overrides the \c QtAbstractItemModel methods for different purposes. The
The example overrides the \l QtAbstractItemModel methods for different purposes. The
columnCount() and rowCount() methods return the count of each in a model. The execution of
each rowCount() occurs in both thread contexts, Qt qtMainLoopThread and Android main thread
contexts.
@ -110,7 +110,7 @@
The example implements methods on the model side for \c MainActivity UI interaction to add
and remove rows and columns. Calls begin, end, insert, and remove rows to update model
indexes, like beginInsertRow().
Because the example uses the \c QtAbstractItemModel, it must call beginInsertRows() and
Because the example uses the \l QtAbstractItemModel, it must call beginInsertRows() and
endInsertRows() every time it inserts new rows into the model. The same applies to removal.
As the methods are called from the Android side, the execution takes place in the Android
main thread context.
@ -126,7 +126,7 @@
\section2 Main Activity
\c MainActivity implements the \c QtQmlStatusChangeListener interface to get status updates
\c MainActivity implements the \l QtQmlStatusChangeListener interface to get status updates
when the QML is loaded. It is also the main Android activity.
The example creates and initializes the data model. See also

15
examples/platforms/android/doc/src/qtabstractlistmodel_kotlin_example.qdoc
View File

@ -16,9 +16,8 @@
This example consists of two separate projects: A QML project and a Kotlin-based Android
project which will host and display the QML content. It shows how to use
\l{QtAbstractListModel Android Class}{QtAbstractListModel}
to share data from the Android side to the QML view which displays the data using a
\l ListView.
\l{QtAbstractListModel} to share data from the Android side to the QML view which displays
the data using a \l ListView.
\section1 Running the example
@ -59,7 +58,7 @@
\section2 Data model
The data model \c MyListModel is a child class of \l{QtAbstractListModel Android Class}{QtAbstractListModel}, with
The data model \c MyListModel is a child class of \l{QtAbstractListModel}, with
\c ArrayList<String> as the internal storage system for data. In the initializer block of
\c MyListModel, it generates some random data for the list.
@ -80,7 +79,7 @@
\snippet android/models/qtabstractlistmodel_kotlin/app/src/main/java/com/example/qtabstractlistmodel_kotlin/MyListModel.kt MyListModel::DataRole enum
When it comes to returning data from the data model, the class must override the
\c "QtAbstractListModel::data()" method. This method takes two parameters: \l{QtModelIndex Android Class}{QtModelIndex} and
\c "QtAbstractListModel::data()" method. This method takes two parameters: \l{QtModelIndex} and
\c Int, which refer to the index and role of the data element, respectively.
In \c "MyDataModel::data()", the \c UUID role returns the data from the given index in the
@ -93,7 +92,7 @@
\snippet android/models/qtabstractlistmodel_kotlin/app/src/main/java/com/example/qtabstractlistmodel_kotlin/MyListModel.kt MyListModel::data
To allow outside actors to manipulate the QtAbstractItemModel, the example adds two additional
To allow outside actors to manipulate the \l QtAbstractItemModel, the example adds two additional
methods to \c MyDataModel. To add data to the row, it has the \c "addRow()" method; to remove
data, there is the \c "removeRow()" method. These are used from the main activity.
@ -105,7 +104,7 @@
The \c MainActivity class is a simple Kotlin-based Activity but also implements the
\l{interface QtQmlStatusChangeListener} to listen to QML loading status events. It also
stores the \c QtQuickViewContent object for the main view of the QML application and an instance
stores the \l QtQuickViewContent object for the main view of the QML application and an instance
of the data model detailed above.
\snippet android/models/qtabstractlistmodel_kotlin/app/src/main/java/com/example/qtabstractlistmodel_kotlin/MainActivity.kt MainActivity definition
@ -123,7 +122,7 @@
Once the UI setup and listeners are done, the QML component can be prepared and loaded. The
example sets the \c MainActivity as a listener for the status change signal of the QML
component and tells \c QtQuickView to load the QML component.
component and tells \l QtQuickView to load the QML component.
\snippet android/models/qtabstractlistmodel_kotlin/app/src/main/java/com/example/qtabstractlistmodel_kotlin/MainActivity.kt Loading the QML component

21
examples/platforms/android/doc/src/qtquick_for_android_studio_projects.qdoc
View File

@ -17,7 +17,7 @@
This example contains a QML project you can import into Android Studio
with the \l {Qt Tools for Android Studio} plugin. There are Java and Kotlin
projects that use the QML project as a View by utilizing the
\l {Qt Quick View Android Class}{QtQuickView} API.
\l QtQuickView API.
For more information on how QML works, see \l {Qt Qml}. This
documentation focuses on how a QML component is embedded into
@ -116,9 +116,8 @@
\endif
Inside the \c onCreate() method, previously declared variables
are initialized with new \l {Qt Quick View Android Class}{QtQuickView}
instances. These instances take the \c Context of the Java/Kotlin
Activity as arguments.
are initialized with new \l {QtQuickView} instances. These instances
take the \c Context of the Java/Kotlin Activity as arguments.
\if defined(onlinedocs)
\tab {m_qtQuickView}{tab-java}{Java}{checked}
@ -143,7 +142,7 @@
\endtabcontent
\endif
The \c QtQuickView instances are added to the Android layout with appropriate layout
The \l QtQuickView instances are added to the Android layout with appropriate layout
parameters.
\if defined(onlinedocs)
@ -170,7 +169,7 @@
\endif
The \c Main and \c Second Java classes inherit from the
\c QtQuickViewContent class. These classes are generated from the QML
\l QtQuickViewContent class. These classes are generated from the QML
project that we've imported.
\if defined(onlinedocs)
@ -197,7 +196,7 @@
\endif
The Qt Quick content is loaded through the \c QtQuickView.loadContent()
method, which takes a \c QtQuickViewContent as an argument.
method, which takes a \l QtQuickViewContent as an argument.
\if defined(onlinedocs)
\tab {loadContent}{tab-java}{Java}{checked}
@ -225,9 +224,9 @@
\section1 Interacting with QML components
To interact with the embedded QML components we implement the
\c QtQmlStatusChangeListener interface and override the \c onStatusChanged
method to get the loading status of the QtQuickViewContent currently being
loaded into the \l {Qt Quick View Android Class}{QtQuickView}.
\l QtQmlStatusChangeListener interface and override the \c onStatusChanged
method to get the loading status of the \l QtQuickViewContent currently being
loaded into the \l {QtQuickView}.
\if defined(onlinedocs)
\tab {listener}{tab-java}{Java}{checked}
@ -316,7 +315,7 @@
The overridden callback function \c onStatusChanged() receives
\c StatusChanged() signal containing the current
status (public Enum QtQmlStatus) of the loading of the current
status, a \l QtQmlStatus Enum, of the loading of the current
\c QtQuickViewContent into the \l QtQuickView. If this \c QtQmlStatus
is confirmed to be \c QtQmlStatus.READY, we can start interacting
with the QML view.

17
src/quick/doc/src/android/qtquick-for-android.qdoc
View File

@ -62,16 +62,23 @@
\target Android Classes
These are the public Java and Kotlin APIs that you will use in an Android
app to embed QML.
//! TODO: Update links to Java API docs when published
\section2 Java classes
\list
\li \l{QtQuickView}
\li \l{QtQuickViewContent}
\li \l{QtAbstractItemModel Android Class}
\li \l{QtAbstractListModel Android Class}
\li \l{interface QtQmlStatusChangeListener} (which uses the QtQmlStatus enum)
\li \l{QtModelIndex Android Class}
\li \l{QtAbstractItemModel}
\li \l{QtAbstractListModel}
\li \l{QtModelIndex}
\endlist
\section2 Interfaces
\list
\li \l{QtQmlStatusChangeListener} (which uses the \l QtQmlStatus enum)
\endlist
\note See the \l{QT_ANDROID_GENERATE_JAVA_QTQUICKVIEW_CONTENTS} CMake
variable for further information on Java code generation of QML components.

14
src/quick/doc/src/qtquick-external-resources.qdoc
View File

@ -7,11 +7,21 @@
*/
/*!
\externalpage https://code.qt.io/cgit/qt/qtdeclarative.git/tree/src/quick/platform/android/jar/src/org/qtproject/qt/android/QtQuickView.java?h=6.10
\externalpage https://doc.qt.io/qt-6/qtquick/android/org/qtproject/qt/android/QtQuickView.html
\title QtQuickView
*/
/*!
\externalpage https://code.qt.io/cgit/qt/qtdeclarative.git/tree/src/quick/platform/android/jar/src/org/qtproject/qt/android/QtQuickViewContent.java?h=6.10
\externalpage https://doc.qt.io/qt-6/qtquick/android/org/qtproject/qt/android/QtQuickViewContent.html
\title QtQuickViewContent
*/
/*!
\externalpage https://doc.qt.io/qt-6/qtquick/android/org/qtproject/qt/android/QtQmlStatus.html
\title QtQmlStatus
*/
/*!
\externalpage https://doc.qt.io/qt-6/qtquick/android/org/qtproject/qt/android/QtQmlStatusChangeListener.html
\title QtQmlStatusChangeListener
*/

364
src/quick/platform/android/jar/src/org/qtproject/qt/android/QtQuickView.qdoc
View File

@ -1,364 +0,0 @@
// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtquickview-android-class.html
\title Qt Quick View Android Class
\ingroup qt_android_classes
\brief Allows you to add QML content to your Android app as a View.
\since 6.7
The QtQuickView class lets you easily add QML content to your Android app as
a \l {Android: View}{View}.
\target QtQuickView
\table
\row
\li Class:
\li QtQuickView
\row
\li Package Name:
\li org.qtproject.qt.android
\row
\li Extends:
\li org.qtproject.qt.android.QtView
– org.qtproject.qt.android.QtLayout
–– android.view.ViewGroup
\endtable
\section1 Detailed description
The QtQuickView class lets you easily add QML content to your Android app as
a \l {Android: View}{View}. \c QtQuickView instantiates a \l QQuickView with
a given QML component source (a local or network file) and embeds it to itself.
You can add it to your Android app's layout as with any other View. \c QtQuickView
is a good choice when you want to extend your non-Qt Android app with QML content but
do not want to make the entire app using the Qt framework. It brings the power
of Qt Quick into your Android app, making it possible to use various Qt Quick
APIs in Android apps.
\note Although we try to keep QtQuickView as thread-safe as possible, that
can't be guaranteed since it follows the same considerations as
\l {Android: View}{View}. See \l {Android: Event Handling and Threading}
{Event Handling and Threading}.
A typical use of the class:
\code
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);
...
}
\endcode
\section2 Changes needed in main.cpp compared to a Qt for Android application
QtQuickView will handle creating the app's window and loading any QML content. The main
function of the QML project you are embedding into your Android project shouldn't do either.
Creating the \l QGuiApplication and \l{QGuiApplication::exec()}{starting the event loop}
is enough. Below is the minimum required \c main.cpp for your QML project.
\code
#include <QGuiApplication>
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
return app.exec();
}
\endcode
For a more detailed example, see \l {Qt Quick for Android Studio Projects}.
\section1 QtQuickViews can be used in Android Fragments
See the \l{Android Fragments and Qt Quick for Android} tutorial for how to do this.
\section1 Known issues
Here are the known issues with this API. They may be resolved and removed in a patch
release.
\section2 Activity recreation leads to an application crash
\warning Activity recreation may lead to a crash. This is due to resources not being released
properly.
Orientation and other configuration changes will recreate the Activity.
See \l{https://bugreports.qt.io/browse/QTBUG-123711}{QTBUG-123711} for more information.
See \l{Qt Quick for Android Studio Projects} for an example of how to handle rotation
manually inside an application without recreating the Activity.
\section1 QtQuickView in an Android Service
It is also possible to add a QtQuickView from a Service context by using
the Android WindowManager interface:
\code
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);
}
\endcode
To clean up the QtQuickView and Qt libraries, the onDestroy() lifecycle
function can be used:
\code
@Override
public void onDestroy() {
super.onDestroy();
m_windowManager.removeView(m_qtView);
m_qtView = null;
}
\endcode
\note Adding a QtQuickView from a Service context requires your application
to have the \l {Android: SYSTEM_ALERT_WINDOW}{SYSTEM_ALERT_WINDOW}
permission, and to be signed with the platform key.
\note QML views embedded within a Service context do not
support keyboard input or accessibility features.
\section1 Multiple QtQuickViews in an Activity
Instantiating multiple QtQuickViews at once is also possible:
\badcode
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);
...
}
\endcode
\section1 Constructors
\section2 public QtQuickView(Context parent, String qmlUri, String appName)
Creates a QtQuickView to load and render a QML component. Instantiating a
QtQuickView will load the Qt libraries, including the app library specified
by \e appName. Then, it creates a QQuickView that loads the QML source specified
by \e qmlUri.
\section3 Parameters
\list
\li \b context: the parent Context.
\li \b qmlUri: the URI of the main QML file.
\li \b appName: the name of the Qt app library to load and start.
This corresponds to the target name set in the Qt app's CMakeLists.txt.
\endlist
\section3 Throws
Throws a \l {Android: InvalidParameterException}{InvalidParameterException} if
a parameter is invalid.
\section2 public QtQuickView(Context context, String qmlUri, String appName, String[] qmlImportPaths)
Creates a QtQuickView to load and view a QML component. Instantiating a
QtQuickView will load the Qt libraries, including the app library specified
by \e appName. Then, it creates a QQuickView that loads the QML source specified
by \e qmlUri. This overload accepts an array of strings \e qmlImportPaths in the
case where the QML application should load QML modules from custom paths.
\section3 Parameters
\list
\li \b context: the parent Context.
\li \b qmlUri: the URI of the main QML file.
\li \b appName: the name of the Qt app library to load and start.
This corresponds to the target name set in the Qt app's CMakeLists.txt.
\li \b qmlImportPaths: an array of strings for additional import paths to
be passed to.
\endlist
\section3 Throws
Throws a \l {Android: InvalidParameterException}{InvalidParameterException} if
a parameter is invalid.
\section1 Interfaces
\section2 public interface SignalListener<T>
\target SignalListener
Invoked on the Android UI thread when the signal has been emitted.
\section3 Parameters
\list
\li \b signalName: literal signal name
\li \b value: the value delivered by the signal or null if the signal is
without a parameter.
\endlist
\section2 public interface StatusChangeListener
\target StatusChangeListener
Invoked on the Android UI thread when the QML component status has changed.
\section3 Parameters
\list
\li \b status: The current status.
\endlist
\section1 Fields
\section2 Status values
\target Status values
The status can be \e NULL, \e READY, \e LOADING or \e ERROR.
For more information, see \l {QQuickView::Status}.
\section1 Methods
\section2 public void setProperty(String propertyName, Object value)
\target setProperty()
Sets the value of an existing property on the QML root object. The supported
types are \c Integer, \c Double, \c Float, \c Boolean, and \c String. These
types get converted to their corresponding QML types int, double/float, bool,
and string. This function does not add properties to the QML root object if
they do not exist.
\section3 Parameters
\list
\li \b propertyName: the name of the existing root object property to set its value
\li \b value: the value of the property
\endlist
\section2 public <T extends Object> T getProperty(String propertyName)
\target getProperty()
Gets the value of an existing property of the QML root object. The supported
return types are \e Integer, \e Double, \e Float, \e Boolean, and \e String.
These types get converted from their corresponding QML types int, double/float,
bool, and string.
\section3 Parameters
\list
\li \b propertyName: the name of the existing root object property.
\endlist
\section3 Returns
If the property does not exist or the status of the QML component is
anything other than \l {Status values}{STATUS_READY}, this function will return null.
\section3 Throws
Throws a \l {Android: ClassCastException}{ClassCastException} if type casting fails.
\section2 public <T> int addSignalListener(String signalName, Class<T> argType, SignalListener<T> listener)
\target addSignalListener()
Associates a \l {SignalListener} with a signal of the QML root object.
\section3 Parameters
\list
\li \b signalName: the name of the root object signal.
\li \b argType: the Class type of the signal argument.
\li \b listener: an instance of the SignalListener interface.
\endlist
\section3 Returns
A \c {Connection ID} between signal and listener or the existing connection
ID if there is an existing connection between the same signal and listener.
Returns a negative value if the signal does not exist on the QML root object.
\section2 public boolean removeSignalListener(int signalListenerId)
Stops a \l {SignalListener} with a given id obtained from \l addSignalListener()
call, from listening to a signal.
\section3 Parameters
\list
\li \b signalListenerId: the connection ID.
\endlist
\section3 Returns
\e True if the connection ID is valid and has been successfully removed,
otherwise returns false.
\section2 public int getStatus()
\target getStatus()
Gets the \l {Status values}{status} of the QML component.
\section3 Returns
\e STATUS_READY when the QML is ready. Invoking methods that operate on the QML
root object, such as \l {setProperty()}, \l {getProperty()}, and
\l {addSignalListener()}, would succeed \b only if the current status is
\c STATUS_READY. It can also return other \l {Status values}{status} values
representing the status of the underlying QQuickView instance.
\section2 public void setStatusChangeListener(StatusChangeListener listener)
Sets a \l {StatusChangeListener} to listen to status changes.
\section3 Parameters
\list
\li \b listener: an instance of a \l {StatusChangeListener} interface.
\endlist
*/