/****************************************************************************
**
** Copyright (C) 2014 BlackBerry Limited. All rights reserved.
** 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$
**
****************************************************************************/

/*!
    \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 References

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

*/
