Among of the biggest news of the Adobe AIR 3 release  is the Native Extensions feature. If you want to get started with this, or maybe just try it, you should check out the Native Extensions page on Adobe Developer Connection.

There are five examples so far:

1. Gyroscope (iOS/Android)
2. NetworkInfo (iOS) – retrieves information about the network interfaces on an iOS device
3. Vibration (iOS/Android) – make the device vibrate
4. iBattery (iOS) – gets the battery status (unknown, unplugged, charging, or full) of an iOS device
5. .NET Image Encoder (Windows) – encodes a bitmap into BMP, JPEG, or PNG format using Microsoft .NET Framework 4

The first three extensions were created by Adobe engineers, the last two by community. As I said before I’m looking forward to seeing many more extensions created and having a central place to go for all of them.

Radu Ticiu of Timisoara Mobile Development Group invited me to speak at their August event about Adobe’s solutions for mobile development. And I must say I’m glad I accepted. Not only because the event and the people were great but because the other speaker was quite interesting.

Stefan is his name and he runs one of the most creative companies in this part of the world. Just to give you some context: they’ve won three FWA awards so far. His presentation was about the making off of an iPad game using Adobe AIR and Flash Builder 4.5. So far nothing new or extraordinary. isn’t it?

Well what really caught my attention were these facts:

• While they had great expertise in building Flash applications for the desktop, this was the first project they’ve done for mobile.
• They completed the game from concept to final IPA file ready for publishing in a week.
• The team who built this consisted of one designer, one developer, and Stefan.

Here are some screen shots of their game – called Chemistry Brothers:

During the presentation (and after while we enjoyed some beer and food) I learned more about this project and the company. And I think this project and the way they approached it is a good example of how you can get into mobile development if you are a web or desktop developer.

These were Stefan’s challenges before deciding to start the project:

• no expertise in mobile development
• no expertise in Flash and AIR mobile development
• no expertise in selling an application on Apple’s app store

Though these challenges were quite big he had something to rely on:

• tons of creativity
• great expertise in desktop and web development including Flash and Adobe AIR
• a plan

The plan he had was as important as the skills of his team. First of all, he decided to spend a week for building the game, from nothing to the polished “thing” you can find in app store. It was an all-or-nothing kind of bet. And to increase the chances of success he took his team out of the town to a remote town with nothing to distract them. They did a sort of software bootcamp.

Second, from the beginning he didn’t want to have anything less than great performances. To ensure this they used a first generation iPad for testing the code and they targeted 30 frames per second for their game. Anything less was not accepted.

Third, they struck a fine balance between the “features” of this game. They spent a lot of time on the graphics and game story but they didn’t spend much time on building lots of levels. It would have been impossible to do all those things with such restrictions (three people and one week).

And finally, they did a kind of agile development not for the code but for the product (game). Remember that I said they didn’t have any prior experience in building and selling mobile applications. So their plan was to build the game in one week and then ship it. If it had success then they would continue to develop as they already had the game story and lots of ideas. Guess what? They are happy with how the game is selling so far. Stefan told me that they will continue this project.

If you are one of the people who couldn’t find time for trying mobile development so far you are not alone. And more importantly, it is not so difficult to make your first move. Just think of an application that you’d like to build and make sure you allocate time for this. It could be a series of weekends during a month or three days of your vacation. It really doesn’t matter. What matters is to be focused and work on this fully committed. Chances are that you’d be surprised by yourself and what you can do.

In the end I just want to share some pictures from their office. Some say that having a creative environment stimulates creativity. After talking to Stefan and seeing his company’s work I’m not sure about this anymore. It looks like creative people change ordinary things into something to remember.

A wall built out of books

Playing around with Darth Vader's helmet

Another inspirational wall closely guarded by a she-clone

Rest room guardian!

Taking a break or having a meeting in a cozy space

If you have similar stories or just want to talk back, don’t hesitate to use the comments :). All I can say is: Bravo Stefan & Company!

One of the important pieces of the Flex framework for mobile development is the ActionBar class. This class lets you create an application title bar with three distinct areas. Starting from left to right you can have a navigation area, a title area, and an actions area. Of course you are not forced to use all these areas.

Why would you want to use this component? There are many reasons for using it but probably the most important is that it is an established user interaction design pattern on Android and iOS. This is how you usually add things like an application or section title, navigation buttons, search input texts, or action buttons.

Here are two screen shots of the Facebook application running on Android and iOS that illustrates this idea:

Using the ActionBar component

Using the ActionBar component is quite easy. First, you’ll need to create a Flex mobile project that uses either ViewNavigatorApplication or TabbedViewNavigatorApplication. Then, you can define the components you want to add to the ActionBar either globally (for all the Views) or individually (for each View).

If you want to add them inside of a View here is how you do it:

<?xml version="1.0" encoding="utf-8"?>
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009"
      xmlns:s="library://ns.adobe.com/flex/spark">

 <s:navigationContent>
     <s:Button label="Back"/>
 </s:navigationContent>
 <s:titleContent>
     <s:TextInput prompt="type to search" width="100%"/>
 </s:titleContent>
 <s:actionContent>
     <s:Button label="+"/>
 </s:actionContent>

</s:View>

This code produces the following ActionBar:

If you want to set it globally then the method differe slightly depending on what Application root tag you chose when creating the project (ViewNavigatorApplication or TabbedViewNavigatorApplication). For ViewNavigatorApplication you’d do something like this:

<?xml version="1.0" encoding="utf-8"?>
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
       xmlns:s="library://ns.adobe.com/flex/spark"
       firstView="views.ActionBarHomeView">

 <s:navigationContent>
      <s:Button label="Back"/>
 </s:navigationContent>
 <s:titleContent>
      <s:TextInput prompt="type to search" width="100%"/>
 </s:titleContent>
 <s:actionContent>
      <s:Button label="+"/>
 </s:actionContent>

</s:ViewNavigatorApplication>

And for TabbedViewNavigatorApplication you’d add one for each tab you have in your application. For example:

<?xml version="1.0" encoding="utf-8"?>
<s:TabbedViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
       xmlns:s="library://ns.adobe.com/flex/spark">

 <s:ViewNavigator label="Tab 1" width="100%" height="100%" firstView="views.Tab1View">
      <s:navigationContent>
           <s:Button label="Back"/>
      </s:navigationContent>
      <s:titleContent>
           <s:TextInput prompt="type to search" width="100%"/>
      </s:titleContent>
      <s:actionContent>
           <s:Button label="+"/>
      </s:actionContent>
 </s:ViewNavigator>
 <s:ViewNavigator label="Tab 2" width="100%" height="100%" firstView="views.Tab2View">

 </s:ViewNavigator>

</s:TabbedViewNavigatorApplication>

And here is how this code looks like at runtime:

If you set the ActionBar globally and you want to override a section or all sections in a particular View all you have to do is to set that section/sections in the View.

You should also know that you can control the ActionBar visibility and rendering mode. For example in any View in which you want to hide the ActionBar you can set actionBarVisible = false. By default the ActionBar is rendered so it takes up some of the available space for the rest of your application. If you want to have the bar hovering on top of the rest of your application you can set the overlayControls to true in your View.

Understanding how the ActionBar component works

Let’s see how everything is put together. Each part of the ActionBar (navigation, title, and action content) is actually a Spark Group object. If you open the ActionBar class file you’ll find three properties named: actionGroup, navigationGroup, and titleGroup. These Groups are populated by calling the setter methods: actionContent(), titleContent(), and navigationContent(). These methods are called by the View class to push the components you set for each section and the argument is an Array (you can set a Button or a number of UI components for each section).

How about the layout used by these three groups? Well you can set a different layout than the default by calling the actionLayout, navigationLayout, and titleLayout setters.

The ActionBar component is a Spark component and this means that the task for laying out the various UI components that you can add to each section is actually implemented by a skin class. And of course the look and feel is implemented by the same skin class. The default skin is spark.skins.mobile.ActionBarSkin. This class extends the MobileSkin class, which in turns extends the UIComponent.

The interesting parts in the skin class are these three methods: createChildren(), measure(), and layoutContents().

If you take a look at the createChildren() method you will see that here is where the three groups (navigationGroup, actionGroup, and titleGroup) used for each section are actually created and the default layout is set. Also you can see that the default layout used by each group is HorizontalLayout. Here is a snippet of the code that creates the navigationGroup:

navigationGroup = new Group();
var hLayout:HorizontalLayout = new HorizontalLayout();
hLayout.horizontalAlign = HorizontalAlign.LEFT;
hLayout.verticalAlign = VerticalAlign.MIDDLE;
hLayout.gap = 0;
hLayout.paddingLeft = hLayout.paddingTop = hLayout.paddingRight
        = hLayout.paddingBottom = 0;
navigationGroup.layout = hLayout;
navigationGroup.id = "navigationGroup";

The measure() method is executed executed after the createChildren() method or when the invalidateSize() method is executed. As the name implies, this method measures the width and the height of the ActionBar taking into consideration the padding (left, right, top, and bottom) and each group width and height (navigationGroup, titleGroup, and actionGroup). It is important to note that the height of the ActionBar is determined by the highest element you have, if this height is bigger than the default height. In other words if you add a Button and set the height of the button to 200, then the ActionBar height will be 200 pixels.

And finally the layoutContent() method is responsible for positioning and setting the size of each Group. This method positions each group starting from left to right with the navigationGroup, titleGroup, and actionGroup. If the total width of the navigationGroup and actionGroup is equal to or more than the total available width then the titleGroup is not displayed (visible = false).

Here is a graphical representation of how these different parts are related:

Skinning the ActionBar component

Let’s talk about styling the ActionBar component. Out of the box you can quite easily change the appearance using the CSS properties. For example you can use CSS to transform the default look and feel  of the ActionBar presented in a screen shot at the beginning of this article to something like this with a little bit of CSS:

And the CSS code that does this is this (please note that you have to include the CSS code or file in the main application file and not in the Views):

<fx:Style>
@namespace s "library://ns.adobe.com/flex/spark";

s|ActionBar {
      chromeColor: #484877;
      defaultButtonAppearance: beveled;
}
</fx:Style>

The second CSS property in the code above (defaultButtonAppearance) is responsible for rendering the buttons in iOS style. If you inspect the ActionBar class you will find all the important CSS properties that you can play with.

If you want to go beyond background and font colors, sizes, and so forth you have to go down the road of creating a custom skin. And the easiest way to do this is to extend the ActionBarSkin class.

Here are the important parts of the ActionBarSkin class from a skinning perspective:

• border and borderClass properties. Border represents the first child of the ActionBarSkin (take a look at the createChildren() method).BorderClass is a reference to an FXG file that is set in the class constructor depending on the applicationDPI value. The borderClass is used for creating the borders of the ActionBar and the shadow at the bottom. Here is a screen shot of what this looks like (I placed a pinkish background behind the graphics to provide some contrast for the highlights you can notice on the left/right side):

• drawBackground() method. This method is responsible for drawing the background. In the previous screen shots this is where the black or dark blue color is coming from. If you take a look at this method you will notice that it uses CSS properties (default or set by the programmer) to draw a gradient.

I think that in the most of cases, when you want to skin an ActionBar component you’ll likely modify the drawBackground() method and create a different borderClass FXG file.

Let me show you an example of a custom skinning. There are three steps involved in this.

First, I created a new FXG file to be used for the background. To do this I opened up the FXG file used by default by the ActionBarSkin in Adobe Illustrator (you can find the path for this FXG in the ActionBarSkin constructor). And I added three green rectangles (some with a solid color, others with a transparent gradient). Here is the result in Illustrator:

Then, I exported the FXG file as an FXG. And I opened this file in a text editor to remove some of the tags and attributes introduced by Illustrator. Finally, I add the FXG file to the Flex mobile project.

Second, I created a new ActionScript class that extends the ActionBarkSkin. In the constructor I make sure that the borderClass uses the FXG file I created in the previous step. And I overrode the drawBackground() method because the FXG file does everything I need. Here is the complete listing:

Third, I changed the CSS from the main application file in order to set the new skin class as the ActionBar skin class, and the chromeColor used for the buttons. Here is the code:

Finally, here is how the skinned ActionBar at runtime:

In conclusion, if you couple these techniques with skinning of the other components you plan to use inside the ActionBar then you can really get something that is quite unique.

You can download the Flex project source code used for this example from here.

A colleague of mine who is building a Flex mobile application had some performance issues with a list. In short, when he used a pretty heavy custom item renderer (with checkboxes, buttons, and labels) the scrolling performance dropped a lot. When using just a label item renderer everything worked well.

So, we started to debug the code and, as I suspected, the culprit was the layout manager: the virtualization was off.

This was strange as he didn’t turn off the useVirtualLayout flag anywhere in the code – at least not explicitly. So why was the virtualization off? Because he used list.itemRenderFunction to change the item renderer at runtime. If you take a look at the documentation you will find this:

Function that returns an item renderer IFactory for a specific item. You should define an item renderer function similar to this sample function:

function myItemRendererFunction(item:Object):IFactory

Currently, when using itemRendererFunction with a virtual layout (useVirtualLayout=true), item renderer recycling is turned off. Because of this, using itemRendererFunction can cause a performance degradation and is not recommended for mobile. This may be fixed in future versions of Flex.

So, if you use a heavy item renderer and/or you have many items, don’t set the item renderer using the itemRendererFunction method.

Instead, you can wrap your custom item renderer in a ClassFactory object and then assign this object to the list.itemRenderer property. Like this:

var factory:ClassFactory = new ClassFactory(MyCustomItemRenderer);
// set the properties for custom item renderer
factory.properties = {iconField:"thumbnailSmall",
                  messageField:"description", iconHeight:180, iconWidth:180};
// set the ClassFactory object as the list item renderer
myList.itemRenderer = factory;

There is one more thing. In the example above I used the properties property of the ClassFactory object to set the properties I needed (for example what data property should be used for the message label). You can’t use this approach for setting CSS properties like fontSize. The only solution I found so far is to create setters that behind the scenes are doing something like this:

public class MyCustomItemRenderer {
   //...

   public function set fontSize(value:int):void {
      setStyle("fontSize", value);
   }

   //...
}

This was my tip of the week. And don’t forget, stay away from useVirtualLayout = false;

One way to improve the user experience for mobile applications is to save data locally. This technique is important for desktop applications and it is even more important for mobile applications (mostly because the network connection is expensive, slower, or intermittent).

When using applications such as mail or Twitter clients local storage enables users to see the messages or tweets loaded in the previous session. And while you are seeing these “old” items the application can pull in newer items behind the scenes. The main idea is to not to make the user stare at an empty screen each time he opens your application.

A second benefit of this technique is that your application will feel much more responsive. As I said it is possible that the user has a slow Internet connection and downloading 12 small pictures and some descriptions could be visibly slow. Local storage can offer a “performance” boost especially for applications that access data that changes rarely.

Depending on your specific use case you may want to save locally:

• media assets (images, MP3 files, video files)
• text or HTML resources
• XML files
• ActionScript data structures (an array of ActionScript value objects for example)

So how can you store data locally in an AIR mobile application (Android, PlayBook, and iOS)? You have almost the same methods as in AIR desktop applications (on the desktop you can use the encrypted local store to save ActionScript objects):

