You know, working in the Developer Relations team at Research In Motion® (RIM®), you get to get to play around with some fun stuff. Recently, Near Field Communication (NFC) has been exercising my brain cells. Some of you may be familiar with the NFC-related articles and code samples that I’ve co-authored with my co-conspirator, Martin Woolley (@mdwrim), which you can find listed in our NFC Article and Code index.

Now, whenever you mention NFC in a conversation, people invariably think of payments. Using NFC to make secure payments is perhaps the most obvious use case. However, when I think of NFC I tend to think of workflows as well. “Workflows,” you say? What do you mean?

OK, let’s think about it anecdotally. How many times have you had the challenge of transcribing some data from an external source to your handset whilst holding a bag and trying to hold a conversation at the same time? How many times have you tried to share information on your handset with someone else and had to struggle with inputting email addresses whilst doing three other things at the same time? These use cases are examples of Workflows, or Business Processes, that stumble on the point of having to accommodate more “human” interaction than is really necessary. NFC can be used to help streamline simple workflows that involve human interactions on mobile devices and ultimately help achieve efficiencies.

So, having thought about this and how to demonstrate a simple but realistic use case (whilst also having some fun), we came up with the concept of the “Fun Run”.

Suppose you’re taking part in a charity “Fun Run” – not quite a marathon but something shorter for fun. The race organizers have developed a simple mobile application to allow you to register for the event and have placed NFC Tags in the starting and finishing areas. As you start you tap on one of the tags, your race timer is started as well as notifying the organizers that you have begun. When you pass the finish line, simply tap on one of the tags in the Finish area to stop your timer and notify the organizers of your finishing time!

In between the start and finish, there may be Way Points with NFC Reader devices that can be used to register intermediate times as the runner passes these points. Tap the handset to the NFC Reader and receive confirmation that the timing data has been transferred successfully.

OK, maybe it’s not 100% realistic, but as an example it is sufficient to demonstrate how a workflow process that involves having to record start and finish times and tracking progress can be made more efficient using NFC. The key learning point is to understand how integrating NFC technology into your application can be used to achieve efficiencies in similar processes.

The Applications

Let’s take a look at how we implemented this simple example using BlackBerry® 10 and BlackBerry® 7 NFC capable devices. There are really three use cases:

1. Tap your handset against an NFC tag at the start of the race to start your race timer.
2. Tap your handset against NFC readers at intermediate waypoints during the race to transfer your current race timer data to an application that manages the reader.
3. Tap your handset against an NFC tag at the end of the race to stop your race timer.

Acting on External Tag Events

To implement the first and last use case, we decided to provide two NFC tags that had specific NDEF messages as their content. There would be one tag that would start the timer at the start of the race and one tag that would stop the timer at the end of the race.

Specifically the data in the two tags is:

1. Tag used to start the timer:

NDEF TNF = External ( integer value 4 )
Type = “my.rim.com:myrecordtype”
Payload = “start”

2. Tag used to stop the timer:

NDEF TNF = External ( integer value 4 )
Type = “my.rim.com:myrecordtype”
Payload = “stop”

Why use this data? Well, firstly we choose an NDEF TNF (Type Name Format) for the NDEF Message because it allows us to define custom tag content that won’t clash with standard tag message types such as Smart Poster (“Sp”) or URL (“U”) or Text (“T”). We want to make sure that when one of these tags is presented, our application, and our application alone, is launched to process the tag.

Secondly, we choose a “Type” of “my.rim.com:myrecordtype“. Within the context of an External TNF record the Type can be arbitrary, but in order to prevent clashes with other organizations’ custom tag formats, we use the DNS naming scheme to set the namespace of the tag as “my.rim.com” to establish it as a RIM NDEF message. We further qualify it with a specific sub-type of “myrecordtype” since an organization may define a whole family of custom tag formats for its own use.

So, these settings ensure that these tags will only make sense to our application and not overlap with tags form elsewhere. The “Payload” of the two tags differs in that one has the string “start” and the other has the string “stop” to mark them as ones to be used to start and stop the timers respectively.

In the case of BlackBerry 10, our application registered with the Invocation Framework through the stanza in its “bar-descriptor.xml” file as shown in Figure 1. The “uris” attribute of the “<property … />” tag has been set to the value “ndef://4/my.rim.com/myrecordtype” which a URI format specification of the two tags just described above.

...
<invoke-target id="com.example.NfcRaceTimeWay">
    <type>APPLICATION</type>
    <filter>
        <action>bb.action.OPEN</action>
        <mime-type>application/vnd.rim.nfc.ndef</mime-type>
        <property var="uris" value="ndef://4/my.rim.com/myrecordtype"/>
    </filter>
</invoke-target>
...

Figure 1 Registering for tag types in BlackBerry 10

