/****************************************************************************
**
** Copyright (C) 2014 BlackBerry Limited. All rights reserved.
** 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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page platform-notes-blackberry.html
    \title Platform and Compiler Notes - BlackBerry
    \contentspage Platform and Compiler Notes

    This page lists features and restrictions that are particular for Qt on BlackBerry 10.

    \section1 Supported Modules

    Most Qt modules (essential and add-on) are supported except for instance Qt WebKit and
    platform-specific ones. \l{BlackBerry supported modules} shows a detailed list of what
    is supported and what isn't.

    \section1 Application Window

    The first top-level window that is shown will always be full screen. This parent-less
    window serves as the application window, all other windows descend from it, even
    if they don't have a parent from Qt's perspective. It is not possible to re-parent this
    window to another window and when it is deleted any other window will vanish, as well.

    In general, it is not possible to promote child windows to top level windows
    (\l{QWindow::}{setParent()} with an argument of \c 0). If you do so, the window will
    vanish along with its child windows.

    \section1 Working Directory

    Applications are restricted to their working directory (aka \e sandbox), they cannot
    read or write outside this directory. Nevertheless absolute file paths are visible,
    for instance calling QDir::currentPath() will initially yield
    \c{/accounts/1000/appdata/namespace.application/}. This is the root directory an
    application is confined to. A more detaild overview how to work with the file system
    can be found in the corresponding
    \l{Working with the file system}{BlackBerry 10 documentation}.

    \section1 Application Lifecycle

    A detailed overview of the states an application can move through can be found
    \l{BlackBerry 10 application lifecycle}{here}.
    Most of the transitions are mapped to Qt signals and events. For instance, if the
    application is minimized a QGuiApplication::applicationStateChanged signal is emitted
    with an argument of \c Qt::ApplicationInactive and a QExposeEvent is sent to the application
    window. In the cases where this is not sufficient, a native event filter can
    be use, that listens for navigator events. The navigator on the BlackBerry 10 OS
    handles the entire application window lifecycle.

    \section1 Peculiarities

    This is a list of topics specific to Blackberry 10 which are discussed in their
    own sections:

    \list
        \li \l{QAbstractNativeEventFilter::nativeEventFilter()}{Native events}
        \li \l{Platform Limitations}{QSettings}
        \li \l{Blackberry Peculiarities}{Cover windows}
    \endlist

    \section1 Multimedia
    Restrictions that apply to Qt Multimedia on BlackBerry are described
    \l{Qt Multimedia on BlackBerry}{here}.

    \section1 Sensors

    Most sensors are supported on BlackBerry (such as accelerometer, compass, magnetometer,
    gyroscope, (IR) proximity, (ambient) light, orientation, rotation and holster sensors).
    However, different devices might support a different set of sensors.
    \l{ QSensor::sensorTypes()} will return a list of sensors that are supported on a
    particular device.

    \section1 Relationship to Cascades

    Cascades is the prevailing UI framework for BlackBerry 10 development. It uses Qt (4.8)
    C++ and QML as a base to provide a standard set of UI controls and other APIs tailored to
    the BlackBerry 10 platform. If you are curious, take a look at the
    \l{http://developer.blackberry.com/native/documentation/cascades/getting_started/intro/index.html}
    {Introduction to Cascades} article.
    Note that Cascades uses its own backend to render on the screen and uses only non-UI
    parts of Qt. It is not possible to mix Qt and Cascades APIs to access the screen in
    one application.

    \section1 Qt Widgets Style

    If the UI of your application is based on \l[QtWidgets]{Qt Widgets}, you should consider
    using the BlackBerry 10 specific Qt widget style. This style matches the system-wide UI
    appearance and improves usability. The BlackBerry 10 style is implemented as proxy style
    in C++ and is loaded as a style plug-in on demand. The style is available only on Qt
    builds for BlackBerry 10 and is not available in builds for other platforms.

    There are two variants of the style fitting the dark and bright themes on the
    BlackBerry 10.1.x and 10.2.x releases:

    \table 50%
    \header
        \li Style key \c{bb10bright}
        \li Style key \c{bb10dark}
    \row
        \li \image bb10bright-style.png
        \li \image bb10dark-style.png
    \endtable


    You can activate one of the styles with \l{ QApplication::setStyle() }, e.g.

    \code
    QApplication::setStyle(QStringLiteral("bb10dark"));
    \endcode

    The BlackBerry 10 style only covers those \l[QtWidgets]{Qt Widgets} which fit well on
    small screens and can be controlled with touch input in a comfortable way:

    \list
        \li \l{QCheckBox}
        \li \l{QComboBox}
        \li \l{QLineEdit}
        \li \l{QPushButton}
        \li \l{QProgressBar}
        \li \l{QRadioButton}
        \li \l{QSlider}
        \li \l{QScrollBar}
        \li \l{QTextEdit}
        \li item view widgets
    \endlist

    Consider using \l{Qt Quick} for more complex UIs.

    \section1 References

    \list
        \li \l{BlackBerry 10 device characteristics}
    \endlist

*/
