I’ve heard a lot of people claim that the gamepad is dead – doomed to be replaced by touch screens. I disagree with this sentiment.  There’s nothing wrong with mobile games using cool new control schemes that make good use of touch screens – but if I’m playing a game that was designed with gamepads in mind, like Shadowgun, why can’t I just use a real controller?

Well, now I can – and so can you. Check out gamepad support now being added in upcoming Unity 4 for BlackBerry 10:

After years of being frustrated by touch screen gamepads, I’m excited about bringing physical gamepad support to the Native SDK for BlackBerry 10. By making use of the new Gamepad API features developers can make their games work with physical controllers, giving their players the tactile responsiveness they’re used to from consoles and desktop PCs. When this is combined with BlackBerry 10’s built-in HDMI connectivity, you end up with a console experience in your pocket!

Here is another video showcasing gamepad pairing instructions and a racer sample on GamePlay3D that now supports not only desktop gamepad support but also BlackBerry 10:

Before you get started implementing this in your own game, I want to answer a few of the most common questions people ask me about the API.

1. What gamepads are supported right now?
   1. The SteelSeries Free.
   2. The Gametel.
   3. The Wii Remote.  Note that currently only the core buttons on the remote itself are supported – that means no attachments and no motion controls, just the D-Pad and other buttons.
2. If new gamepads come out, do I have to update my game to support them?
   1. No, you don’t!  When new controllers become available, we’ll update the mappings in a system update and your game will start receiving gamepad inputs from the new hardware.  Because the Gamepad API is an abstraction above HID, and because we map each gamepad’s unique HID report format to the Gamepad API, you don’t need to write any code that’s specific to a single controller.
3. Do users need to install anything to set up or configure their gamepads?
   1. No.  The Gamepad API is integrated into the Screen library, the same library you are already using to handle touch, keyboard, and other input events.  All users have to do is pair their device through the Bluetooth settings screen for it to start sending inputs to your game.

We realize there are other gamepads out there and continue to work towards supporting as many devices as possible. If you know of a Bluetooth, HID-compatible game controller that’s not supported yet, please let us know in the comments. Meanwhile, the fact that you won’t have to change your code when we add more devices to the list means you only help yourself (and your users) by starting to use this new feature right away.

Here’s a tutorial that should get you up and running. It includes plenty of code snippets and is based on this open-source sample project, which started as a little app I whipped up to test the new API. It eventually turned into a demo of two-player connectivity and a configuration screen.  I hope you find it useful.

Please, for the sake of everyone who’s ever been frustrated by touch controls, try this new feature and leave your feedback – I’m eager to do what I can to help if you have any trouble.  Most of all, I’m looking forward to playing your games with a real gamepad!

Links:

• Tutorial
• Sample code
• SteelSeries Free
• Gametel

code:

a.icon.good2 {
	background: #215387 url(test-sprite@2x.png) 4px -6px / 40px 82px no-repeat;
	}

Note: Including the size in the background property is not supported in older browsers. See example 2 below for a more backwards compatible solution.

Issue:

The W3C spec for the background shorthand property specifies that when declared without a size property it initializes size to ‘background-size: auto auto;’. Previously there was quirk with WebKit where if size was omitted it just didn’t initialize the size property for the background. This allowed for a previously declared background-size declaration to remain intact, displaying the image at its proper size. This quirk has since been removed and the latest release of WebKit now follows the W3C spec.

Bad code

a.icon {
	background-size: 40px 82px;
	}
a.icon.bad {
	background: #215387 url(test-sprite@2x.png) 4px -6px no-repeat;
	}

Produces

Solution

1. Add size to the background short-hand property and eliminate the background-size property

Code

a.icon.good2 {
     background: #215387 url(test-sprite@2x.png) 4px -6px / 40px 82px no-repeat;
}

Produces

2. If you must resize a background-image via a background-size property declare background size after the background property so it isn’t overridden.

Code

a.icon.good {
	background: #215387 url(test-sprite@2x.png) 4px -6px no-repeat;
	}
a.icon.good {
	background-size: 40px 82px;
	}

Produces

References:

http://www.w3.org/TR/css3-background/#the-background
https://bugs.webkit.org/show_bug.cgi?id=97761
http://lists.w3.org/Archives/Public/www-style/2012Oct/0112.html
http://caniuse.com/#search=background-size

Now it has to be said that it wasn’t the best summer here in the UK (though fortunately the weather gave us a break just in time for the Olympics!) and so I occasionally found myself at the weekend with “fine weather-dependent plans” cancelled and time on my hands. One such weekend, I was thinking about NFC and my thoughts turned to discussions I’d had with John about whether NFC could enrich games and the gaming experience in some way.

The world of computer games has changed somewhat in the 30-something years I’ve been playing them! It’s gone from text-based adventure games (“go north!”) played on a PDP-11 with a teletype and no screen, through the block graphics of Lunar Lander on a Commodore Pet, and onwards through Space Quest, Civilisation I, the Monkey Island series and (many) more favourites.

In the beginning and for many years, games were single-player — or at least they were single machine games. More than one player could play, but you’d have to share the keyboard or take turns. Then came LAN games, and this evolved into Internet-based gaming with huge online gaming communities (without whom, I have no doubt, the world would now be over-run with zombies). The truly great thing about online gaming is that you need never know that “goreslayer765” who just destroyed you in your favourite game is actually a 9-year-old with far more knowledge of automatic weapons than can possibly be healthy. I mean, whose fragile ego could handle knowing that?

So, both extreme ends of the single player vs. multiplayer spectrum are well catered to these days. But in what way might NFC enrich the gaming experience, and in what kind of games? I had a quick brainstorm with John on IM and we came up with a few use cases:

But why would you want to do this? After all, there are plenty of other ways to trigger “new game” or “it’s your turn now” and to share data across a network. Well, the appeal of using NFC is simply this: it adds a physical, tactile element to the game. You’re sitting right next to the person you’re playing with, and having to touch devices at intervals in the game could add a novel and fun element to the experience.

We then realized our most important task. We needed a name for the phenomenon of NFC-enabled games that we were now thinking about. In a flash, I had it! Please welcome “Proximity Gaming” to the world!

Armed with a few ideas, we decided to develop a game as a proof of concept and set about thinking about what the first game would be and how it would work. We decided we’d develop an NFC-enabled version of “tic tac toe” or “noughts and crosses” as it’s known in the UK.

We decided to use NFC in two places. Firstly, players would have to touch devices to start a game, and secondly, they’d touch devices to indicate “it’s your turn now”.

We had to consider a few issues regarding the implementation. It was immediately apparent that we’d have to pass some kind of message from device A to device B and that we’d probably need several message types. In other words, we’d need a simple protocol.

We could also see several technical ways of sending a message from one device to another. We could use virtual target emulation in theory, or maybe we could use one of the two NFC peer-to-peer APIs, SNEP (Simple NDEF Exchange Protocol) or LLCP (Logical Link Control Protocol).

We dismissed target emulation and focused on the peer-to-peer options, since this was clearly a peer-to-peer scenario. We concluded that either SNEP or LLCP could be used, but that SNEP would be a little easier to work with — LLCP being a lower-level connection-oriented protocol whereas SNEP is a higher-level message-oriented protocol. We’d worked with both in the past, so we had a pretty good feel for what the coding would be like.

In conclusion, we decided to invent a simple message-oriented protocol and use SNEP as the NFC protocol, which would transport game messages between devices. The UI design was to be basic: an initial screen that prompted players to touch devices to start a new game; a screen for “player 1” to choose either noughts or crosses; and the main game screen upon which to place noughts and crosses.

We also decided to implement the game for both BlackBerry® 7 OS using Java®, and our BlackBerry® 10 Dev Alpha devices using C++/Qt/Cascades. Being able to play the game between a BlackBerry 7 device and a BlackBerry 10 device would be a nice proof of the interoperability of NFC between generations of BlackBerry technology.

Here are some screen shots from the proof of concept game, first from the BlackBerry 7 version of the game:

Figure 1 – New game screen

Figure 2 – Player 1, choose nought or cross

Figure 3 – Main game screen