• Use the embedded SQLite database – obviously perfect for data that are a good match for a relational database
• Save ActionScript objects or collections of objects in files – serialize the objects into a file and read back when needed. Or you can use SharedObject to do the same
• Save binary assets directly into files – perfect for saving images or videos locally

I won’t go into details about these three techniques. Almost three years ago I wrote a blogpost that explains each technique (back then it was only AIR for desktops, but remember that apart from the encrypted local store you can use the same approach on mobile or desktop). So click here if you want to learn how to use these techniques.

There is one aspect I do want to highlight, however. When you want to save data locally using files you should always use the application storage folder. This folder is outside of the application installation folder. So you can update the application without worrying about the saved data. Here is a simple example for creating a new file inside the application storage folder:

var file:File = File.applicationStorageDirectory.resolvePath("new-file.png");
var fileStream:FileStream = new FileStream();
fileStrean.open(file, FileMode.WRITE);
fileStream.writeBytes(data, 0, data.length);
fileStream.close()

Flex mobile support for persistence

You probably already know about the persistence support of the Flex mobile framework. If you save your information to the data property of your View pages and set the persistNavigatorState attribute in the main application file to true, then all the information will be automatically saved when the application is closed and restored when the application is re-opened.

So here is a simple example. Suppose that you use this data model in your application:

package {

[Bindable]     
class User {
    public var firstName:String;
    public var lastName:String;   
}
}

Next, you turn on the persistence support in the main application file:

<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark"
    firstView="views.HomeView"
    persistNavigatorState="true"/>

And finally you use the data property to save the current instance of User. Bellow is the first View of the application. It uses bidirectional binding for displaying the User first name and last name properties.

<?xml version="1.0" encoding="utf-8"?>
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009"
   xmlns:s="library://ns.adobe.com/flex/spark"
   title="HomeView"
   viewActivate="onViewActivated()">
<fx:Script>
 <![CDATA[

   private function onViewActivated():void {
      // if it is the first time the application runs t
      // here is no data
      if (!data) {
         // create a new User instance and
         // save it to data property
         data = new User();
      }
   }

 ]]>
</fx:Script>
 <s:layout>
     <s:VerticalLayout/>
 </s:layout>
 <s:Spacer height="10"/>

 <s:Label text="First Name:"/>
 <s:TextInput width="100%" text="@{data.firstName}"/>
 <s:Label text="Last Name:"/>
 <s:TextInput width="100%" text="@{data.lastName}"/>
</s:View>

When you run the application for the first time you won’t see any information in the two text input boxes. However if you type in something and then close the app and re-open it, you will see the information you typed during the previous session.

When is the data property of a View saved to disk? Every time the application is closed or a View is destroyed/replaced by a new View. In terms of events right after the View deactivate event is triggered.

When is the data property of a View recreated if persistence is turned on? Right before the View activated event is thrown.

The data property of each View is saved to disk using flash.net.SharedObject and the object that does this is the ViewNavigator instance accessible in any View class by using the navigator property.

If you want to be sure that the data property is persisted you can call navigator.saveViewData() in your View. Why would you want to trigger the saving process manually? Because in the unlikely event the app is closed by the operating system due to low battery or memory events you cannot be sure that the normal event flow for closing the app will be followed. By calling navigator.saveViewData() manually each time the user updates something you can make sure that nothing will be lost.

RegisterClassAlias

When you serialize ActionScript objects to files or use SharedObject the original data type is lost when you deserialize them. The same applies when using the data property of the View because, under the hood, SharedObject is used for storing the data. If you want to keep the custom data type, all you have to do is to use registerClassAlias() method.

Why? Because the serialization is done using the AMF3 format (Action Message Format) and if you want to preserve the class information for the objects you serialize/deserialize then you have register the class alias of the class object. If you don’t do this, when you decode the objects you’ll get anonymous objects.

In a previous section I used a custom data type User. If I want to make sure that the data type is preserved I can register this class in the main application file (this way I make sure that the class is registered before any decoding is performed):

<?xml version="1.0" encoding="utf-8"?>
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
 xmlns:s="library://ns.adobe.com/flex/spark"
 firstView="views.HomeView" persistNavigatorState="true">

<fx:Script>
<![CDATA[
   import flash.net.registerClassAlias;

   registerClassAlias("User", User);
]]>
</fx:Script>

</s:ViewNavigatorApplication>

Conclusions

On Android you have to remember to set the appropriate permission in the application configuration file if you want to write files to disk (android.permission.WRITE_EXTERNAL_STORAGE). Also take into consideration how much space the data you want to saved will occupy. You should let the user know if you plan to consume GB of space.

There are many places where you can optimize your code especially when working on mobile applications. In this post I will focus on caching images using the spak.core.ContentCache class (part of the Flex framework).

Right from the Flex documentation, you can see ContentCache could be useful:

Provides a caching and queuing image content loader suitable for using a shared image cache for the BitmapImage and spark Image components.

Why cache images?

So why would you cache images? Every time you set a new source for a Spark Image or a BitmapImage object a new flash.display.Loader object is created to load the image bytes.

Now, let’s suppose you display a list of items and each item has an image (could be an icon or could be a picture). Each image is hosted on a remote server so it has to be downloaded. Finally, some of these images are the same for different items in the list (for example for a Twitter client it is quite common to see many entries with the same avatar; each entry represents a tweet from the same user and the avatar is the same in this case).

If you don’t use a caching mechanism, you will notice that as you scroll through the list it will take some time to load images. And the same could happen for images stored locally especially if they are not very small. While waiting for images to load and be displayed the first time is OK (and there isn’t much to do other than preload them) waiting for the same image every time it is displayed is quite annoying.

Here comes the ContentCache class. This class stores the bytes loaded (actually it stores the LoaderInfo object used for loading each image) and every time an image must be loaded it first checks the cache; if is not there then it goes through the loading process. If it is cached already, then it provides the LoaderInfo object.

How do you use the ContentCache class?

You can enable caching for your Spark Image or BitmapImage objects quite easy. All you have to do is to create an instance of ContentCache and set this instance to the contentLoader property of the BitmapImage or Image object. Other than this, it’s business as usual. When you want to load an image you just set the source property of the Image or BitmapImage object and the ContentCache object will take care of the rest.

There is one thing you must be aware of: if an image was changed after it was cached and the source is the same then you have to invalidate the cache yourself in order to see the new image. Otherwise you will see the old version. When you want to remove an image from the cache you use the removeCacheEntry() method and pass the source for the image you want to invalidate in the cache.

You control the number of cached images using maxCacheEntries property (the default value is 100).

Let’s see a simple example:

private var cache:ContentCache = new ContentCache();

private function setImage(source:String):void {
   //if we didn't set the cache
   if ( !img.contentLoader ) {
       img.contentLoader = cache;
   }
   //set the image source
   img.source = source;
}
...
<s:Image id="img"/>

Using ContentCache with Lists

The Flex framework has a built-in list item renderer that supports images: IconItemRenderer. This is perfect for displaying lists that have images and text. By default the IconItemRenderer uses a ContentCache object to cache the images. However the ContentCache instance is not shared across all the item renderers.

What do I mean? A Flex mobile list uses virtualization. This means that if the list displays 10 items at once it will create about 11 item renderer instances and reuse them. So even if the list has 1,000 items to display only 11 item renderers will be created. Next, each item renderer instance will use a ContentCache instance to cache the images. So in total there will be 11 ContentCache instances. This means that it could happen to have an image already displayed by the list but because it was cached by a different ContentCache instance than the one used by the current item it will be loaded again.

The IconItemRenderer class uses a static property to hold an instance of the ContentCache. This means that the same image cache will be used by your list. However, if you have a second list or you use multiple item renderers for the same list, by default, it will be used another instance of ContentCache. The easiest way to fix this is to first create a single ContentCache instance (you can use the Singleton pattern here):

Then you extend the IconItemRenderer and set this Singleton as the contentLoader object:

When you build from scratch a list item renderer that uses images, you can use the same approach.

Obviously this technique can be used for other places as well not only for lists.

Drawbacks

As with any caching or pooling technique there are trade-offs. You have to find a fine balance between not caching any images and caching all the images. By default the ContentLoader is set to cache 100 entries. But this doesn’t mean that it is the best value.  It all depends on how big the images are and how much memory you want to use for caching. So be sure you take this into consideration when caching images.

Ever wondered how to create a modal dialog window in Flex mobile applications? For example, you may want to ask the user for a confirmation when he performs a delete operation or maybe to select an item from a list. Well, if you don’t know how to do it, then read on.

Flex has a class that just does this: SkinnablePopUpContainer. SkinnablePopUpContainer extends SkinnableContainer class and has a very simple API you can use in order to “open” and “close” the dialog.

Understanding SkinnablePopUpContainer

Because SkinnablePopUpContainer extends the SkinnableContainer it is extremely easy to create any kind of dialog window you want. You can create a new MXML component that extends the SkinnablePopUpContainer. Then you set a layout manager that works for you (VerticalLayout, HorizontalLayout). And finally, you add the UI components you need – labels, buttons, lists, and so on.

Suppose you want to create a simple alert window that looks like this:

Here is the code to implement this (as a new MXML component that extends SkinnablePopUpContainer):

<?xml version="1.0" encoding="utf-8"?>
<s:SkinnablePopUpContainer xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark"
    backgroundColor="0x898989">

    <s:layout>
        <s:VerticalLayout horizontalAlign="center"/>
    </s:layout>

   <s:Label text="The contact was saved" width="100%" textAlign="center"/>
   <s:Button label="OK" width="100%" click="this.close()"/>
</s:SkinnablePopUpContainer>

The API for controlling the SkinnablePopUpContainer is pretty simple:

• To open or display the window you create a new instance and then call the open() method of SkinnablePopUpContainer. This method has two arguments. The first argument is the display object container where it will be created. The second argument is a flag that tells Flex if the window will be modal or not.
• To close the window and send data from the window to the application you use the close() method of SkinnablePopUpContainer. This methods also has two arguments. The first argument is a flag. You can set this to true if, for example, the user clicked the OK button, and false otherwise. If you want to send some data back to the application you use the second argument. For example, if you have a TextInput in your dialog and you want to send the text you will use this second argument.
• To listen for the close event and read the data sent from the SkinnablePopUpContainer you have to register an event listener on the SkinnablePopUpContainer. The event type is PopUpEvent. PopUpEvent has two properties that you can use to read the flag and data set when calling the close() method: commit and data.

Here is an example of how to open a SkinnablePopUpContainer component and read the flag/data when it is closed:

//create the component and open it
var alertWindow:SkinnablePopUpContainer = new SkinnablePopUpContainer();
alertWindow.addEventListener(PopUpEvent.CLOSE, onAlertClose, false, 0, true);
alertWindow.width = stage.width;
alertWindow.height = stage.height / 2;
alertWindow.x = 0;
alertWindow.y = 100;
alertWindow.open(this, true);

private function onAlertClose(event:PopUpEvent):void {
    trace(event.commit);
    trace(event.data);
    alertWindow = null;
}

Creating custom dialog windows

Once you understand how to use the SkinnablePopUpContainer it is pretty simple to create any kind of dialog window you might need: confirmation messages, simple alerts, pop up lists, and so on. Here is the code for a confirmation window that has two buttons (Yes and No) and lets you set the message text:

And here is how this component look on my Android phone:

And here is the code for a pop up list that lets you to set the title, the list’s data provider, the list’s label field, the list’s initial selected items, and multiple selections (you can retrieve the selected items by listening for PopupEvent.CLOSE and reading the data attribute).

And here is the component running on my phone:

Skinning

The two custom dialog windows I showed you in the previous section use the default look and feel. What about skinning a SkinnablePopUpContainer? There is a Flex class that provides the default skin for a SkinnablePopUpContainer: SkinnablePopUpContainerSkin. By creating a skin that extends this default skin you can change the background of the component quite easily. If you look at the SkinnablePopUpContainerSkin skin you’ll notice that it has a rect with the id equal to background. This is the starting point to change the default background. You can draw additional stuff on top of this background or replace it alltogether with an FXG or PNG file.

For the rest of the UI components used in a SkinnablePopUpContainer (buttons, text inputs, labels, and so on) you will create additional skins and/or use CSS. Here is a screenshot with the same confirmation window but this time using a custom skin:

Here is the skin class used to customize the confirmation window presented in the previous section:

And this is the FXG used by the skin class to draw the background:

Download

You can download a working Flex project that includes all the code used in this article from here.

We just released AIR 3 Beta 2 for desktop and Flash Player 11 Beta for desktop. You can download them from here and here.

Here is a list of the most important news in these releases.

AIR 3 Beta:

• You can download the AIR 3 SDK and start building mobile and desktop apps. You can also download the AIR 3 runtimes for Windows and Mac OS
• Stage Video Hardware Acceleration for mobile ( previously, this was available only for desktops). This will enable developers to leverage hardware acceleration for decoding and composing the video on the screen. This means reduced memory and CPU usage and smoother video playback.
• Captive Runtime Support (AIR for desktop and Android). You will be able to package your application with a captive runtime. This enables you either to use a specific version of the runtime instead of what the user might have or to push the app together with the runtime so the user doesn’t have to go through the installation process of the runtime. Needless to say that this was one popular request :)
• iOS Background Audio Playback Support. You can write multi-tasking apps that can play audio in background.
• Android Licensing Service Support. You have access to the Android Market Licensing Service so you can enforce licensing policies for paid apps that are published through Android Market.
• Android Front-facing Camera Support. This is another popular request. This was already available on iOS and PlayBook; now you can use it on Android too.
• Encrypted Local Storage for Mobile. Another feature that developers wanted badly. Now you can store encrypted data the same way you would do on AIR desktop apps. Great for storing passwords and other sensitive data.
• H.264/AVC Software Encoding for Cameras for Desktop. You can stream high-quality video from your computer’s camera with better compression and industry-standard support.

You can read more here.

Flash Player 11 desktop Beta:

• Stage3D APIs (AKA Molehill). 3D GPU accelerated graphics.
• Native 64-bit support. For 64-bit operating systems (Linux, Mac OS, and Windows).
• G.711 audio compression for telephony. Real-time voice and telephony capabilities and support for integration with existing phone systems using a G.711 codec.
• Socket Progress Events. This was another feature requested by many developers.
• JPEG-XR support. Support for JPEG-XR compression format so you can use higher quality images with less bandwidth. Plus you can use alpha channel transparency.

You can read more here.

My fellow evangelist, Michael Chaize, has way too much time. During the weekend he put together this nice site to announce a contest to the world. Oops, not to the world, but to those living in the European Union.

So, if you live in European Union and you publish an AIR application to Android Market, Apple App Store, and BlackBerry App World by September 1st 2011 then you can enter in this competition. What can you win? Well, it depends. If the grand jury (all European Adobe Evangelists) picks you as  one of the winners then you can get a trip to Adobe MAX 2011 Los Angeles or Adobe Creative Suite software. If your application is not a winner than you can still win experience and maybe some good feedback from the jury :)

Here is the man himself introducing the contest (don’t ask me why he is talking like this. All I know is that he lives in Paris :D):

Now, don’t be lazy and start working on your amazing app! You can read more about the contest here.

