/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** 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 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.
**
** 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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \title Qt Notifier
    \ingroup examples-qtandroidextras
    \example notification
    \brief Demonstrates calling Java code from an Android application.

    \image notification.png

    This example demonstrates how to add a custom Java class to an Android application, and
    how to call into this using the JNI convenience APIs in the Qt Android Extras module.
    The application UI is created by using Qt Quick.

    Click on either of the smiley faces to put a notification in the status area of the Android
    device.

    \include examples-run.qdocinc

    \section1 Calling Java Methods from C++ Code

    We define a custom Java class called \c NotificationClient in the
    NotificationClient.java file:

    \quotefromfile notification/android/src/org/qtproject/example/notification/NotificationClient.java
    \skipto org.qtproject.example.notification
    \printuntil /^\}/

    In the NotificationClient C++ class header file, notificationclient.h, we
    declare a simple C++ API to display notifications on an Android device. It
    consists of a single string property, \c notification, and a slot,
    \c updateAndroidNotification(), that calls the Java code:

    \quotefromfile notification/notificationclient.h
    \skipto Q_PROPERTY
    \printuntil )
    \dots
    \skipto private slots
    \printuntil updateAndroidNotification()

    A NotificationClient object is exposed to the QML in the main source file,
    main.cpp:

    \quotefromfile notification/main.cpp
    \skipto QQuickView view;
    \printuntil notificationClient);

    In the NotificationClient C++ class source file, notificationclient.cpp, we
    import the QtAndroid class:

    \quotefromfile notification/notificationclient.cpp
    \skipto <QtAndroid
    \printuntil >

    This will allow us to use \c QAndroidJniObject for JNI calls, and also allow
    us to pass our application's context to the Java methods as in:

    \code
        QtAndroid::androidContext().object()
    \endcode

    We connect the \c notificationChanged() signal to the
    \c updateAndroidNotification() slot to update the notification text when the
    \c notification property changes:

    \printuntil }

    The \c NotificationClient::updateAndroidNotification() function calls the
    Java method. We construct a Java string from the \c notification string
    property:

    \skipto updateAndroidNotification()
    \printuntil fromString

    And pass the string object as a parameter to the Java \c notify() method.
    Note that we must supply the signature ourselves:

    \printuntil }

    \sa {Qt for Android}, {Qt Android Extras}
*/
