diff options
7 files changed, 281 insertions, 53 deletions
diff --git a/src/androidextras/androidextras.pro b/src/androidextras/androidextras.pro index f3caeea..24d4371 100644 --- a/src/androidextras/androidextras.pro +++ b/src/androidextras/androidextras.pro @@ -1,6 +1,7 @@ TARGET = QtAndroidExtras DEFINES += QT_NO_USING_NAMESPACE -QMAKE_DOCS = $$PWD/doc/qtandroidextras.qdocconf +QMAKE_DOCS = \ + $$PWD/doc/qtandroidextras.qdocconf QT -= gui QT += core-private load(qt_module) diff --git a/src/androidextras/doc/qtandroidextras.qdocconf b/src/androidextras/doc/qtandroidextras.qdocconf index c69586c..8992696 100644 --- a/src/androidextras/doc/qtandroidextras.qdocconf +++ b/src/androidextras/doc/qtandroidextras.qdocconf @@ -24,18 +24,16 @@ qhp.QtAndroidExtras.subprojects.classes.title = C++ Classes qhp.QtAndroidExtras.subprojects.classes.indexTitle = Qt Android Extras C++ Classes qhp.QtAndroidExtras.subprojects.classes.selectors = class fake:headerfile qhp.QtAndroidExtras.subprojects.classes.sortPages = true - -tagfile = ../../../doc/qtandroidextras/qtandroidextras.tags +qhp.QtAndroidExtras.subprojects.examples.title = Examples +qhp.QtAndroidExtras.subprojects.examples.indexTitle = Qt Android Extras Examples +qhp.QtAndroidExtras.subprojects.examples.selectors = fake:example depends += qtcore qtdoc - headerdirs += .. sourcedirs += .. exampledirs += ../../../examples/androidextras \ - ../ \ snippets -excludedirs += ../../../examples/widgets/doc imagedirs += images navigation.landingpage = "Qt Android Extras" navigation.cppclassespage = "Qt Android Extras C++ Classes" diff --git a/src/androidextras/doc/snippets/code/src_androidextras_qandroidjniobject.cpp b/src/androidextras/doc/snippets/code/src_androidextras_qandroidjniobject.cpp index 899ca74..1388873 100644 --- a/src/androidextras/doc/snippets/code/src_androidextras_qandroidjniobject.cpp +++ b/src/androidextras/doc/snippets/code/src_androidextras_qandroidjniobject.cpp @@ -81,3 +81,55 @@ void function() } } //! [Check for exceptions] + +//! [Registering native methods] +static void fromJavaOne(JNIEnv *env, jobject thiz, jint x) +{ + Q_UNUSED(env) + Q_UNUSED(thiz) + qDebug() << x << "< 100"; +} + +static void fromJavaTwo(JNIEnv *env, jobject thiz, jint x) +{ + Q_UNUSED(env) + Q_UNUSED(thiz) + qDebug() << x << ">= 100"; +} + +void registerNativeMethods() { + JNINativeMethod methods[] {{"callNativeOne", "(I)V", reinterpret_cast<void *>(fromJavaOne)}, + {"callNativeTwo", "(I)V", reinterpret_cast<void *>(fromJavaTwo)}}; + + QAndroidJniObject javaClass("my/java/project/FooJavaClass"); + QAndroidJniEnvironment env; + env->RegisterNatives(env->GetObjectClass(javaClass), + methods, + sizeof(methods) / sizeof(methods[0])); + +} + +void foo() +{ + QAndroidJniObject::callStaticMethod("my/java/project/FooJavaClass", "foo", "(I)V", 10); // Output: 10 < 100 + QAndroidJniObject::callStaticMethod("my/java/project/FooJavaClass", "foo", "(I)V", 100); // Output: 100 >= 100 +} + +//! [Registering native methods] + +//! [Java native methods] +class FooJavaClass +{ + public static void foo(int x) + { + if (x < 100) + callNativeOne(x); + else + callNativeTwo(x); + } + +private static native void callNativeOne(int x); +private static native void callNativeTwo(int x); + +} +//! [Java native methods] diff --git a/src/androidextras/doc/src/qtandroidextras-examples.qdoc b/src/androidextras/doc/src/qtandroidextras-examples.qdoc new file mode 100644 index 0000000..725641e --- /dev/null +++ b/src/androidextras/doc/src/qtandroidextras-examples.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + \group examples-qtandroidextras + \title Qt Android Extras Examples + \brief Examples in the Qt Android Extras module. + \ingroup all-examples + + These are the examples available in the \l{Qt Android Extras} module. + + \note These examples will only work on Android. +*/ diff --git a/src/androidextras/doc/src/qtandroidextras-index.qdoc b/src/androidextras/doc/src/qtandroidextras-index.qdoc index cf7d3df..74ca249 100644 --- a/src/androidextras/doc/src/qtandroidextras-index.qdoc +++ b/src/androidextras/doc/src/qtandroidextras-index.qdoc @@ -40,8 +40,7 @@ #include <QtAndroidExtras> \endcode - To link against the module, add this line to your \l qmake \c - .pro file: + To link against the Qt Android Extras module, add this line to your project file: \code QT += androidextras @@ -53,4 +52,10 @@ \list \li \l{Qt Android Extras C++ Classes}{C++ Classes} \endlist + + \section1 Examples + + \list + \li \l{Qt Android Extras Examples} + \endlist */ diff --git a/src/androidextras/doc/src/qtandroidextras-module.qdoc b/src/androidextras/doc/src/qtandroidextras-module.qdoc index badb8a7..8a5eccb 100644 --- a/src/androidextras/doc/src/qtandroidextras-module.qdoc +++ b/src/androidextras/doc/src/qtandroidextras-module.qdoc @@ -40,8 +40,7 @@ #include <QtAndroidExtras> \endcode - To link against the module, add this line to your \l qmake \c - .pro file: + To link against the Qt Android Extras module, add this line to your project file: \code QT += androidextras diff --git a/src/androidextras/jni/qandroidjniobject.cpp b/src/androidextras/jni/qandroidjniobject.cpp index 79740e3..dafd145 100644 --- a/src/androidextras/jni/qandroidjniobject.cpp +++ b/src/androidextras/jni/qandroidjniobject.cpp @@ -48,55 +48,193 @@ QT_BEGIN_NAMESPACE /*! \class QAndroidJniObject \inmodule QtAndroidExtras - \brief The QAndroidJniObject is a C++ wrapper around a Java class. + \brief Provides APIs to call Java code from C++. \since 5.2 - QAndroidJniObject provides APIs to call Java methods + \sa QAndroidJniEnvironment - \section1 JNI types + \section1 General Notes - Object types: \list - \li jobject - \li jclass - \li jstring - \li jarray - \li jobjectArray - \li jbooleanArray - \li jbyteArray - \li jcharArray - \li jshortArray - \li jintArray - \li jlongArray - \li jfloatArray - \li jdoubleArray + \li Class names needs to contain the fully-qualified class name, for example: \b"java/lang/String". + \li Method signatures are written as \b"(Arguments)ReturnType" + \li All object types are returned as a QAndroidJniObject. \endlist - Primitive types: - \list - \li jboolean - \li jbyte - \li jchar - \li jshort - \li jint - \li jlong - \li jfloat - \li jdouble - \endlist + \section1 Method Signatures + + For functions that take no arguments, QAndroidJniObject provides convenience functions that will use + the correct signature based on the provided template type. For example: + + \code + jint x = QAndroidJniObject::callMethod<jint>("getSize"); + QAndroidJniObject::callMethod<void>("touch"); + \endcode + + In other cases you will need to supply the signature yourself, and it is important that the + signature matches the function you want to call. The signature structure is \b \(A\)R, where \b A + is the type of the argument\(s\) and \b R is the return type. Array types in the signature must + have the \b\[ suffix and the fully-qualified type names must have the \b L prefix and \b ; suffix. + + The example below demonstrates how to call two different static functions. + \code + // Java class + package org.qtproject.qt5; + class TestClass + { + static String fromNumber(int x) { ... } + static String[] stringArray(String s1, String s2) { ... } + } + \endcode + + The signature for the first function is \b"\(I\)Ljava/lang/String;" + + \code + // C++ code + QAndroidJniObject stringNumber = QAndroidJniObject::callStaticObjectMethod("org/qtproject/qt5/TestClass", + "fromNumber" + "(I)Ljava/lang/String;", + 10); + \endcode - \section1 General Notes: + and the signature for the second function is \b"\(Ljava/lang/String;Ljava/lang/String;\)\[Ljava/lang/String;" + + \code + // C++ code + QAndroidJniObject string1 = QAndroidJniObject::fromString("String1"); + QAndroidJniObject string2 = QAndroidJniObject::fromString("String2"); + QAndroidJniObject stringArray = QAndroidJniObject::callStaticObjectMethod("org/qtproject/qt5/TestClass", + "stringArray" + "(Ljava/lang/String;Ljava/lang/String;)[Ljava/lang/String;" + string1.object<jstring>(), + string2.object<jstring>()); + \endcode - - Class name strings needs to be the fully-qualified class name, for example: "java/lang/String". - - Method signatures are written as "(Arguments)ReturnType" - - All object types are returned as a QAndroidJniObject. - \section1 Handling Java exception: + \section1 Handling Java Exception - When calling Java functions that might throw an exception, it is important that you handle and - clear out the exception before continuing. + When calling Java functions that might throw an exception, it is important that you check, handle + and clear out the exception before continuing. + + \note It is unsafe to make a JNI call when there are exceptions pending. \snippet code/src_androidextras_qandroidjniobject.cpp Check for exceptions + \section1 Java Native Methods + + Java native methods makes it possible to call native code from Java, this is done by creating a + function declaration in Java and prefixing it with the \b native keyword. + Before a native function can be called from Java, you need to map the Java native function to a + native function in your code. Mapping functions can be done by calling the RegisterNatives() function + through the \l{QAndroidJniEnvironment}{JNI environment pointer}. + + The example below demonstrates how this could be done. + + Java implementation: + \snippet code/src_androidextras_qandroidjniobject.cpp Java native methods + + C++ Implementation: + \snippet code/src_androidextras_qandroidjniobject.cpp Registering native methods + + \section1 The Lifetime of a Java Object + + Most \l{Object types}{objects} received from Java will be local references and will only stay valid + in the scope you received them. After that, the object becomes eligible for garbage collection. If you + want to keep a Java object alive you need to either create a new global reference to the object and + release it when you are done, or construct a new QAndroidJniObject and let it manage the lifetime of the Java object. + \sa object() + + \note The QAndroidJniObject does only manage it's own references, if you construct a QAndroidJniObject from a + global reference that reference will not be released by the QAndroidJniObject. + + \section1 JNI Types + + \section2 Object Types + \table + \header + \li Type + \li Signature + \row + \li jobject + \li {1, 3} L\e<fully-qulified-name>}; + \row + \li jclass + \row + \li jstring + \row + \li jobjectArray + \li [L\e<fully-qulified-name>; + \row + \li jarray + \li [\e<type> + \row + \li jbooleanArray + \li [Z + \row + \li jbyteArray + \li [B + \row + \li jcharArray + \li [C + \row + \li jshortArray + \li [S + \row + \li jintArray + \li [I + \row + \li jlongArray + \li [J + \row + \li jfloatArray + \li [F + \row + \li jdoubleArray + \li [D + \endtable + + + \section2 Primitive Types + \table + \header + \li Type + \li Signature + \row + \li jboolean + \li Z + \row + \li jbyte + \li B + \row + \li jchar + \li C + \row + \li jshort + \li S + \row + \li jint + \li I + \row + \li jlong + \li J + \row + \li jfloat + \li F + \row + \li jdouble + \li D + \endtable + + \section3 Other + \table + \header + \li Type + \li Signature + \row + \li void + \li V + \endtable + For more information about JNI see: \l http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html */ @@ -192,7 +330,7 @@ QT_BEGIN_NAMESPACE /*! \fn T QAndroidJniObject::callMethod(const char *methodName) const - Calls the method \a methodName and returs the value. + Calls the method \a methodName and returns the value. \code QAndroidJniObject myJavaString = ...; @@ -228,7 +366,7 @@ QT_BEGIN_NAMESPACE /*! \fn T QAndroidJniObject::callStaticMethod(jclass clazz, const char *methodName) - Calls the static method \a methodName on \a clazz and returns the value T. + Calls the static method \a methodName on \a clazz and returns the value. \code ... @@ -265,8 +403,7 @@ QT_BEGIN_NAMESPACE /*! \fn T QAndroidJniObject::callStaticMethod(jclass clazz, const char *methodName, const char *signature, ...) - Calls the static method \a methodName with \a signature on \a clazz and returns the value T, - unless T is void. + Calls the static method \a methodName with \a signature on \a clazz and returns the value. \code ... @@ -453,15 +590,15 @@ QT_BEGIN_NAMESPACE /*! \fn T QAndroidJniObject::object() const - Returns a jobject as type T. + Returns the object held by the QAndroidJniObject as type T. \code QAndroidJniObject string = QAndroidJniObject::fromString("Hello, JNI"); jstring jstring = string.object<jstring>(); \endcode - Note that the jobject is still owned by the QAndroidJniObject. If you want to keep the jobject valid - you should create a new QAndroidJniObject or make a new global reference to the jobject and + \note The returned object is still owned by the QAndroidJniObject. If you want to keep the object valid + you should create a new QAndroidJniObject or make a new global reference to the object and free it yourself. \snippet code/src_androidextras_qandroidjniobject.cpp QAndroidJniObject scope @@ -477,7 +614,7 @@ QT_BEGIN_NAMESPACE \fn QString QAndroidJniObject::toString() const Returns a QString with a string representation of the java object. - Calling this function on a Java String object is a convenient way of getting the actuall string + Calling this function on a Java String object is a convenient way of getting the actual string data. \code |