For a mobile application I’m working on I need a section list. If you are familiar with the Flex framework you know that you don’t have built-in section list components (you can have vertical, horizontal, and tile lists). I played a little bit with the Flex List, IconItemRenderer, and BasicLayout classes and managed to put together two section lists: a vertical section list and a tile section list. In this post I will talk about how I did it and about some theory behind the list components.

What is a Section List?

Before talking about code, let’s establish what a section list is:

• It is a list that provides a way to render items grouped in sections. For example, if you have a data structure like “Fruits, Banana, Cherry, Kiwi, Cheese, Cheddar, Gorgonzola” a section list will render this data in a way that makes it clear that Fruits/Banana/Cherry/Kiwi is one section and Cheese/Cheddar/Gorgonzola is another one;
• The section title items can’t be selectable. In our example, clicking on Fruits or Cheese items will not throw a select event nor will it select the item;
• Section title items should be rendered so that it is clear they are different from regular items.

Here is an example of a vertical section list (blue items are section title items, the gray Blueberries item represents the current selection):

If you wonder why you’d need such a list, here are a couple of examples where you can find it pretty useful:

• You have a list of people and you want to display the items sorting alphabetically. By creating sections A, B, C, and so on users can easily navigate through the sections to find what they are looking for;
• You have a properties or preference page in your application with a bunch of options (for example, Editing, Account, and so forth). You can nicely organize the information so users can find their way quickly.

Some Theory Behind Flex lists

This is the boring section of this post :) If you don’t like it, feel free to skip it :D

Flex mobile lists inherit the architecture of the Spark components introduced in Flex 4 back in 2010. An oversimplified dissection of a Flex mobile list would reveal these “organs”: list component, DataGroup, Scroller, layout manager, and item renderer. By default a Flex mobile list is a vertical list (items are rendered vertically and if there are more than can be fitted on the view port than you can scroll the list up and down).

Here is a description of how these things work together:

• The list component uses a container for holding the items that will be displayed. This container is an instance of the DataGroup class.
• The DataGroup container implements the IViewport interface. If the items to be displayed don’t fit in the viewport, they are clipped.
• To scroll the viewport of the DataGroup and see the rest of the items, a Scroller is used. In the case of the mobile Flex list the Scroller displays a scrollbar only when you interact with the list (by default it is hidden). Its size gives a visual clue about the number of the elements from the list (the more elements in the list, the smaller the thumb).
• The list component uses a layout manager. This class is in control of how and where the items displayed in the DataGroup are rendered.
• Each item of the list is displayed using an item renderer. The Flex framework gives you two built-in item renderers for lists: IconItemRenderer and LabelRenderer. The item renderer class is in charge of how an item will be rendered on the screen. Lists are designed to work with a single item renderer.
• The list component has a property called dataProvider that you can use to set the data you want to display. Typically you’d assign to this property and Array or an ArrayCollection of Strings or Objects.
• Finally, mobile lists use virtualization (the virtualization part is implemented actually by the layout manager). This means that only the items that are visible in the viewport are rendered. And when the viewport is moved (for example, you scroll the list down) the item renderers of the items that were moved out of the view port are reused for the items that just got in the view port. This way, even on a mobile device, you can have lists with 10,000 items and you want run out of memory. However there is still a cost with this approach: the DataGroup has to execute a bunch of removeChildAt() and addChildAt() calls in order to reuse the item renderer instances.

I won’t get into details about how everything is linked together at runtime and what methods are called and when. I’ll save this for another post.

The first section list I wanted to create was a vertical section list. Let’s see how I implement it.

Creating a Vertical Section List

I looked at the built-in Flex mobile list and I realized that making a Vertical Section List would be quite easy. The VerticalLayout manager does all the work I needed, and the only things I had to change were:

1. Disabling item selection for list items that are section titles;
2. Finding a simple way to define the data provider structure (which data items are section title items and which are just regular items).
3. Extend one of the two built-in item renderers so I can have two distinct looks: one for section title items and one for regular items;

First, I decided on how to model the data provider used for the SectionList. I decided that I want to be able to use an Array or ArrayCollection of objects and I will use different properties to store the label for section title items and regular items.

Next, I created a new class that extends the Flex List class. In this class I override the item_mouseDownHandler() method. This method is executed each time you touch the list. So all I had to do is to check whether the item touched is a section title item or not. If it is, then I just call event.preventDefault() to cancel the selection.

Next, I added a property named sectionField to store the property name used for defining a data as an section list. Here is the code of the SectionList class:

Then I created a new item renderer by extending the built-in mobile item renderer IconItemRenderer. IconItemRenderer enables you to display more than just a label (you can have a decorator, an image, and a subtitle). To tell you the truth, I have used only the label. So, I guess I could have chosen the LabelRenderer as well.

The first thing I did was to override the set data() method. This method is called automatically everytime the item renderer class is used to render a data item. So this is the perfect place to check if the data that is about to be displayed is a section title item or not. Depending on the result I change the font alignment and weight and I change the labelField value to the property name to be used as the source of the text.

Next, I override the drawBackground() method. This method draws the background of the item. Depending on what data I have to render I change the color of the background.

Finally, I added three new properties that allow me to set the name of the property that holds a section title item, a regular item, and background color to be used for section title items: sectionField and normalLabelField.

Here is the code of the custom item renderer:

With all this sorted out, here is how you use the SectionList component in your code:

This example uses the data provider defined below. This is why I set the sectionField property of the SectionList and SectionListItemRenderer to “section“. You can see how the background color for section title items is set.

Defining the data provider:

Here’s a video with the list running in the Flash Builder desktop simulator and on my Android phone:

Creating a Tile Section List

A tile section list could be handy, especially on tablets. Because you have plenty of space on the horizontal axis you can fit multiple items on the same row and thus make better use of the available screen on the device. Here is an example of tile section list (the item renderer used here doesn’t do a good job of separating visually adjacent items):

If all you need is a tile list then you can use the Flex list with the built-in TileLayout manager.

With the vertical section list up and running all I had to do was to create a new layout manager. This layout manager lays out the items (starting from left to right and top to bottom) using these rules:

• If the item is a regular item and it is enough room to accommodate it on the current row it will draw the item next to the previous one;
• If the item is a regular item and there is not enough room to fit the item on the current row, it goes on the next row;
• If the item is a section title item it goes on the next row and fills is the entire view port width.

Fortunately, back in 2010, Evtim Georgiev (an engineer on the Flex SDK team) created a custom layout that was pretty close to what I needed. So I took this layout manager and modified it a little bit. The magic happens in the updateDisplayList() method. This method is called every time the display list of the List is invalidated (for example if you change the width/height of the list or when the list component is initialized). The two arguments of this method represent the view port’s height and width.

updateDisplayList() method is where you position and size the items. For my first run I chose to create a layout manager that doesn’t use virtualization. This means that updateDisplayList() will iterate over all the items you have in the list and create an item renderer for each one and then position and size the item. The layout manager positions the items in the DataGroup instance used by the list for displaying the items. The item renderer class implements the ILayoutElement interface. Using this API, the layout manager can set the width/height and x/y of each item renderer.

As I explained, the layout manager uses the whole width of the view port for section title items. For regular items, I added a property to the layout manager called columnWidth – so you can control how many items you can have on the same row.

Here is the code of this custom layout manager (I called it SectionListLayout):

The item renderer and list data provider are the same as the ones used for the vertical section list. I’m using the same SectionList I created earlier. Here is how I instantiate the SectionList and set the various properties:

And here is a video with the tile section list in action:

Caveat

Obviously, a layout manager that doesn’t support virtualization could trigger performance issues when you have hundreds or thousands of items (at least on mobile devices; on the desktop you probably won’t run into this most of the time). However, if you don’t have many items, than it could be actually faster than a layout that uses virtualization.

LATER UPDATE: You can read here how you can create layout managers that support virtualization.

Why? Because when a list uses virtualization, it recycles the item renderers (as soon as you move out of the screen an item, its item renderer is reused for an item that just got into the view port). This means that as each item renderer is recycled, it must be removed from the DataGroup display list, new data are set, the item is redrawn if necessary, and it is added to the DataGroup display list.

Right now I’m working on a Tile Section Layout manager with support for virtualization. Once I finish it, I will write another blog post that will explain in greater depth “the art” of creating layout managers.

Download the code

You can download the source code of the Flex mobile project from my GitHub account.

When we launched Flash Builder and Flex 4.5 in May we said that we will have an update a month later that brings Flex mobile development to all three platforms: Android, iOS, and PlayBook (BlackBerry Tablet OS). And this is the update we were talking about.

So starting today, you can build all sorts of amazing mobile apps that run across these different devices.

If you want to find more about this, make sure you register for Adobe Developer Week. This is a series of webinars that will start today.

In the meantime you can check Serge‘s videos.

We’ve just released Adobe AIR 2.7 for desktop, Android, iOS, and PlayBook. In terms of features, here is a list of the most important.

Mobile:

• Improved performance for AIR apps (including those built with Flex) running on iOS. You will see up to a 4X improvement for the same app when running on AIR 2.7.
• Faster development time for iOS applications – there is a new mode for testing and debugging your AIR app on iOS devices that will enable faster cycles.
• And this is one I’m sure you’ll love: you can install the AIR runtime on the SD card of your Android device.

Desktop:

• Integrated support for Media Measurement – allows companies to see how content is distributed and viewed by users
• Acoustic echo cancellation – this is the same feature already available in Flash Player 10.3. It means you can enable users to do VoIP using speakers and microphone (no need for headsets).
• Navigation Improvements for HTML Content – developers can now respond to a new event to be notified when content within the HTMLLoader control attempts to change the location of a page. This enhancement provides developers with a better way to implement intra-application navigation.

Watch my fellow evangelist, Renaun Erickson, showing AIR app performance on an iPad:

You can download AIR 2.7 from here. This month, Flash Builder 4.5 will get an update to enable support for AIR 2.7 and PlayBook will receive an update OTA of AIR 2.7 by the end of June.

As you might have heard, we released earlier this week Flash Builder and Flex 4.5. Part of this release is a new product called Flash Builder for PHP 4.5. This is something you should make sure you try if you are a PHP and Flash/Flex developer.

So what is Flash Builder for PHP? This product will install Flash Builder 4.5 with Zend Studio 8.1 as a plugin plus some additional plugins that integrate these two products. Using this IDE you can create mixed projects (Flex and PHP both for desktop and mobile devices) and you can streamline testing, deploying, debugging, and consuming PHP services via Flex remoting (with the help of Zend Framework).

Instead of writing a pretty long article, I decide to shoot a video tutorial on how you can create a Flex mobile app that uses a PHP service. This tutorial will walk you through:

• Using the new project type Flex Mobile and PHP
• Creating a mobile application that has two views/screens. I will explain how to use the ViewNavigator and View classes to control your application state
• Consuming a PHP service from a Flex mobile app using remoting
• Testing and debugging the code (Flex and PHP) on the desktop simulator and physical device

I hope you will enjoy this. If you want to download the files used for this tutorial, click here (unzip the file and you will get the Flex project you can import it and the PHP files plus the database dump).

The Flex framework offers a number of methods to adjust the size of the application UI depending on the device screen resolution and density. For example, you can set the applicationDPI attribute or you can use different CSS files.

In this post I will show you how you can scale or adapt the application UI at runtime using the Capabilities API. But first, why would you want to change the size of the application UI? Consider these two pictures.

Nexus One:

Samsung Galaxy Tab:

The first one is a screen capture taken on a Nexus One phone and the second is taken on a Samsung Galaxy Tab. Obviously, the Samsung Galaxy Tab has a higher screen resolution (600 X 1024) compared to the Nexus One (480 x 800). So, if you don’t make any adjustments to your UI, everything will be smaller on the bigger screen (as you can see from these pictures).

Sometimes, this is not a problem. In other situations, you might want to increase the size for some parts of your design due to aesthetic or usability reasons, or maybe both.

Using scaling to adjust the content size

When I worked on the aTabSplitter application, the first thing I did regarding the UI was to make sure that it wouldl fit nicely on a screen with a resolution of 400 x 800. By using Flex containers (VGroup, TileGroup, and HGroup) and playing with a mix of absolute and relative sizes I was able to easily create a “liquid” design. For example the keyboard is designed to take up about 320 pixels x 320 pixels. The TextArea at the top is set to fill in all the available space. Why did I choose this resolution? By looking at various Android devices I felt that this is the smallest resolution. Here is the code:

For the aTabSplitter application I wanted to increase the size of the virtual keyboard when the application runs on devices with a screen resolution higher than 480 x 800. And the simplest solution is to use the Capabilities API. When you run your application on a device, Capabilities.screenResolutionX gives you the horizontal resolution. If you want to check for the screen density, you can use Capabilities.screenDPI.

Back to the code, I set an ID to the HGroup that holds the buttons and then I registered a listener for the creationComplete event on the view. Using this listener I can check for the screen resolution and if needed I can change the size of the HGroup using its scaleX and scaleY properties. When the container scale is changed, all the contained components are scaled too. Thus everything is kept in place, nicely aligned.

<?xml version="1.0" encoding="utf-8"?>
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009"
 xmlns:s="library://ns.adobe.com/flex/spark"
 title="HomeView" creationComplete="layoutButtons()">
<fx:Script>
<![CDATA[

private function layoutButtons():void {
  if (Capabilities.screenResolutionX == 600) {
     buttonsHolder.scaleX = buttonsHolder.scaleY = Capabilities.screenResolutionX / 450;
   }
}
]]>
</fx:Script>

[...]

<s:HGroup id="buttonsHolder" gap="5">
[...]
</s:HGroup>

And here is how the keyboard looks when I run the code on a Samsung Galaxy Tab (compare to the previous screenshot taken on the same device):

Of course, you can apply scale in the other direction – decreasing the size of a component.

Conclusions

This is a pretty simple trick yo can use to adjust your content to different screen sizes. In the next post I will show you how you can adapt the content to screen orientation changes – device held in portrait or landscape mode.

You can download the project code from here (you’ll need Flash Builder 4.5 and Flex 4.5 to run and compile the project).

We just released the first beta of Adobe AIR 2.7 on Adobe Labs. You can get the bits from here. What’s new with this release?

First, this beta is available just for desktops for now. Second, the main features are:

• Acoustic Echo Cancellation -  you can create now high quality collaborative or chat apps that deliver excellent sound quality without a headset. Now, Flash Player 10.3 supports acoustic echo cancellation, noise suppression, voice activity detection, and automatic compensation for various mic input levels.
• Enhanced HTMLLoader API – developers have more control on how clickable links behave in HTMLLoader.
• Media Measurement – this feature enables companies to understand how their videos are distributed and consumed and to collect this data in real-time. There is a new set of open APIs that can be used to implement video analytics.

Some of these features have already made their first appearance in the Flash Player 10.3 beta released a couple of weeks ago. Now, they are integrated into Adobe AIR as well. The final version should come not later than Q2 2011.

Now go and download the bits :)

I got some requests about how to use both Flex and QNX UI components for building PlayBook apps. In this post I will show you how to do it.

Here are the basic steps.

1. Create a Flex mobile project. Make sure that you enable the project for BlackBerry Tablet OS development.

2. Edit project properties to include the QNX libraries in the project build path (right-click on the project name > Properties). Select BlackBerry Tablet OS section and then select the Include BlackBerry Tablet OS Libraries in Build Path option.

