1. Register to receive push messages with the device
2. Register with the BlackBerry Push Service in the cloud to allow push messages for the app to begin being delivered
3. Register with your server side app so it knows there’s a new subscriber
4. Be ready to receive push messages at any time
5. Process pushes in a quick and efficient manner

The server-side portion of consumer push is identical between all BlackBerry smartphone versions, meaning you can use your current server-side app and push service credentials.

By włodi from London, UK (The Big Red Button Uploaded by Yarl) [CC-BY-SA-2.0 (http://creativecommons.org/licenses/by-sa/2.0)%5D, via Wikimedia Commons

BlackBerry 7

In BlackBerry 7 Java, there were two main ways to set up your application to receive push messages – open a port and begin listening indefinitely or register your port and application details with the device. The former basically required that your application begin a background process when the app was first installed, as well as every time the device started up. When the push arrived on the port opened by the app, the data could then be processed however required by the app, followed by the app once again listening on the open port for the next message. This method also required the app to perform “manual” registration, an HTTP POST, with the BlackBerry Push Service to allow devices to begin receiving push messages for your app.

https://github.com/blackberry/JDE-Samples/tree/master/com/rim/samples/device/httppushdemo
(this sample shows Enterprise Push which is similar to the pre-5.0 Push API method through BIS)

The latter approach was introduced in BlackBerry 5 where new APIs were introduced that removed the need to keep an app thread running at all times. Instead, the app would register itself with the device by passing it the assigned port and push app ID, allowing the device to listen for push messages on behalf of the app and launch to pass the push message to be processed. This method provided a simple way to allow the app to perform the registration with the BlackBerry Push Service.

http://www.blackberry.com/developers/docs/7.0.0api/net/rim/blackberry/api/push/package-frame.html

BlackBerry 10

The approach used in BlackBerry 10 is most similar to the last approach mentioned for BlackBerry 7 and is arguably the simplest way to handle push messages yet. One simplification is that developers no longer need to worry about application ports, as the on-device service will now handle port selection directly with the BlackBerry Push Service. Another is that rather than needing to deal with reading network streams to receive the push payload, it is not delivered directly to the app fully available in the data portion of an invocation.

Application flow

The first thing your app will need is an entry in the bar-descriptor.xml file that registers the app to receive invocations from the device push notification service. Below is an example entry. The only thing you need to change is the invoke-target id value to a string unique to your app:

              <invoke-target id="com.unique.string.for.your.app">	
      <type>APPLICATION</type>
      <filter>
         <action>bb.action.PUSH</action>
         <mime-type>application/vnd.push</mime-type>
      </filter>
    </invoke-target>

The second thing to add to the bar-descriptor is the permission for consumer push (this can also be added through the GUI editor in the IDE):

<permission system=”true”>_sys_use_consumer_push</permission>

After the above entries exist, we are ready to start programming. Using the various Push APIs, the following flow needs to occur in the device app:

Create a Session

Frequency: Every time your app launches

This is where your app registers itself to receive push messages. Once your app passes the on-device service, it’s provided a push app ID as well as the invoke-target ID you specified in the bar-descriptor file. This basically tells the service, “If a push comes in with this push app ID, invoke my app using this invoke-target ID”.

PushService* m_pushService; //Member variable creation in header file

//In this case BLACKBERRY_INVOKE_TARGET_ID would be “com.unique.string.for.your.app” from above

m_pushService = new PushService(BLACKBERRY_PUSH_APPLICATION_ID, BLACKBERRY_INVOKE_TARGET_ID);
m_pushService->createSession();

Create a Channel

Frequency: Once for the lifetime of the app

After the session has been established on the device, the app then needs to register itself with the BlackBerry Push Service. This operation is referred to as “creating a channel”. The creation of a channel tells the BlackBerry Push Service, “If a push message arrives with this app ID and is addressed to my device, please let it through”. Without this step, pushes will never be delivered to the device.

m_pushService->createChannel(QUrl(BLACKBERRY_PUSH_URL));

Another important part of this step is that when the channel is created, it should return a “token” which currently is simply the value of the device PIN. This can be sent to your server once retrieved to let it know that a new device has subscribed.

Register to Launch

Frequency: Once for the lifetime of the app

Following the channel creation, your last step is to call the “register to launch” function. Unlike BlackBerry 7, BlackBerry 10 apps do not run all the time. When a push arrives however, the application can be launched into the tiled state to perform processing on the push it’s not already running. In order to be launched when a push arrives, the app must call the “register to launch” function. Otherwise if this function is not called and the application is closed, the push data will be lost.

m_pushService->registerToLaunch();

Once the above steps are completed, your app is ready to start receiving push messages. As push uses invocation, you can handle the messages in about the same way you would for a standard invocation of your app:

https://developer.blackberry.com/cascades/documentation/device_platform/

invocation/receiving_invocation.html

The one difference is that you need to use the PushPayload class to retrieve the push payload from the InvokeRequest’s data:

https://developer.blackberry.com/cascades/documentation/device_comm/push/

cs_receiving_a_push_message.html

Ready to get porting your BlackBerry Java push app over to BlackBerry 10? Here’s a great resource that walks through the entire service including lots of code snippets:

https://developer.blackberry.com/cascades/documentation/device_comm/push/index.html

Need a sample to test your current push credentials? Check our GitHub repositories:

https://github.com/blackberry/Cascades-Samples


https://github.com/blackberry/Cascades-Community-Samples

Never used Push before? Check out this overview of the service:

https://developer.blackberry.com/services/push/?CPID=PUSHAPI00

If you still have questions toss a post in the Push Development forums or send me a tweet:

http://supportforums.blackberry.com/t5/BlackBerry-Push-Development/bd-p/Applications_using_Push_Technology

@garettBeuk

The Cascades framework is a rich and powerful modern UI framework build on top of the Qt application framework. The UI can be developed in C/C++ or Qt Modeling Language (QML) or both.

Lets take a look at a sample HelloWorld application in both frameworks:

HelloWorld side-by-side. A label in both Java and Cascades

// MAIN: the setup
public static void main(String[] args)    
{
      HelloApp app = new HelloApp();
      app.enterEventDispatcher();

}

	// MAIN: the setup
Q_DECL_EXPORT int main
(int argc, char **argv)
{
   Application app(argc, argv);
   new HelloWorld(&app);
   return Application::exec();
}

// HELLO WORLD CLASS

public class HelloApp extends
   UiApplication {
public HelloApp () {
 HScreen scr = new HScreen();
  pushScreen( scr );
      }

	// HELLO WORLD CLASS

HelloWorld::HelloWorld 
(bb::cascades::Application *app)
: QObject(app)
{
    QmlDocument *qml = 
QmlDocument::create("asset:///main.qml")
.parent(this);

    // create root object for the UI
    AbstractPane *root = 
qml->createRootObject();
    app->setScene(root);
}

// SCREEN CLASS: THE UI

public class HScreen 
extends MainScreen {

  private LabelField lbl;
  public HScreen()
  {
    lbl = new   LabelField( "Welcome!" );

    add( lbl );

  }}	// QML Page : THE UI

Page {
    Container {
        layout: DockLayout {}
        Label {
            text: qsTr("Hello World")
}}}

Both frameworks start with the main application and the HelloWorld class. In the case of Java a screen gets pushed on the screen stack. In the case of Cascades a QML document gets associated with root UI object.

In Java, a Screen Class gets created by extending MainScreen and adding a LabelField to it. In Cascades a Page gets declared and a Label is placed inside a container as shown on the screen.

When embarking on porting any application that include the User Interface. It’s important to review the UI guidelines for both platforms.

The BlackBerry Java UI guidelines can be found at:

https://developer.blackberry.com/design/bb7/

The BlackBerry 10 UI guidelines can be found at:

https://developer.blackberry.com/design/bb10/

A note on Java UI

The BlackBerry Java Development Environment (JDE) or the Eclipse Plugin is used to develop applications for BlackBerry OS 7.1 or lower.

There are two main supported frameworks for creating user interfaces in Java:

• MIDP UI APIs
• BlackBerry UI APIs

For compliance, the MIDP APIs are included for porting apps from MIDP devices. The BlackBerry UI APIs target specifically BlackBerry development and are the main focus of this article.

Rendering in Java And Cascades UI Frameworks

In Java UI rendering is done in “widgets” using the paint() functions. Normally, a list of such “widgets” will represent your entire UI. The system will go through the entire set of “widgets” and ask them to draw themselves by calling the “paint()” method. The consequences of this implementation are as follows:

In Cascades, rendering is done differently. Unlike in Java where the application is part of the rendering loop a Cascades application only manages the UI tree. The Cascades Rendering engine (which executes on a separate thread) takes care of drawing the UI. The consequences of this implementation are as follows:

For more information on the topic please see this blog post.

(
http://devblog.blackberry.com/2012/09/cascades-custom-ui/
)

Navigation:

Single Screen

Normally a single screen Java application would extend from MainScreen as in the HelloWorld sample provided. Similarly in Cascades a Page would get created with individual components added to it.

Screen	Page

Stack of Screens

In traditional Java applications flow is maintained by adding and removing screens to/from the stack, which is owned by the main application. The equivalent to this on BlackBerry 10 is the Navigation pane where individual pages can be pushed and popped from a stack. For more information on Cascades Navigation Pane please see:
http://developer.blackberry.com/cascades/reference/bb__cascades__navigationpane.html

Tabs and Filtering content

In Java applications Tabs are used to display filtered content and are achieved with the PaneManagerModel. This can be achieved in Cascades using Segmented Control.

Cascades tabs allow the apps to change the flow of the application. In BlackBerry Java, this effect was achieved through the use of custom components.

PaneManagerModel, Pane, HorizontalTabTitleView, PaneView, PaneManagerView	SegmentedControl http://developer.blackberry.com/cascades /reference/bb__cascades__segmentedcontrol.html
Custom Component implementing custom Toolbar http://docs.blackberry.com/en/developers/ deliverables/17965/Toolbars_6_0_1137042_11.jsp	Tabbed Pane http://developer.blackberry.com/cascades /reference/bb__cascades__tabbedpane.html

Layout

Java:

http://btsc.webapps.blackberry.com/btsc/fetch/2000/348583/800332/800505/800508/How_To_-_Create_tabbed_view_screens.html?nodeid=1357482&vernum=0

Cascades:

http://developer.blackberry.com/cascades/reference/user_interface_layouts.html

The following tables illustrate layout mapping of the most frequently used layouts.

In BlackBerry Java, the most common approach is to use combination of HorizontalFieldManager and VerticalFieldManager. This can be achieved in Cascades using the DockLayout.

FlowFieldManager	Stack Layout default behavior

Combination of Horizontal and Vertical Field Managers	Dock Layout

AbsoluteLayout

Menus:

The Java Menus documentation can be referenced at:

http://developer.blackberry.com/java/documentation/menu_items_1970228_11.html

The Cascades Menus can be reference at:

http://developer.blackberry.com/cascades/documentation/ui/navigation/menus.html

The most common way of interacting with content in BlackBerry Java was through the BlackBerry Menu (the hardware key). On BlackBerry 10, Cascades applications would use an action in the action menu to get the equivalent functionality.

BlackBerry Key Menu vs. BlackBerry 10 Action Menu

Menu (Screenshot)	ActionSet

Application “Settings” Menu. [BlackBerry 10 Only]

A swipe-down menu is accessible on BlackBerry 10 for infrequently used actions such as settings, getting customer information, managing accounts or downloads etc…

N/A	Menu class and ActionItem object

Context Menu

Context menu is a common BlackBerry specific method of acting upon an item in a specific context. This can be achieved on both platforms as illustrated below.

Context Menu	contextActions

Custom Menu

In certain cases you might want to create a completely custom menu that makes sense for your application. This is possible in BlackBerry 10 using the MenuManager API.

Override keyDown and then create a custom component to display on the screen.	MenuManager

Active Home Screen Elements

In BlackBerry Java, apps would normally change the icons and the icon descriptions to keep track of the application state. For more information on the APIs please see:

http://www.blackberry.com/developers/docs/7.1.0api/

In BlackBerry 10, apps would use Active Frames to update the status of an application. For more information of Active Frames please see:

http://developer.blackberry.com/cascades/documentation/ui/active_frames/index.html

Active Home Screen App Elements

Active Icons	Active Frames

Notifications

To learn more about BlackBerry 7 notifications please see:

https://developer.blackberry.com/java/documentation/message_list_1984778_11.html

To learn more about BlackBerry 10 hub notifications please see:

https://developer.blackberry.com/cascades/documentation/device_comm/notifications/index.html

MessageList	Hub Notifications

Popup Dialogs

DialogFieldManager and PopupManager	NotificationDialog

Custom Controls

In BlackBerry Java, custom controls are challenging to implement and often involve overriding the paint() method of native components. For more information and samples please see:

https://developer.blackberry.com/java/documentation/

advanced_ui_components_and_managers_1970227_11.html

In Cascades, custom controls are created by combining existing components and modifying their behavior. For more information on how to create a custom control in Cascades, please see:

http://developer.blackberry.com/cascades/documentation/

dev/integrating_cpp_qml/custom_control_tutorial.html

Sample Use of Custom Components	Custom Control

Dialog Boxes, Prompts, Toasts

The BlackBerry Java platform supports Dialogs of different format (information, status, inquiry). For information on dialog boxes please see:

http://developer.blackberry.com/java/documentation/dialog_boxes_1970203_11.html

Cascades supports dialog boxes, prompts and toasts. For more information on how to implement them please see:

http://developer.blackberry.com/cascades/documentation/ui/dialogs_toasts/index.html

Dialog Class	Dialog, SystemDialog, SystemListDialog … Below is an example of a custom dialog box.

Lists

For reference of List implementations in Java please see:

http://developer.blackberry.com/java/documentation/lists_and_tables_1970216_11.html

For list implementation in Cascades please see:

http://developer.blackberry.com/cascades/documentation/ui/lists/

Active Home Screen App Elements

SimpleList, RichList, TableView	ListView

Text

For reference on how to handle text in Cascades please see:

http://developer.blackberry.com/cascades/documentation/ui/text/index.html

Label

Label http://developer.blackberry.com/java/ documentation/text_field_label_1984828_11.html	Label

Text Field

LabelField, RitchTextField, BasicEditField, PasswordEditField, EmailAddressEditField, KeywordFilterField, AutoTextEditField	TextField with TextFieldInputMode Of type: Default, Text, EmailAddress, Password, Chat, Url, PhoneNumber, NumbersAndPunctuation,NumericPassword, Pin

Text Area

RitchTextField and ActiveRitchTextField	TextArea with TextAreaInputMode of type: Default, Text, Chat, EmailAddress

Web Content

WebView

BrowserField http://www.blackberry.com/developers/ docs/7.1.0api/net/rim/device/api/ browser/field2/BrowserField.html BrowserField BrowserField browserField = new BrowserField(); screen.add( browserField ); browserField.requestContent ( "http://blackberry.com" );	WebView http://developer.blackberry.com/ cascades/reference/bb__cascades __webview.html WebView { id: webView url: " http://blackberry.com " }

http://giphy.com/gifs/TznYiZCFXeLle

Multimedia on BlackBerry 7 was based on the multimedia JSR (135). There were a lot of limitations regarding supported formats, how many sounds could be played at the same time, and even what worked on which device.

In BlackBerry 10, there are a wide range of supported codecs, containers, and protocols.

For video, we recommend an MP4 containing H.264 video at 720p and AAC audio. For audio, it depends a lot on your use case. In addition to mainstays such as MP3 and AAC, we support things like FLAC and Ogg Vorbis.

To actually play your multimedia, you should be looking at the MediaPlayer class. That will handle audio or video. You can also easily play the built in system sounds with the SystemSound class.

• Tutorial: Playing Audio or Video
• Tutorial: Playing SystemSounds in an app

Recording audio is through the AudioRecorder class. You can record a few different formats, including AAC (.mp4) and PCM (.wav).

• Recording Audio

This is all pretty straightforward and should be pretty easy to adjust to if you are used to the Java way of doing things. There are a few key differences that you might not be expecting though.

The first is the NowPlayingConnection. If you are building any sort of media player type application: use it. What it does is let the user control the volume and playback of your app from in another app, using the volume keys on the side. You can also provide a bit of data like a thumbnail image and the current song playing. No user is going to want to have to go back into your application just to change the volume, and it’s really easy to implement.

• Working with NowPlayingConnection

Secondly, unlike in BlackBerry 7, in BlackBerry 10 you can enable echo cancellation in order to do VoIP. There is no convenient Qt API to do this, but you can use QSA and open a connection to the “voice” PCM audio interface.

• BlackBerry 10 VoIP

The other big difference is that you can’t just feed bytes directly into the media player. You need to have an actual file to play, or be using one the streaming protocols supported. Of course, there is nothing stopping you from dropping down to OpenAL/ALUT and doing whatever you need if that’s your style. You also have QSA available as mentioned before, as well as mm-renderer (which is what MediaPlayer is using), but that is all beyond the scope of this article.

Networking in BlackBerry 10 is done through the QNetwork module. You no longer need to worry about transport selection. Your typical HTTP communication can be handled through QNetworkAccessManager. It provides methods such as get() and post(), which take a QNetworkRequest and then asynchronously return a QNetworkReply.

For example:

QUrl *url = new QUrl("http://www.iana.org/domains/example/");

    QNetworkAccessManager *manager = new QNetworkAccessManager(this);

    connect(manager, SIGNAL(finished(QNetworkReply*)),
    		this, SLOT(replyFinished(QNetworkReply*)));

    manager->get(QNetworkRequest(*url));

And then in your replyFinished slot:

void App::replyFinished(QNetworkReply* reply) {
	qDebug() <readAll();

	// Call deleteLater to make sure the reply gets cleaned up
	reply->deleteLater();
}

You can also do TCP with QTCPSocket and QTCPServer, UDP with UDPSocket , and FTP with QFtp.

And of course, lower level libraries such as cURL are available if you should require them.

Guest post from Roberto S. – Ed.

In Part 2 of this series, we would like to introduce BlackBerry Java developers to what has changed with respect to application lifecycle in BlackBerry 10, and what you should be aware of when you port this aspect of your application to Cascades.

All BlackBerry 10 applications have a similar lifecycle that includes three possible states: running in the foreground, running in the background, and stopped.

• An app running in the foreground is visible and is taking up the entire screen.
• An app running in the background is either displayed as a thumbnail, such as when a user swipes up from the bottom of the screen to display a list of running apps, or is invisible but has the run_when_backgrounded permission to run in the background.
• An app that is stopped is not visible and doesn’t have permission to run in the background.
• An app that is pooled (the app is paused and ready to be opened in the foreground)

Developers porting their apps from BlackBerry OS will need to take this into account and make the following changes to their apps:

1. Unlike in BlackBerry OS, apps do not have an extra entry point available to them for starting up a background thread at startup, or for modifying theirs icons. Homescreen Icons are not modifiable in BlackBerry 10 so any such logic is not portable as is. However, the active frames feature allows developers to customize their frames when minimized. Therefore, this may allow some of the icon logic to be applied to the cover instead on a BlackBerry 10 version of the app. For more information about Active covers, go to
   https://developer.blackberry.com/cascades/documentation/ui/active_frames/index.html
   .
2. Background services capabilities are currently not available to third party developers. They will be available in a future release of BlackBerry 10. Developers relying on background services to poll servers for updates or execute code when they are not running will have to implement an alternative approach for the time being. The alternative currently recommended is to use push to launch your apps when new data is available. With Push, your server side application can poll for new data on behalf of the client application and deliver any new data in a push message which can be processed even if the client application is closed. Check out this recent blog post on push for more information:
   http://devblog.blackberry.com/2013/01/push-samples/
   .
3. To handle the life cycle changes that occur in your app, there are several signals made available to Cascades apps that an app developer can intercept and process accordingly. For more details on application lifecycle and the various signals available, go to
   https://developer.blackberry.com/cascades/documentation/dev/fundamentals/index.html
   and
   https://developer.blackberry.com/cascades/reference/bb__application.html
   for more information. The developer must take their state into consideration and reduce app activity accordingly:
   • When your app enters the thumbnail state, it should stop any extraneous processing and use only the resources it needs to update the cover or maintain critical functionality like maintain a server connection or check a remote server for updates. Your app should stop other threads that aren’t required when running in the background. Examples of what to stop are rendering, multimedia playback, audio playback, etc.
   • The invisible signal is emitted when the app (and its thumbnail) is no longer visible. This state might occur if the device backlight is off or if another app has been brought to the foreground. When your app is in this state and doesn’t have the run_when_backgrounded permission, it is considered stopped and won’t receive any processing time. If your app does have the run_when_backgrounded permission, your app should stop any rendering operations (for example, updating the UI) and any other unnecessary operations. Your app should only listen for events that it needs to respond to, and process these events when they occur.
   • It is very important for applications to reduce processing as much as possible while thumbnailed or invisible. It will conserve CPU usage and also save on battery life. This is an important criterion that is taken into consideration when applications are evaluated during the BlackBerry World approval process.
4. When a user closes your app, your app usually needs to perform some final cleanup operations, whether it be saving the user’s data, shutting down your threads in a particular way, or manually closing the app database or network connections. Cascades provides developers with a choice of automatic or manual exit mechanisms that they can take advantage depending on their cleanup needs.
5. BlackBerry OS developers should be aware of the fact that C++ does not have automatic garbage collection like Java does. However, Qt does provide some built-in mechanisms that provide limited object cleanup. Please refer to the API references for QObject and other QtCore classes like QSharedPointer for additional information on how to manage pointers and automatically delete objects after use. For more information about object ownership in C++ and QML and what that entails, go to
   https://developer.blackberry.com/cascades/documentation/dev/fundamentals/index.html
   
6. The new pooled state is designed to take advantage of the extra memory added to BlackBerry 10 devices. The system sends a signal to the app to prepare to be pooled. The app is expected to reset its UI t o a point that matches startup conditions and signal back that the operation is completed. If the app fails to do this, the app will be terminated.
7. Another limitation to be aware of is that currently only eight apps can run at the same time on BlackBerry 10. As a best practice, developers should ensure that any apps launched in the background to process push events should exit as soon as possible if user interaction is not required or if they launch a notification to alert the user to launch the app later. This will prevent push interactions from bumping up the number of running apps for more than a short period of time.

Please stay tuned for series Part 3 – UI Overview.

With all the excitement around BlackBerry 10 launch, one key request from our developer community is how to bring your existing BlackBerry Java applications to BlackBerry 10. As always, we at RIM developer relations constantly strive to break any barriers for developers.

Starting today, we will be publishing a series of blog posts specifically designed to help port your existing BlackBerry Java application to BlackBerry 10. As you may already be aware, BlackBerry Java is no longer supported on BlackBerry 10. Our goal here is to provide you all the info needed to quickly migrate your app functionality.

The BlackBerry 10 Native SDK enables you to develop applications in C/C++ and provides an open-source friendly environment for porting POSIX compliant code. It comes with the Cascades framework allowing you to build visually rich applications. The key focus of this development guide is specifically on BlackBerry 10 Cascades development. For more information on BlackBerry Native Development, please refer to
http://developer.blackberry.com/native/

What is Cascades?

BlackBerry Cascades is built using the Qt framework, which allows Cascades to leverage the Qt object model, event model and threading model. BlackBerry Cascades enables you to develop your UI in C++, Qt Modeling Language (QML), or both. Qt Modeling Language (QML) is a declarative language that’s based on JavaScript and is included as part of Qt. You can use QML to describe the structure and behavior of a set of UI controls. BlackBerry Cascades uses a modified version of QML to let you create UIs for your apps.

One fundamental importance when looking to develop your BlackBerry Cascades application is deciding when to use QML or C++. You can use both of these languages in your application, but as a general rule of thumb you should use QML for your UI development and C++ for your business logic. Please refer to the below link more information on BlackBerry Cascades development and to download Native SDK and BlackBerry 10 Simulator.
https://developer.blackberry.com/cascades/

API Feature Parity

One of the main challenges while migrating app functionality from BlackBerry Java to Cascades is finding the correct mapping of APIs. To simplify this process, below is an API Feature Parity table that covers the most common BlackBerry Java APIs and their corresponding equivalent API in Cascades.

As you can see from the above table image, most of the common Java APIs have a direct mapping in Cascades making it easy for you to port your existing BlackBerry Java application to BlackBerry 10.

Please stay tuned for series Part 2 – Application Life Cycle.

Calling all Java® developers: We have some news regarding the BlackBerry® Java® Plug-in for Eclipse™!

We are pleased to announce a new Open Source project for the BlackBerry development platform. While we have stopped SDK work on BlackBerry® 7 OS, we’ve decided to make the source code open for all those developers using the Java Plug-in for Eclipse. The BlackBerry Java Plug-in for Eclipse is now available as a repository provided under the Eclipse Public Licenses 1.0. The BlackBerry Java Plug-in for Eclipse lets you develop, test, and debug BlackBerry Java applications using the Eclipse IDE, in combination with the BlackBerry SDK appropriate for the BlackBerry OS your application is targeting.

The readme file on the project page details all the information you will need to build the source code for Windows or Mac, build your own update site for the plug-in or even build your own full installer. For all the details, jump to the project page.

Additionally, the BlackBerry Java Plug-in for Eclipse 2.0 is now available for download as a complete install for Windows and Mac, or as an update via our Eclipse update sites. For more BlackBerry Java related information, tool downloads, sample apps and documentations, please visit our Java development page — and make sure to fork us on Github!

About a month ago, I took the plunge and started a Cascades™ project for BlackBerry® 10.

Initially I was in a state of shock. This is an entirely different world compared to legacy BlackBerry Java® development – including the language (C++), the framework (Qt/Cascades), and a declarative language to build the UI (QML). Slowly and surely things started coming together. Fortunately, I had done a lot of C++ programming in my distant past, and somewhere in the back of my brain most of that old knowledge was still there. Nonetheless, I found myself staring at compiler error messages in bewilderment when I attempted to make a static function member call using dot syntax (Java) instead of using :: (C++).

After a couple of days the state of shock wore off and I found myself getting excited about this new way of writing BlackBerry applications. So what’s so great?

RIM® has been spotlighting Cascades with its cool controls and animation as a great framework for a new generation of apps. This is all true, but to me, what really makes the difference is the Qt foundation on which Cascades is built. It is Qt that enables rapid and solid development with a clean separation of the UI from the code behind.

In an attempt to summarize what I like about Qt, here’s a short list of the things that have made me smile so far. No doubt as I progress, the list will grow.

QML

Defining a UI via markup is more intuitive than defining it via code. The markup clearly expresses the hierarchical structure of the UI. Such a hierarchy is almost impossible to see when looking at the equivalent in code. Furthermore, the structure can be expressed with minimal lines of markup in contrast to hundreds of lines of code without any loss of functionality. Needless to say, tweaking the UI and finding and fixing bugs via markup are all a breeze. QML also supports components. This means that I can define QML fragments in separate files and refer to these components from other QML files. I have already found myself defining re-usable pieces of QML. Of course, QML isn’t the only markup language in use today for writing non-HTML applications (e.g., XAML), so it’s great to see this “tried and proven” concept come to the world of BlackBerry development.

Code Behind

QML wouldn’t be very useful if it didn’t connect well with C++ code. Qt’s support for named properties and invocable methods in C++ makes it really easy to put code behind the UI. The UI can easily be configured to read values from a C++ object exposed via “properties”. In fact, when configured as such, a control’s property is “bound” to an object’s property. This means that as the value of the object’s property changes, the UI automatically updates to reflect these changes. C++ objects can also expose “methods” which can be invoked directly from QML.

Qt Threading

Qt expands on the basic notion of a thread by providing a built-in event loop for any thread. Qt allows an object to be “associated” with a thread. Via dynamic method invocation, a method can be invoked on an object associated with another thread. When such invoked, Qt transparently wraps the method invocation in an event and places it in the appropriate thread’s event queue. As such, the method will be ultimately invoked on the object’s thread. I found this to be extremely helpful when dealing with a particular object type, containing long-running methods. If used correctly, one can use this technique to gain the benefits of multi-threading without the dangers of concurrency.

Signals and Slots

Qt uses a mechanism known as signals and slots to allow objects to “listen” to events triggered by other objects. I have found this mechanism to be much more flexible than the Java listener paradigm (i.e., implementing interfaces). Any object can be eligible to listen to “signals” of any other object, simply by implementing a method “slot” with the correct signature. Needless to say, should the receiving object be associated with a different thread, the invocation of the “slot” will be invoked on the object’s thread.

Maturity and Community Support

Qt is not new. That’s good! It’s good because it means that it is stable and mature. It means that it contains hundreds of classes providing everything from a basic string wrapper (QString) to XML processing (QDomDocument). It is also very well documented. Both officially on the Qt site and unofficially by the zillions of posts on various forums.

In short, I’m enjoying the ride. Qt is a great foundation for writing apps. Coupled with Cascades, I can definitely say that we have a strong framework for building the next generation of BlackBerry apps.

Last month, we looked at how to internationalize your BlackBerry® Java® application. In this post, we will look at how to internationalize your BlackBerry® WebWorks™ application. There are a few options for accomplishing this – let’s take a look.

Using JavaScript and storing all the texts locally

One common way to internationalize your web application is to remove all strings from your code and have them all in an object with key-value pairs. All the code exists locally and nothings get stored on the server side.

This looks something like:

var strings = {
	"en" : {
		"BUTTON_CANCEL" : "Cancel",
		"BUTTON_SAVE" : "Save"
	},
	nl: {
		"BUTTON_CANCEL" : "Annuleer",
		"BUTTON_SAVE" : "Opslaan"
	}
}

Now let’s assume you keep the chosen language somewhere in a variable called language. You can then access the right string for the user language, like with the cancel button text for example:

Strings[language].BUTTON_CANCEL

That will give you either ‘Cancel’ or ‘Annuleer’ depending on whether the language variable contains ‘en’ or ‘nl’.

Using JavaScript and storing all the texts on a remote server

Another way of internationalizing your application in BlackBerry WebWorks platform is to use the server side code. Unfortunately, JavaScript does not have the concept of a resource file, and strings that will be generated by JavaScript must be defined in the code.

The easiest approach to deal with this issue is to define your JavaScript strings dynamically in server-side code (Java/JSP, ASPX, PHP, etc.). The following example defines some string resources in a JavaScript script block at the top of a JSP page:

Assuming the currentLocale object is set to English (US), the resulting block should look like this:

When currentLocale is set to German (Germany) it should change to this:

There are a couple things to keep in mind with this approach. First, any strings that are embedded in the files, whether JSP/ASPX/PHP/etc. or JavaScript .js files, must be externalized, i.e. the strings should be moved into the string resource block as demonstrated above, and replaced in the code with their variable names. Second, the JavaScript string resource block should be defined before any other embedded blocks or .js file includes that make use of these externalized strings. For example, the resource block should be defined before the following function is called:

Using JavaScript Object Notation (JSON)

Finally, another way to add multi-language support to your BlackBerry WebWorks application is to use JSON objects. Here is a sample which illustrates the use of JSON objects and changes the text dynamically based on the user’s language selection:

<html>
<body>
<h2>Internationalization Sample in WebWorks</h2>
<h3>Select a language:</h3>
<p>

<select id="languagechoice" onChange="displayGreeting()" >
  <option value="1">English</option>
  <option value="2">French</option>
  <option value="3">Spanish</option>
  <option value="4">German</option>
</select>

<br/> 
<br/>
<br/>

 <span id="greetings"></span> <br/>
</p>

<script type="text/javascript">

function displayGreeting(){

 var lang = document.getElementById("languagechoice");
 var lang_value = lang.options[lang.selectedIndex].value; 

 var JSONObject_en = {"hello":"Hello, Welcome to Internalization of WebWorks Applications in English!"};
 var JSONObject_fr = {"hello":"Hello, Welcome to Internalization of WebWorks Applications in French!"};
 var JSONObject_es = {"hello":"Hello, Welcome to Internalization of WebWorks Applications in Spanish!"};
 var JSONObject_de = {"hello":"Hello, Welcome to Internalization of WebWorks Applications in German!"};

 if(lang_value == 1){
   document.getElementById("greetings").innerHTML=JSONObject_en.hello 
 }
 else if (lang_value == 2 ){
   document.getElementById("greetings").innerHTML=JSONObject_fr.hello
 }
 else if (lang_value == 3 ){
   document.getElementById("greetings").innerHTML=JSONObject_es.hello
 }
 else{
   document.getElementById("greetings").innerHTML=JSONObject_de   .hello
 }
}

</script>

</body>
</html>

Download the sample app

So this is it folks — no more hair-pulling to figure out how to talk to social networks directly. There are already apps for them, so let’s learn how to leverage those apps from ours instead of reinventing it.

The first step is to create the data or context we would like to share. This context is simply a JSON object that encapsulates our data. Here is an example:

JSONObject context = new JSONObject();
try {
context.put(SendCommandContextKeys.TEXT, "Your Text");
context.put(SendCommandContextKeys.SUBJECT, "Your Text");
// context.put(SendCommandContextKeys.PATH, "file:///.....");
} catch (JSONException e) {
System.out.println(e.toString());
}

I intentionally commented out the PATH type data because we cannot use PATH data in a context that also has TEXT or SUBJECT types. But I still wanted to highlight that we can also share a file path (e.g. a photo).

Once we have our data context nicely wrapped up in a JSONObject, we need to create SendCommand objects that point to specific apps with a specific context. So how do we get these SendCommands? Easy peasy — we simply query the Send Command Framework with our context data. Here’s how:

SendCommand[] commandsAll =
SendCommandRepository.getInstance().get(SendCommand.TYPE_TEXT, context, true);

Notice that the 3rd parameter above is a Boolean. If true, the query returns all commands regardless if their associated applications can be opened; if false, it returns only commands whose associated applications can be opened. Ideally we would set it to false; however, in this post we will see how we can get them all and filter them in our own application logic.

Each SendCommand object has an ID that uniquely identifies the target app and the context. Note that the IDs are not documented as there could be so many of them, but it is fairly easy to figure them out by experimentation. Since our target is the Facebook app and the Twitter app, let me save you the work by telling you what their IDs are.

Now let’s filter:

for (int i = 0; i < commandsAll.length; i++) {
if (commandsAll[i].getId().equals("Twitter_text")) {
commands[0] = commandsAll[i];
}
if (commandsAll[i].getId().equals("Facebook_text")) {
commands[1] = commandsAll[i];
}
}

…and we are done. We have our SendCommand objects and we are free to call their run() method anywhere in our app. Be it a Button click or a Menu selection, knock yourself out!