When a “start” or “stop” tag is presented to the handset, then our application is launched if it’s not already running, and the tag contents are handled as shown in Figure 2 — where the payload of “start” or “stop” is extracted once we’ve verified that it’s of the correct type.

...
void NfcListener::receivedInvokeRequest(const bb::system::InvokeRequest& request) {

    QByteArray data = request.data();
    QtMobilitySubset::QNdefMessage ndefMessage = QtMobilitySubset::QNdefMessage::fromByteArray(data);

    handleNdefRequest(ndefMessage);
}

void NfcListener::handleNdefRequest(const QtMobilitySubset::QNdefMessage ndefMessage) {

    QList::const_iterator ndefRecord;

    for ( ndefRecord = ndefMessage.begin(); ndefRecord != ndefMessage.end(); ndefRecord++) {
        if (ndefRecord->typeNameFormat() == QtMobilitySubset::QNdefRecord::ExternalRtd) {
            if (QString(ndefRecord->type()).compare("my.rim.com:myrecordtype") == 0 ) {
                emit raceTagDetected(QString(ndefRecord->payload()));
            }
        }
    }
}
...

Figure 2 Handling a Start or Stop tag in BlackBerry 10

In the case of BlackBerry 7, registration is achieved in Java® by registering a listener for the specific NDEF message type as shown in Figure 3.

...
    nfcManager = ReaderWriterManager.getInstance();
    nfcManager.addNDEFMessageListener(listener, NDEFRecord.TNF_EXTERNAL, "my.rim.com:myrecordtype", true);
...

Figure 3 Registering for tag types in BlackBerry 7

A similar behaviour is achieved for BlackBerry 7 through the implementation of the “onNDEFMessageDetected()” method of the “NDEFMessageListener” interface as shown in Figure 4.

...
    public void onNDEFMessageDetected(NDEFMessage msg) {
        NDEFRecord[] records = msg.getRecords();
        int numRecords = records.length;
        if(numRecords > 0) {
            byte[] payloadBytes = records[0].getPayload();
            try {
                String ascii_payload = new String(payloadBytes,"US-ASCII");
                Utilities.log("XXXX payload="+ascii_payload);
                if (ascii_payload.equals("start")) {
                    startTimer();
                }
                if (ascii_payload.equals("stop")) {
                    stopTimer();
                }
            } catch(UnsupportedEncodingException e) {
                Utilities.log("XXXX "+e.getClass().getName()+":"+e.getMessage());
            }
        }

    }

...

Figure 4 Handling a Start or Stop tag in BlackBerry 7

So, what we’ve achieved here is the ability to use an external NFC tag to trigger a process in our application. In this case it’s simply the starting and stopping of a timer, but it could be extended quite easily to, say, call a web service and integrate the event into a larger workflow process.

What does this look like in practice? Well, here’s a short video of the BlackBerry 10 application in action:

[ YouTube link for mobile viewing ]

Virtual Tag Emulation

Let’s get back to the original use cases. To implement the second one, we decided to have the BlackBerry handset emulate a virtual tag and allow the contents of the virtual tag to be read by an external NFC reader.
What format of tag should be emulated by the handset? This is what we chose:

1. Virtual tag emulated by the application

NDEF TNF = External ( integer value 4 )
Type = “my.rim.com:myrecordtype”
Payload = “hh:mm:ss”

a. That is the time displayed on the handset in:
Hours (hh)
Minutes (mm)
Seconds (ss)

The type of the virtual tag is exactly the same as for the “start” and “stop” physical tags for the very same reasons, except that the payload is a representation of the current race timer value (“hh:mm:ss”) as displayed by the application.