Once you apply these changes your project should be ready for QNX components. Of course you have to add QNX components using ActionScript code; you can’t use QNX components as MXML tags.

You have to remember that the QNX UI components don’t inherit or extend the Flex base UI components. And because of this you can’t add them, for example, directly to a View Flex class using view.addElement(QNX-UI-component); instead you can use an instance of Flex UIComponent as a wrapper. Here is a code snippet that illustrates this technique:

Here is screencast that walks you through the setup and shows a sample app:

Download

You can download the project code from here.

Yesterday, fellow evangelist, Terry Ryan, showed me  a tablet app for Android called Conqu. After I installed and played with it for about 5 minutes, I said: “Wow! Mate, this is the coolest app for Android tablets ever!”.

The application helps you to “Get the things done” – by managing tasks. Here is a video and screenshots:

And by the way, this application is built using Flex 4.5 (“Hero”) and uses Adobe AIR for Android as a runtime. Now this is something pretty cool. Well done guys!!!

Because they use the Flash Plaform, it isn’t that hard to target other Flash supported devices such as: PlayBook, desktops, or iOS. In fact if you take a look at their roadmap, this is exactly what they are up to.

I really like the fact that they work on a feature that allows synchronization between devices over the cloud. This will facilitate team work and make this app an interesting and appealing choice for small/medium business.

Getting the App

You can install the application from here (for now there is only the tablet version) and here you can check the roadmap and features.

Congratulations to the people behind this project. I’m looking forward to testing their desktop/PlayBook/iPad versions and hope to meet them in person. I’m really curious to talk  about their experience building this app.

In this post I want to show you how you can use animations/transitions for QNX components to create a better user experience. User experience designers use transitions when they want to highlight or focus user attention to a specific part of the application.

For example, when you add a new component to the screen as a result of user interaction you can do it in two ways:

• just add the new component to the display
• create a transition or animation that gradually introduces the new component to the display

I think it is easiest to understand the subtle difference between the two approaches by seeing this screencast:

In my application I used the tweener library for animating the container that holds the list. This ActionScript library is one of the most used libraries out there for this task. You can grab it from here.

LATER EDIT: QNX is using Tweener internally. So you don’t have to add this library, is already part of the SDK (qnx-screen.swc). Thanks to Julian Dolce of RIM for pointing this out.

Once you get the SWC file, you have to add it to your ActionScript mobile project. The easiest way, especially if you plan to use more libraries, is to add a folder to the ActionScript build path and configure Flash Builder so that every SWC file you drop in this folder will be added to the project.

The steps are:

• Create a folder in your project. I created a folder called libs for my project.
• Copy the tweener.swc file into this folder
  
• Open the project properties page (right-click the project name and select Properties) and select the ActionScript build path. Then click the Add SWC Folder button and select the folder you created earlier. Click the OK button and you are good to go.

How do you use this library? Actually it is pretty simple. There is a static method on the Tweener class called addTween(). You use this method to specify the display object you want to animate, the properties you want to animate (could be the x, y, size, etc), and the animation duration. You can also specify a number of functions to be called for example when the animation is completed or for each step of the animation.

Here is the code for animating the list in the screen:

// rightDock is the container that holds the list
// it is docked to the right-side of the screen
Tweener.addTween(rightDock, {size : 200, time : 1, onUpdate: onUpdateTween});

private function onUpdateTween():void {
    myMain.layout();
}

And this is the code for removing the list from the screen:

Tweener.addTween(rightDock, {size : 1, time : 1, onUpdate: onUpdateTween,
    onComplete: onCompleteTween});

private function onCompleteTween():void {
    myMain.removeChild(rightDock);
}

Why do I call myMain.layout() for each step of the animation? This method is executed in order to reposition and redraw the components on the screen so they account for the width change of the rightDock container.

You can download the project source code from here.

After I tried the available list components from QNX UI library for PlayBook development, my fist question was: how can I customize both the look and feel, and the functionality of these components? In this post, I will show you how you can extend the TileList and AlternatingCellRenderer QNX components to change the UI and add additional functionality.

By default, a TileList looks like this:

You use the dataProvider property to set the data, and its default renderer (CellRenderer) expects the data to be an object that has a String property called label. And this property will be used to display the text for each tile. You control can control the number of tiles by using the columnCount property, and you can set the width and the height of the tiles by using columnWidth and rowHeight properties. You use the cellPadding property to control the space between the tiles.

This is pretty cool. But what if you want to display more complex data? Let’s say you want to have a picture, label, and some graphic? Obviously you’ll have to extend the default renderer to do this. Here is what I have in my mind:

Second, I wanted the TileList to be able to calculate dynamically the number of columns that can be layout, depending on three input data: the width of the TileList, the cellPadding value, and the size of a tile. So, instead of hard coding the columnCount property when creating the component, I just set the size of the tiles (columnWidth and rowHeight) and the width of the TileList and based on these the TileList will calculate how many columns can fit in the given width and sets the columnCount property accordingly. Here is an example (in the first picture the tiles size is set to 130pixels, in the second one to 250pixels):

This means that I have to extend the TileList component to add this behavior. But, the first step is to create a custom CellRenderer so I can display the picture, label, and gray rounded square. Luckily, fellow evangelist, Renaun Erickson, created a example that was pretty close to what I needed.

Creating a custom CellRenderer for the the TileList

Renaun’s example is pretty closed to what I want to achieve. The reason I needed to modify it, was that I want a different arrangement of the components and, more importantly, I want to push the width and the height of the tiles from the TileList – I don’t want to have these values hard coded in the CellRenderer class.

Now, let’s step back and talk about the lifecycle of a CellRenderer component. The lists components use virtualization; this means that the list will create a limited number of CellRenderer components and reuse them as you scroll down and up the list. Every time an instance of the CellRenderer is reused, the TileList component will push the new data that needs to be displayed by that cell using the data property of the CellRenderer.

Next, every time you change the columnWidth/rowHeight properties, the TileList will loop through all the instances of the CellRender and call the setSize() method to push the new values.

Knowing this it became quite clear what I need to do in order to create my custom CellRenderer: override the set data() and setSize() methods, and add the parts I needed (image, rectangle, label). Here is some of the code (for the complete code go do Download section and get the project source):

public class PictureCellRenderer extends AlternatingCellRenderer {

    /**
     * Skin parts used to render the data
     */
    protected var img:Image;
    protected var lbl:Label;
    protected var bg:Sprite;
    protected var format:TextFormat;

    public function PictureCellRenderer() {
        super();
        // hide the built in label
        label.visible = false;
        createUI();
    }
    /**
     * setSize() is called everytime the tiles size are changed
     * this is where we add our method layout() to reposition/redraw
     * various parts of the cell renderer.
     */
    override public function setSize(w:Number, h:Number):void {
        super.setSize(w, h);
        //we want to draw the skin parts only when the
        //actual width/height are set
        //this method is called first for the default sizes and then for
        //for the user prefered sizes
        if (stage) {
            layout();
        }
    }
    /**
     * Updates the text and image everytime a new data is set
     * for this renderer instance.
     */
    override public function set data(value:Object):void {
        super.data = value;
        //Update the image source and text if there is valid data.
        if (value) {
            img.setImage(value.img);
            lbl.text = value.label;
        }
    }
    /**
     * Create all the cell renderer components just once
     */
    private function createUI():void {
        img = new Image();
        bg = new Sprite();
        lbl = new Label();

        //...
        //code to position the img, Sprite, and label
        //...

        addChild(img);
        addChild(bg);
        addChild(lbl);
    }
    /**
     *     Draws the rectangle used as background
     *  for the label
     */
    private function drawBg():void {
        //code to redraw the gray rounded rectangular
    }
    /**
     * Reposition/redraw the renderer parts
     * everytime the tile size is changed
     */
    private function layout():void {
        lbl.y = height - 20;
        lbl.width = width - 10;
        drawBg();
        onComplete(new Event(Event.COMPLETE));
    }
    /**
     * Resize the image once the bits were loaded
     */
    private function onComplete(e:Event):void {
        img.setSize(width - 20, height - 20);
    }
}

Few notes on the code above:

• The components used to display the data (Image, Sprite, and Label) are created inside the createUI() method called from the constructor – they are created only once
• When you load an image, you have to listen to the Event.COMPLETE event if you want to set width and height to something different than the size of the image
• Every time the setSize() method is called, the layout() function is executed; thus the Image, Sprite, and Label components are repositioned or resized to use the new width and height available
• In the constructor I turn invisible the built-in label component of parent class. I tried to reuse it instead of creating a new label but I couldn’t find a method to change it’s position nor the format. I’m not sure if this is bug or is something wrong with my approach
• I extended the AlternatingCellRenderer instead of CellRender just to get different backgrounds for adjacent cells. The code should work as well if you extend the latter
• The data you pass to this render must be an object that has a label property for the text and an img property for the Image URL (both must be Strings)
• This renderer uses ImageCache in order to cache the images. Depending on your application you must see how many images you should cache so you don’t use too much system memory

Extending the TileList component to support liquid layout

With the custom CellRenderer in place, more than half of the work was done – or at least this is what I thought first :). So what was left to be implemented was the ability of the TileList to decide automatically how many columns fit in the given width and every time the width of the component or width of the tiles was changed, to recalculate the number of columns and update its layout. Having this behavior incorporated in my custom TileList means that:

• I don’t have to do anything when the display orientation changes – the TileList will automatically change the number of columns to fit the new width and height
• I can control the size of the tiles at runtime; for example the user can zoom in or out using a slider

I had two options to get this behavior:

• Create a method that does all the math to determine the new columnCount
• Or to extend the TileList component and build this behavior in the component itself

I chose the second option and before explaining how I did it, here is the LiquidTileList component code:

public class LiquidTileList extends TileList {
	/**
	 * if true, when changing the size of the tiles
	 * scrolls the list so the first tile from the previous
	 * state is still visible
	 */
	public var keepVisibleItem:Boolean;

	public function LiquidTileList() {
		super();
		setSkin(PictureCellRenderer);
	}
	/**
	 * Overriding the draw method to inject 
	 * our method of calculating the number of
	 * tiles that fit the screen
	 * This method is called every time the width/height
	 * is changed
	 */
	override protected function draw():void {
		var i:int;
		if (keepVisibleItem && firstVisibleItem)
			i = firstVisibleItem.index;
		scrollIndexVisible(0, 0);
		calculateColumns();
		super.draw();
		if (keepVisibleItem && i)
			scrollIndexVisible(i, 0);
	}
	/**
	 * Calculates the number of tiles that fit
	 * the width
	 */
        private function calculateColumns():void {
		var columnNumber:int = Math.floor( (width - (cellPadding * columnCount -1) )
                                                      / columnWidth);
		if (columnNumber != columnCount)
			columnCount = columnNumber;
	}
}

In the constructor I set the PictureCellRenderer as the default skin. Next, I over wrote the draw() method. This method is called every time the width and height of the list is changed, or you change the tiles size (columnWidth, rowHeight); first I calculate the number of columns using the new sizes (by calling the calculateColumns() method) and then I call the parent draw() method to redo the layout using the new columnCount value.

If you wonder what’s the deal with the scrollIndexVisible() calls, well this was the hard part. I think there is a bug in the virtualization engine of the TileList because when I changed the size of the tiles, sometimes you end up with items missing or you can’t scroll anymore. So this is the only way I found to get around this issue. Second, I wanted to be keep in the view the first visible element. For example, suppose you have a large list and you scrolled a bit and then you decide to increase the size of the tiles three times. I think that the user would expect to see the the first items of the previous view. So this is why I added a public property called keepVisibleItem.

In my tests, the component works fine after applying the scrollIndexVisible fix. However, if you want to change the tiles size using a slider and you apply the new values live (you apply the new values listening for SliderEvent.MOVE event) then it is better to set the keepVisibleItem to false.

And here is a snippet of code of how you can use this custom component:

peopleList = new LiquidTileList();
peopleList.keepVisibleItem = true;
peopleList.dataProvider = getPeople();
peopleList.scrollDirection = ScrollDirection.VERTICAL;
peopleList.size = 100;
peopleList.sizeUnit = SizeUnit.PERCENT;
peopleList.sizeMode = SizeMode.BOTH;
//provide a default number of columns;
//this can be override by LiquidTileList so it fill all
//the available width
peopleList.columnCount = 5;
peopleList.columnWidth = 150;
peopleList.rowHeight = 150;
peopleList.cellPadding = 5;
peopleList.selectionMode = ListSelectionMode.SINGLE;

slider = new Slider();
slider.minimum = 130; //min value
slider.maximum = 250; //max value
slider.value = 150;   //default value
slider.addEventListener(SliderEvent.END, onSliderMove);
slider.addEventListener(SliderEvent.MOVE, onSliderMove);
...
/**
 * Slider event changeing the size of the tiles
 */
private function onSliderMove(e:SliderEvent):void {
	peopleList.columnWidth = e.value;
	peopleList.rowHeight = e.value;
}

And here is a screencast of this example:

Download the code

You can download the entire project from here. Have a look at it, and drop a comment if you find bugs or you have a better idea :)

If you’ve ever worked with Flex “Hero” mobile components you probably love the way Flex “Hero” handles the screen metaphor. It provides a neat way to encapsulate the UI and business logic for each screen in a class.

On a mobile device, you need to keep in mind that an application can be closed anytime by the operating system. This could be because the OS is trying to free some resources or maybe the battery just died. In either case when the user reopens the app, he expects to see the last screen he was working on as well as any data that was entered. Again, with Flex “Hero” mobile applications all you have to do is to set the sessionCachingEnabled to true and assign the information you want to be persisted to the data property of your views.

This is great; however if you develop applications for PlayBook using the QNX libraries (the native Tablet OS SDK for Adobe AIR) you can’t use Flex “Hero” and, as a result, you don’t have support for the screen metaphor. I wanted this kind of support for an application I plan to build for PlayBook.

Lucky for me, I didn’t have to start from scratch because my fellow evangelist, Piotr Walczyszyn, has already created a small library that does nice tweening between two screens and implements the methods for adding a screen or popping one. So, I took his library and I modified it a little bit. Why did I modify the library? First, I wanted to have session caching capabilities and to be able to push data from one screen to another in the same manner as a Flex “Hero” mobile application. And second, I wanted to make it easier to work with QNX UI components (the original library supported generic ActionScript mobile projects).

Basic usage

To use this library you have to add the library code to your project and create classes that extends org.corlan.asviews.BaseView for each view/screen you need for your application.

In the main application file you create an instance of the org.corlan.asviews.ViewNavigator class. You use its pushView() method to define the first view/screen and to move to new screens. You use the popView() method to move back to the previous screen/view or popToFirstView() to jump directly to the first view/screen.

If you need session caching for your app there are two things you have to do. First, when you create the ViewNavigator instance, you set the second argument to true. Second, you register the ViewNavigator.prepareForClosing() method as an event listener for the application Close event:

 NativeApplication.nativeApplication.addEventListener(
     Event.EXITING, navigator.prepareForClosing, false, 0, true);

See this screencast for more information or read on the next section.

Downloading and using the library

You can download the sample project from here and the library from here.

It is quite simple to use it once you set up the library project and add it as a dependency to your ActionScript mobile project. Here are the steps:

1. Download the as3viewnavigator library from here and import it in Flash Builder Burrito. Then open the project properties dialig box, select Flex Library Build Path, and make sure that qnx-screen.swc file is added to the build path (you can find this swc in the sdks/blackberry-tablet-sdk-0.9.2/frameworks/libs/qnx-screen/ folder inside the Flash Builder Burrito installation folder).
   
2. Create a new ActionScript Mobile Project for PlayBook development. Then open the project properties dialog box, select ActionScript Build Path, click the Add Project, and choose the as3viewnavigator project.
   

Now you are ready to use it. The basic steps are:

• For each screen you want, create a class that extends the org.corlan.asviews.BaseView (this class extends the QNX Container class and implements the org.corlan.asviews.IView interface). When you create the screen classes you have to keep in mind that you need to override two methods from the BaseView class:
  • createUI() – this is where you create the UI for the screen using the components from the QNX libraries or your own components.
  • applyData() – you use this method to populate the UI with the data saved in the previous session. This method is called automatically once your screen class is added to the stage.
• Store whatever data you want to be persisted in the data property of your screen classes
• In the main application file, you instantiate the org.corlan.asviews.ViewNavigator class and push the first screen. Also, you need to register the ViewNavigator.prepareForClosing method to listen for application Close events.
• In any screen that you need to push a new screen (or move back) you just call the navigator.pushView(View-Class-Name, data), navigator.popView(), or navigator.popToFirstView() methods

Now let’s see some snippets of code to better understand the workflow. First here is the code for the main application file:

[SWF(height="600", width="1024", frameRate="30", backgroundColor="#FFFFFF")]
public class ASViews extends Sprite
{

	private var navigator:ViewNavigator;

	public function ASViews()
	{
		stage.align = StageAlign.TOP_LEFT;
		stage.scaleMode = StageScaleMode.NO_SCALE;

		// Creating an instance of ViewNavigator
		// if second argument is set to true then the history
		// is persisted between sessions
		navigator = new ViewNavigator(this, true);
		// Pushing first view to the navigator
		navigator.pushView(HomeScreen);
		//listening for application closing event
		//in order to save the history
		NativeApplication.nativeApplication.addEventListener(Event.EXITING,
				navigator.prepareForClosing, false, 0, true)
	}

}

And here is the code for the first screen, HomeScreen (in the onItemSelected() method I push the second screen passing along the current selected item from the list to be used in the second screen):

public class HomeScreen extends BaseView
{

	private var list:List;

	public function HomeScreen(s:Number=100, su:String="percent")
	{
		super(s, su);
	}

	override protected function createUI():void {
		flow = ContainerFlow.HORIZONTAL;

		var optionsArr:Array = [
			{label: "Flash Gordon - The fastest man on earth!"},
			{label: "Superman - This guy could use some fashion advisory!"},
			{label: "Batman - The coolest bat in town!"},
			{label: "Green Lantern - Not a friend of Green Hornet"},
			{label: "Green Hornet - Can be tricked with some good coffee!"}
		];

		//list with the options
		list = new List();
		list.containment = Containment.BACKGROUND;
		list.dataProvider = new DataProvider(optionsArr);
		list.selectionMode = ListSelectionMode.SINGLE;
		list.addEventListener(ListEvent.ITEM_CLICKED,
                        onItemSelected, false, 0, true);

		addChild(list);
	}

	private function onItemSelected(e:ListEvent):void {
		if (!data)
			data = new Object();
		data["selectedItem"] = list.selectedIndex;
		navigator.pushView(SecondScreen, list.selectedItem);
	}

	override protected function applyData():void {
		trace("applyData() HomeScreen");
		if (!data)
			return;
		if (data["selectedItem"])
			list.selectedIndex = data["selectedItem"];
	}
}

This is the code for the second screen, SecondScreen (in the onGoBack() method I call the navigator.popView() method to move back to the previous screen):

