Upgrading to 10.0 Gold

This document lists the major changes that affect applications that were built using the beta 4 release of the BlackBerry 10 Native SDK. Upward compatible changes are not listed here. Here are some links that you can visit for more information:

Deprecated functions

  • The DataSource::registerQmlTypes() method was deprecated.

    The DataSource class is automatically registered for use in QML. The following code is no longer necessary:

    // Register the DataSource class as a QML type so that it's accessible in QML
    bb::data::DataSource::registerQmlTypes();
  • The invocation framework viewer-related classes (InvokeViewerMessage and InvokeViewerRequest) and methods have been deprecated.

    The viewer-related classes and methods have been replaced by Card classes and methods. The splash() method of InvokeTarget is now deprecated as well. For more information on these APIs, see the Cards documentation and the Invocation framework API reference page.

API changes

The following changes affect applications that use the following bb::pim::calendar APIs to manage calendar events:

Changes were made to the values of the Frequency::Type enumeration to ensure that the Recurrence class is consistent with the ActiveSync recurrence APIs.

Previous value New value
Undefined = -1 no change
Daily = 0 no change
Weekly = 1 no change
MonthlyAtWeekDay = 2 Monthly = 2
Monthly = 3 MonthlyAtWeekDay = 3
YearlyAtWeekDayOfMonth= 5 Yearly = 5
Yearly = 6 YearlyAtWeekDayOfMonth = 6

API behavior changes

The following API behavior has changed and you might need to change your app to adjust to the new behavior:

Relative paths

Relative paths are now relative to asset:///a.qml. The use of asset:/// has been discontinued for file paths, and you should use /app/native/assets/ instead.

If you use relative paths and want them to resolve with the file:// prefix, this is not supported if your QML file was referenced with asset://. The asset:///a.qml file path will remain as asset:///a.qml and will not be resolved to the file path.

If you are accessing a file that isn't located in your assets directory, you must use file://<URL> to specify the file path (for files outside of your application’s asset directory). Only files in your assets directory should use the asset:// path.

For more information about referencing files in the file system, see Working with the file system.

Example 1: An image file exists in your assets directory and you reference it using a relative path. For example, you can reference imageSource as follows:

imageSource: "/dev/sfs/IMG/personal/3.jpg"
  • This image path was previously resolved to file:///dev/sfs/IMG/personal/3.jpg.
  • The image path is now resolved to asset:///dev/sfs/IMG/personal/3.jpg.
  • Since the asset:// scheme is used, Cascades looks for the path and file within your assets directory, which may not exist.

Example 2: An image file exists outside of your asset directory and you reference it using an absolute path. For example, you can reference imageSource as follows:

imageSource: "file://" + "/dev/sfs/IMG/personal/3.jpg"
  • The image path is now resolved to file:///dev/sfs/IMG/personal/3.jpg (an absolute path).
  • Note that file:// is added explicitly.

Multi-line text control behavior

To comply with QNX/UNIX standards, multi-line text controls, such as TextArea, return a QString containing the Unicode character sequence 0x0A for a line feed (LF) when the user presses Enter. Previously, the carriage return (CR) character string (0x0D) was returned. If you are listening for the QString value for CR in your app, you will need to listen for LF instead.

Momentics IDE changes

If you already have the BlackBerry 10 Native SDK installed, you can install the latest version without uninstalling the previous version. However, you must select the latest version to use.

  1. Start the IDE.
  2. In Windows and Linux, on the Window menu, click Preferences. In Mac OS, on the Momentics menu, click Preferences.
  3. In the Select SDK drop-down list, select the latest SDK. For example, select BlackBerry 10 Native SDK 10.0.9.1673 for the Gold release. This option is available from the drop-down list on the toolbar as well.
  4. Click Apply.
  5. Click OK.

If you experience problems upgrading from an older version of the SDK, consider uninstalling the previous version before installing the latest BlackBerry 10 Native SDK. For example, if you receive the error message "QML preview is unavailable", this might indicate that you are using a version of the SDK that is not compatible with a previously installed version.

In this release, the IDE automatically detects when your device OS version and SDK version are different and displays a warning. You can then choose to find an SDK version that matches your device OS version.