And here are some screen shots from the proof of concept game, from the BlackBerry 10 version of the game:

  
Figure 4 – New game screen; Figure 5 – In game; Figure 6 – Game over

Thoughts on the “game protocol” crystalized properly as we worked through prototyping the game and we found we needed the following message types in the simple protocol:

We’d like to tell you how we went about coding the game.

If you want to know how to use SNEP in general terms, we’ve written articles on the subject for both BlackBerry 7 and BlackBerry 10 and sample code too. You’ll find details here:

BlackBerry 7 – Peer to Peer Communication with SNEP
BlackBerry 10 – Peer to Peer Communication with SNEP

There’s a key point here: you could implement your Proximity Gaming ideas for either BlackBerry 7 or BlackBerry 10 because both have the specific types of NFC peer-to-peer capabilities that you will need.
Harnessing NFC SNEP in the way we wanted for our game was easy. The APIs themselves are very straightforward to use. For BlackBerry 7 we designed some Java classes, which represent the various message types in the game protocol. This was standard stuff if you’re accustomed to working with protocols, and we ended up with an abstract class called ProtocolMessage and a series of concrete sub-classes, one for each message type. Each of these classes implemented a marshall and demarshall method so that we could easily swap between byte array representations, which would be exchanged over NFC SNEP and Java objects for internal use in the application.

Here’s an example of one of the protocol message classes:

public class ProtocolMessageMasterBid extends ProtocolMessage {

    private int bid;

    public ProtocolMessageMasterBid() {
        message_id = Constants.PROTOCOL_MASTER_BID;
        Random rand = new Random(System.currentTimeMillis());
        bid = rand.nextInt(1000000);
    }

    public byte[] marshall() {
        byte [] bid_bytes = Utilities.toBytes(bid);
        byte [] bytes = new byte[1+bid_bytes.length];
        bytes [0] = message_id;
        System.arraycopy(bid_bytes, 0, bytes, 1, bid_bytes.length);
        return bytes;
    }

    public void demarshall(byte[] bytes) {
        if (bytes.length != 5) {
            Utilities.log("XXXX invalid parameter length passed to ProtocolMessageMasterBid demarshall:"+ bytes.length);
            return;
        }
        message_id = bytes[0];
        bid = Utilities.toInt(bytes,1);
    }

    public int getBid() {
        return bid;
    }

    public void setBid(int bid) {
        this.bid = bid;
    }

    public String toString() {
        String string = super.toString() + ",ProtocolMessageMasterBid" + ",bid="+bid;
        return string;
     }
}

We also implemented classes called NfcReceiver and NfcSender, which implemented NDEFMessageListener and NDEFMessageBuilder respectively and provided the basic mechanism for sending and receiving my protocol messages.

For BlackBerry 10, life was actually simpler and we just needed to create message using the Qt QbyteArray class and then utilize the BlackBerry 10 native APIs for NFC, as shown below:

void NfcWorker::sendTurnData(bps_event_t *bps_event) {
	nfc_event_t *nfc_event;
	nfc_target_t* target;
	nfc_ndef_record_t* myNdefRecord;
	nfc_ndef_message_t* myNdefMessage;
	// Obtain NFC target object from our BPS NFC event object
	//------------------------------------------------------------------------------
	CHECK(nfc_get_nfc_event(bps_event, &nfc_event));
	CHECK(nfc_get_target(nfc_event, &target));
	//------------------------------------------------------------------------------

	QByteArray ba;
	ba.resize(9);
	ba[0] = 2; // turn over message ID
	// tile changed
	ba[1] = 0;
	ba[2] = 0;
	ba[3] = 0;
	ba[4] = _state->lastSelection();
	int ls = _state->lastSelection();
	// symbol changed
	ba[5] = 0;
	ba[6] = 0;
	ba[7] = 0;
	ba[8] = _state->mySymbol();
	int ms = _state->mySymbol();
	_state->mySymbol();
	myNdefRecord = makeTurnOverRecord(ba.constData());
	//------------------------------------------------------------------------------
	CHECK(nfc_create_ndef_message(&myNdefMessage));
	//------------------------------------------------------------------------------
	CHECK(nfc_add_ndef_record(myNdefMessage, myNdefRecord));
	qDebug() << "XXXX Pushing NDEF message over SNEP";
	//------------------------------------------------------------------------------
	CHECK(nfc_push_ndef_message(target, myNdefMessage));
	//------------------------------------------------------------------------------
	CHECK(nfc_delete_ndef_message(myNdefMessage, true));
	CHECK(nfc_destroy_target(target));
}