public class SecondScreen extends BaseView
{

private var lbl:Label;

public function SecondScreen(s:Number=100, su:String="percent")
{
	super(s, su);
}

override protected function createUI():void
{
	flow = ContainerFlow.VERTICAL;

	var topContainer:Container = new Container();
	//			topContainer.margins = Vector.([1,1,1,1]);
	//			topContainer.debugColor = 0x33FF33;
	topContainer.size = 50;
	topContainer.sizeUnit = SizeUnit.PIXELS;
	topContainer.flow = ContainerFlow.HORIZONTAL;
	topContainer.containment = Containment.DOCK_TOP;

	var left:Container = new Container();
	//			left.margins = Vector.([1,1,1,1]);
	//			left.debugColor = 0x33FF33;
	left.size = 70;
	left.sizeUnit = SizeUnit.PERCENT;
	left.flow = ContainerFlow.VERTICAL;
	left.align = ContainerAlign.NEAR;

	var right:Container = new Container();
	//			right.margins = Vector.([1,1,1,1]);
	//			right.debugColor = 0x33FF33;
	right.size = 30;
	right.sizeUnit = SizeUnit.PERCENT;
	right.flow = ContainerFlow.VERTICAL;
	right.align = ContainerAlign.FAR;

	lbl = new Label();
	lbl.text = "";
	lbl.autoSize = TextFieldAutoSize.CENTER;

	var backBtn:BackButton = new BackButton();
	backBtn.label = "Go Back";
	backBtn.addEventListener(MouseEvent.CLICK, onGoBack, false, 0, true);

	left.addChild(new Spacer(50));
	left.addChild(lbl);
	right.addChild(new Spacer(1));
	right.addChild(backBtn);

	topContainer.addChild(left);
	topContainer.addChild(right);
	addChild(topContainer);
}

private function onGoBack(e:MouseEvent):void {
	navigator.popView();
}

override protected function applyData():void {
	trace("applyData() SecondScreen");
	if (!data)
		return;
	lbl.text = data["label"];
}

In case you’re wondering how do I save the data, I’m using SharedObject and I persist an array representing the current screen stack (the screen class name and the data object for each instance).

Conclusions

Although I intend to use this library in my projects, I haven’t tested it extensively ywt. This means you may find bugs. If so, please let me know. Furthermore, there is a big difference in how this library manages the views compared to how Flex does: Flex’s ViewNavigator destroys by default a view when removing it. This library doesn’t. So, if you have lots of views with lots of components you might end up using a lot of memory. For such a use case it should be modified to mimic the Flex approach.

If you’ve started to create apps for PlayBook I’m eager to learn how you manage the screens. So, please talk back :D!

In a previous post I talked about all sorts of lists available to developers when using the BlackBerry Tablet OS SDK for Adobe AIR. In this article I will focus on the remaining UI controls. I have an idea for a PlayBook application and before writing a single line of code I wanted to make sure that I understood all the UI components that are available as part of the BlackBerry SDK. By the way, in case you didn’t know, RIM offers a free PlayBook device to any developer who gets his application on BlackBerry App World. I thought I’d share with you the results of my research.

I won’t cover how to skin these components. This is a topic for another blog post. In the meantime you can read Ryan’s posts on skinning ( buttons/text fields and lists) and Renaun’s post.

Buttons

There are seven buttons in the package qnx.ui.buttons. If you want to do something when a buttons is clicked you have to register an event listener for MouseEvent.CLICK, Event.CHANGE (only for SegmentedControl), or Event.SELECT (for ToggleSwitch); for example:

myButton.addEventListener(MouseEvent.CLICK, doSomethingOnClick);

private function doSomethingOnClick(e:MouseEvent):void {
    //do something
}

LabelButton and IconButton, as the names suggest, enable you to create buttons with either text labels or icons. Both these buttons extend the Button class (if you use the Button class  itself you will get a button without a label or icon). You can enable toggle by setting the the property with the same name to true. This will give you a button, that once clicked, stays selected and then is unselected when you click it again. In the image below you can see these two buttons with toggle on in the selected and unselected state.

You can use a flash.Text.TextFormat object to change the label settings for a LabelButton. You set the image to be used by the IconButton by calling the setIcon() method and passing the path to the image to be used or a Bitmap/BitmapData instance. Here is the code used for rendering the example above:

var format:TextFormat = new TextFormat();
format.font = "BBAlpha Sans";
format.size = 22;
format.color = 0x990000;
format.align = TextFormatAlign.CENTER;

var btn:LabelButton = new LabelButton();
btn.size = 50;
btn.sizeMode = SizeUnit.PIXELS;
btn.label = "Label Button";
btn.toggle = true;
btn.setTextFormatForState(format,SkinStates.DISABLED);
btn.setTextFormatForState(format,SkinStates.UP);
btn.setTextFormatForState(format,SkinStates.DOWN);
btn.setTextFormatForState(format,SkinStates.SELECTED);
btn.setTextFormatForState(format,SkinStates.DISABLED_SELECTED);
container.addChild(btn);

var btn2:IconButton = new IconButton();
btn2.size = 100;
btn2.sizeMode = SizeUnit.PIXELS;
btn2.setIcon("assets/icon.png");
btn2.toggle = true;
container.addChild(btn2);

BackButton extends the LabelButton and you can set the label if you want (the default label is Back). It also has an arrow icon to the left of the button. As in the case of LabelButton you can use a TextFormat object and play with the toggle property.

var btn3:BackButton = new BackButton();
btn3.label = "Go Back";
container.addChild(btn3);

CheckBox extends LabelButton too and has the toggle property set to true (you can’t change this one). However, you can control where to display the text relative to the check mark by using the labelPlacement property. Using the labelPadding property you can set the space between the label and icon. And of course TextFormat can be used to customize the label look. You have to pay attention to the width property if you don’t want to have the label cropped.

var cb:CheckBox = new CheckBox();
cb.label ="Select Me";
cb.width = 150;
cb.labelPlacement = LabelPlacement.RIGHT;
cb.labelPadding = 30;
container.addChild(cb);

The last component that extends the LabelButton is RadioButton. You use this component to force the user make a single selection from a group of at least two radio buttons. You can use TextFormat to customize the look of the label. You assign a radio button to a group by setting the same string to the groupname property. If you want to have one option preselected, you set the selected property to true.

var rb1:RadioButton = new RadioButton();
rb1.size = 30;
rb1.sizeUnit = SizeUnit.PIXELS;
rb1.groupname = "group1";
rb1.label = "Yes";
rb1.selected = true;
container.addChild(rb1);

var rb2:RadioButton = new RadioButton();
rb2.size = 30;
rb2.sizeUnit = SizeUnit.PIXELS;
rb2.groupname = "group1";
rb2.label = "No";
container.addChild(rb2);

SegmentedControl displays a series of connected radio buttons and the user can select only one of them. As with lists you use a DataProvider to add the labels you want. An alternative is to add labels one by one using the  addItem() or addItemAt() methods. Each label is set using an instance of Object with one property named label. You can preselect an option using the selectedIndex property and you listen for user selection by registering an event listener for the flash.events.Event.CHANGE event. You can skin this component by setting up a new skin for the background and buttons.

var segData:Array= [
		{label:"< 10"},
  		{label:"10-19"},
  		{label:"> 20"}
	];
var seg:SegmentedControl = new SegmentedControl();
seg.dataProvider = new DataProvider(segData);
seg.selectedIndex = 1;
container.addChild(seg);

The last button is the ToggleSwitch. This component extends the Slider component. It enables you to create a button with two labels and slider that always hides one of the two labels. To set the label from the left you use the selectedLabel property, and for the one on the right you use the defaultLabel property. You can control the default selection by setting selected property to true/false and you react to component changes by listening for Event.SELECT events. You can see in the image below the component using the default skin in the two states:

var tog:ToggleSwitch = new ToggleSwitch();
tog.selectedLabel = "On";
tog.defaultLabel = "Off";
tog.selected = true;
container.addChild(tog);

Text Controls

In the package qnx.ui.text you’ll find two UI components: Label and TextInput. You can use the Label component for displaying text (it can’t receive focus). There are a number of properties you can use for fine control over how the text will be displayed:

• By default a label is 100 pixels wide. If you don’t set the autoSize property or adjust the width, then it is quite possible you will not see the whole text. The easiest way is to use the autoSize property and set how the label should grow so the text will be fitted; for example: label.autoSize = TextFieldAutoSize.CENTER;
• If you want to set the font family name/size/type-face/color you use an instance of TextFormat to set these values and then you assign it to the label’s format property
• You set the text you want to be displayed using either the text property or the htmlText property. After playing with the htmlText property, I found that the main benefit is that you can throw in some HTML formatted text and it will be displayed just like text – this is useful if you don’t want to see the tags.
• When you set the multiline property to true, and display HTML text like this <p>one</p><br/><p>two</p> then you will see the text in two paragraphs with one line between them
• The selectable property, when set to true, allows user to select the text
• You can use the wordWrap property to allow wrapping the words so the text can be displayed without increasing the width of the label

Here is a code example and its rendering:

var format:TextFormat = new TextFormat();
format.font = "BBAlpha Sans";
format.bold = true;
format.size = 19;
format.color = 0x000099;

var lbl:Label = new Label();
lbl.format = format;
lbl.autoSize = TextFieldAutoSize.CENTER;
lbl.wordWrap = true;
lbl.multiline = true;
lbl.selectable = true;
lbl.htmlText =
"<p><strong>This is a label!!!</strong></p><br/><p>Second Paragraph</p>";
container.addChild(lbl);

If you want to let the user type some text or edit it, then you’ll use the TextInput component. This component is pretty powerful because it lets you add custom icons inside of it (on the left/right sides) and control when they are displayed. You can also control what type of the keyboard should be displayed when the text field gets the focus (the keyboard is pulled out automatically when a TextInput is selected). Just set the keyboardType property to one of the following values; for example: KeyboardType.DEFAULT, KeyboardType.EMAIL, KeyboardType.URL, KeyboardType.PIN, or KeyboardType.PHONE. You can customize the label displayed on the Enter key by using the returnKeyType property: txt.returnKeyType = ReturnKeyType.GO. If you want to use the text field for passwords you can set the displaysAsPassword property to true.

When you want to format the text you use a TextFormat object, exactly as in the case of the Label. By default you can have a Clear icon inside of the text field that you can use for deleting the entire text. You can control when it is displayed using the clearIconMode property; for example: txt.clearIconMode = TextInputIconMode.ALWAYS. If you want to add a custom icon to the left or right side, one way to do it is to create a transparent PNG file with the icon you want and then embed the PNG file and set the class to the leftIcon or rightIcon properties. From my tests it seems that is better to have the icon bigger rahter than smaller compared to what will be actually rendered. And you can control when it is displayed using the leftIconMode or rightIconMode properties. For example:

[Embed(source="assets/arrow48x48.png")]
private var ArrowIcon:Class;
...
txt.leftIcon = new ArrowIcon();
txt.leftIconMode = TextInputIconMode.UNLESS_EDITING;

Here is the code used to create the example displayed in the pictures:

var format:TextFormat = new TextFormat();
format.font = "BBAlpha Sans";
format.bold = true;
format.size = 19;
format.color = 0x000099;

var txt:TextInput = new TextInput();
txt.format = format;
txt.width = 400;
txt.keyboardType = KeyboardType.PHONE;
txt.returnKeyType = ReturnKeyType.GO;
txt.clearIconMode = TextInputIconMode.ALWAYS;
txt.leftIcon = new ArrowIcon();
txt.leftIconMode = TextInputIconMode.UNLESS_EDITING;

If you want to do something when the user introduces or edits the text, then you have to register an event listener for the Event.CHANGE event:

txt.addEventListener(Event.CHANGE, onChange);

Here are the shortcomings I found so far for the TextInput (as of writing this post the SDK is in beta):

1. You can’t test it outside of the emulator without a hack – see Renaun’s post on this topic. This is  because this component requires a class that is part of the RIM AIR runtime.
2. When setting the autoSize property to TextFieldAutoSize.CENTER you can’t select the field and type in it.
3. It doesn’t support multiple lines. Some people found a way to get around this, but I think we need official support from RIM in the form of a different component or an addition to the TextInput.

Sliders

In the package qnx.ui.slider you’ll find Slider and VolumeSlider components. VolumeSlider extends the Slider and provides a default skin suited for media applications. You can set the minimum and maximum values using the properties with the same name. You can’t set the step when moving the thumb around. You can retrieve the current value using the value property and keep in mind it is a Number and not Integer (so you can get 6.7, for example). If you want to have the slider’s thumb position to something other than the left side by default, you set the value property to what you need.

var slider:Slider = new Slider();
slider.width = 300;
slider.height = 40;
slider.minimum = 1;
slider.maximum = 10;
slider.value = 5.5;
slider.addEventListener(SliderEvent.START, onDragStart);
slider.addEventListener(SliderEvent.END, onDragEnd);
slider.addEventListener(SliderEvent.MOVE, onMove);

var volume:VolumeSlider = new VolumeSlider();
volume.minimum = 0;
volume.maximum = 1;

While you can set the width of the component, setting the height doesn’t change anything. You need to create skins for thumb and track if you need more customization, and use the setThumbSkin() and setTrackSin() methods to apply them.

There are three events you can listen for: SliderEvent.START (when the thumb starts to move), SliderEvent.END (when the user has finished the dragging), and SliderEvent.MOVE (while the thumb is moving). It seems that both these sliders can be only horizontal.

Progress Bars

When you want to display progress to the user you can use components available in the qnx.ui.progress package. The ActivityIndicator component lets you display visual feedback when a time-consuming operation is executing. You start the animation by calling the animate(true) method and stop it with animate(false). You can check if the animation is running by calling the isAnimating() method. It should be possible to skin it by extending ActivityIndicatorSkin.

var activity:ActivityIndicator = new ActivityIndicator();
activity.setSize(30, 30);
activity.animate(true);

Using the ProgressBar and PercentageBar you can give a sense of progress of how much of the work has been completed and how much is remaining. You change this by setting the progress property to a number between 0 and 1, where 1 represents 100% of the job done. PercentageBar has a label as well, so the user knows exactly what the progress is – you can hide it by setting the showPercent property to false.

var prog:ProgressBar = new ProgressBar();
prog.width = 200;
prog.progress = 0.3;

var per:PercentageBar = new PercentageBar();
per.width = 200;
per.progress = 0.9;

Extending the skins from the qnx.ui.skins.progress package is the way to customize the look and feel.

Image Controls

In the qnx.ui.display you’ll find two components: Image and TilingBackground. You use the Image class when you want to display an image. By calling the setImage() method you set a local path to an image, an URL, or a Bitmap/BitmapData object. There are two events you can listen for:

• Event.COMPLETE – this event is triggered once the image was loaded and ready to use
• IOErrorEvent.IO_ERROR – dispatched when the image can’t be loaded

If you plan to scale the image (up or down) you might want to set the smoothing property to true. To cache the images, create a single instance of ImageCache and assign it to the Image.cache property. You can force the cache to reload an image if you need.

Here is an example that loads an image from the application folder:

private static var imageCache:ImageCache = new ImageCache();
private static const IMAGE_PATH:String =  "assets/picture.jpg";
...
var img:Image = new Image();
img.smoothing = true;
img.cache = imageCache;
img.addEventListener(Event.COMPLETE, onComplete);
img.setImage(IMAGE_PATH);
container.addChild(img);
...
private function onComplete(e:Event):void {
    container.layout();
}

Please note that in the above example I didn’t explicitly set the width and height of the image. These were set automatically to the values taken from the loaded image. If you want to set them to something different you have to do it after the image is loaded when the Event.COMPLETE event is thrown. Otherwise they will be overwritten.

When you want to create a tile from images, you use the TilingBackground component. You don’t have much control on how the image will be tiled (it will be tiled on both X and Y depending on how much space it is available and how large the image to be tiled is). What surprised me was the way you set the image. I was expecting to have the same options available as for Image.setImage(). Instead, you use the bitmapData property and set it to a BitmapData object. In the following example I’m using the ImageCache.getImage() API to get the BitmapData object loaded by the Image object and set it to the bitmapData property of the TilingBackground:

tile = new TilingBackground();
tile.containment = Containment.BACKGROUND;
container.addChild(tile);
//inside the complete event handler of the Image
tile.bitmapData = imageCache.getImage(IMAGE_PATH, false);

Dialog

The QNX UI library provides a number of classes for creating a floating window on top of your application. I think that this is a useful feature, because with the real estate available on the PlayBook tablet you may want to use one of these dialogs instead of “pushing” an entirely new screen (screen metaphor approach).

There are five dialog boxes to choose from, and you have to remember that the appearance is controlled by the BlackBerry Tablet OS. You can control the position, size, and the type of the window:

• system modal – blocks the entire tablet until the window is closed – use Dialog.open()
• application modal – blocks the interaction only with the application – use Dialog.open(IowWindow.getAirWindow().group)

Using DialogAlign and the align property of the dialog you can specify where on the vertical axis it should be placed (it is always centered horizontally). You can add buttons and set properties to them like this:

var myDialog:AlertDialog = new AlertDialog();
myDialog.addButton("Yes");
myDialog.addButton("No");
myDialog.addButton("Cancel");
myDialog.setButtonPropertyAt("enabled", false, 2);

Once the user clicks one of the buttons you add to the window, if you registered an event listener on the dialog box for the Event.SELECT event you can determine what button was pressed:

myDialog.addEventListener(Event.SELECT, alertButtonClicked);
...
private function alertButtonClicked(e:Event):void {
	trace((e.target as AlertDialog).selectedIndex)
}

The life cycle for a dialog box is:

1. You create a new instance of the dialog you want
2. You configure the content (messages, buttons, labels…) and the positioning/sizing of the dialog
3. You register an event listener for the Event.SELECT event
4. You call the show() method on the dialog to display it

AlertDialog is the simplest window. You use this window in order to display some text to the user and allow him to click on one of the buttons you add to it. You set the title and message using the properties with the same names.

And here is the code:

var myDialog:AlertDialog = new AlertDialog();
myDialog.title = "AlertDialog";
myDialog.message = "This is an alert dialog. Do you like it?";
myDialog.addButton("Yes");
myDialog.addButton("No");
myDialog.addButton("Cancel");
myDialog.setButtonPropertyAt("enabled", false, 2);
myDialog.dialogSize = DialogSize.SIZE_MEDIUM;
myDialog.align = DialogAlign.TOP;
myDialog.addEventListener(Event.SELECT, alertButtonClicked1);
myDialog.show(IowWindow.getAirWindow().group);
...
private function alertButtonClicked1(e:Event):void {
	trace((e.target as AlertDialog).selectedIndex)
}

LoginDialog presents the user an interface for providing the information necessary for a login operation: user name, password, remember me. It extends the AlertDialog class so everything you can do with it applies to LoginDialog too. Using the rememberMe, password, and username properties you can retrieve the information the user introduced. You can set the text used for username/password/remember me using these properties: usernameLabel, passwordLabel, passwordPrompt, and rememberMeLabel.

var login:LoginDialog = new LoginDialog();
login.title = "Login";
login.message = "Please enter your username and password:";
login.addButton("OK");
login.addButton("Cancel");
login.passwordPrompt = "password";
login.rememberMeLabel = "Remember me";
login.rememberMe = true;
login.dialogSize = DialogSize.SIZE_SMALL;
login.addEventListener(Event.SELECT, alertButtonClicked2);
login.show(IowWindow.getAirWindow().group);
...
private function alertButtonClicked2(e:Event):void {
	var login:LoginDialog = e.target as LoginDialog;
	trace(login.password); //retrieve the password
	trace(login.username); //retrieve the username
	//retrieve whather the remember me option was selected
	trace(login.rememberMe);
	trace(login.selectedIndex); //retrieve the button was clicked
}

PasswordChangeDialog, as the name suggests, is handy when you want to let the user change his password. It extends the LoginDialog. As with its superclass, you can customize the labels of the predefined UI components.

Here is the code to create the dialog box above:

var password:PasswordChangeDialog = new PasswordChangeDialog();
password.title = "Password Change";
password.message = "Please choose your new password:";
password.addButton("OK");
password.addButton("Cancel");
password.dialogSize= DialogSize.SIZE_MEDIUM;
password.addEventListener(Event.SELECT, alertButtonClicked3);
password.show(IowWindow.getAirWindow().group);

And here is how you retrieve the user input:

private function alertButtonClicked3(e:Event):void {
	var login:PasswordChangeDialog = e.target as PasswordChangeDialog;
	trace(login.password); //retrieve the old password
	trace(login.username); //retrieve the username
	trace(login.newPassword); //retrieve the new password
	trace(login.confirmation); //retrieve the confirmation for the new password
	trace(login.selectedIndex); //retrieve the button was clicked
}

The PromptDialog extends AlertDialog and provides a way to capture user text input. You can set the hint to be used by the TextField using the prompt property. And you can retrieve the text entered using the text property.

Here is the code:

var prompt:PromptDialog = new PromptDialog();
prompt.title = "Choose your username!";
prompt.message = "Please enter an username between 6-10 chars:";
prompt.prompt = "username";
prompt.addButton("OK");
prompt.addButton("Cancel");
prompt.dialogSize= DialogSize.SIZE_SMALL;
prompt.addEventListener(Event.SELECT, alertButtonClicked4);
prompt.show(IowWindow.getAirWindow().group);
...
private function alertButtonClicked4(e:Event):void {
	var d:PromptDialog = e.target as PromptDialog;
	//retrieve the text introduced by the user
	trace(d.text);
}

The last dialog window is the PopupListcomponent. This dialog creates a window that presents a scrollable list and the user can select either a single entry or multiple entries. You set the items that will be rendered in the list by assigning an Array of strings to the items property. If you want to allow multiple selections then you set the multiSelect property to true. If you want to preselect an item or a number of items, just set the selectedIndices property to an array of indices of the items you want selected.

Here is the code:

var popUp:PopupList = new PopupList();
popUp.title = "Chose your title:";
popUp.items = ["Mr.", "Ms.", "Miss", "Dr.", "Phd"];
//allow multiple selection
popUp.multiSelect = true;
//preselect the second item
popUp.selectedIndices = [1];
popUp.addButton("OK");
popUp.addButton("Cancel");
popUp.dialogSize= DialogSize.SIZE_SMALL;
popUp.addEventListener(Event.SELECT, alertButtonClicked5);
popUp.show(IowWindow.getAirWindow().group);
...
private function alertButtonClicked5(e:Event):void {
	var d:PopupList = e.target as PopupList;
	//retrieve the selected index/indices
	trace(d.selectedIndex);
	trace(d.selectedIndices.toString());
}

One last note on dialog box components: it doesn’t look like you can skin them or extend them. It would be nice to be able to create a custom dialog with the components you want in it. On the other hand they really cover most use cases you might think of.

Download

If you want the code used for this article, just download this ActionScript mobile project for Flash Builder 4.5 (you’ll need the PlayBook simulator and the BlackBerry plug-in for Flash Builder installed in order to run and compile the code).

Conclusions

These are not all the components available in the QNX libraries. Though I feel that with this post and the previous one on lists I’ve covered the vast majority. Check Ryan‘s and Renaun‘s blogs for articles on containers and playing multimedia.

I have to say that I really think that RIM did an amazing job with this QNX UI library. I think it includes pretty much all you need to create great applications. Especially the list components seemed to be almost complete and the dialog components are a nice touch particularly for tablet devices (though I’m not sure how well they will perform on smartphone screens).

In general everything seems to be well engineered and designed. The biggest caveat of all this is that we don’t have the library source code. Any Flex developer will tell you how important it is that the Flex framework is open source and you can inspect all the code you wish. It’s great when learning the framework and it is definitely great when debugging. Right now even a process that shouldn’t be that complicated (skinning) is a trial and error process.

What do you think?

Two days ago I stumbled upon a rather cool AIR application for managing ASDoc documentation offline and I thought it might help others too. Because sometimes I end up in a place without Wi-Fi, I needed a simple way to make ASDoc references, like the BlackBerry® Tablet OS SDK for Adobe® AIR® API Reference, available offline.

I was happy to find that one solution is an AIR application called DOC?. You can download it from here. You can add as many ASDoc sources you wish, the app will download and index them locally.

And then you can select the “book” you want and navigate to your heart’s content between the pages:

Of course it is not perfect (I wish I could use it for any type of documentation not only ASDoc) and occasionally you may hit a bug (it seems that a big documentat takes a lot of time to index). But for me, it is just perfect! Big kudos to Jeroen Beckers and Michiel Vancoillie, the creators of this nice little app. And, at the same time, this application illustrates perfectly the power of AIR and Flex. Well done Jeroen and Michiel.

If you plan to create applications for PlayBook using the BlackBerry Tablet OS SDK for Adobe AIR then you’ll be happy to learn that the support for lists is quite extensive. If you look at the components from the qnx.ui.picker and qnx.ui.listClasses you will find nine UI components:

1. List
2. RoundList
3. ScrollPane
4. SectionList
5. TileList
6. SectionTileList
7. DropDown
8. PickerList
9. Picker

In this post I will discuss each one of these components so you can get a sense of how to use them and when. I strongly believe that you need good ‘List’ components if you want to create great mobile applications. Lists represent one of the most important mean you have to deal with the small size of tablet/phone screens.

Data Provider

All these components (except ScrollPane) use a data provider in order to set the data used for displaying the items. For List, RoundList, TileList, DropDown, Picker, and PickerList you will use the qnx.ui.data.DataProvider class. Typically you wrap an Array into a DataProvider. For example:

var arr:Array = new Array();
arr.push("item 1");
arr.push("item 2");
var dp:DataProvider = new DataProvider(arr);
myRoundList.dataProvider = dp;

SectionList and SectionTileList use an instance of qnx.ui.data.SectionDataProvider for setting the data.

Dealing with Item Selection

When you want to do something once an item (or multiple items) is selected, usually you have to register an event listener for flash.events.Event.SELECT or qnx.ui.events.ListEvent.ITEM_CLICKED.

For List, PickerList, SectionList, SectionTileList, TileList, and RoundList you will do something like this:

list.addEventListener(ListEvent.ITEM_CLICKED, onSelected, false, 0, true);

private function onSelected(e:ListEvent):void {
    trace(e.index); //selected item index
    trace(e.section); //selected section for SectionList and SectionTileList
}

For DropDown you will do:

list.addEventListener(Event.SELECT, onDropDownSelection, false, 0, true);

private function onDropDownSelection(e:Event):void {
    //retrieve the selected item index
    trace((e.target as DropDown).selectedIndex);
}

For Picker you want to listen for the Event.CLOSE event. Usually, you use Picker with at least two data providers and if you listen for the Event.CLOSE event, you can check the selectedItems property of the Picker to see what was selected.

List

This is the most basic list you can use. It allows you to set single selection, multiple selection, or no selection. The default skin for all lists looks for the label property for each item you supplied in the dataProvider property. If you don’t have a label property in your data, then you have to create a custom renderer and use the list.setSkin(SkinName) method to set it. Otherwise nothing will appear in your list.

var arr:Array = [
        {label: "List"}
        {label: "RoundList"}
        {label: "ScrollPane"}
        {label: "SectionList"}
    ];
var list:List = new List();
list.dataProvider = new DataProvider(arr);
list.selectionMode = ListSelectionMode.SINGLE;
list.addEventListener(ListEvent.ITEM_CLICKED, onItemSelected, false, 0, true);

RoundList

A RoundList is pretty much a List that continues to be scrollable after you reach the first/last element by displaying the same elements once again. In the image below you can see a RoundList that has 10 items; once you passed the 10th item, you will see the first items (1, 2, 3, 4).

Here is a snippet of code:

var list:RoundList = new RoundList();
list.dataProvider = new DataProvider(arr);
list.rowHeight = 30;
//set width & height; if not nothing will be rendered.
list.width = 100;
list.height = 300;
list.addEventListener(ListEvent.ITEM_CLICKED, onSelected, false, 0, true);

ScrollPane

ScrollPane components let you set a view port over a component. In the code example below I create an image, create a ScrollPane with the width/height smaller than the image, and then set the image as the ScrollPane content. You can control the direction of the scrolling (Horizontal/Vertical/Both).

var img:Image = new Image();
img.setImage("assets/map.png");

var pane:ScrollPane = new ScrollPane();
pane.x = 30;
pane.y = 30;
pane.width = 300;
pane.height =  300;
pane.scrollDirection = ScrollDirection.BOTH;
pane.setScrollContent(img);

As of writing this post, both in PlayBook Simulator and Flash Builder simulator the ScrollPane doesn’t seem to work as advertised. I wasn’t able to scroll the content.

SectionList

You will find SectionList quite useful when dealing with large collections of data that can be grouped by some criteria. For example a contact list can be grouped by the first letter or a play list could be grouped by the artist name. The list will be renderered with sections and each section will have a number of items.

You can control the section header row height and the item row height. You can also set a custom skin for the header or item. The only trick when using section lists is building the data provider because this list uses SectionDataProvider instead of DataProvider. Here is an example:

//create the data provider
var data:ISectionDataProvider = new SectionDataProvider();
//create 3 sections
var s1:Object = new Object();
s1.label = "Section 1";
var s2:Object = new Object();
s2.label = "Section 2";
var s3:Object = new Object();
s3.label = "Section 2";
//add the sections
data.addItem(s1);
data.addItem(s2);
data.addItem(s3);
//add items to each section
for (var i:int = 0; i < 5; i++) {
	data.addChildToItem({label: 1 + i}, s1);
	data.addChildToItem({label: 11 + i}, s2);
	data.addChildToItem({label: 21 + i}, s3);
}

As you see you have two steps: one for adding a section (data.addItem(section)) and one for adding an item to a section (data.addChildToItem(item, section)).

And here is an example of how to create a list and handle item selection:

var list:SectionList = new SectionList();
list.dataProvider = createSectionDataProvider();
list.selectionMode = ListSelectionMode.SINGLE;
list.width = 200;
list.height = 500;
list.headerHeight = 50;
list.rowHeight = 30;
list.setHeaderSkin(CustomHeader); //set a custom header skin
list.addEventListener(ListEvent.ITEM_CLICKED, onItem, false, 0, true);

private function onItem(e:ListEvent):void {
	trace(e.section);
	trace(e.index);
	var d:ISectionDataProvider = (e.target as SectionList).dataProvider as ISectionDataProvider;
	//retrieve the current selected section
	var tmp:Object = d.getItemAt(e.section);
	//retrieve the current selected item
	var item:Object = d.getChildInItemAt(tmp, e.index);
}

TileList

You use TileList to display more than one item on a row. You do so by using the columnCount property. Here is an example:

var list:TileList = new TileList();
//create a data provider with 1 to 10 numbers
list.dataProvider = createDataProvider();
list.width = 300;
list.height = 200;
//set 3 cells on a row
list.columnCount = 3;
list.cellPadding = 1;
list.selectionMode = ListSelectionMode.SINGLE;
list.addEventListener(ListEvent.ITEM_CLICKED, onItem, false, 0, true);

This code will render a list that looks like this:

SectionTileList

SectionTileList is a combination of TileList and SectionList – no big surprise is it? This means you create SectionDataProvider the same way as with SectionList and you use the columnCount property to set the number of items on a row as with TileList.

Here is an example:

var list:SectionTileList = new SectionTileList();
list.dataProvider = createSectionDataProvider();
list.columnCount = 3;
list.cellPadding = 1;
list.selectionMode = ListSelectionMode.SINGLE;
list.width = 300;
list.height = 500;
list.addEventListener(ListEvent.ITEM_CLICKED, onItem, false, 0, true);

private function onItem(e:ListEvent):void {
	trace(e.section);
	trace(e.index);
	var d:ISectionDataProvider = (e.target as SectionList).dataProvider as ISectionDataProvider;
	//retrieve the current selected section
	var tmp:Object = d.getItemAt(e.section);
	//retrieve the current selected item
	var item:Object = d.getChildInItemAt(tmp, e.index);
}

DropDown

DropDown list displays the currently selected item and when clicked, it expands and lets you scroll through the items and make a selection. Here you can see a DropDown in its normal and expanded state.

You use the rowCount property to set how many rows are displayed when the component is expanded. Code example:

var list:DropDown = new DropDown();
list.rowHeight = 45;
list.rowCount=3;
list.width = 250;
list.dataProvider = createDataProvider();
//3 events: Event.OPEN / CLOSE / SELECT
list.addEventListener(Event.SELECT, onDropDownSelection, false, 0, true);

private function onDropDownSelection(e:Event):void {
	trace((e.target as DropDown).selectedIndex);
}

PickerList

PickerList is used by the Picker component (though you can use it too). It offers the same behavior as the RoundList (you can’t reach the end of the list; the elements will be repeated forever). The difference is that by default, it displays the currently selected item, and only when pressed it opens and displays more items. In the expanded state it uses a mask with variable Alpha to give some sense of depth.

Code example:

var list:PickerList = new PickerList();
list.dataProvider = createDataProvider();
list.selectionMode = ListSelectionMode.SINGLE;
list.width = 50;
list.height = 40;
list.opaqueBackground = 0xFFFFFF;
//you can listen for Event.SELECT
list.addEventListener(ListEvent.ITEM_CLICKED, onSelected, false, 0, true);

Picker

A Picker uses a number of PickerList. Picker has two states: a compact one for displaying the current selection and an expanded one for making the selection. Here is an example with the two states:

It is quite useful for situations when you want to present related lists together; like in the picture above where you want to provide a way for setting the date. Or you want to provide a way for selecting the time.

As in the case of the SectionList/SectionTileList the trickiest part is to create the data provider. Basically for each PickerList you want you need a qnx.ui.data.DataProvider object. So, for creating the data provider used by the Picker (it uses three PickerList components) from the image above you’d do something like this:

private function createPickerDataProvider():IDataProvider {
	// Create three arrays to handle days, months, years.
	var day:Array = new Array();
	var month:Array = new Array();
	var year:Array = new Array();

	// Populate the month
	for (var i:int=1; i<32; i++) {
		day.push({label: i.toString()});
	}

	// Populate and month array and create the month
	month.push({label: "January"});
	month.push({label: "February"});
	month.push({label: "March"});
	month.push({label: "April"});
	month.push({label: "May"});
	month.push({label: "June"});
	month.push({label: "July"});
	month.push({label: "August"});
	month.push({label: "September"});
	month.push({label: "October"});
	month.push({label: "November"});
	month.push({label: "December"});

	// Create the year DataProvider
	for (var i:int=1950; i<2012; i++) {
		year.push({label: i.toString()});
	}

	// create the data provider
	var data:Array = new Array();
	data.push(new DataProvider(day));
	data.push(new DataProvider(month));
	data.push(new DataProvider(year));
	return new DataProvider(data);
}

You create a Picker like this:

var list:Picker = new Picker();
list.dataProvider = createPickerDataProvider();
list.width = 400;
list.height = 50;
//you can set the width for each section
list.setListWidth(0, 100);
list.setListWidth(1, 200);
list.setListWidth(2, 100);
list.selectedIndices = [1,1,45];
list.addEventListener(Event.SELECT, onPickerSelection, false, 0, true);
list.addEventListener(Event.OPEN, onPickerSelection, false, 0, true);
list.addEventListener(Event.CLOSE, onPickerSelection, false, 0, true);

private function onPickerSelection(e:Event):void {
       trace(e.type);
       if (e.type == Event.CLOSE) {
           var p:Picker = (e.target as Picker);
           for (var i:int = 0; i < p.selectedItems.length; i++) {
                trace("Picker.selectedItems " + p.selectedItems[i].label);
            }
            trace("Picker.selectedIndices " + p.selectedIndices);
            trace("Picker.data " + p.data);
       }
}

If you want to take an action when the user has finished making a selection, you should register an event listener for the Event.CLOSE event. This is triggered when the user taps outside the component boundaries and makes the component return to the compact state.

Skinning Lists

There aren’t many resources for skinning list components. And so far I haven’t played enough to talk about this. However, there is one thing I want to say about lists. In general they expect to be fed them with a data provider of objects that have a label property.

If you want to use an array of Strings as the source for the data provider you have to create a custom CellRenderer:

package org.corlan.renderers {
	import qnx.ui.listClasses.AlternatingCellRenderer;

	public class CellRenderer extends qnx.ui.listClasses.AlternatingCellRenderer {

		public function CellRenderer() {
			super();
		}

		override public function set data(value:Object):void {
			super.data = value;
			setLabel(value as String);
		}

	}
}

You can use this renderer like this:

var optionsArr:Array = ["item 1", "item 2", "item 3"];

var list:List = new List();
list.setSkin(CellRenderer);
list.dataProvider = new DataProvider(optionsArr);

Download

You can download a Flash Builder project with examples for all these components from here.

Last year, I made two Android applications that connect to desktop apps: AndroidPictures (you can see the phone’s camera roll on a desktop) and Remote Control for desktop MP3 player (you can control an AIR desktop MP3 player from your mobile phone). At that time, Flex “Hero” wasn’t available, so last week I decided to rewrite these apps, this time using the mobile components from Flex “Hero”.

The reason I rewrote them with Flex “Hero” is quite simple: to see if it simpler or more complicated compared to plain Flex. And not surprisingly it is much simpler with Flex “Hero”. Actually I like the Views and ViewNavigator so much, that I’d love to have them available for desktop applications too.

One note on how these apps connect to each other: I used the new Peer 2 Peer capabilities from AIR/Flash Player. This part is extremely simple actually and if you have a look at the source code you’ll find that I wrap this functionality in a library that is used in both projects.

You can download them from here:

• AndroidMedia – APK file / source code / desktop app
• MP3RemoteControl – APK file / source code / desktop app

In a previous post I showed you how you can use  QNX UI components in a Flex Mobile project that uses Flex RPC services (REST Style Services/Web Services/Remoting). What if you want to use Flex RPC services in an ActionScript Mobile Project? It isn’t possible, isn’t it? Wrong, you can make it work with a little bit of extra work.

This works because, as my colleague Renaun Erickson said, Flex != MXML. In other words if you add the right parts from the Flex framework to your project you will be able to reuse these Flex services. Though, you won’t be able to write MXML code. Everything will be just ActionScript code.

Once you created a new ActionScript Mobile Project (these project supports Android and BlackBerry Tablet OS as target platforms) there are two steps you have to complete to enable Flex RPC support.

Step 1. Right-click on the project name and choose Properties. Then click on the ActionScript Build Path entry. You will notice there are already some parts of the Flex framework added.

Expand the first entry (Flex Hero) and add these two SWCs: framework.swc and rpc.swc (on my computer these SWCs are in /Applications/AdobeBeta/Adobe Flash Builder Burrito/sdks/4.5.0/frameworks/libs). Then you have to add the bundles for the default locale. So, this time, click on the “Add SWC Folder…” button and add the locale folder from Flex SDK (on my computer this is the path: /Applications/AdobeBeta/Adobe Flash Builder Burrito/sdks/4.5.0/frameworks/locale/en_US).

Once you apply these changes your project should compile with no errors.

Step 2. You have to do some of the work the Flex compiler does for you automatically when you work with Flex projects. Remember, this project is an ActionScript project. You have to register a number of classes used by the AMF3 protocol. If you don’t do this, HTTPService will work, but when you try to use RemoteObject (this method uses AMF3 for encoding the messages) you will get this error:

TypeError: Error #1034: Type Coercion failed: cannot convert Object@3779ee1 to mx.messaging.messages.ErrorMessage.

Fortunately, this is an easy fix. You can register the classes needed at the top of your ActionScript application (in my project this class is named PlaybookRPC):

[SWF(height="600",width="1024")]
public class PlaybookRPC extends Sprite {

