The Apes Corner

Developing mobile applications using Gear episode 5: Display a splash screen

2009-02-03T15:51:00.010+01:00

During the first phase of a MIDlet's life, it's common to find a lot of setup code used to initialize resources, data structures, user interfaces and anything else will be required. In this case, it's a best practice to display a splash screen to inform the user that the application is not frozen but is starting up. With the release of version 1.2.0 of Gear Java Mobile Framework, we've included a consistent yet customizable implementation for this feature.

1 How to achieve it ?

To properly setup Gear SplashScreen, all you have to do is create some keys inside the JAD file:

"SplashScreenImage:" -> contains a string with the path to the desired background image
"SplashScreenText:" -> contains a string with the desired text

If you are developing your application inside Eclipse with MTJ plugin (former EclipseME), you can easily achieve this by opening the Application Descriptor tab and "Add" the two key-value entries.

If your development environment is a different one, you have to manually insert those keys inside your application's JAD file.

As long as there is at least one of the two keys inside your JAD file, Gear will display the SplashScreen, so if you don't want it, simply don't specify anything.

2 Writing initialization code

Now that the SplashScreen is enabled, all you have to do is to override a single method inside your MIDlet

protected void onMidletInitializationComplete()

and fill it with your custom initializzation logic. We encourage users to follow this practice to put setup code inside this function rather than into the GearMIDlet constructor so they can take advantage from SplashScreen avoiding user interface freezes.

Here is an example of a possible implementation:

protected void onMidletInitializationComplete() {
// Call some custom initializzation methods
initDatabase();
doSomeHeavyDutyWork();
  initUserInterface();
// ... and finally show the user the UI
EventManager.getInstance().enqueueEvent(new DisplayWidget(this, LoginForm.class));
}

3 The result

Gear's SplashScreen can display an image background, text and comes with an animated throbber centered vertically and anchored to the bottom of the screen. This is a possible result obtained with it:

Unfortunately this screen-shot is just a static image and you can't actually see the spinning animation of the throbber.

Developing mobile applications using Gear episode 4: On-device debug

2009-02-02T10:26:00.014+01:00

Last version of Gear framework (1.2) introduced a new message logging system.
By using Gear logger it's now possible to trace various types of application messages and print out the resulting log on different output types, including device screen.

1. New library debug release
Introducing a logging system in the framework brought a big advantage but leaded also to a performance issue: most of the times the whole logger is useless in the final release of an application and the operations required by the logger to do its work may "steal" precious resources to the rest of the application.
So, starting from version 1.2 we dediced to make two separate releases of the library's JAR: one including the whole logging sub-system and one including only the method stubs.
The two packages are fully compatible, so you can switch anytime between them.

2. Logger structure and usage
The base class of the logging sub-system is Logger. Through this class it is possible to select what kind of messages have to be printed

// Tells the Logger to print gear system level messages
Logger.logSystemMessages(true);

and select the desired output destination

// Tells the Logger to print his messages on to the Standart Output
Logger.out = new StandardOutput();