So, having designed and implemented a message-oriented protocol and coded classes which used NFC SNEP to transport those messages between devices, the rest of the effort that rainy weekend was spent on standard game development issues like creating the UI. The UI was really easy to create for the BlackBerry 10 version using Cascades™, and took a fraction of the time and effort we spent on the BlackBerry 7 Java version of the game. In both cases, the NFC part was also quite easy and took relatively little effort as a portion of the whole application.

The next step was to find some guinea pigs to test the application out. (Not real guinea pigs, of course — their paws are too small and they have claws that make working with a touch screen problematic. So instead, we decided to use humans — our respective friends and family to be precise. )

Testing was informal. In my case, I explained I’d developed a two-player game that allowed you to take certain actions just by touching the two devices back to back. My guinea pigs generally looked a bit blank or even cynical at this point. “Just touch them together? Really?!” But with a little coaxing I got them started and watched them carefully.

At the very start of the game, the two players are instructed to touch devices to start the game. Looking a little unsure at first, the players touched devices and held them together for a second. The devices responded, vibrating to indicate an NFC message had been received, and the game moved on to the next screen to allow the selected Player 1 to choose noughts or crosses. At this point, the expressions on the players’ faces changed — from expressions that suggested they were being asked to participate in a black magic ritual to sheer delight with big smiles all around! And from that point, there was no stopping them. They were each playing on devices with touch screens – the BlackBerry® Bold™ 9900 and 9790 smartphones, to be precise – so selecting a place to put their mark on the game “board” was simply a case of touching the screen. And passing turns to the other player? They just touched the devices together, of course!

Here’s a video showing the game in use:

[ YouTube link for mobile viewing ]

The verdict was very positive. Players liked the idea in general and enjoyed the tactile element of the game play. It seemed that Proximity Gaming was a big hit!

The two versions of our NFC-enabled tic tac toe games are available with full source code from our github repositories here:

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

So over to you, BlackBerry developers! How could you use NFC in your BlackBerry smartphone game?

First and foremost, there are two kinds of invocations – unbound and bound. An unbound invocation is performed when an app does not specify a specific target app that should get invoked, and hence relies on the invocation framework to select the best target. For example, if there are three apps that can open .DOC files, the framework chooses the best one based on its own target selection logic. So, for unbound invocations, the framework provides automatic brokering to find the best-fit targets and also performs target selection to choose the best among the best. This is very powerful because the client application does not need to know any target applications at all, and yet it can discover and invoke them via the invocation framework.

On the other hand, a bound invocation is performed when the target app is specified by the client application while sending an invocation request. For example, a client app may request that Docs to Go® should be invoked for opening a .doc file. In this case, the invocation framework does not provide any brokering (or target selection) and blindly invokes the specified target app with the request parameters. Extra care must be taken when performing a bound invocation because an app may be sending a request to a target that the target does not understand at all. One thing is clear — bound invocation assumes that the client knows the target well.

There are really two ways you can know a target. First, you might have had a conversation with the author of the target app and have an agreement on the invocation request parameters. In return, they have made you aware of their target ID that you can use to perform a bound invocation. Second, you can query the invocation framework with an invocation request to get a list of best-fit targets and programmatically parse their attributes (capabilities) including their target IDs and invoke one programmatically. Note that querying is another way to discover apps without knowing them and is even more powerful and flexible than unbound invocations. As long as you have a valid target ID, you can perform a bound invocation with the appropriate parameters.

So far so good, but how does the invocation framework know about all the target apps? It does because each target app is required to register with the framework if they wish to be considered by the framework. While registering with the framework, targets must specify a target id which alone makes them candidates for bound invocation. However if a target wants to make itself available for unbound invocations or invocation queries, it must define one or more invoke filters. Each filter is a combination of the following attributes.