   registerClassAlias("flex.messaging.messages.RemotingMessage", RemotingMessage);
   registerClassAlias("flex.messaging.messages.CommandMessage",CommandMessage);
   registerClassAlias("flex.messaging.messages.AcknowledgeMessage",
           AcknowledgeMessage);
   registerClassAlias("flex.messaging.messages.ErrorMessage", ErrorMessage);
   registerClassAlias("DSC", CommandMessageExt);
   registerClassAlias("DSK", AcknowledgeMessageExt);
   registerClassAlias("flex.messaging.io.ArrayList", ArrayList);
   registerClassAlias("flex.messaging.config.ConfigMap", ConfigMap);
   registerClassAlias("flex.messaging.io.ArrayCollection", ArrayCollection);
   registerClassAlias("flex.messaging.io.ObjectProxy", ObjectProxy);

   // You may want to register pub/sub and other rpc message types too...
   registerClassAlias("flex.messaging.messages.HTTPMessage", HTTPRequestMessage);
   registerClassAlias("flex.messaging.messages.SOAPMessage", SOAPMessage);
   registerClassAlias("flex.messaging.messages.AsyncMessage", AsyncMessage);
   registerClassAlias("DSA", AsyncMessageExt);
   registerClassAlias("flex.messaging.messages.MessagePerformanceInfo",
           MessagePerformanceInfo);