By default the Logger class is created with NullLogger set as output destination (it doesn't print any message) and logs just user messages (printed by the programmer inside code) and exceptions (any exception printed within code using Logger.out.println(Exception)).
Gear provides three implementation for LogOutput:

NullLogger : every method is implemented with an empty body and thus no message will be traced.
StandardOutput : prints messages on the Standard Output, usually the development console.
GWConsole : displays a graphic console directly on device's screen and prints messages on it.

For example, to print a log message on device's screen, the following code should be used:

Logger.out = new GWConsole();
Logger.logUserMessages(true);
Logger.out.println("Log message");

Note that the second line is not compulsory since user messages logging is enabled by default.

3. Make your own LogOutput
If you have special logging requirements, such as redirecting logs to a remote server, you can write your own custom output target and then use it with Gear's Logger. The class must implement LogOutput interface and should extend the InternalLogger abstract class.
The class structure should look like this one:

public class RemoteLogger implements LogOutput
                  extends InternalLogger {

// Instance fields ...
// ...

public void println(int logLine) {
 if (Logger.isUserMessagsLogged()){
           // Network communication ...
 }
}

public void println(double logLine) {
 if (Logger.isUserMessagsLogged()){
           // Network communication ...
 }
}

public void println(String logLine) {
 if (Logger.isUserMessagsLogged()){
           // Network communication ...
 }
}

public void println(Exception logLine, Object sender) {
 if (Logger.isExceptionsLogged()){
           // Network communication ...
 }
}

public void println(Exception logLine,
           Object sender, String methodName) {
 if (Logger.isExceptionsLogged()){
 }
}

protected void printSystemMessage(String message) {
 if (Logger.isSystemMessagsLogged()){
           // Network communication ...
 }
}

}

4. Conclusions
Gear's logging system allows keeping track of application activities for debug, statistical or any other purpose, it provides a simple system to filter messages and handle different output targets. In addition to this, the overhead introduced by the Logger system can be stripped without changing any line of code, just by switching from Gear's debug JAR to the release one.

Developing mobile applications using Gear episode 7: Work with EventManager and async messages

2009-01-29T10:59:00.018+01:00

With this tutorial we're going to learn the basic concepts behind EventManager class and how we can send asynchronous messages across our Midlet with Gear Java Mobile Framework. To better understand this guide, we suggest you to read at least this post about configuring Eclipse and to download Gear's latest release (1.2.0).

1.0 EventManager:

Working with Gear in most cases requires to use EventManager class to dispatch asynchronous messages to other Objects within your MIDlet. It's implemented following the Singleton pattern so there will be only one instance of it during execution time and you can reference it wherever you want inside your code via public method getInstance(). Let's go on how to use this class and its methods.

1.1 Events

Every message you want to be forwarded through EventManager must derive from the abstract class Event. It contains the basic structure and methods to keep track of the sending Object and category. Here's an example:

public class ConnectionClosed extends Event {
// Public constructor with empty EventArgs object
public HideMidlet(Object sender){
 super(sender);
}
// Public constructor with user defined EventArgs
public HideMidlet(Object sender, ConnectionClosedEventArgs eventArgs){
        super(sender, eventArgs);
// Override of getCagegory method to return the desired type
public Category getCategory() {
 return Category.APPLICATION;
}
}

1.2 EventArg

As you noticed in last example, you can assign some custom defined arguments to an event to pass on additional data to the receiving Object. To achieve this, you have to extend EventArg class and implement your own private fields along with proper getter and setters. Here's an example:

public class ConnectionClosedEventArgs extends EventArg {
private ConnectionStatus connectionStatus;

   public ConnectionClosedEventArgs(ConnectionStatus connectionStatus) {
 super();
 this.connectionStatus = connectionStatus;
}

public ConnectionStatus getConnectionStatus() {
 return connectionStatus;
}

where ConnectionStatus is a user defined class containing additional information about the reason for connection termination.

1.3 Dispatch events

This task is pretty simple. Suppose Object A wants to send some message to Object B (we'll see on the next poit how B will actually receive it). All it have to do is to obtain a reference to EventManager and enqueue the desired message, wrapped inside an Event object.

EventManager.getInstance().enqueueEvent(new MyEvent(this))

That's it. In this particular case, we're sending a MyEvnet (which derives from Event class) and we don't have to care about anything else. EventManager will internally manage our request and dispatch it. Notice we passed "this" parameter to the Event constructor to allow a reference of the original sender to be kept.

1.4 Register and receive Events

In order to receive an Event, an Object must first implement an interface named EventHost and thus it's only method

public void notify(Event event);

and secondly register itself to EventManager by calling

public void registerHost(EventHost host, Event.Category category)

where the second argument is one of the categories mentioned before. A class that is registered to at least one Event.Category will be notified of incoming messages. Whenever you need to unregister an Object from EventManager you can call

public void removeHost(EventHost host)

to totally remove it from the queue or

public void removeHost(EventHost host, Event.Category category)

if you just want to stop being notified for a specific category of events.

1.5 Events and GearMIDlet

By default, GearMidlet register itself to APPLICATION and GRAPHICS categories inside its base constructor, but if you need to be aware of more Events or less you can register/unregister from EventManager as seen in previous sections.

2.0 Putting it all together

With all the concepts from previous section, we can now create a GearMidlet with full support for asynchronous messages:


public class GearTouchDemo extends GearMidlet {

protected boolean onDestroy() {
 return true;
}

protected void onPause() {

}

protected void onStart() throws MIDletStateChangeException {
              // Enqueue a request to display MainMenu user interface
 EventManager.getInstance().enqueueEvent(new DisplayWidget(this, MainMenu.class));
}

public class MainMenu extends GWGrid {
public MainMenu(){
 super(2,2);
 addItem("Photo browser", "/icons/c1.png");
 addItem("Drops", "/icons/c2.png");
 addItem("None", "/icons/c3.png");
 addItem("Nothing here", "/icons/c4.png");
 setTitle("Main menu");
 addCommand(CommonCommands.SELECT);
 addCommand(CommonCommands.EXIT);
 setCommandListener(new MainMenuCommandListener());
}

public void itemClicked(ImageItem clickedItem) {
 if (commandListener != null){
  commandListener.commandAction(CommonCommands.SELECT, this);
 }
}

public void selectElement(){
 switch (getSelectedIndex()){
 case 0:
                      // Enqueue a request to display MainMenu user interface
  EventManager.getInstance().enqueueEvent(new DisplayWidget(this, PhotoBrowser.class));
  break;
 case 1:
                      // Enqueue a request to terminate the MIDlet.
  EventManager.getInstance().enqueueEvent(new QuitEvent(this));
  break;
 default:
  displayAlert("Function not implemented");
  break;
 }
}

}

Develop Ogre3D applications using Eclipse on Mac OS X

2009-01-20T12:40:00.020+01:00

This tutorial will lead you trough all the steps required to configure Eclipse for Ogre 3D applications development on Mac OS X.

Requirements
To perform the tasks described in this tutorial it is necessary for you to setup a basic development system including:

Developer tools for Mac OSX (XCode 3.1.2 or later)
Eclipse (3.4 or later) and Eclipse CDT plugin (downloadable from eclipse official update site) or directly Eclipse for C/C++ Developers version
Ogre pre built SDK (1.6 or later)

Application creation
To create your first application start Eclipse and select New -> C++ Project from the File menu.
Now select Hello World C++ Project and give it a name (let's say MyFristOgreApp).

Application configuration
The application is now created, but is not connected in any way to Ogre, thus any ogre specific code, if compiled, would give compilation, link and run-time errors.
To solve this problem you have to include the Ogre framework in your application, and make the project aware of the Ogre and Carbon frameworks position.

Right-click on your project name in the Project Explorer and select Import, then select import from File System.
Browse to the Dependencies directory of the OgreSDK folder, select the subfolders and then import it in the Frameworks subdir for your project.
Now right-click again on your project name in the Project Explorer and select Properties.
Move to C/C++ General -> Paths and Symbols and press the Add button.
Select Frameworks/Ogre.framework/Header directory in you workspace and check Add to all configurations, Add to all languages and Is a workspace path.
Do the same for Frameworks/Cg.framework/Header and Frameworks/include directories.
Press Add again, select /Developer/Headers/FlatCarbon folder and check only Add to all configurations, Add to all languages this time.
Move to Library Paths tab and press Add; again check Add to all configurations, Add to all languages and Is a workspace path and add Framworks/lib/Release directory.
Now select C/C++ Build ->Settings from the tree menu on the left and set the configuration selector to [ All configurations ].
Click on C++ Linker -> Libraries and add ois to Libraries
Finally click on C++ Linker -> Miscellaneous and write -F${CWD}/../Frameworks -framework Ogre -framework Carbon -framework IOKit -framework Cg in the Linker flags text box.

Last bug-fix
Now your IDE is correctly configured but your application will not compile due to an error within the Frameworks/Ogre.framework/Headers/OSX/OgreTimerImp.h file. Edit this file and change the line #include <ogre/OgrePrerequisites.h> to #include <OgrePrerequisites.h>.

Conclusion and last hints
Now this setup will allow you to compile any Ogre based application, however, if you want to work with Ogre official tutorials, you have to go through some further steps:

Import in you application the headers required by the tutorial you are working on (most of the times ExampleApplication.h and ExampleFrameListener.h are required).
You can find them in the Samples directory of your OgreSDK.
Import the Media directory of your OgreSDK into your project's root (this directory contains all the tutorials required textures, models, etc... )
Import the .cfg files from you OgreSDK and modify them to match the path of your Media directory (typically ../Media is good).
Add this command: install -d ${CWD}/Contents/Resources && cp -f ${CWD}/../*.cfg ${CWD}/Contents/Resources to your project's Post-build step (set it in the Build steps tab of the C/C++ Build -> Settings configuration form and remember to do it for all configurations)

ZappOne.tv FAQ

2009-01-19T17:10:00.012+01:00

In this little FAQ I will address some common questions about ZappOne.tv

First things first, what's this thing all about ?

ZappOne.tv is a Rich Web 2.0 Interactive Ajax Enabled Multimedia Videoclip Streaming Internet Application (oh yes and also iSomething).

Said with poorer words, it's a Web application based on a very simple concept: create an enhanced experience with YouTube.

In straight words, a continuous stream of YouTube videoclips without the hassle of clicking on next video's link.

How to reach this paradise ?

Simply go to ZappOne.tv website and start using it

What can i do with it?

Well, you can search YouTube media library for your favourite videoclips and watch them one after another.

Ok, but how ?

The easiest way is to put in some keywords into the tex box on the homepage, then you can press on the GO! button and enjoy your videclips.

Following you can find two screenshots along with some explaination about other functions.

This is the main search page for ZappOne.tv

Keyword to search for: here you can insert your keywords separated by a space
Ordering: this selection determines which order your results will be displayed (default is by most relevant to lesser)
Filter criteria: these options let you filter and further optimize your search results by selecting only ones that match checked categories (this is very usefull for music :P )
Recent tags: just to remember what you have searched so far
Popular tags: the classic Web 2.0 tag cloud containing most used keywords by every user browsing through ZappOne.tv (you can click them to add to your search)
Submit Button: the button with a "Go!" label. As it's name suggests, it starts your experience. Plain and simple.

This is an example of a result page

Current video: Just to remember you what are you looking at. Also contains a link to the original media on YouTube
Playlist: a strip with the thumbnails of your search results. You can scroll it and peek what will be the next videoclip to be shown.
Remove button: by hovering over a thumbnail you will be able to exclude it from the playlist by simply clicking on this red button (you can then restore it by pressing it again)
Link button: have you found a particular playlist you want to share with your best friends ? Here's a link to show them from this point on.

Who developed this marvel ?

digitalapes, of course ;)

Now tell me the real thing: how much does it cost ?

Nothing. ZappOne.tv is absolutly costless and ad-free. The only thing we ask you is to give us a little of feedback on your experience. That's it.

What am I waiting for ?

Don't know ... go visit ZappOne.tv

Developing mobile applications using Gear episode 3: Managing user inputs

2008-11-13T10:58:00.016+01:00

This tutorial will discuss how to handle user inputs in gear based applications and will guide you through the development of a simple picture viewing application.

User input is generally handled by classes inheriting from GWCanvas (thus also GWForm, GWList, GWGrid, etc…). In J2ME applications there are 3 types of inputs available: commands (triggered by soft keys), keypad and touch screen.
In Gear based applications touch screen events can be handled in two different ways: as pointer events and as gesture based events.

Command and gesture triggered events don't need to be handled necessarily in the widgets classes since they use a listener based paradigm, but it is common practice to do so.

To start developing the picture viewer demo we'll have first to create a Gear based J2ME application as explained in the first tutorial "Developing mobile applications using Gear episode 1: Create the first empty application".

The picture viewer demo will permit the user to browse through a set of images included as resources in the JAR archive and to see them in full-screen mode.

Note that the content of this tutorial applies to version 1.1.1 of Gear framework

Step 1: Creating the photo browser widget

First let's create the PhotoBrowser class, make it inherit from GWScrollableList and set it's title and its title icon.

public class PhotoBrowser extends GWScrollableList {
public PhotoBrowser() {
 setTitle("Photo browser");
 setTitleIcon("/Digitalapes.png");
}
}

Then let's add two commands to the interface (View and Exit).
To do so we have to make PhotoBrowser implement GWCommandListener interface, we have to register it self as a command listener and finally add two commands.

public class PhotoBrowser extends GWScrollableList
implements GWCommandListener {
 
Command viewCommand = new Command("View",Command.ITEM,0);
 
public PhotoBrowser() {
setTitle("Photo browser");
setTitleIcon("/Digitalapes.png");
setCommandListener(this);
addCommand(viewCommand);
addCommand(CommonCommands.EXIT);
}

public void commandAction(Command command, GWCanvas sender) {
}
}

Now we need to make the photo browser show the images thumbnail.
This step requires to load the pictures in the photo browser constructor, note that we'll suppose to have a list of the available pictures contained in the PhotoList class (the class code, along with the pictures is included in the demo source code).

public PhotoBrowser() {
setTitle("Photo browser");
setTitleIcon("/Digitalapes.png");
setCommandListener(this);
setStretchIcons(true);
for (int i=0;i < PhotoList.list.length;i++){
 ListItem tmp =
    new ListItem(PhotoList.list[i],"/"+PhotoList.list[i]);
 tmp.setMinVisibleLines(3);
 addItem(tmp);
}
addCommand(viewCommand);
addCommand(CommonCommands.EXIT);
}

Now photo browser displays all the thumbnails but no actions are associated to the user inputs.
Let's associate a quit action to the Exit command pressure and a let's make the PhotoView class (that we are going to implement in the next step) displayed when the View command or the fire button are pressed.
At the end your class should look like this one:

public class PhotoBrowser extends GWScrollableList implements
GWCommandListener {
 
Command viewCommand = new Command("View",Command.ITEM,0);
 
public PhotoBrowser() {
setTitle("Photo browser");
setTitleIcon("/Digitalapes.png");
setCommandListener(this);
setStretchIcons(true);
for (int i=0;i < PhotoList.list.length;i++){
 ListItem tmp =
   new ListItem(PhotoList.list[i],"/"+PhotoList.list[i]);

 tmp.setMinVisibleLines(3);
 addItem(tmp);
}
addCommand(viewCommand);
addCommand(CommonCommands.EXIT);
}
 
public void itemClicked(ImageItem clickedItem) {
commandAction(viewCommand, this);
}

public void itemSelected(ImageItem selectedItem) {
super.itemSelected(selectedItem);
PhotoList.setCurrentPhoto(getSelectedIndex());
}

public void commandAction(Command command, GWCanvas sender) {
if (command == viewCommand)
 EventManager.getInstance().enqueueEvent(
     new DisplayWidget(this,SlideShow.class));
else if (command == CommonCommands.EXIT)
 EventManager.getInstance().enqueueEvent(new QuitEvent(this));
}
 
protected boolean showCheck(Display display, EventArg eventArgs) {
setSelectedIndex(PhotoList.getCurrentPhotoIndex());
return true;
} 
}

Step 2: Creating the photo viewer widget

As before the first step is creating the class (this time inheriting from GWCanvas), setting title and icon, and managing commands

public class SlideShow extends GWCanvas implements GWCommandListener{

Command browseCommand = new Command("Browse",Command.OK,0);
 
public SlideShow() {
setTitle("Photo viewer");
setTitleIcon("/Digitalapes.png");
setCommandListener(this);
addCommand(browseCommand);
addCommand(CommonCommands.EXIT);
}

protected void contentPaint(Graphics g, int x, int y, int w, int h) {
}

public void commandAction(Command command, GWCanvas sender) {
if (command == browseCommand)
 EventManager.getInstance().enqueueEvent(new
       DisplayWidget(this,PhotoBrowser.class));
else if (command == CommonCommands.EXIT)
 EventManager.getInstance().enqueueEvent(new QuitEvent(this));
}
}

Now let's handle the current picture paintig: to paint something in the GWCanvasthe paint operations should be performed in the contentPaint() method, using the parameter as paintable area bounds.
In order to make this widget display the picture requested by the PhotoBrowser, we should also put the proper loading code in the showCheck() method.

String currentImage=null;

protected void contentPaint(Graphics g, int x, int y, int w, int h) {
g.drawImage(ImageResourcesBuffer.getImageResource(
   currentImage, w-this.formPadding*2, h-this.formPadding*2),
    x+w/2, y+h/2, Graphics.VCENTER|Graphics.HCENTER);
}

protected boolean showCheck(Display display, EventArg eventArgs) {
String photoName = PhotoList.getCurrentPhoto();
currentImage = "/"+photoName;
setTitle("Photo view - "+photoName.substring(0, photoName.length()-4));
return true;
}

Now let's associate to the left and right key pressed events a slide action, making the visualize respectively the next and the previous picture

protected void rightArrowPressed() {
PhotoList.getNextPhoto();
EventManager.getInstance().enqueueEvent(new
   DisplayWidget(this,SlideShow.class,SlideRight.class));
}
 
protected void leftArrowPressed() {
PhotoList.getPrevPhoto();
EventManager.getInstance().enqueueEvent(new
   DisplayWidget(this,SlideShow.class,SlideLeft.class));
}

The last step for this widget is the handling of touch screen gestures. To handle touch screen gestures we have to make our class implement the GWGestureListener interface, register it as a gesture listener and then implement the required callbacks.
Finally your class should look like this one:

public class SlideShow extends GWCanvas
   implements GWCommandListener, GWGestureListener{
Command browseCommand = new Command("Browse",Command.OK,0);
String currentImage=null;

public SlideShow() {
setTitle("Photo viewer");
setTitleIcon("/Digitalapes.png");
setCommandListener(this);
setGestureListener(this);
addCommand(browseCommand);
addCommand(CommonCommands.EXIT);
}

protected void contentPaint(Graphics g, int x, int y, int w, int h) {
g.drawImage(ImageResourcesBuffer.getImageResource(
           currentImage, w-this.formPadding*2, h-this.formPadding*2),
           x+w/2, y+h/2, Graphics.VCENTER|Graphics.HCENTER);
}

public void reset() {
}

public void commandAction(Command command, GWCanvas sender) {
if (command == browseCommand)
   EventManager.getInstance().enqueueEvent(
           new DisplayWidget(this,PhotoBrowser.class));
else if (command == CommonCommands.EXIT)
   EventManager.getInstance().enqueueEvent(new QuitEvent(this));
}

public void downToUpScrollGesture() { 
}
 
public void upToDownScrollGesture() {
}
 
public void rightToLeftScrollGesture() {
PhotoList.getNextPhoto();
EventManager.getInstance().enqueueEvent(
    new DisplayWidget(this,SlideShow.class,SlideRight.class));
}

public void leftToRightScrollGesture() {
PhotoList.getPrevPhoto();
EventManager.getInstance().enqueueEvent(
    new DisplayWidget(this,SlideShow.class,SlideLeft.class));
}
 
protected void rightArrowPressed() {
PhotoList.getNextPhoto();
EventManager.getInstance().enqueueEvent(new
     DisplayWidget(this,SlideShow.class,SlideRight.class));
}
 
protected void leftArrowPressed() {
PhotoList.getPrevPhoto();
EventManager.getInstance().enqueueEvent(new
   DisplayWidget(this,SlideShow.class,SlideLeft.class));
}
 
protected boolean showCheck(Display display, EventArg eventArgs) {
String photoName = PhotoList.getCurrentPhoto();
currentImage = "/"+photoName;
setTitle("Photo view - "+photoName.substring(0, photoName.length()-4));
return true;
}

}

Step 3: Adding the glue

First we need to implement the class containing the pictures index:

public class PhotoList {

private static int selectedPhotoIndex=0;
private PhotoList() {
}
public static final String[] list = {
  "Church.jpg",
  "Dema.jpg",
  "Marco.jpg",
  "Paolo.jpg",
  "PizBoe.jpg",
  "SellaRonda.jpg",
  "Track22.jpg",
  "Zoncolan.jpg"
};
public static String getNextPhoto(){
  selectedPhotoIndex++;
  if (selectedPhotoIndex>=list.length)
    selectedPhotoIndex=0;
  return getCurrentPhoto();
} 
public static String getPrevPhoto(){
  selectedPhotoIndex--;
  if (selectedPhotoIndex<0)
    selectedPhotoIndex=list.length-1;
  return getCurrentPhoto();  
}
public static void setCurrentPhoto(int i){
  if (i>=0 && i<list.length)
    selectedPhotoIndex = i;
} 
public static String getCurrentPhoto(){
  return list[selectedPhotoIndex];   
} 
public static int getCurrentPhotoIndex(){
  return selectedPhotoIndex;   
}
}

And finally we have to enable graphic effects in the Gear midlet (to see the transitions) and display the PhotoBrowser at midlet initialization.

setGraphicEffectsEnabled(true);
EventManager.getInstance().enqueueEvent(new DisplayWidget(this,PhotoBrowser.class));

Conclusions

The application we have just created shows how to handle different types of user inputs and gives some basic knowledge about creation of custom graphic widgets and about usage of advanced graphic effects.
It is possible to download the source code and the binary package of this application from Gear's download page.

Developing mobile applications using Gear episode 2: Start using gear widgets and events

2008-09-05T10:57:00.046+02:00

The previous episode of this tutorial covered all the necessary steps to setup a development environment for J2ME applications using Eclipse, EclipseME end Gear.
The previous instructions (available here) are still valid except for the Gear framework version since a new release is now available for download (Gear 1.0.0) .
This tutorial will cover the basic steps required to develop a simple application displaying two forms using Gear widgets system end its event based paradigm.
At the end of this tutorial you will have produced an application like the one you can see in the following screen shots:

Step 1: Create the first GearMidlet
In the step 3 of the previous tutorial we have created an empty J2ME application (midlet suite) and we have added Gear to it.
The midlet suite itselft is not a real application, it's a container for one or more midlet and each midlet is potentially a completely independent application, however most of the midlet suites available contain just one midlet thus a midlet suite is commonly considered equivalent to a mobile application.
Anyay, to start developing our application, we need to create a midlet that will be considered the execution entry point of our midlet suite.

Enter the "New->Other" menu and select "J2ME Midlet"
Enter the midlet name, the package and change the superclass to "gear.application.GearMidlet"
Now you have the midlet created it still does nothing but you can try executing it by right clicking on it and selecting "Run As->Emulated J2ME Midlet" as shown in the following screen shot.

NOTE: In order to continue developing the application of this tutorial it is necessary to add this icon to the "res" folder of your project.

Step 2: Create two forms using GWGrid and GWList
To crate a form using Gear Widgets system simply create a class and inherit one of the available form types.
In Gear version 1.0.0 there are four forms already implemented (GWText, GWGrid, GWList and GWScrollableList) each of these forms can be extended to add any functionality and new forms can be created by extending GWCanvas and GWForm classes.
In this article we'll learn how to display two forms containing 4 items using GWGrid and GWList classes.

First we have to create two classes and make one inherit from GWGrid and the other one from GWList, the two classes should look similar to these two:
```
public class TestGWGrid extends GWGrid{
public TestGWGrid() {
super();
}
}
```
```
public class TestGWList extends GWList{
public TestGWList() {
super();
}
}
```

Now we have to fill both classes with the items to be displayed and we have to set the title and the title icon, to do so we have to put the following code in the TestGWGrid constructor:

// Constructs the grid with 2 rows and 2 columns
super(2,2);

// Set the Grid to stretch properly the icons
setStretchIcons(true);

// Add four items to the Grid
addItem("Item 0", "/digitalapes.png");
addItem("Item 1", "/digitalapes.png");
addItem("Item 2", "/digitalapes.png");
addItem("Item 3", "/digitalapes.png");

// Set the grid title
setTitle("TestGWGrid");

// Set the grid title icon
setTitleIcon("/digitalapes.png");

and the following code in TestGWList constructor:


super();

// Set the List to stretch properly the icons
setStretchIcons(true);

// Add four items to the list
addItem("Item 0", "/digitalapes.png");
addItem("Item 1", "/digitalapes.png");
addItem("Item 2", "/digitalapes.png");
addItem("Item 3", "/digitalapes.png");

// Set the list title
setTitle("TestGWGrid");

// Set the list title icon
setTitleIcon("/digitalapes.png");

Setting title and title icon is not compulsory, if none is set the top bar is not displayed

Finally to interact with the user we'll add two commands to the forms and we'll intercept these commands.
To do this we have to add the following code at the end of both constructors:

// Add two commands
addCommand(CommonCommands.NEXT);
addCommand(CommonCommands.EXIT);

// Add this class as a command listener
addCommandListener(this);

And both classes have to implement the "GWCommandListener" interface this way:

public void commandAction(Command command, GWCanvas sender) {
if (command == CommonCommands.NEXT){
// Do something
} else if (command == CommonCommands.EXIT){
// Do something else
}
}

Step 3: Connecting everything using events
The Gear architecture is based on a multi threading paradigm, so, to permit easy thread to thread communication, Gear provides an event based communication system.
Each event is an object of a class inheriting from the "Event" class, an event may be dispatched by any object and caught by any other.
Dispatching an event requires simply to call the method "enqueueEvent" of the "EventManager" singleton.
Catching an event is a bit more complicated: the class which wants to catch the event should implement the "EventHost" interface and should register to the "EventManager" using the "registerHost" method.
By default the GearMidlet catches the "Quit" and the "DisplayWidget" events. When receiving the first one the midlet will call the "onDestroy" callback and will quit the application if the return value is true. When receiving the "DisplayWidget" event the midlet will handle the eventual widget instantiation and will make the widget visible on screen and active.

To start a widget on midlet start we'll have to dispatch a "DisplayWidget" event in the midlet constructor.

public TestGearMidlet() {
// This event requires the midlet to handle
// instantiation of a TestGWGrid and display it
EventManager.GetInstance().enqueueEvent(
                 new DisplayWidget(this,TestGWGrid.class));
}

To permit the user to exit and switch between the two forms we'll have to add the proper event dispatching functions in the command handling callbacks.
In TestGWList command callback we'll have to put the following code:

public void commandAction(Command command, GWCanvas sender) {
if (command == CommonCommands.NEXT){
EventManager.GetInstance().enqueueEvent(
                  new DisplayWidget(this,TestGWList.class));
} else if (command == CommonCommands.EXIT){
EventManager.GetInstance().enqueueEvent(
                  new Quit(this));
}
}

And in TestGWGrid command callback we'll have to put this code:

public void commandAction(Command command, GWCanvas sender) {
if (command == CommonCommands.NEXT){
EventManager.GetInstance().enqueueEvent(
                 new DisplayWidget(this,TestGWList.class));
} else if (command == CommonCommands.EXIT){
EventManager.GetInstance().enqueueEvent(
                  new Quit(this));
}
}

This way, when the user will press the "Exit" command a "Quit" event will be dispatched and midlet will close.
And, when the user will press the "Next" command a "DisplayWidget" event will be dispatched and the midlet will change the currently displayed forom.

Conclusions
The application we have just created shows the structure of a typical Gear based application and gives some examples of basic widgets handling.
It is possible to download the source code and the binary package of this application from this page.
In the next tutorial more advanced features of the Gear widgets system will be explained (like transitions, list and grid items customization, arrows and fire keys handling, themes, etc...), then the tutorials will focus more on the event communication system, the location abstraction layer and the other Gear functionalities.

Developing mobile applications using Gear episode 1: Create the first empty application

2008-07-24T10:41:00.000+02:00

This is the first episode of a series of tutorials about developing mobile applications in J2ME using Gear framework. This tutorial will cover the first steps required to start developing any J2ME applications with or without using the Gear framework, the next tutorials will be more focused on Gear based applications. Every step of the tutorial has been tested on Windows Vista/XP and Ubuntu Linux, if you want to develop using MacOS, due to the lack of official Sun emulator, you should try MPowerPlayer or MicroEmulator tutorials.

Step 1: Obtain the required software
There are two IDEs suitable for J2ME development: Eclipse and NetBeans, this tutorial will cover the steps required to develop using Eclipse. The required software thus will be:

Eclipse IDE
(Eclipse 3.3 Europa)
Sun Wireless Toolkit
(WTK 2.5.2)
EclipseME
(EclipseME 1.7.9, update site: http://www.eclipseme.org/updates/)
Gear framework
(Gear JMF 0.9.0)

Download Eclipse IDE and Sun WTK from the links above and install both on your system. Installing Eclipse requires simply to extract the compressed package downloaded from the Eclipse site in a folder, typically "c:\Programs" on Windows or "/opt" on Linux. The Wireless Toolkit has a self installing procedure that will ask the user the target installation directory, again the typical directories are "c:\Programs" and "/opt".
If you plan to use Gear framework download the Gear jar and javadoc and put them in a directory of your choice (/opt in this tutorial).
We'll assume that after this step you'll have an Eclipse and a WTK directory in either one of the two directories listed above and eventually Gear files in the directory "/opt".

Step 2: Configure Eclipse and EclipseME
Now that you have installed the basic software it is time to execute Eclipse and configure it to support J2ME development.

First run Eclips and go to the plug in install section.
Select "Search for new features to install", click "Next" and add a new remote site.
Select finish and install the plugin.
Go to the preferences dialog and enter the "J2ME" section.
Enter the "Device Management" subsection, press the "Import" button, select the directory where you have installed the WTK before and press "Finish" button.
Now go to the "Java->Debug" section of the preferences and change the "Debugger timeout" value to 30000.

Now Eclipse is configured correctly to write, run and debug J2ME applications.

Step 3: Create an application and reference the Gear framework
Now it is time to create an empty J2ME application.

Enter the Eclipse "New" menu and select "Other".
Now create a new J2ME midlet suite, enter the name
and press Next until you find the "Java settings" screen.

The following steps are optional, if you don't want to use the Gear framework just press "Finish".

Select the "Libraries" tab, press the "Add External JARs..." button and select the Gear jar file from the directory where you saved it.
Add JavaDoc to Gear: click "javadoc location" sub menu and press the "Edit" button.
Select Gear to be deployed within your application: enter the "Order and Export" tab, and click on Gear check box.

Now simply press the "Finish" button and you'll be ready to start programming your J2ME application.

Conclusions
The midlet suite we have created, is now ready to be filled with a set of midlets and all your application classes. In the next tutorials we'll describe how to create the midlets, how to display an interface, how to andle user's input and much more.