1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
/****************************************************************************
**
** 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 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
*/
|
