Upgrading to 10.2 beta

This document lists the major changes that affect applications that are upgrading from the 10.1 Gold release to the 10.2 beta release of Cascades. Upward compatible changes are not listed here.

For more information about functionality that is new in this release, see the 10.2 beta 1 Release Notes.

Before you upgrade to the 10.2 beta version of the SDK, you should remove all previous versions of the Native SDK.

Changes to permissions

The read_geolocation permission has been deprecated. Use the access_location_services permission instead.

Changes to the build system (OS X users)

The libbbcascades library is now dependent on the libicu library.

You must set the DYLD_LIBRARY_PATH to also include $STAGE_DIR/target/darwin/x86/usr/lib.

You can export the following:

DYLD_LIBRARY_PATH=
    $STAGE_DIR/target/darwin/x86/usr/lib:$STAGE_DIR/target/darwin/x86/usr/lib/qt4/lib

Or you can set it as an environment variable in XCode under Edit Scheme.

Changes to the Momentics IDE

The Momentics IDE for BlackBerry has a simplified interface with the following features:

  • Improved installation and setup. For more information, see Set up your environment.
  • Device and project targeting from the Active Device and Active Project drop-down lists.
  • Automatic detection of your device and simplified management of new devices using a new Device Manager.
  • Simulator download and configuration directly from the IDE.
  • Preprocessing of QML files to allow more controls to be seen in QML Preview. For more information, see Troubleshooting QML Preview.
  • qDebug() and console.log() messages sent directly to console. For more information, see Testing and debugging.
  • API levels for compatibility with BlackBerry 10 OS versions. For more information, see API levels.
  • Sample apps integrated into the IDE.

The template for the Standard empty project have been updated to include localization handling.

Changes to the Cascades QML library

Cascades has changed the revision for the Cascades QML library from 1.0 to 1.2 for the 10.2 release. If your app uses 10.2 Cascades features, you must update the Cascades import statement or your app will break.

For QML files that use 10.2 Cascades features, replace import bb.cascades 1.0 with import bb.cascades 1.2. For example:

import bb.cascades 1.2

Page {
    Container {

        Label {
            // Localized text with the dynamic translation 
            // and locale updates support
            text: qsTr("Hello World") + Retranslate.onLocaleOrLanguageChanged
            textStyle.base: SystemDefaults.TextStyles.BigText
        }
    }
}

Apps that use features only from 10.1 Cascades or earlier should continue to use import bb.cascades 1.0.

If you use import cascades 1.2 with an earlier version of the SDK, your app will break. Because 10.2 is a beta release, you should use import bb.cascades 1.2 only if your app requires a 10.2 API.

Changes to APIs

Image library (libimg.so.1)

The img_decode_get_frame_count() and img_decode_set_frame_index() functions have changed signatures.

Previously:

img_decode_get_frame_count  ( img_codec_t  codec, 
    io_stream_t*   input, 
    img_decode_callouts_t const*   callouts,   
    img_t*  img,   
    _Uintptrt*   decode_data, 
    unsigned int*  count)

Now:

img_decode_get_frame_count  ( img_codec_t  codec, 
    io_stream_t*   input, 
    _Uintptrt*   decode_data,   
    unsigned int*  count)

Previously:

img_decode_set_frame_index  ( img_codec_t  codec, 
    io_stream_t*   input, 
    img_decode_callouts_t const*   callouts,   
    img_t*  img,   
    _Uintptrt*   decode_data, 
    unsigned int  index)

Now:

img_decode_set_frame_index  ( img_codec_t  codec, 
    io_stream_t*   input, 
    _Uintptrt*   decode_data,   
    unsigned int  index)

Camera library (camera_api.h)

The following enumerated type has changed:

  • camera_error_t: Value CAMERA_EALREADY has been changed from 16 to 23.

QNX library (fs_qnx6.h)

  • The value of constant QNX6FS_EMODE_MASK has been changed from 0x0001 to 0x0003.

Changes to application behavior

Changes to theme support

Specifying theme support has changed to reduce startup time for apps. You must change the way that you specify a theme or your app may not use the correct theme. For more information, see ThemeSupport and Themes.

Previously:

<cascadesTheme>dark</cascadesTheme>
<cascadesTheme>bright</cascadesTheme>

Now:

<env var="CASCADES_THEME" value="dark"/>
<env var="CASCADES_THEME" value="bright"/>

Visual updates to core controls

The following changes have been made to the Button control so that it looks better on all devices. For more information, see Device characteristics.

  • Button height is now 79 pixels for all-touch devices and 73 pixels for devices with a physical keyboard. The original button height was 101 pixels.
  • Icons have changed from 51 pixels to 61 pixels.
  • The font is smaller and wider.
  • The button has a wider default width.

You may need to adjust the UI of your app so that it looks good on all devices. For tips and tricks, see Resolution independence.

Changes to file system access

In QML, you must prefix the absolute file path of an external resource with file:// or your app won't be able to access the resource. This is very important in apps that use the FilePicker APIs, which return absolute file paths that are not prefixed with file://. File paths returned from FilePicker must be prefixed with file:// to be used as an absolute path to ImageView or MediaPlayer. For more information about accessing external images, see External images.

If your app was compiled with a version of the SDK prior to the 10.1 Gold release, it will continue to work, but it is a good practice to prefix your absolute paths with file:// in QML anyway.

A reminder about signal-slot connections

To ensure that your app works as you designed, you must evaluate the Boolean value that is returned by the QObject::connect() function. A signal-slot connection fails if the sender or the receiver objects are invalid or the types of the signal arguments are not registered in Qt as a meta-type. By default, in these cases, Qt generates a warning that is posted to slog2info logs on the device.

This situation is a critical error. A signal-slot connection is not established, which means that the execution flow of your app is not correct and your app might behave unexpectedly. For example, you might encounter strange UI behavior, memory leaks, device crashes, and so on. Your app assumes that the connection has been established and that the signal will arrive when it is sent, but this never happens.

You must resolve any signal-slot connection failures before publishing your app.

Recommended solution

You should use the Q_ASSERT() macro to evaluate the return value of connect() as suggested in Signals and slots. This technique affects only the debug builds of your code, because the release builds define QT_NO_DEBUG, which disables Q_ASSERT(). Because all apps and libraries (including Qt) are released in release mode (not debug mode), the handling of the connect() return values using Q_ASSERT() will not have any effect on published apps. This technique has no code to recover from a failed connection because it assumes that there is no safe recovery.

// If any Q_ASSERT statement(s) indicate that the slot failed to connect to 
// the signal, make sure you know exactly why this has happened. This is not
// normal, and will cause your app to stop working!
bool connectResult;
  
// Since the variable is not used in the app, this is added to avoid a 
// compiler warning.
Q_UNUSED(connectResult);
  
connectResult = QObject::connect(smokeDetector, SIGNAL(smokeDetected()), 
                                 sprinkler,     SLOT(dispenseWater()));
                                   
// This affects only Debug builds.
Q_ASSERT(connectResult);

Alternate solution

You can also check the return value of the connect() function using an if statement and add some code to recover from the failed connect(). You can use qWarning() to send a message to the console. This technique should not be used to recover from coding errors. If a signal-slot connection fails because of a error in code, it should be fixed before it is published to users.

if(!connect(...)) {
   qWarning("Recovering from the failed connect()");
   // Add your code here to make sure that your app still works correctly,
   // even though this connection has not been established.
}

You can also set the QT_FATAL_WARNINGS environment variable in your bar-descriptor.xml file. If the QT_FATAL_WARNINGS environment variable is set to 1, your app will exit after qWarning() prints the warning message.

Another alternate solution

If you believe that a recovery makes no sense because a successful connection is critical to your code, you can use qFatal() to close the app immediately. You can also consider adding additional code to clean up before closing the app.

if(!connect(...)) {

   // If your app uses shared files, write details what happened  
   // into a log file and ask users to send it to you.
   writeErrorLog();   
   
   // Make sure that you save as much user data as possible.
   saveOpenUserData();
   
   // Consider notifying users about the fatal error and 
   // warning them that the app will close now.
   qFatal("Cannot recover from the failed connect()");
}

Last modified: 2014-01-23

comments powered by Disqus