diff options
Diffstat (limited to 'src/corelib/doc')
| -rw-r--r-- | src/corelib/doc/snippets/signalsandslots/signalsandslots.h | 2 | ||||
| -rw-r--r-- | src/corelib/doc/src/cmake/cmake-configure-variables.qdoc | 23 | ||||
| -rw-r--r-- | src/corelib/doc/src/cmake/cmake-properties.qdoc | 50 | ||||
| -rw-r--r-- | src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc | 1 | ||||
| -rw-r--r-- | src/corelib/doc/src/foreach-keyword.qdoc | 3 | ||||
| -rw-r--r-- | src/corelib/doc/src/jni.qdoc | 230 | ||||
| -rw-r--r-- | src/corelib/doc/src/objectmodel/metaobjects.qdoc | 3 | ||||
| -rw-r--r-- | src/corelib/doc/src/objectmodel/properties.qdoc | 25 |
8 files changed, 322 insertions, 15 deletions
diff --git a/src/corelib/doc/snippets/signalsandslots/signalsandslots.h b/src/corelib/doc/snippets/signalsandslots/signalsandslots.h index 2f5a53231c..a590e8fd5e 100644 --- a/src/corelib/doc/snippets/signalsandslots/signalsandslots.h +++ b/src/corelib/doc/snippets/signalsandslots/signalsandslots.h @@ -33,6 +33,8 @@ class Counter : public QObject { Q_OBJECT +// Note. The Q_OBJECT macro starts a private section. +// To declare public members, use the 'public:' access modifier. public: Counter() { m_value = 0; } diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc index b710ba7275..8422a688f0 100644 --- a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -318,6 +318,29 @@ The mentioned variables are used internally by \l{androiddeployqt}. */ /*! +\page cmake-variable-qt-android-generate-java-qml-components.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_GENERATE_JAVA_QML_COMPONENTS +\target cmake-variable-QT_ANDROID_GENERATE_JAVA_QML_COMPONENTS + +\summary {Enables the generation of QtQmlComponent-based classes.} +\cmakevariablesince 6.8 +\preliminarycmakevariable +\cmakevariableandroidonly + +This variable enables Java code generation for QML components of the target application. The +generated code will be included in the resulting package. The Java package name of generated +classes will be the same as the Android app package. If the leaf part of the package name is +not the same as the target executable, an extra static class with the same name as the +capitalized target executable will surround all QML modules enclosing Java classes. Each QML +module class, again in a capitalized form, will contain QtQmlComponent extension classes that +represent QML components of that module. +*/ + +\sa{androiddeployqt} +/*! \page cmake-variable-qt-use-target-android-build-dir.html \ingroup cmake-variables-qtcore diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc index 8fe2b0e88f..4b602d5d07 100644 --- a/src/corelib/doc/src/cmake/cmake-properties.qdoc +++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc @@ -245,6 +245,56 @@ CMake will attempt to use the latest installed version. */ /*! +\page cmake-target-property-qt-android-package-name.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_PACKAGE_NAME +\target cmake-target-property-QT_ANDROID_PACKAGE_NAME + +\summary {The app's package name.} + +\cmakepropertysince 6.8 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the app's package name. This is usually a unique dot separated +name for the app, that will be used to identify the app on devices or in +the Play Store. For example, "org.qtproject.example.gallery". + +The package name set by this property is passed to the \c build.gradle file +as a \c namespace property, instead of \c AndroidManifest.xml, since the +latter is deprecated since Android Gradle Plugin 7.4. + +The package name considers some words or characters as illegal and the build +will clean such names if any is encountered. An underscore (\c _) either replaces +illegal characters or is appended to illegal words. + +\list + \li Allowed characters: alphanumeric, an underscore or a dot [a-zA-Z0-9_.]. + \li Illegal words: abstract, continue, for, new, switch, assert, default, + if, package, synchronized, boolean, do, goto, private, this, break, + double, implements, protected, throw, byte, else, import, public, + throws, case, enum, instanceof, return, transient, catch, extends, + int, short, try, char, final, interface, static, void, class, finally, + long, strictfp, volatile, const, float, native, super, while. +\endlist + +The default package name for Qt for Android apps is \c org.qtproject.example.<target_name>. + +\note Setting the package name manually in \c build.gradle (via +\c namespace property) takes precedence over \c AndroidManifest.xml +(via \c package attribute), and the latter also takes precedence over +this property. + +For more information, see Android's +\l{Android: Configure the app module}{configure the app module}. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! \page cmake-target-property-qt-android-version-code.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore diff --git a/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc index 5a7bbdc33f..daa3680070 100644 --- a/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc @@ -63,6 +63,7 @@ how to accomplish this. \li \l{cmake-target-property-QT_ANDROID_MIN_SDK_VERSION}{QT_ANDROID_MIN_SDK_VERSION} \li \l{cmake-target-property-QT_ANDROID_PACKAGE_SOURCE_DIR}{QT_ANDROID_PACKAGE_SOURCE_DIR} \li \l{cmake-target-property-QT_ANDROID_TARGET_SDK_VERSION}{QT_ANDROID_TARGET_SDK_VERSION} +\li \l{cmake-target-property-QT_ANDROID_PACKAGE_NAME}{QT_ANDROID_PACKAGE_NAME} \li \l{cmake-target-property-QT_ANDROID_VERSION_NAME}{QT_ANDROID_VERSION_NAME} \li \l{cmake-target-property-QT_ANDROID_VERSION_CODE}{QT_ANDROID_VERSION_CODE} \li \l{cmake-target-property-QT_QML_IMPORT_PATH}{QT_QML_IMPORT_PATH} diff --git a/src/corelib/doc/src/foreach-keyword.qdoc b/src/corelib/doc/src/foreach-keyword.qdoc index b3a4482528..6aa21d5880 100644 --- a/src/corelib/doc/src/foreach-keyword.qdoc +++ b/src/corelib/doc/src/foreach-keyword.qdoc @@ -81,7 +81,10 @@ /*! \macro QT_NO_FOREACH \since 6.0 + \relates <QtGlobal> Defining this macro removes the availability of Qt's \c foreach loop. + + \sa QT_NO_KEYWORDS */ diff --git a/src/corelib/doc/src/jni.qdoc b/src/corelib/doc/src/jni.qdoc new file mode 100644 index 0000000000..d05dd44ff6 --- /dev/null +++ b/src/corelib/doc/src/jni.qdoc @@ -0,0 +1,230 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \namespace QtJniTypes + \inmodule QtCore + \ingroup frameworks-technologies + \keyword JNI + \since 6.8 + + \brief The QtJniTypes namespace declares C++ types that correspond to Java types. + + The \l{Java Native Interface Specification}{Java Native Interface} + framework enables native C or C++ code to call Java APIs, and to register + native C or C++ functions that Java code should be able to call with the + JVM. In Qt, the QJniObject and QJniEnvironment types provide convenient + wrappers for using JNI. + + Since the Java language, similar to C++, supports overloading, functions + need to be specified including their entire signature string. This is + complex, repetitive, and error prone, especially when functions take + several parameters. QJniObject provides variadic template APIs that can + deduce the signature string for a function call at compile time, based on + the C++ types passed into the template. For this to work, the mapping of + those C++ types to their corresponding JNI string needs to be known at + compile time. + + Qt implements this mapping for the standard \l {JNI types}. + By using the Q_DECLARE_JNI_CLASS macro, the mapping can be extended for + arbitrary Java types. + + \sa Q_DECLARE_JNI_CLASS, Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_METHOD +*/ + +/*! + \macro Q_DECLARE_JNI_TYPE(Type, JavaSignature) + \internal + \relates QtJniTypes + \since 6.8 + + Declares a C++ type \a Type in the QtJniTypes namespace that wraps the Java + type \a JavaSignature. The signature needs to start with \c{[L} to indicate + an array of a class, or with \c{L} for classes, and end with a semicolon + \c{;}. + + \code + Q_DECLARE_JNI_TYPE(StringArray, "[Ljava/lang/String;") + \endcode + + \sa Q_DECLARE_JNI_CLASS +*/ + +/*! + \macro Q_DECLARE_JNI_CLASS(Type, JavaSignature) + \relates QtJniTypes + \since 6.8 + + Declares a C++ type \a Type in the QtJniTypes namespace that wraps the Java + class \a JavaSignature. The Java class name in \a JavaSignature needs to be + fully qualified, using \c{/} as the separator. + + \code + Q_DECLARE_JNI_CLASS(File, "java/io/File") + Q_DECLARE_JNI_CLASS(FileWriter, "java/io/FileWriter") + \endcode + + The C++ classes \c{QtJniTypes::File} and \c{QtJniTypes::FileWriter} are + then QJniObject-like types that can be used to instantiate the + corresponding Java class, to call methods, and to pass such instances + through QJniObject variadic template methods with automatic, compile-time + signature deduction. + + \code + using namespace QtJniTypes; + + File file("path/to/file"); // instantiates the java.io.File type in Java + if (file.callMethod<bool>("createNewFile")) { + FileWriter writer(file); // instantiates a java.io.FileWriter that operates on file + writer.callMethod("write", 42); + } + \endcode + + In addition to the QJniObject API, those C++ classes also have a static + \c{registerNativeMethods} member function that can be used like this: + + \code + QtJniTypes::File::registerNativeMethods({ + Q_JNI_NATIVE_METHOD(freeFunction) + }); + \endcode + + \sa Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_METHOD +*/ + +/*! + \macro Q_DECLARE_JNI_NATIVE_METHOD(Method) + \relates QtJniTypes + \since 6.8 + + Declares the free C or C++ function \a Method as a native method. The + method can later be registered with the JNI framework using + QJniEnvironment::registerNativeMethod() with the help of the + Q_JNI_NATIVE_METHOD macro. + +//! [register-free-function] + \code + // C++ side + + Q_DECLARE_JNI_CLASS(MyJavaType, "my/java/Type") + + static void nativeFunction(JNIEnv *env, jobject thiz, jlong id) + { + // ... + } + Q_DECLARE_JNI_NATIVE_METHOD(nativeFunction) + + Q_DECL_EXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) + { + QJniEnvironment env; + env.registerNativeMethods<QtJniTypes::MyJavaType>({ + Q_JNI_NATIVE_METHOD(nativeFunction) + }); + } + + // Java side + public class MyJavaType + { + native public nativeFunction(long id); + } + \endcode +//! [register-free-function] + + \sa Q_JNI_NATIVE_METHOD, Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE +*/ + +/*! + \macro Q_DECLARE_JNI_NATIVE_METHOD(Method, JavaName) + \relates QtJniTypes + \overload + \since 6.8 + + Declares the free C or C++ function \a Method as a native method that's + available in Java as \a JavaName. The method can later be registered with + the JNI framework using QJniEnvironment::registerNativeMethod() with the + help of the Q_JNI_NATIVE_METHOD macro. + + \sa Q_JNI_NATIVE_METHOD, Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE +*/ + +/*! + \macro Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(Method) + \relates QtJniTypes + \since 6.8 + + Declares the C++ static class member function \a Method as a native method. + The method can later be registered with the JNI framework using + QJniEnvironment::registerNativeMethod() with the help of the + Q_JNI_NATIVE_SCOPED_METHOD macro. + +//! [register-scoped-function] + \code + class NativeHandler + { + // ... + private: + static void handleChange(JNIEnv*, jobject, jlong id); + Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(handleChange) + }; + + \dots + QJniEnvironment env; + env.registerNativeMethods<QtJniTypes::MyJavaType>({ + Q_JNI_NATIVE_SCOPED_METHOD(handleChange, NativeHandler) + }); + \endcode +//! [register-scoped-function] + + \sa Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_SCOPED_METHOD +*/ + +/*! + \macro Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(Method, JavaName) + \relates QtJniTypes + \overload + \since 6.8 + + Declares the C++ static class member function \a Method as a native method + that's available in Java as \a JavaName. The method can later be registered + with the JNI framework using QJniEnvironment::registerNativeMethod() with + the help of the Q_JNI_NATIVE_METHOD macro. + + \sa Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_SCOPED_METHOD +*/ + +/*! + \macro Q_JNI_NATIVE_METHOD(Method) + \relates QtJniTypes + \since 6.8 + + Makes the previously \l{Q_DECLARE_JNI_NATIVE_METHOD}{declared} native + method \a Method available for registration with the JNI framework. Use + this macro when registering the method with JNI using + QJniEnvironment::registerNativeMethod(). + + \code + Q_DECL_EXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) + { + QJniEnvironment env; + env.registerNativeMethods<QtJniTypes::MyJavaType>({ + Q_JNI_NATIVE_METHOD(nativeFunction) + }); + } + \endcode + + \sa Q_DECLARE_JNI_NATIVE_METHOD +*/ + +/*! + \macro Q_JNI_NATIVE_SCOPED_METHOD(Method, Scope) + \relates QtJniTypes + \since 6.8 + + Makes the previously + \l{Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE}{declared} native method + \a Method in scope \a Scope available for registration with the JNI framework. + Use this macro when registering the method with JNI using + QJniEnvironment::registerNativeMethod(). + + \sa Q_JNI_NATIVE_METHOD, Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE +*/ diff --git a/src/corelib/doc/src/objectmodel/metaobjects.qdoc b/src/corelib/doc/src/objectmodel/metaobjects.qdoc index 3d7685447f..44f574816e 100644 --- a/src/corelib/doc/src/objectmodel/metaobjects.qdoc +++ b/src/corelib/doc/src/objectmodel/metaobjects.qdoc @@ -19,8 +19,7 @@ \list 1 \li The \l QObject class provides a base class for objects that can take advantage of the meta-object system. - \li The Q_OBJECT macro inside the private section of the class - declaration is used to enable meta-object features, such as + \li The Q_OBJECT macro is used to enable meta-object features, such as dynamic properties, signals, and slots. \li The \l{moc}{Meta-Object Compiler} (\c moc) supplies each QObject subclass with the necessary code to implement diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index 99a3e60d88..0e66c8445c 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -186,12 +186,11 @@ \section1 A Simple Example - Suppose we have a class MyClass, which is derived from QObject and - which uses the Q_OBJECT macro in its private section. We want to - declare a property in MyClass to keep track of a priority - value. The name of the property will be \e priority, and its type - will be an enumeration type named \e Priority, which is defined in - MyClass. + Suppose we have a class \c MyClass, which is derived from QObject and which + uses the Q_OBJECT macro. We want to declare a property in \c MyClass to keep + track of a priority value. The name of the property will be \c priority, and + its type will be an enumeration type named \c Priority, which is defined in + \c MyClass. We declare the property with the Q_PROPERTY() macro in the private section of the class. The required \c READ function is named \c @@ -200,7 +199,7 @@ System} using the Q_ENUM() macro. Registering an enumeration type makes the enumerator names available for use in calls to QObject::setProperty(). We must also provide our own declarations - for the \c READ and \c WRITE functions. The declaration of MyClass + for the \c READ and \c WRITE functions. The declaration of \c MyClass then might look like this: \snippet code/doc_src_properties.cpp 5 @@ -213,24 +212,24 @@ potentially forcing re-evaluation in other places if nothing has changed. - Given a pointer to an instance of MyClass or a pointer to a - QObject that is an instance of MyClass, we have two ways to set + Given a pointer to an instance of \c MyClass or a pointer to a + QObject that is an instance of \c MyClass, we have two ways to set its priority property: \snippet code/doc_src_properties.cpp 6 In the example, the enumeration type that is the property type is - declared in MyClass and registered with the \l{Meta-Object System} + declared in \c MyClass and registered with the \l{Meta-Object System} using the Q_ENUM() macro. This makes the enumeration values - available as strings for use as in the call to \l{QObject::}{setProperty()}. Had - the enumeration type been declared in another class, its fully + available as strings for use as in the call to \l{QObject::}{setProperty()}. + Had the enumeration type been declared in another class, its fully qualified name (i.e., OtherClass::Priority) would be required, and that other class would also have to inherit QObject and register the enumeration type there using the Q_ENUM() macro. A similar macro, Q_FLAG(), is also available. Like Q_ENUM(), it registers an enumeration type, but it marks the type as being a - set of \e flags, i.e. values that can be OR'd together. An I/O + set of \e flags, i.e., values that can be OR'd together. An I/O class might have enumeration values \c Read and \c Write and then QObject::setProperty() could accept \c{Read | Write}. Q_FLAG() should be used to register this enumeration type. |