• Actions (e.g. bb.action.OPEN) that describes the action it can perform
• MIME types (e.g. application/pdf) describing the content type it can perform the action on
• URIs (e.g. http://, file://) specifying the protocols it can handle to retrieve the data
• EXTs describing the file extensions it can handle if the URI scheme is file://

Note that at least one action and one MIME type is mandatory for each filter definition, and if the URI is file://, at least one EXT must be specified. Filters are what really allow the invocation framework to broker between clients and potential targets as well as target selection that lead to successful invocations.

Well, that’s a 30,000 feet overview of the invocation framework but as a developer I know your hands are itching for some real code. The good news is I have that covered — I have already uploaded a few sample applications on Github that you may find very (very) useful.

• InvokeClient – An application that demos different ways to invoke and to query for targets
• InvokeTarget1 – A dummy target app that can be used with InvokeClient
• InvokeTarget2 – A second dummy target app that can also be used with InvokeClient

Samples are great, but so are documentations (if we read them) for a solid understanding. Please refer to our App Integration development guide for a comprehensive guide with code snippets for both invoke clients and targets.

I am more excited than ever before to introduce the invocation framework as part of the BlackBerry 10 Native SDK beta 2 and have no doubt that this will help most app developers out there to provide a deeply integrated user experience. Invocation is one of the core aspects of the BlackBerry 10 experience and come launch, it is going to be hard to find an app that does not invoke or get invoked. I will keep everyone posted on new features as we add them to this framework but more importantly, I am all ears to your feedbacks at shaque[at]rim[dot]com, @BlackBerryDev and @shadidhaque.

We have been busy making the BlackBerry® 10 browser one of the most advanced browsers on the market with class leading HTML5, CSS3, and WebGL support. However, even if you build one of the greatest browsers to ever hit the mobile web, you still need content providers to serve up a rich mobile experience. To help ensure our users receive high quality content, we have changed our user agent string. It’s not an ideal solution, but feature detection and responsive design have not yet become the norm among web designers, and we needed an interim solution.

Thus, without further ado, I introduce to you the new and improved BlackBerry user agent string!

Mozilla/5.0 (BB10; <Device Model>) AppleWebKit/<WebKit Version> (KHTML, like Gecko) Version/<BB Version #> Mobile Safari/<WebKit Version>

Explained

1. Mozilla/5.0 Mostly customary, historically used to indicate Mozilla compatible browser
2. BB10 The primary identifier of a BlackBerry 10 device
3. <Device Family> Device product family name
4. AppleWebKit/<WebKit Version> The WebKit Version number
5. KHTML, like Gecko The engine WebKit originated from
6. Version/<BB Version #> The software version number
7. Mobile Indicates the device is mobile; it may have a small physical screen and potentially limited bandwidth
8. Safari/<WebKit Version> Mostly customary, historically used to indicate Safari-compatible browser

What has changed?

1. Many websites are filtering on the word “BlackBerry” and providing our very capable browser with the most basic of mobile web pages, while rich content is being pushed to our competitors. To avoid this pitfall, we removed the word “BlackBerry” from our user agent and replaced it with “BB10”. This change will require web administrators to add this new identifier to their user agent detecting scripts
2. We cleaned up the user agent string by removing both the locale (e.g. “en-US”) and the strong encryption indicator (e.g. “U”) [don’t worry, we still support strong encryption]

Suggested Identification Pattern

• BlackBerry10 Smartphone: 'BB10' + 'Mobile'

Example: htaccess file

RewriteEngine On

RewriteCond %{HTTP_USER_AGENT} BB10.+Mobile 
RewriteRule ^$    http://www.example.com/mobile [L]

So there you have it, our updated BlackBerry 10 user agent string!

The idea was conceived and implemented at the BlackBerry Jam World Tour in Toronto, where Tim Neil (@brcewane) was scheduled to present. If you didn’t know, Tim is one of the main authors of bbUI.js. During one of the breaks, an attendee approached Tim with the idea of adding an independently scrolling panel to the bbUI.js. Funny thing is, Tim thought it was a great idea and produced the initial branch over lunch! Right there in front of us, the birth of a new feature.

I have been waiting for this feature for my application: ZenLottery. With ZenLottery, you can generate lottery numbers based on your location. One feature of ZenLottery is the ability to save the sets of generated numbers. If you can save the numbers, then you should be able to delete them as well. The design called for the numbers to be displayed and a delete button at the bottom. Without the Scroll-Panel feature, the delete button may be off the bottom of the screen, if the user chooses to generate more than 8 sets of lottery numbers.

That’s not a good user experience. How do they even know the Delete button is there? The solution is to have a scrollable panel for the sets of numbers. Then, the user can scroll through the numbers without losing the Delete button off the bottom of the screen. With the new scroll-panel feature in bbUI.js, I was ready to rock n’ roll!

The code for showing the sets of numbers is pretty simple. There are two divs: the outer and the inner div. The two divs work together to make sure the numbers are centered on the screen:

<div class="centerOuter">
<div id="numberDiv" class="centerInner"></div>
</div>

For completeness, here’s the centerOuter and centerInner CSS:

.centerOuter
{
width: 100%;
text-align: center;
}

.centerInner
{
display: inline-block;
}

As with the other elements in the bbUI.js, the scroll-panel is a div that gets a special tag. The tag used is data-bb-type and the value is “scroll-panel”. I figured I would add this to the outer div and all would be grand:

<div data-bb-type=”scroll-panel” style=”height: 800px” class="centerOuter">
<div id="numberDiv" class="centerInner"></div>
</div>

Notice I also added a style tag to specify the height of the panel. This style tag limits the height of the div and helps to create the scrolling affect I wanted. Now the numbers could scroll and the delete button could stay put. However, there was an unforeseen side effect: I lost the centering of the numbers.

It turns out that the only formatting you can add to the scroll panel is style=”height: ###px”. This tag is necessary so the panel knows its boundaries. Without this style, the panel would occupy the whole screen. At first I thought: no center, bummer. But not to worry! There is a simple solution: keep the centerOuter and centerInner divs the way they were and add the scrolling panel as a wrapper:

<div data-bb-type="scroll-panel" id="scrollPanel" style="height: 800px">
<div class="centerOuter">
<div id="numberDiv" class="centerInner"></div>
</div>
</div>

Voila! I now have the centered, scrollable sets of numbers while the delete button stays right where it is. Groovy!

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

You might have heard the terms “push” and “push notifications” thrown around before. So in a nutshell, what’s push good for? Push does pretty much what the name implies: it allows you to push information to BlackBerry® smartphones the moment it is available, and the user gets the push message almost immediately after it’s sent.

Push is an interesting technology because you need to write two applications for it to work:

1) You have to write a server-side push application (sometimes called a Push Initiator) so that you can send out push messages to BlackBerry smartphones.
2) You also have to write a client-side push application (sometimes called a push-enabled application) so that users can receive those push messages on a BlackBerry smartphone.

I highly recommend that you look at the Push Service SDK to write your Push Initiator. You can download and find information on that SDK here: https://developer.blackberry.com/services/push

The rest of this blog post concentrates on the push-enabled application, and explains how to write a good application using the BlackBerry® WebWorks™ SDK.

The Push Service APIs that are part of the BlackBerry WebWorks SDK are brand new for BlackBerry® 10. When we created the APIs, our goal was to start fresh – to make things clean and simple. We also wanted to make sure that the Push Service APIs would work well with other new APIs introduced for BlackBerry 10, like invoke events (that is, the blackberry.invoked feature).

There are only two classes that you have to worry about in the Push Service APIs:

1) PushService has the business logic that you need to start receiving push messages in your app

and

2) PushPayload is essentially a value object containing the content and headers of your push message.

Now that you want your app to start receiving pushes, where do you start? The first question to ask yourself is whether or not you’re developing this app for the general public. If you are, you should register to evaluate the Push Service at this link: https://www.blackberry.com/profile/?eventId=8121 After registering, you’ll receive an email with all the information that you need to write your push-enabled application, including your application ID, password, and the PPG URL you will be pushing messages to. If you’re developing your app for enterprise users, you don’t have to worry about registering.

Alright, what’s next?

At some point, you should check out the Push Capture sample app available here: https://github.com/blackberry/BB10-WebWorks-Samples/tree/master/pushCapture. The sample is a fully functional app that uses the Push Service APIs.

The UI for the sample app looks like this:

There are also a lot of good examples and information in the API Reference about the PushService and PushPayload classes. For information about the PushService class, see https://developer.blackberry.com/html5/apis/blackberry.push.PushService.html For information about the PushPayload class, see https://developer.blackberry.com/html5/apis/blackberry.push.PushPayload.html

In order to use the Push Service APIs, you need to update your application’s config.xml:

1) You need to reference the blackberry.push feature:

<feature id=”blackberry.push” />

2) You need to add a feature tag for blackberry.invoked:

<feature id=“blackberry.invoked” />

This feature tag relates to the handling of invoke events. A push notification comes into your application as an invoke event.

3) Finally, you need to have an entry relating to the invoke events that you receive for push messages:

Take note of the id attribute (also known as the “invoke target id”). This attribute has to match the options.invokeTargetID that is passed in to the call to the static create function of the PushService class (more about the create function in a moment). Another important detail is that the action tag is set to “bb.action.PUSH”. This setting makes it clear that the invoke relates specifically to push messages.

Now, here’s a quick rundown of the Push Service APIs. Don’t worry, there aren’t many.

1) Call the static create function on the PushService class to get a PushService object you can start using. If the create call fails, you won’t have access to a PushService object. That’s why the create function has success and fail callbacks. You’ll need a lot of the info from the email you received when you registered to evaluate the Push Service (for public apps), so have that info handy for this call.

2) If your application is not running, one of the major advantages of push is to allow your application to be launched when a new push comes in, and to have your app continue to run in the background. This allows valuable device resources to be saved because your app doesn’t have to be running all the time to be able to receive push messages.

The default behavior for your application is to not have it launch when a new push comes in. That’s where the launchApplicationOnPush function comes in (from the PushService class). If you call it with a value of true, then it will activate the launch functionality. You can turn this functionality off at any time by calling launchApplicationOnPush again with a value of false.

3) Call the createChannel function on your PushService object to allow pushes to start coming to your app.

When that’s done, how does the server-side Push Initiator know who to push to? There’s something we call a “token” that you get back when you do a createChannel. You need to pass the toke along to the Push Initiator so it knows who to address a push to. If you’re using the Push Service SDK I recommended above, then you just simply pass this token to the Push Initiator using an HTTP request (we call it a subscribe operation).

4) Ok, you’re now ready to receive pushes (you created the channel) and you’re ready to send pushes (the Push Initiator has the token). Fire off a push to the token using your Push Initiator.

5) In BlackBerry 10, the push comes to the app as an invoke event using the new blackberry.invoked feature in BlackBerry WebWorks. We register for the event with the following call:

Now that we have the invoke request in our invokedCallbackFunc callback, how do we get the push out of it? Simply call the PushService object’s extractPushPayload function passing in the invoke request and it will give you back a PushPayload object.

(Quick side note: You’ll probably want to make sure the invoke event you received was for a push. The invoke event can be for other various reasons too. It’s easy to check though. Just make sure

before you call extractPushPayload).

Here’s a link to the blackberry.invoked API Reference if you want to check it out: https://developer.blackberry.com/html5/apis/blackberry.invoked.html

6) And there you go. You have the PushPayload object, and you can do whatever you want with the data.

You might have noticed that the “data” property of the PushPayload object is of type Blob. Look at the extractPushPayload function in the API Reference for PushService (see the link I gave above). It shows examples of how to convert that Blob into something that you can actually display to users.

7) From this point onwards, you app will continue to receive push messages. If at any time you want your app to stop receiving push messages, simply call the destroyChannel function on your PushService object.

Sure, using push requires some extra effort. You do need to write two applications, but the benefits to your users are huge. Just imagine displaying notifications in your app the moment an event of interest happens in the real world. That’s a pretty powerful thing.

And that’s why the BlackBerry WebWorks SDK for the client-side application (and Push Service SDK for the server-side application) is there to help make your life easier and to use push to its full potential.

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>

Today’s tip will demonstrate a QML-language feature: the ability to add new properties to an already-existing component. The example is based on the Slider control in Cascades™ and gives a hint on how the feature can be used, at least for this particular situation.

If you read the Slider control documentation, you’ll find a property named value of type “float” — which, of course, holds a Slider’s current value. If you bind the value property to a Label’s text property, you’d expect the text to change as soon as you start to drag the Slider’s handle, but that is not how the Slider is implemented in Cascades. The slider will only notify value changes when the user removes the finger from the Slider. If you want to track changes to the Slider’s value while the user is moving the handle, you need to connect to the valueChanging signal.

The following is a typical Slider scenario where the Slider’s value is tracked. The code isn’t complete in the following two examples because I only want to highlight the relevant parts. You’ll find a complete example at the end of the article.

ImageView {
    id: imageView
}

Slider {
    id: imageScaleSlider

    fromValue: 0.5
    toValue: 2.5
    value: 1.0

    onValueChanging: {
        scaleValueLabel.text = "Scale: " + value.toFixed(2)
        imageView.scaleX = value
        imageView.scaleY = value
    }
}

Label {
    id: scaleValueLabel
    text: "Scale: " + imageScaleSlider.value.toFixed(2)
}

The example above does the job. The Slider will update the label’s text property and also the ImageView’s scale factor, but personally, I don’t think this is a good solution. First of all, the code doesn’t utilize property bindings well which is one of the major advantages with QML. Secondly, the dependencies are inverted. The Slider has a strong coupling to both imageView and the scaleValueLabel. It should be the other way around — imageView and scaleValueLabel should bind to a property on imageScaleSlider.

So let’s take a look on how we can re-factor the code above, and try creating a more QMLified solution which makes use of proper property binding by adding a new property to the Slider control.

ImageView {
    scaleX: imageScaleSlider.scaleValue
    scaleY: imageScaleSlider.scaleValue
}

Slider {
    id: imageScaleSlider

    // Introducing the trackable scale value property
    property real scaleValue: value

    fromValue: 0.5
    toValue: 2.5
    value: 1.0

    onValueChanging: scaleValue = value
}

Label {
    text: "Scale: " + imageScaleSlider.scaleValue.toFixed(2)
}

So what happened? Well, we actually managed to remove imageScaleSlider’s dependency to the ImageView and the Label and we only have one line left of imperative code in the onValueChanging callback. Now the responsibility of how the scale value is used is given back to ImageView and Label. For example, the formatting of two decimals is handled by the expression in the Label’s text property on not in the onValueChanging callback.

I’m always trying to use property bindings as much as possible because it really fits well with the declarative QML language. Also, it often results in a more maintainable code and it’s easier to tell where a component gets its value from.

Finally, here’s the complete example:

import bb.cascades 1.0

Page {
    id: mainPage

    content: Container {
        background: Color.create ("#262626")

        layout: StackLayout {
            leftPadding: 16
            rightPadding: 16
        }

        Container {
            layoutProperties: StackLayoutProperties {
                horizontalAlignment: HorizontalAlignment.Fill
                spaceQuota: 1
            }

            clipContentToBounds: true

            ImageView {
                imageSource: "asset:///image.jpg"

                layoutProperties: StackLayoutProperties {
                    verticalAlignment: VerticalAlignment.Center
                    horizontalAlignment: HorizontalAlignment.Center
                    spaceQuota: 1
                }

                scaleX: imageScaleSlider.scaleValue
                scaleY: imageScaleSlider.scaleValue
                scalingMethod: ScalingMethod.AspectFit
            }
        }

        Divider {}

        Container {

            Slider {
                id: imageScaleSlider

                property real scaleValue: value

                fromValue: 0.5
                toValue: 4
                value: 1.0

                onValueChanging: scaleValue = value
            }

            Label {
                id: label

                layoutProperties: StackLayoutProperties {
                    horizontalAlignment: HorizontalAlignment.Center
                }

                text: "Scale: " + imageScaleSlider.scaleValue.toFixed(2)
            }
        }
    }
}

And that’s it! Let me know if you have any questions in the comments.