The following changes affect the Momentics IDE for BlackBerry. You may be required to rebuild your application, re-apply template changes, or make changes to your .pro file.

  • The new project wizard has changed. You can create a Cascades application using a simplified wizard. To create a new project, click File > New > BlackBerry Project, choose Application as your project type, and click Cascades. Select your favorite template and continue.

  • When you create a new Cascades project, shared libraries are now pre-compiled into one library that is pre-loaded, which helps decrease start-up time. The changes to the project templates affect only applications built using the Device-Release configuration. Applications built using the Device-Debug and Simulator-Debug configurations should not pre-compile their libraries as this can cause issues for debugging.

    If you have a project that was created using an older version of Cascades, you can migrate to the new template without creating a new project. For more information, see Migrating an existing project.

Migrating an existing project

If you have a project that was created using an older version of Cascades, you can migrate to the new template without creating a new project.

To start, open the .pro file in your project. As an example, here's the project file for the Cascades Cookbook application:

TEMPLATE = app
TARGET = cascadescookbookqml

CONFIG += qt warn_on debug_and_release cascades
INCLUDEPATH += ../src   SOURCES += ../src/*.cpp
HEADERS += ../src/*.h

device {
    CONFIG(release, debug|release) {
        DESTDIR = o.le-v7
    }
    CONFIG(debug, debug|release) {
        DESTDIR = o.le-v7-g
    }
}

simulator {
    CONFIG(release, debug|release) {
        DESTDIR = o
    }
    CONFIG(debug, debug|release) { 
        DESTDIR = o-g
    } 
}

OBJECTS_DIR = $${DESTDIR}/.obj
MOC_DIR = $${DESTDIR}/.moc
RCC_DIR = $${DESTDIR}/.rcc
UI_DIR = $${DESTDIR}/.ui

As mentioned above, pre-linked libraries are applicable only to release binaries, so you need to make changes to that configuration only. The first step is to add a template override from app to lib in the Device-Release configuration section of the project file. You can also change the visibility of default symbols to -fvisiblility=hidden to prevent internal symbols from being available, which makes the library smaller and faster to link against.

...

device { 
    CONFIG(release, debug|release) {
        DESTDIR = o.le-v7
        TEMPLATE=lib
        QMAKE_CXXFLAGS += -fvisibility=hidden
    }

...

Next, you must update the main() declaration in the main.cpp file:

int main(int argc, char **argv)

Add the Q_DECL_EXPORT symbol before the declaration:

Q_DECL_EXPORT int main(int argc, char **argv)

The final change is in the bar-descriptor.xml file. Here's the bar-descriptor.xml file for the Cascades Cookbook application:

<configuration id="com.qnx.qcc.toolChain.1485069140" name="Device-Debug">
  <platformArchitecture>armle-v7</platformArchitecture>
  <asset path="arm/o.le-v7-g/cascadescookbookqml" entry="true"
         type="Qnx/Elf">cascadescookbookqml</asset>
</configuration>

<configuration id="com.qnx.qcc.toolChain.1120265426" name="Device-Release">
  <platformArchitecture>armle-v7</platformArchitecture>   
  <asset path="arm/o.le-v7/lib/cascadescookbookqml.so.1.0.0" entry="true"
          type="Qnx/Elf">cascadescookbookqml.so</asset>
</configuration> 

Add an app entryPointType to the Device-Release configuration called Qnx/Cascades:

...

<configuration id="com.qnx.qcc.toolChain.1120265426" name="Device-Release"> 
    <entryPointType>Qnx/Cascades</entryPointType>

...

After you update the bar-descriptor.xml file, you must export the project to a .zip file. To export the project:

  1. Right-click the project and click Export.
  2. Expand General, select Archive File, and click Next.
  3. Click Browse, find a location to save the file, provide a file name, and click Save.

Next, you must create a new workspace. If you created a new workspace when you installed the latest version of the BlackBerry 10 Native SDK, that's fine. The workspace just can't be the one that you initially created the project with. To create a new workspace, click File > Switch Workspace > Other and specify a location for the new workspace.

Now you must import the project into your new workspace. To import the project:

  1. Click File > Import.
  2. Expand General, select Existing Projects into Workspace, and click Next.
  3. Click Browse, locate the project, and click Finish.

Lastly, it's time to test your new application. To test out your app:

  1. Right-click your project, click Build Configurations > Set Active > Device-Release.
  2. Right-click your project and click Clean Project.
  3. Build and deploy your app.
 

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus