diff options
Diffstat (limited to 'examples/androidextras/musiclist/doc/src/qtandroidextras-example-musiclist.qdoc')
-rw-r--r-- | examples/androidextras/musiclist/doc/src/qtandroidextras-example-musiclist.qdoc | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/examples/androidextras/musiclist/doc/src/qtandroidextras-example-musiclist.qdoc b/examples/androidextras/musiclist/doc/src/qtandroidextras-example-musiclist.qdoc new file mode 100644 index 0000000..39efb6a --- /dev/null +++ b/examples/androidextras/musiclist/doc/src/qtandroidextras-example-musiclist.qdoc @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtAndroidExtras module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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 The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\title Qt JNI Music List + \ingroup examples-qtandroidextras + \example musiclist + \brief Demonstrates how to exchange data from complex Java objects. + + \image musiclist.png + + This example demonstrates how to move around data from a Java ArrayList of + objects over to Qt. The example uses Android APIs to retrieve a list of music + tracks, and displays some information about them with QML. + + When the application starts, it displays a list of music tracks, showing the + track name, artist, and duration. + + \include examples-run.qdocinc + + \section1 Create the Music Classes + + Let's create a Java class, \c MusicTrack, that defines some of the basic + information about a track. In the Java side, create the following: + + \quotefromfile musiclist/android/src/org/qtproject/example/musiclist/MusicList.java + \skipto class MusicTrack + \printuntil /^\}/ + + Create another class with the same variables or information on the C++ side. + The definition for \c MusicTrack class is the following: + + \quotefromfile musiclist/musiclist.h + \skipto class MusicTrack + \printuntil }; + + \note The \c MusicTrack class must be a \l{QObject}-derived class to be used + with as a QML context property. For more information, see + \l{Overview - QML and C++ Integration}{QML and C++ Integration}. + + \section1 Fetch the Music List + + To retrieve the music list, the Android APIs are used. Add the following method + to find music tracks that are available on the system. This method returns + an ArrayList of \c MusicTrack. + + \quotefromfile musiclist/android/src/org/qtproject/example/musiclist/MusicList.java + \skipto package + \printuntil /^\ {4}\}/ + \printline } + + Using the JNI helpers provided with Qt, call the previous method to + first get an \l{QAndroidJniObject} containing an ArrayList of objects. In the + C++ code, you need to go through the Java ArrayList and create a parallel list + on C++. Add the following lines to do that: + + \quotefromfile musiclist/musiclist.cpp + \skipto QAndroidJniObject + \printuntil /^\ {4}\}/ + + Then, add a function to return the resulted \l{QList}: + + \quotefromfile musiclist/musiclist.cpp + \skipto MusicList::assembledMusicList + \printuntil } + + To display the music list, create a \l{ListView} that uses the \l{QList} + as a property. Register the property as follows: + + \quotefromfile musiclist/main.cpp + \skipto MusicList + \printuntil assembledMusicList + + In the QML code, define the model of the \l{ListView} as follows: + + \quotefromfile musiclist/main.qml + \skipto model + \printline model + + \sa {Qt for Android}, {Qt Android Extras} +*/ |