...
void NfcListener::startTagEmulation(const QString &tagData) {
    nfc_ndef_record_t *ndefRecord = makeCustomRecord(QString("my.rim.com"), QString("myrecordtype"), tagData);
    if (_emulateNdefMessage) {
        CHECK(nfc_delete_ndef_message(_emulateNdefMessage, true));
        _emulateNdefMessage = 0;
    }
    CHECK(nfc_create_ndef_message(&_emulateNdefMessage));
    CHECK(nfc_add_ndef_record(_emulateNdefMessage, ndefRecord));
    CHECK(nfc_start_ndef_tag_emulation(_emulateNdefMessage));
...

Figure 5 BlackBerry 10 – starting virtual tag emulation

As shown in Figure 5, starting tag emulation in BlackBerry 10 is quite simple. It just involves calling “nfc_start_ndef_tag_emulation()”. In addition we can use BPS (BlackBerry Platform Services) to determine when a read on the virtual tag has been successful, as shown here in Figure 6:

...
void NfcListener::handleNfcEvent(bps_event_t *event) {
    uint16_t code = bps_event_get_code(event);
    if (NFC_VIRTUAL_TAG_SELECTION_EVENT == code) {
        emit tagEmulationSelectEvent();
    } else if (NFC_VIRTUAL_TAG_LEFT_EVENT == code) {
        emit tagEmulationLeftEvent();
    } else if (NFC_VIRTUAL_TAG_READ_EVENT == code) {
        emit tagEmulationReadEvent();
    }
}
...

Figure 6 BlackBerry 10 – stopping virtual tag emulation

So, what we’ve achieved here is the ability to transmit live information from an application in the BlackBerry handset in real time to an external application via an NFC reader. The external application simply displays the time displayed by the BlackBerry application, but it could easily be extended to integrate with some larger workflow process.

Take a look at the video here for a demonstration of this on BlackBerry 10:

[ YouTube link for mobile viewing ]

If you’re interested, the virtual tag emulation functionality was tested using an NFC Reader attached to a PC controlled by a Python application using the “PyScard” (Python for Smart Cards) library available from SourceForge.net. (Python and Ruby are my favorite programming languages!)

The two versions of our NFC-enabled “Fun Run” applications are available with full source code from our GitHub repositories here:

https://github.com/blackberry/Cascades-Community-Samples/tree/master/NfcRaceTimeWay
https://github.com/blackberry/Samples-for-Java/tree/master/NFC/NfcRaceTime7

Just in closing, it’s worth making one or two comments about the relative ease of developing applications to the same set of end user specifications in BlackBerry 10 Cascades™ versus BlackBerry 7 Java. I’ve been developing code in C/C++ for more years than I care to remember and for a shorter time in Java (but still since the language first saw the light of day), so I feel I’m qualified to make comparisons. I’ll be honest: I’ve found it much easier to develop applications using C/C++ and Cascades. The user interface elements are particularly easy to use, and I’ve found it possible to get a user interface up and running in Cascades much faster than I would have done in Java. It’s much easier to modify and extend since Cascades elements map directly to Qt/Cascades C++ classes and the SIGNAL() / SLOT() model makes it so easy to connect events to handlers.

I’m definitely sold on Cascades, Qt and C/C++!

After a bunch of hard work, bbUI version 0.9.4 is finally here. The focus in this release has really been around bug fixes, optimizations and additional JavaScript® interfaces. The previous versions of bbUI have been VERY declarative and haven’t allowed for much manipulation after the fact via JavaScript. This release takes a step in the right direction to allow you to create more dynamic user interfaces via JavaScript. While there are some improvements in this department with v0.9.4, we’re not finished yet and have much more planned for v0.9.5.

One of the best things I’ve seen lately is the number of people participating in the project. It’s absolutely fantastic to see members of the community grab items from the roadmap, implement them and send them back as pull requests. These pull requests are full on feature creation as well as bug fixes. A gigantic THANK YOU goes out to all those who are helping to improve bbUI!

Be sure to check out the full change log for this release to know what kind of adjustments you may need to make to your JavaScript in order to run v0.9.4, and check out the closed issues for details on bugs that have been fixed and features that have been added. The v0.9.4 JavaScript changes are fairly minor and are meant to make your life easier as we continue to move forward.

Notable Improvements

• Updated coloring/styling to better match Cascades™
• New Title Bar styling which now allows images in the Title Bar
• New BlackBerry® PlayBook™ tablet 2.x styling for Activity Indicators, Text Input, Image Lists and Buttons
• Many new JavaScript interfaces to manipulate controls on-the-fly
• Native scrolling speed increases
• Screen stack bug fixes
• Control bug fixes

Changes to your code

I mentioned that there were a few changes that were made that will affect your applications JavaScript so let’s talk about those.

• bb.init()
  • bb10ActionBarDark renamed to actionBarDark
  • bb10ControlsDark renamed to controlsDark
  • bb10ListsDark renamed to listsDark
  • bb10HighlightColor renamed to highlightColor
• You no longer specify a viewport meta tag in your main index.htm. This is now supplied by the toolkit at runtime based on the OS version.
• BlackBerry® 10 title bars now take on the control coloring.
• You no longer need to specify a unique id for your script tags used with screens.
• Scroll Panel JavaScript interfaces have been modified.
• If you were calling bb.scroller.refresh() you will want to change your code to “if (bb.scroller) bb.scroller.refresh();”

More to Come

We’ve now created an additional v0.9.5 milestone for bbUI that contains additional BlackBerry 10 styling improvements, but also includes more JavaScript interfaces for dynamic screen creation and manipulation. If you’re interested in following the bbUI.js changes as they go, feel free to follow me on Twitter®.

OpenAL, from Khronos, is designed to solve that exact problem. It is an open source, cross platform 3D Sound API for use in games and multimedia apps. Thankfully, OpenAL 1.1 is readily available on BlackBerry® 10. It is supported on multiple platforms and due to its API looking strikingly similar its 3D graphics cousin OpenGL API, it has proved to be very easy to learn and integrate. OpenAL, however, does not directly support compressed audio formats out-of-the-box. This could result in games having bigger audio files and hence a bigger memory footprint.

Enter OggVorbis.

There are several compressed audio formats and associated libraries available and I recommend OggVorbis for the following reasons:

• It’s lightweight
• It’s open source
• It’s professional quality audio encoding
• It’s streaming support

If you need further convincing, please visit their site.

This blog post uses a sample project to show how to set up and use OpenAL and OggVorbis with the BlackBerry 10 Native SDK. The sample is forked off the famous “cascades cowbell app” and minor modifications have been made to show how to load and play .ogg and .wav files. Assuming you are already familiar with the BlackBerry 10 Native SDK, here are the main steps to follow:

Convert your assets

Download a tool of your choice from http://www.vorbis.com/software to convert the heavy WAV PCM files to the slender OGG files.

Add the OggVorbis library to your project

OggVorbis is already ported and available at the BlackBerry Github community, so go ahead download the source code () and compile it using BlackBerry 10 Native SDK. Once compiled, add the library (example: libvorbis.a) and the headers into a folder inside the cowbell application project directory. Let’s call it “external-lib”. Now modify the cowbell.pro project to include the header and library files.

LIBS   += -lOpenAL -lalut -L../external-lib/oggvorbis/lib/qnx/arm/ -L../external-lib/oggvorbis/lib/qnx/x86/ -lvorbis

INCLUDEPATH += ../src ../external-lib/oggvorbis/include
SOURCES += ../src/*.cpp 
HEADERS += ../src/*.h

Now that we have the project setting done, we can focus on loading and playing the .ogg file.

Open the OGG file

The function that opens up the access to the OggVorbis file is ov_open. Declare an OggVorbis_File file type that is returned by the ov_open. This file will be used to decode the OggVorbis file.

OggVorbis_File ogg_file;
ALenum format;
int result;
unsigned int size = 0;

rewind(file);

// Open the ogg file
if (ov_open(file, &ogg_file, NULL, 0) < 0)
fclose(file);

Calculate the unpacked audio file size

In order to load the uncompressed data into an OpenAL buffer, we need to store the audio data in a temporary buffer. The size of the audio buffer can be found using a simple formula: (number of channels) * (number of samples) * (number of bytes per packet)

The number of channels info can be retrieved into vorbis_info using the ov_info function. The number of samples can be found using the ov_pcm_total function.

vorbis_info* info;
// Get the file info for creating the audio buffer
info = ov_info(&ogg_file, -1);

if (info->channels == 1)
	format = AL_FORMAT_MONO16;
else
	format = AL_FORMAT_STEREO16;

// buffer size = (no. of channels) * (no. of samples) * 2 (for 16 bit)
unsigned int data_size = ov_pcm_total(&ogg_file, -1) * info->channels * 2;

Decode the audio file

Once we have a temp buffer allocated, the ov_read function can be used to read and decode blocks of audio data.

char* data = new char[data_size];

// Read the Ogg file into audio buffer
while (size < data_size) {
	result = ov_read(&ogg_file, data + size, data_size - size, 0, 2, 1, &section);
	if (result > 0)
		size += result;
	else if (result < 0) {
		delete data;
		return false;
	}
	else {
		break;
	}
}

Load the data into an OpenAL buffer

Assuming we have already initialized OpenAL context and audio buffers to hold audio data, we can now upload the unpacked data into it.

// Load PCM data into OpenAL buffer.
alBufferData(buffer, format, data, data_size, info->rate);

ALenum error = alGetError();
if (error != AL_NO_ERROR)
	reportOpenALError(error);

Playing the audio is no different than playing regular PCM audio data.

The full sample is available under an Open Source license at here. Enjoy and consider participating in our Open Source community

We’ve been receiving lots of great feedback on the bbUI framework as we’ve been continuing the BlackBerry® 10 Jam World Tour. Thank you all for your constant collaboration and continuous feedback! We even had a chance to receive a feature request during the morning of the Toronto stop and implement a new scrolling panel feature by the end of that same day

This release looks to further close the gap between what’s being offered in the Cascades™ UI framework and what’s available in bbUI.

Be sure to check out the full change log for this release to know what kind of adjustments you may need to make to your markup in order to run v0.9.3 and check out the closed issues for bugs that have been fixed. The v0.9.3 markup changes are fairly minor and are meant to make your life easier as we continue move forward.

Notable Improvements:

• Action Bar
  • Now has tab overflow menus
  • UX updates to match latest Cascades experience
  • Full control of which items to show on the action bar vs. the overflow menus
  • Ability to “pin” an action to the bottom of action overflow and context menus
• Image List
  • Supports multiple new styles such as allowing secondary action buttons for items
  • Additional JavaScript® interfaces for list manipulation
  • Adjusted alignment to support “title only” list items
• Buttons
  • Now allow for text only | image only | text + image
  • Additional JavaScript interfaces for button manipulation
• BlackBerry® PlayBook™ tablet controls with BlackBerry 10 styling have been re-sized to better fit the device resolution
• File Input controls now have BlackBerry 10 styling to appear as a button which launches the browse dialog
• Added toggle button styling for BlackBerry 10 with some funky animation
• New activity indicator styling for BlackBerry 10
• Additional JavaScript interfaces for Title Bar manipulation
• Added checkbox styling and JavaScript interface for BlackBerry 10
• New scroll panel for master/detail type of views on BlackBerry PlayBook tablet
• New sliding screen transitions for BlackBerry 10 and BlackBerry PlayBook tablet styling
• Font adjustments now look better when emulating in Ripple

Changes to your code:

I mentioned that there were a few changes that were made that will affect your application markup so let’s talk about those.

• Default control color for BlackBerry 10 has been changed from dark to light. You should explicitly state your color choice in the bb.init() function to suit your application’s style
• The progress bar’s pause() function has been removed and replaced with setState() to allow for normal, warning and error states
• You now must explicitly state which actions/tabs on the Action Bar are to show on the overflow menus
• Arrow List control has now been merged as a feature of the image list. You will have to change your existing arrow list markup to image list markup with the proper style attribute
• By default a screen’s background color is now white unless you explicitly set its style. This was needed in order to implement the sliding transitions
• BlackBerry 10 buttons no longer stretch by default. To stretch you need to set the data-bb-style=”stretch” attribute
• Default font has been changed from Slate to Slate Pro for BlackBerry 10

More to Come:

We’ve now created an additional v0.9.4 milestone for bbUI that contains additional BlackBerry 10 controls but also includes more JavaScript interfaces for dynamic screen creation and manipulation. It also contains some updates around Tablet user experience. If you’re interested in following the bbUI.js changes as they go, feel free to follow me on Twitter®.

Okay…now that we’ve covered what’s new and what’s changed, I think it’s time for some of that good old eye candy

Image List Additional Styles

Tab Overflow menu, item centering and action pinning

Sample Action Bar Layouts

Buttons with Images and Activity Indicators

Scrollable Areas for Master/Detail Layout

Toggle Buttons and Checkboxes

Beta 2 of the BlackBerry® 10 SDK for Adobe® AIR® now has support for participating in the BlackBerry 10 Invoke Framework. You can find all of the APIs in the QNXDevice.ane and they are all documented.

Invoking a Application

By leveraging the Invoke API, you can invoke virtually any other application on the BlackBerry® smartphone through some simple API call, where you’ll set a parameter for the app you want to invoke and then pass in any parameters that application is expecting. A typical example would be that your application can invoke the BlackBerry® Maps application when it comes across an address. InvokeManager.invoke() will invoke an application.

When the application has been successfully invoked, an InvokeEvent.INVOKE_TARGET event will be dispatched. If there was an error invoking the target, an ErrorEvent.ERROR event will be dispatched. Please refer to the following Knowledge Base article for details on some known issues which will be addressed in an upcoming patch.

Invoking a Viewer

InvokeManager.invokeViewer() will invoke a viewer. A Viewer class is returned and is used to communicate with the viewer.

Let’s say you have an image viewer application and you want to invoke it from the main application you’re working on. In the main application, you want to pass the image file that the imager viewer app will open when invoked.

Below is a sample of how you can invoke a viewer and wait for it to be created. This example assumes that you have created the viewerRequest object with the correct data for your viewer.

var viewer:Viewer = InvokeManager.invokeManager.invokeViewer( viewerRequest );
viewer.addEventListener( ViewerEvent.VIEWER_CREATED, viewerCreated );

private function viewerCreated( event:ViewerEvent ):void
{
   //viewer is created and ready to communicate with.
}

Making your Application an Invoke Handler

If you are developing an application that can be invoked by another application, you will want to add a listener for the invoke event at the very start of your application. These should be the first lines of your application.
Once you have received the invoke event, you can check the startup mode and get the data that you were invoked with.
Below is a sample of how you would accomplish this:

InvokeManager.invokeManager.addEventListener(InvokeEvent.INVOKE, onInvoked );
private function onInvoked( event:InvokeEvent ):void
{
    if( InvokeManager.invokeManager.startupMode == InvokeStartupMode.INVOKE )
    {
        var invokeRequest:InvokeRequest = InvokeManager.invokeManager.startupRequest;
    }
    else if( InvokeManager.invokeManager.startupMode == InvokeStartupMode.VIEWER )
    {
        var viewerRequest:InvokeViewerRequest = InvokeManager.invokeManager.startupViewerRequest;
    }
}

Query a list of targets

You can also query a list of targets or viewers on the device by calling the InvokeManager.queryTargets() method. At some point in the future, this will make a pop-up list in your application that will allow users to select items from the list. For now, it returns the results and it is up to you to use those values in your invoke() and invokeViewer() calls.

InvokeEvent

No matter how your application is started, you will receive an InvokeEvent dispatched by the InvokeManager. In order to determine how your app was started, you can check the InvokeManager.startupMode in your InvokeEvent handler. So, your application would look something like the following, assuming that your application can be launched as a target and a viewer:

package
{
    import qnx.events.InvokeEvent;
    import qnx.invoke.*;

    public class Main extends Sprite
    {

        public function Main()
        {
            //NOTE: THIS MUST BE THE FIRST THING SET IN YOUR APPLICATION CONSTRUCTOR
            InvokeManager.invokeManager.addEventListener(InvokeEvent.INVOKE, onInvoke );
        }

        private function onInvoke( event:InvokeEvent ):void
        {
            if( InvokeManager.invokeManager.startupMode == InvokeStartupMode.INVOKE )
            {
                //invoked as an application/target.
                var data:InvokeRequest = InvokeManager.invokeManager.startupRequest;
            }
            else if( InvokeManager.invokeManager.startupMode == InvokeStartupMode.VIEWER )
            {
                //invoked as a viewer
                var data:InvokeViewerRequest = InvokeManager.invokeManager.startupViewerRequest;
            }
            else
            {
                //launched by the pressing on the icon on the home screen.
            }
        }
    }
}

Closing a Viewer

There are two different ways a viewer can be closed:

1. From the application
2. From the viewer

When an application wishes to close a viewer that it has created, it can simply call the Viewer.dispose() method. This will cause the viewer to be removed immediately.

A viewer can request to be closed by the application and should never actually attempt to close itself directly. Viewers can call the InvokeManager.requestViewerClose() method. This will send a message to the application requesting that it be closed. The Viewer instance in the application will dispatch a ViewerEvent.VIEWER_CLOSE_REQUEST event. When application receives this event, it should call the dispose() method on the viewer to close it. The reason this doesn’t happen automatically is so that applications can transition viewers out before removing them. We may make this a bit more automated in the future, and we’ll let you know when this happens.

Viewer message relay

Viewers can send data to applications using the InvokeManager.viewerSendMessage() method. The Viewer instance will then dispatch ViewerEvent.VIEWER_MESSAGE events with the message and data properties set to what was passed into the viewerSendMessage(). Here is an example of how you would use this:

Viewer code

InvokeManager.invokeManager.viewerSendMessage( "select", {name:"Fred"});

App Code

__currentViewer = InvokeManager.invokeManager.invokeViewer(viewerRequest);
__currentViewer.addEventListener( ViewerEvent.VIEWER_MESSAGE, onMessage );

private function onMessage( e:ViewerEvent ):void
{
    trace( e.message, e.data ); //outputs "select Fred";
}

In today’s post, I’ll talk about property aliases and why they’ll be your friend when creating custom components in QML. I’ll give you an introduction to the topic by creating a Header component, which consists of a Label and a Divider wrapped inside a Container.

I assume that you already know how to create custom components in QML. Basically you create a new file and name it to whatever the name of your component is, for example ‘Header.qml’. So say we have a file ‘Header.qml’ with the following content:

import bb.cascades 1.0

Container {

    Label {
        id: titleLabel
        text: "Sample Title"
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }

    Divider {
    }
}

To create a Header instance from another QML file, we simply write the following lines:

...

Header {
}

...

Looks good, but I assume that we also want to set the title to something more appropriate for the context where the header is to be used. Because we don’t have direct access to the Label’s text property from outside the Header component (you can only access top level properties), we need to add a new property to the Container in the Header component:

import bb.cascades 1.0

Container {
    property string titleText: “Sample Title”

    Label {
        id: titleLabel
        text: titleText
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }

    Divider {
    }
}

The Label’s text property binds to the newly added titleText property. Now we can specify a title by setting the titleText property:

Header {
    titleText: “My Header”
}

Looks nice and works great, but I’m still not satisfied. I had to introduce a new property just to be able to specify a title text. What I actually want is to expose the Label’s text property to users of the Header component. Fortunately there’s a solution for this, and the name is property alias:

import bb.cascades 1.0

Container {
    property alias titleText: titleLabel.text

    Label {
        id: titleLabel
        text: “Sample Title”
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }

    Divider {
    }
}

Much better. We got rid of the titleText property by simply making it an alias to the titleLabel’s text property instead. Even the instance of the Label can be exposed as an alias, which gives you access to all of the Label’s properties, if that’s what you need:

import bb.cascades 1.0

Container {
    property alias titleLabel: titleLabel

    Label {
        id: titleLabel
        text: “Sample Title”
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }

    Divider {
    }
}

Now that we have access to all of the Label’s properties, we can also change the text style:

Header {
    titleLabel {
        text: “My Title”
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }
}

Handy, right?

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!

BlackBerry® evangelists met with Android™ developers last week at AnDevCon III in Burlingame, CA to talk about the cool development options of bringing Android apps to the BlackBerry platform, and how to publish them on the BlackBerry App World™ storefront to reach a global audience. The word of how easy the process is started to spread out quickly among conference participants at two full-house events on day one of the conference – the Lightning Talk presented by Larry McDonough, Head of Developer Evangelism Americas at Research In Motion (who talked about bringing existing Android apps to the BlackBerry® PlayBook™ tablet), and at the class taught by Rajeev Mohindra, Director, Handheld App Architecture (about running Android applications on BlackBerry).

More BlackBerry development action was happening at the RIM booth, where developers signed up as vendors to BlackBerry App World and learned from BlackBerry experts how to use some of the tools for BlackBerry Runtime for Android apps to convert their Android “apk” files into BlackBerry-compatible “bar” files. Those developers who completed both these steps became the happy recipients of a free BlackBerry PlayBook tablet on which to continue their development work. That they were all excited to convert their Android apps for the BlackBerry platform is an understatement — not to mention how pleasantly surprised they were to see how easy it was to make their apps work on the BlackBerry PlayBook tablet without having to change any code. The BlackBerry team saw all kinds of interesting apps – ranging from games to educational – all successfully ported to the BlackBerry platform.

To top it all off, a BlackBerry PlayBook tablet was in the mix for the AnDevCon III Winner’s Circle Prize, and was won by Erol Yesin from Navman Wireless. Congratulations to Erol and to all the other developers from whom we are waiting to hear back soon with progress updates.

You can catch up with us again in a couple of weeks, as the BlackBerry 10 Jam World Tour will be making a stop in Santa Clara, California.

One of our priorities is to make sure that apps written with the BlackBerry Native SDK for Tablet OS will transition with minimal hassle to our BlackBerry 10 platform. We don’t want you, our developer community, to have to reinvent the wheel or tweak significant amounts of code. We also want to make sure that our developers are aware of changes coming to the platform that may impact them so they can prepare accordingly. With that in mind, I want to talk about two important upcoming changes to the BlackBerry 10 Native SDK in order to help developers prepare for upcoming releases. The motivation for both changes is to help developers scale their apps from tablets to phones.

The first change has to do with multi-icon support. We want to create a seamless way for developers to port their BlackBerry PlayBook tablet applications to the BlackBerry 10 smartphone. As we support two device screen sizes, applications may need to provide more than one icon size depending on the device they are being installed on. Developers will now be able to specify a list of icons and splash screens per locale and per resolution in the bar descriptor. These would be of various sizes to suit the different target displays. The runtime will then choose the icon and splash screen that matches the given display. We will be maintaining backwards compatibility, so existing apps written for the BlackBerry PlayBook tablet should not have to modify anything. However, if you are moving your app to a BlackBerry 10 device, you will have to specify icons and splash screens with alternate sizes.

The second important change is with respect to orientation. On BlackBerry 10, native applications will not be able to get the width and height values that they need for sizing their windows and determining orientation by querying the ‘WIDTH’ and ‘HEIGHT’ environment variables. If the width is greater than the height, the application will know it is running in landscape mode and vice versa. This behaviour has changed from BlackBerry PlayBook OS 2.0. On BlackBerry PlayBook OS 2.0, an application would query the screen APIs to get its width and height. For applications running on BlackBerry PlayBook OS 2.0, they can continue to rely on this behaviour as this is now going to change. On BlackBerry 10, however, applications are discouraged from querying for their width and height using the screen APIs. The following code snippet illustrates how an app can query for its width and height:

int screen_resolution[2];
screen_resolution[0] = atoi(getenv("WIDTH")); //get width
screen_resolution[1] = atoi(getenv("HEIGHT")); //get height

Once the application gets these values (which it can and should do at startup), the application can proceed to create and set up its window.

screen_create_window(&window, context);
rc = screen_set_window_property_iv(window,
SCREEN_PROPERTY_SIZE, screen_resolution);
if (rc) {
//handle error …
}

rc = screen_set_window_property_iv(screen_win,
SCREEN_PROPERTY_BUFFER_SIZE, screen_resolution);
if (rc) {
//handle error …
}

Applications written for BlackBerry 10 should not set the SCREEN_PROPERTY_ROTATION value, as Navigator will set this for the application automatically when it posts its window.

Furthermore, if you were writing native apps on BlackBerry PlayBook OS 2.0, you would have had to write extra logic to rotate your window based on what you read out from the “ORIENTATION” environment variable. The box below shows an example of how orientation was set up in the BlackBerry PlayBook OS 2.0 setup. This code can now be removed, thereby simplifying your setup logic.

//THIS CODE CAN NOW BE DELETED

int angle = atoi(getenv(“ORIENTATION”));
int buffer_size[2] = {screen_resolution[0], screen_resolution[1]};
int flip = false;

if ((orientation == LANDSCAPE) && (buffer_size[0] <
buffer_size[1])) {
//In landscape, rotate to portrait
buffer_size[0] = screen_resolution[1];
buffer_size[1] = screen_resolution[0];

if ((angle == 0) || (angle == 180)) {
//Landscape device in landscape mode
angle = 90;
} else if ((angle == 90) || (angle == 270)) {
//Portrait device in landscape mode
angle = 0;
}

flip = true;
}

if (flip) {
rc = screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_ROTATION,
&angle);
if (rc) {
//handle error …
}

rc = screen_set_window_property_iv(screen_win,
SCREEN_PROPERTY_BUFFER_SIZE, buffer_size);
if (rc) {
//handle error …
}
}

When it comes to determining current orientation, applications should always rely on the navigator to present current orientation. You should never use the accelerometer to determine orientation. The navigator will also inform the application when it needs to rotate and will initiate the rotation sequence by sending the application a rotate (PORTRAIT or LANDSCAPE) message. These new “rotate” messages are replacing the “orientation” messages on the current 2.0 Navigator. It is to be noted as well that the old orientation messages used to specify rotation in angles, while rotation will be specified as Landscape or Portrait in the new messages. These new units are much more intuitive in my opinion and map more closely with how we think of orientation on the device.

As a native app developer, there are several things you need to consider:

• Continuing to support your application on BlackBerry PlayBook OS 2.0 won’t require any change – things will continue to work as before.
• If you are developing a native app only for BlackBerry 10, you should make sure to use the new method of getting width and height parameters from navigator as well as using the new rotate messages.
• If you already have an app on BlackBerry PlayBook OS 2.0 and want to move it to BlackBerry 10, you will have some minor changes to make to port your app over. Your code on BlackBerry PlayBook OS 2.0 will not be able to get the width/height parameters via environment variables, so you will continue to use the old methods. On BlackBerry 10, you should use the parameters you receive from navigator for this.

These changes are not drastic, and our hope is that you will be able to migrate from BlackBerry PlayBook OS 2.0 to BlackBerry 10 with minimal fuss. In passing, I should also point out that these changes target developers who are writing applications right on top of our low-level windowing framework, so these changes mainly impact game developers. If you are writing a Cascades™-based application, you should also be abstracted from most of these changes and should consult your Cascades documentation.

I am personally excited about these changes as they will enhance the development capabilities of the BlackBerry 10 Native SDK when it comes to supporting multiple resolutions and orientation. When the time comes for you to start developing or moving your app or game over to the BlackBerry 10 platform, you should definitely consult the developer documentation for more details on these two features and how they will impact your application.

Happy developing!

One of the true pleasures of my job is talking with developers. Creative, outspoken, funny, smart, artistic, genuine – they’re just some of the best people in the world to hang with. BlackBerry® 10 Jam was amazing last week. The code demos, AppCircus, the lunches and down time with people at the bar – these were the highlights for me.

As you know, I publish my email address everywhere (alec.saunders@rim.com), and people write to me. Nobex Chief Software Architect Jamie Julius wrote me the following last Friday, and gave me permission to share it with you all:

Hi Alec,

I wanted to thank you personally for such a great BB 10 Jam.

Last November, a letter that I had sent to someone at RIM was forwarded to you. In it I described my feelings after attending DevCon last fall in San Francisco.

Well, things have definitely changed. The difference between that DevCon and this Jam is like night and day.

Over the last three days, in keynotes and in sessions, the messages coming from RIM were very clear. Not only do we now see more clearly where RIM is going, but also what we should be doing as developers. As opposed to a vague range of technologies to be supported, it has now been made more clear which will work best for what.

For Nobex Radio, for example, all the RIM technical representatives made it very clear to me why Cascades is the way for us to go. The list of reasons is long. We never received such a clear message before.

I came away feeling that BB10 is now tangible. And I don’t just mean that I can hold the Dev Alpha device in my hand. I see real API’s! Even if some aren’t ready yet, I see them coming. I know what they will cover. That makes a really big difference. I also have an IDE with which to start writing real code. That makes a big difference too.

Back in November, games were over-emphasized. Not anymore. I think RIM has re-focused its identity. Games should definitely have an important place on BlackBerry smartphones, but not blown out of proportion.

So, a big congratulations to you and your team for doing such a great job putting together BB 10 Jam.

The enormous investment that RIM is making in dev relations has not gone unnoticed.

THANK YOU!

Jamie Julius
Chief Software Architect
Nobex Technologies

Thanks Jamie.

There are still lots of milestones to cross on the road to BlackBerry 10, but last week was a major step forward for RIM and the development community. We hope everyone who came to BlackBerry 10 Jam walked away with the same experience as Jamie, and we’re counting on you all, so let’s go write some code together!