   public function PlaybookRPC() {
      super();

      // support autoOrients
      stage.align = StageAlign.TOP_LEFT;
      stage.scaleMode = StageScaleMode.NO_SCALE;

   }
}

Now, you are ready to use Flex RPC services in this project. You can write something along these lines if you want to use Remoting:

var remoting:mx.rpc.remoting.RemoteObject = new RemoteObject("AuthorsService");
remoting.source = "AuthorsService";
remoting.endpoint = BASE_URL + "remoting/gateway.php";
var token:AsyncToken = remoting.getData();
var responder:Responder = new Responder(onResult, onFault);
token.addResponder(responder);

You can download my project from here (server side services are not included). I haven’t tried Web Services (WSDL/SOAP) or Messaging (Producer/Consumer) but I don’t see any reason for them not to work.

If you are an experienced developer, it’s easy to connect your Flex applications to almost everything. You can use REST Style services, remoting (Remote Procedure Call), and Web Services (WSDL/SOAP). Using a server library like BlazeDS you can use messaging (Producer/Consumer) as well.

What about using these methods with an AIR project for PlayBook created using the BlackBerry Tablet OS SDK for Adobe AIR and the QNX UI library? In this post I will show you how you can create a PlayBook application using QNX components for the UI and HTTPService/RemoteObject for reading data from a server.

Note: In theory, it should be possible to use HTTPService, RemoteObject, and WebService even in a Mobile ActionScript project. I will write another post on this matter. See this post on how to do it.

Prerequisites

If you want to try this tutorial you will need to have Flash Builder “Hero” installed and enabled for PlayBook development. See this post for more info on this topic.

Creating the application

The first step is to create a Flex Mobile Project. Choose File > New > Flex Mobile Project, enter a name for your project, and click the Next button. In the second page of the wizard make sure you select BlackBerry Tablet OS and Blank for “Application template”.

Once the project is created, you have to enable it for using QNX UI components. To do this, right-click on the project name and choose Properties. Then select the Flex Build Packaging > BlackBerry Tablet OS entry and check the “Include BlackBerry Tablet OS libraries in build path” option.

Now, you are ready to create the application UI using QNX UI components. Open the MXML file if it isn’t already opened (mine is called MobileRemoting.mxml).

Now, it is time to create the application UI. I want to have a radio button group to choose from Remoting/HTTPService, a label, and a list for displaying the results. The finished result will look like this:

I created a function named createUI() and I registered this function for the ApplicationComplete event. Inside this function I created the UI using the QNX building blocks, just as you would do in a Mobile ActionScript Project.

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark"
    applicationComplete="createUI()" backgroundColor="0xffffff">

   <fx:Script>
      <![CDATA[
private function createUI():void {
    this.stage.align = StageAlign.TOP_LEFT;
    this.stage.scaleMode = StageScaleMode.NO_SCALE;

    base = new Container();
    base.flow = ContainerFlow.HORIZONTAL;

    var bottom:Container = new Container();
    bottom.size = 100;
    bottom.sizeUnit = SizeUnit.PERCENT;

    var header:Container = new Container();
    header.size = 60;
    header.sizeUnit = SizeUnit.PIXELS;
    header.containment = Containment.DOCK_TOP;
    header.flow = ContainerFlow.HORIZONTAL;
    header.opaqueBackground = 0x999999;

    var headerLeft:Container = new Container();
    headerLeft.align = ContainerAlign.NEAR;
    headerLeft.containment = Containment.BACKGROUND;

    var headerRight:Container = new Container();
    headerRight.flow = ContainerFlow.HORIZONTAL;
    headerRight.align = ContainerAlign.FAR;
    headerRight.containment = Containment.CONTAINED;

    var label:Label = new Label();
    label.format.bold = true;
    label.format.color = 0x0000ff;
    label.width = 170;
    label.text = " Read Data Using:";

    var spacer:Spacer = new Spacer();
    spacer.size = 50;
    spacer.sizeUnit = SizeUnit.PERCENT;

    var rb1:RadioButton = new RadioButton();
    rb1.size = 100;
    rb1.sizeUnit = SizeUnit.PERCENT;
    rb1.sizeMode = SizeMode.BOTH;
    rb1.groupname = "group1";
    rb1.label = METHOD_1;
    rb1.selected = true;
    rb1.addEventListener(MouseEvent.CLICK, onMethodSelection);

    var rb2:RadioButton = new RadioButton();
    rb2.size = 100;
    rb2.sizeUnit = SizeUnit.PERCENT;
    rb2.sizeMode = SizeMode.BOTH;
    rb2.groupname = "group1";
    rb2.label = METHOD_2;
    rb2.addEventListener(MouseEvent.CLICK, onMethodSelection);

    headerLeft.addChild(spacer);
    headerLeft.addChild(label);
    headerRight.addChild(new Spacer());
    headerRight.addChild(rb1);
    headerRight.addChild(rb2);
    header.addChild(headerLeft)
    header.addChild(headerRight)

    list = new List();
    list.setSkin(CellRenderer);
    list.containment = Containment.BACKGROUND;

    bottom.addChild(list);
    base.addChild(header);
    base.addChild(bottom);
    this.stage.addChild(base);

    base.setSize(stage.stageWidth,stage.stageHeight);
    //read the data using the current selected method
    getData();
}

 ]]>
 </fx:Script>

Once the createUI() function is executed, the application should have the entire UI in place. The last line of this function calls a method named getData(). This is where the HTTPService and RemoteObject classes will be used. When you use these classes in Flex, you usually use the mx.rpc.http.mxml.HTTPService and mx.rpc.remoting.mxml.RemoteObject. But these objects are meant to be used in MXML, so what you’ll need is the super classes of these (which can be used in ActionScript): mx.rpc.remoting.RemoteObject and mx.rpc.http.HTTPService.

Now, it is pretty straightforward to read data from the server (there is some code for handling the switch between RemoteObject/HTTPService which I haven’t include it in snippet below):

private function getData():void {
     //HTTP Service
     if (method == METHOD_1) {
        if (!http) {
           http = new HTTPService();
           http.method = "GET"; //this is the default method anyway
           http.url = BASE_URL + "rest/index.php";
           http.resultFormat = HTTPService.RESULT_FORMAT_OBJECT;
           http.addEventListener(FaultEvent.FAULT, onFault);
           http.addEventListener(ResultEvent.RESULT, onResult);
        }
        var param:Object = {what: "getAuthors"};
        http.send(param);
    //remoting
    } else {
        if (!remoting) {
           remoting = new RemoteObject("AuthorsService");
           remoting.source = "AuthorsService";
           remoting.endpoint = BASE_URL + "remoting/gateway.php";
        }
        var token:AsyncToken = remoting.getData();
        var responder:mx.rpc.Responder = new mx.rpc.Responder(onResult, onFault);
        token.addResponder(responder);
    }
 }

I used this project to play a little bit with QNX lists, more precisely with CellRenderer. The default renderer looks for a property “label” as the source for the text. My data structure is different, depending on the method used to read the data. I created a new renderer by extending AlternatingCellRenderer:

package org.corlan.renderers {
    import qnx.ui.listClasses.AlternatingCellRenderer;  

    public class CellRenderer extends qnx.ui.listClasses.AlternatingCellRenderer {
        public function CellRenderer() {    
            super();
        }

        override public function set data(value:Object):void {  
            super.data = value;
            var str:String = "";
            if (data["id_aut"])
                str = data.fname_aut + " " + data.lname_aut + " (" + data.id_aut + ")";
            else
                str = data.first + " " + data.last;
            setLabel(str);
        }
    }
}

And I set this custom renderer by calling the setSkin() method on the list. For the complete code, please have a look at the Download section.

Conclusions

With all these new devices that keep coming, it is a good idea to be able to reuse the code you wrote for other applications as much as possible from. If you’ve created Flex projects using Remoting/REST style services/Web Services and you need the same data in a mobile project for PlayBook then you now know one way to do it. I will write another post about how to use the same methods in a mobile ActionScript project.

Download

You can download the project archive file from here.

Yesterday, RIM released version 0.9.2 of their BlackBerry Tablet OS SDK for Adobe AIR. This was just one of the bits announced yesterday – my fellow evangelist, Renaun Erickson, already wrote about this.

So what’s new for AIR development for PlayBook? Here is a list of what caught my eye:

• New tablet simulator. If you don’t have a physical device you can use this simulator (this is just a virtual machine) to test and debug your application. This new version brings support for screen orientation (you just swipe up from the bottom-right corner to rotate the screen). You enable the support for screen orientation support by adding <autoOrients>true</autoOrients> in the application descriptor file.
• Application control permissions. If you want to use the camera, then you have to explicitly opt in by adding <permission>use_camera</permission> in the blackberry-tablet.xml descriptor file.
• Support for splash screens, SSH connection to the tablet simulator, and development on Linux.
• New APIs and .
• A number of bugs fixed, like the infamous: “Dialog boxes moved when users typed text in a text input field”.

Updating your environment to 0.9.2

If you want to try all these new goodies the first thing is to go here and download the BlackBerry Tablet OS SDK Beta3 for Adobe AIR and BlackBerry PlayBook Simulator Beta2 – make sure you select the versions for your operating system.

If you have Flash Builder 4 or Flash Builder “Burrito” (the preview version we’ve made available last year at Adobe MAX) then you can enable PlayBook development for your Flash Builder installation. On my machine I have installed “Burrito” and the previous version (0.9.1) of the BlackBerry Tablet OS SDK. To update the version I just unzipped the BlackBerryTabletSDK-Air-Installer-0.9.2-Mac.zip file,  started the installer, and followed the steps (specifying the “Burrito” location, AIR 2.5 SDK, and so on).

Once the installation has finished, if you, open Flash Builder, go to “About Flash Builder”, and click the “Installation Details” button. You should see an entry for BlackBerry Tablet OS Platform features with a version like 0.9.2.XXX.

Although you could use the previous simulator version, I recommend upgrading the BlackBerry PlayBook simulator to the most recent version. So grab the BlackBerryPlayBookSimulator 2 for your operating system and start the installation process.

I used the default options and after the installation finished on my Mac, I got a new ISO file inside of my user folder: BlackBerryPlayBookSimulator-0.9.2.iso. The next step is to configure a new virtual machine using this file. So I started VMWare Fusion and chose New Virtual Machine. This will start a wizard. On the first page, just click the “Continue without disk” button.

On the second page of the wizard choose the “Use operating system installation disk image file” option, select the BlackBerryPlayBookSimulator-0.9.2.iso file from your hard disk, and then click Continue.

In the third step just make sure you’ve selected Other for both options (Operating System and Version) and click Continue. On the last step of the wizard if you click the “Customize Settings” button you can set up the amount of memory and support for 3D (I advise you to do so). Also you can change the name of the virtual machine (by default it will be named “Other” or “Other 2″).

The next step is to start this new virtual machine. After a couple of seconds you will be presented with the screen below – type Y and press Enter (don’t worry, this is not deleting your files, it is just preparing the virtual machine files). This process will take some time, so be patient. After a couple more minutes you’ll be prompted to press Enter to reboot the virtual machine.

Once the virtual machine has rebooted (this process that can take couple of minutes too) you are ready to use it.

Before being able to deploy applications from Flash Builder, you have to set up the device password, enable development mode, and retrieve the virtual machine IP address (don’t worry this is a one-time operation). Click the top-left icon and choose Security from the left list on the left. First set up a password, and then in the same screen enable development mode. You’ll be asked to enter a password, so enter the password you’ve just provided in the previous step.

Finally, choose the About entry from the left menu and scroll down to retrieve the VMWare Network Address. You’ll use this information to configure the run configuration in Flash Builder.

If you want to test screen orientation just swipe with your mouse cursor (holding the left button) from the bottom-right corner towards the center of the screen.

If you want to test the whole setup (Flash Builder and Simulator) the easiest way is to create the PlayBook example project (choose File > New > Project expand Examples > BlackBerry Tablet OS Examples, and select the BlackBerry Tablet OS Example AIR Project).

Once you have the HelloWorld project created, choose the “Run Configurations…” option from the Run icon. This will open a configuration window. Choose Mobile Application from the left list and then click the “New launch configuration” icon (from the top-left). Then select the HelloWorld project (if it isn’t already selected), choose the “On device” option, and fill in the device IP address and password you set up earlier.

If you click Run you should have the application compiled, installed on the device, and opened in a matter of seconds. Now you have a working development environment for PlayBook AIR development.

The Flex framework “Hero” makes the task of creating mobile applications for BlackBerry Tablet OS, Android, and soon iOS extremely simple. I think that one of the best looking apps for Android is MAX Companion 2010 and please bear in mind that this app was created using an early build of Flex “Hero”.

This is a reasonably complex application with lots of screens and social integration (Twitter) and yet on my Nexus One and Samsung Galaxy Tab it still works great. This is exactly where the Flex framework can shine on mobile devices: fast and easy development of applications that can connect to virtually anything (web services, REST services, RPC).

In this article I will talk about Flex Mobile Views and ViewNavigator. If you want to use Flex “Hero” to create mobile apps you need to understand how these components work.

Oh and one more thing, if you want to try this yourself you’ll need the Flash Builder “Burrito”. You can download it from here.

Screen Metaphor

Before talking about Flex mobile components let’s talk a little bit about a concept called screen metaphor. This is basically a neat solution for a very big problem any developer encounters when developing for mobile devices: screen real estate.

On a desktop computer we have enough resolution to fit all the information we want on the screen. By using hierarchical menus and pop-up windows we can push a lot to the screen. Compared to this, a smartphone screen feels (almost) like a stamp. Besides resolution, pixel density plays an important role  – my Nexus one has a resolution of 480X800 pixels and 254 pixels per inch. This means that you have to enlarge the text roughly two to four times compared to the same resolution on a desktop/laptop screen when building apps for mobile devices. Thus you end up with less space to display information.

Using the screen metaphor you can split the information/UI of your application on multiple screens. For example when a user wants to see details for a particular session (see the above pictures of MAX Companion 2010 app) another screen is presented. When he wants to go back to the session list, the previous screen is presented.

Elegant though it might be, the screen metaphor is not rocket science. However there are some things to be considered such as:

• memory management – pushing dozens of screens can eat up all the memory available on the device
• transitions from one screen to another – those nice effects that help you create an application like a professional UX Designer
• passing data from one screen to another
• preserving application state when the OS choose to close it
• integration with hardware buttons – for example using the Back button of the phone to navigate to the previous screen

Fortunately, the Flex framework has built-in support for the screen metaphor so you don’t have to reinvent the wheel.

Flex Mobile Project

When you install Flash Builder “Burrito” you will notice that there are two new types of projects related to mobile: Flex Mobile Project and ActionScript Mobile Project.

If you want to use Flex support for mobile development you should choose Flex Mobile Project and on the second page of the wizard make sure you select Mobile Application (this option makes a project that has uses Flex built-in support for the screen metaphor). As you can see in the screen capture below, you can choose to target both BlackBerry Tablet OS and Google Android platforms or just one of these platforms (as I said before we are working to extend the reach of the Flex framework to iOS – sometime in 2011).

Once you click Finish you will have a project structured like this:

Compared to a desktop AIR project you have one extra file: views/MobileProjectHome.mxml. The other two files are the “usual suspects”: the main application file (MobileProject.mxml) and the application descriptor file (MobileProject-app.xml). So what you have here is a skeleton for a Flex mobile application that has a single screen/View for now: MobileProjectHome.mxml. And if you open the main application file (MobileProject.mxml) you’ll see that on the MobileApplication tag there is an attribute named firstView and its value is set to views.MobileProjectHome – this is how you set the default screen for your mobile app.

Now, I’d like to step back and tell you about the two options you have when building Flex mobile apps. The first one is to use MobileApplication like in the project above. However if you work on an application that has lots of screens, it might be a good idea to use TabbedMobileApplication. As the name suggests you’ll have an application with support for tabs and for each tab you can have a stack of screens/Views (for each tab you can define the default/first screen). Here is an example: