Mobile games development

After an explosive J2ME class, now it’s the time for sliding transition effects. With the following SlidingImage class you’ll be able to seamlessly add both SlideIn and SlideOut effects to your toooo static apps!

As usual, take a look at how this would appear in a real phone, and then proceed with the simple these 1,2,3 steps

1. Download and include in your code the SlidingImage.java class
2. Instantiate a new SlidingImage:

   SlidingImage image = new SlidingImage(
   	Image.createImage("/image1.png"),
   	10,
   	SlidingImage.SLIDE_OUT);

   These are the constructor arguments:

   • An Image object to be slided
   • The number of pieces of the sliding image
   • The type of slide, can be SlidingImage.SLIDE_IN or SlidingImage.SLIDE_OUT
3. Start the sliding effect, specifying its direction and duration (in milliseconds):

   image.slide(Canvas.RIGHT, 3000);

   Direction can be one of Canvas properties UP, RIGHT, DOWN and LEFT.

4. Now you can paint it simply specifying coordinates and an anchor, as usual:

   image.paint(g,
   	100, 100,
   	Graphics.HCENTER | Graphics.VCENTER);

5. If you remember ExplodingImage class, you can check if effect is ended with the public ended property:

   if(image.ended)
   {
   //effect-end related code
   }

6. If you want to reset the effect, also changing the sliding image pieces and effect type (slide in or out), you can use the reset() method:

   //to reset changing also slides and type properties
   image.reset(12, SlidingImage.SLIDE_IN);
   //otherwise, to simply reset:
   image.reset();

You can download source code here:

• SlidingImage.java: main class source code
• SimpleSlidingCanvas.java: example of Canvas using SlidingImage

Yesterday I’ve finished 2 projects developed using FlashLite 3.0 in conjunction with KuneriLite. Now, it’s time for some considerations.

About FlashLite

My opinion: FlashLite is far from being a mature platform for mobile development. Why?

No access to native phone functionalities.

This means no GPS, no data storage (apart from text), no video/audio capture, and much more. Since one of mobile apps strengths is in its integration with the device itself, this sounds like a big limitation (but someway it’s something like first J2ME years). This could be due to a different perspective and target users/developers, but having a powerful platform like Flash being limited to casual games or screensavers looks a bit odd to me.

Odd, senseless behavior.

What happens if you try to load more that 5 resources together? They won’t load, simple.

Or want to quit your application? You can, but at conditions: user must press some key for quit to work and, even if he does, there’s the chance that the app simply won’t close.

And if a network or local resource, for example loaded via LoadVars, is not available? You’ll have a terrible popup telling the user that he has a “Problem with content: -6″, or other similar, anti-usability things.

Security encounters insanity.

Since FlashLite 3.0, there was a nice introduction, with the new player Security settings. About this there are good articles from Ugur and chall3ng3r that point out this has caused problems in having, for example, an application loading both local and remote resources. Fortunately, there are workarounds that allow to overcome some of the limitations involved in this (like using the notorious “Trusted” folder), but we’re still far from painless development

Good news under the sun.

Bill Perry from Adobe posted back, few days after the posts from Ugur and chall3ng3r, with the news that Adobe is working to solve some of the issues pointed out, and this is absolutely a welcome kind of feedback from Adobe team!

About KuneriLite

Install, plug, use.

When you must merge 2 technologies to overcome their own limitations, it’s already a pain. So, when you do it, you want simple, immediate tools, that would make your work easier, not harder. With KuneriLite you have exacly this: an easy-to-use, understand and test tool. You have an intuitive Wizard that will allow you to create, setup and SIS package all your apps, and an emulator for easy testing and debugging. This IS what we want!

Support matters!

Briefly said: KuneriLite team is fantastic! Having worked with their product for more than 2 months, I can say to be more than happy for their help and support. You can find all the infos you want on their forums an Wiki pages.

Yes, but what?

Ok, maybe you don’t know what KuneriLite is, so here’s a brief introduction: KuneriLite is a tool that allows you to access Symbian native functionalities from your FlashLite application. They (your FlashLite app and KuneriLite) will interact via simple HTTP requests, and results are returned in the classical form of key/value pairs. So said, integration with your app will be quite straightforward.

Past, present and future.

Mobile Development is currently undergoing a lot of changes, merging and shuffles.

FlashLite seems to be trying to find his way by merging with other technologies, from Java (see Jarpa) to Python (FlyerFramework) to Symbian C++ (KuneriLite, Janus, and others) and, why not, Web Runtime. Far from having a definite solution, there’s a lot to see and experiment.

And we’re here to do it

After a MIDP 1.0 utility to rotate images now time has come for some image fun

When writing mobile applications, it’s always cool to add some effects or transitions. But, while for example FlashLite has a nice builtin support for them, with J2ME you have to hand-code even the simplest movement (and this is the main reason why most J2ME apps are all but attractive).

So, here’s a first class that you can use to add an “explode” effect to images in a straightforward way. How to do it? Here we come:

1. Download the ExplodingImage.java source code and put it straight in your project
2. Instantiate an ExplodingImage this way:

   //get your Image
   Image sourceImage = Image.createImage("/image.png");
   //and then use it in ExplodingImage constructor
   ExplodingImage image = new ExplodingImage(sourceImage , 5, 8, 8);

   The ExplodingImage constructor accepts the following arguments:

   • An Image instance
   • An int representing the “level” for the exploding effect, that is the strength of the effect itself (higher the level, stronger the effect).
   • The last 2 int arguments represent the horizontal and vertical pieces of the exploded image.
3. Start the explode effect with the explode() method, that will accept the effect duration as argument:

   image.explode(2000L);

4. To paint it, simply use its paint() method, very similary to the Graphics drawImage() one. For example, in a Canvas paint() method, you can do something like this:

   protected void paint(Graphics g)
   {
   	g.setColor(0xffffff);
   	g.fillRect(0, 0, width, height);
   	image.paint(g, getWidth() / 2, getHeight() / 2, Graphics.HCENTER | Graphics.VCENTER);
   }

   To give the effect a “smooth” animation, you should paint it quite frequently (let’s say, not once per second :)). So, always using Canvas, a sample code could be like this:

   public void run()
   {
   	while(true)
   	{
   		repaint();
    
   		try
   		{
   			synchronized(this)
   			{
   				wait(50L);
   			}
   		}
   		catch(Exception e)
   		{
   			e.printStackTrace();
   		}
   	}
   }

5. To test if the effect has ended, you can simply access your ExplodingImage ended instance variable:

   if(image.ended)
   {
   	//effect-end related code
   }

6. And you’re done! See it in action here: J2ME image explode effect in action

Sample source code is available here:

• ExplodingImage.java: main class
• ExplodingImageCanvas.java: sample usage of ExplodingImage within a Canvas

So you’re still using MIDP 1.0 uh? And maybe you need to rotate an image?

If this is your case, you could find useful this simple function:

public static Image rotateImage(Image image, int angle) throws Exception
{
	if(angle == 0)
	{
		return image; 
	}
	else if(angle != 180 && angle != 90 && angle != 270)
	{
		throw new Exception("Invalid angle");
	}
 
	int width = image.getWidth();
	int height = image.getHeight();
 
	int[] rowData = new int[width];
	int[] rotatedData = new int[width * height];
 
	int rotatedIndex = 0;
 
	for(int i = 0; i < height; i++)
	{
		image.getRGB(rowData, 0, width, 0, i, width, 1);
 
		for(int j = 0; j < width; j++)
		{
			rotatedIndex = 
				angle == 90 ? (height - i - 1) + j * height : 
				(angle == 270 ? i + height * (width - j - 1) : 
					width * height - (i * width + j) - 1
				);
 
			rotatedData[rotatedIndex] = rowData[j];
		}
	}
 
	if(angle == 90 || angle == 270)
	{
		return Image.createRGBImage(rotatedData, height, width, true);
	}
	else
	{
		return Image.createRGBImage(rotatedData, width, height, true);
	}
}

So, how can you use it? Nothing more than:

Image original = Image.createImage("/original_image.png");
 
Image rotated_image = rotateImage(original, 90);

You know that J2ME support for Canvas is quite ridiculous.. One list, some form items, and stop. Canvas is left to its terrible destiny, with nothing more than a couple of lines and circles.. isn’t it sad?
So, after this melodramatic introduction, we’re ready for today’s code: a fully featured, customizable, Canvas based calendar!

If you prefer a live demonstration rather than a simple screenshot, just go here: Canvas Calendar in action.

So, how to use it?

1. Download its source code (CalendarWidget.java) and put it straight in your project
2. Instantiate it within your Canvas with its plain-old-unique constructor:

   CalendarWidget calendar = new CalendarWidget(new Date());

3. Customize it with the colors/fonts/padding you prefer:

   calendar.headerFont = Font.getFont(Font.FACE_PROPORTIONAL, Font.STYLE_BOLD, Font.SIZE_LARGE);
   calendar.weekdayFont = Font.getFont(Font.FACE_PROPORTIONAL, Font.STYLE_BOLD, Font.SIZE_MEDIUM);
   calendar.weekdayBgColor = 0xccccff;
   calendar.weekdayColor = 0x0000ff;
   calendar.headerColor = 0xffffff;

4. After you’ve customized it, remember to always call its initialize() method:

   calendar.initialize();

5. Now, to paint it, you can simply call its paint() method from your Canvas paint(), like this:

   protected void paint(Graphics g)
   {
       g.setColor(0xffffff);
       g.fillRect(0, 0, getWidth(), getHeight());
       calendar.paint(g);
   }

6. Now you must allow users to interact with it, so you can, for example, use Canvas keyPressed() method to interact with calendar:

   protected void keyPressed(int key)
   {
       int keyCode = getGameAction(key);
       if(keyCode == FIRE)
       {
           Display.getDisplay(midlet).setCurrent(
               new Alert("Selected date", calendar.getSelectedDate().toString(), null, AlertType.CONFIRMATION)
           );
       }
       else
       {
           calendar.keyPressed(keyCode);
           repaint();
       }
   }

   As you see, what we do is this:

   • if the user press FIRE button, we alert the current selected date
   • otherwise we call calendar keyPressed() method, to make it behave accordingly
7. Other customizable properties include:
   • MONTH_LABELS: change this to customize month labels in your own language
   • WEEKDAY_LABELS: as above, change this to customize weekday labels
   • startWeekday: this represents the week starting day, and its values range goes from 0 (for Monday) to 6 (for Sunday)

You can download source code of the example described above here: CalendarCanvas.java.

To get some more details about CalendarWidget source code, you can take a look at my article on Forum Nokia Wiki: Building a J2ME Canvas based Calendar / Date picker.

Some days ago I’ve posted J2ME code to parse RSS feeds using kXML library. Today’s code is about parsing a generic XML, so you can use it to parse any XML document you want. Code is splitted in the following two classes.

XmlNode class

This is the class representing a single node. We’ll define 2 node types:

• Text nodes: nodes without a name, contanining only a textual value. For them we’ll define a TEXT_NODE final variable
• Element nodes: nodes with a tag name, that can have children nodes and/or attributes

XmlNode class source code is available here: XmlNode.java

GenericXmlParser class

This is the class that will actually do XML parsing. We’ll define only one public method, parseXML(), that will accept 2 arguments:

• a KXmlParser instance, that will be used to do XML parsing
• a boolean that will tell if whitespace-only text nodes must be ignored or not

and will return and XmlNode representing the root node of the parsed XML tree.

GenericXmlParser class source code is available here: GenericXmlParser.java

Sample usage

Let’s see how we can use the two classes above. First we must instantiate and initialize a KXmlParser, and then we can call our GenericXmlParser parseXML() method.

InputStreamReader reader = new InputStreamReader(getClass().getResourceAsStream("/test3.xml"));
 
KXmlParser parser = new KXmlParser();
 
parser.setInput(reader);
 
GenericXmlParser gParser = new GenericXmlParser();
 
XmlNode xml = gParser.parseXML(parser, true);

Now, we have our resulting XmlNode that will hold the whole XML tree. We can make a simple dump of it to check if it’s all ok, using this test function:

void dumpXML(XmlNode node, int deep)
{
	for(int i = 0; i < deep; i++)
	{
		System.out.print(" ");
	}
	System.out.print(node.nodeName + " - ");
 
	if(node.nodeValue != null)
	{
		System.out.print("(" + node.nodeValue + ") - ");
	}
	String[] attributes = node.getAttributeNames();
 
	for(int i = 0; i < attributes.length; i++)
	{
		System.out.print(attributes[i] + ": " + node.getAttribute(attributes[i]) + ", ");
	}
 
	System.out.println();
 
	for(int i = 0; i < node.children.size(); i++)
	{
		dumpXML((XmlNode)node.children.elementAt(i), deep + 1);
	}
}

Note: This article is available also on Forum Nokia Wiki: How to parse an XML file in J2ME with kXML

Note: You can find this article also on Forum Nokia Wiki: How to use Google Maps data in mobile applications

Today we’ll see how to use Google Maps data within a mobile application.
Google Maps offers REST services that allows accessing its data with simple HTTP requests, so we can easily integrate them within our mobile apps.

Signup for a Google Maps API key

First thing you must do is to signup on this page:
http://code.google.com/apis/maps/signup.html
Once done, you’ll get a key (a simple String) you’ll use for all your query to Google Maps services

Static maps

Standard Google Maps code is suited for web applications, since it includes alot of Ajax functionalities, that are not really useful if you’re building a mobile application. So, the solution is to use static maps service, that will allow us to retrieve single images, easily usable within our apps.

Static maps service supports different image formats (png32, gif, jpg) and customizable image size, so that we can get perfect images for all our needs. As an example, suppose we want to retrieve the location at:

• latitude: 41.867878
• longitude: 12.471516

We can simply retrieve this URL with an HTTP GET request:

http://maps.google.com/staticmap?center=41.867878,12.471516&
format=png32&zoom=8&size=240x320&key=<API_KEY>

This way, we’ll get a PNG32 image, with a width of 240 pixels, and a height of 320, centered at point (41.867878,12.471516), and with a zoom level of 8 (zoom can go from 0 to a maximum level of 19).

Geocode an address

From Google Maps docs:
Geocoding is the process of converting addresses (like “1600 Amphitheatre Parkway, Mountain View, CA”) into geographic coordinates (like latitude 37.423021 and longitude -122.083739)

So, let’s assume we want to build an application that displays the address typed by our user. We should firstly geocode its address to geographics coordinates.
To do this, Google Maps offer another REST service easily accessible with simple HTTP requests.

Let’s say you want to geocode this address “Leicester Square, London”, then you’ll request this URL:

http://maps.google.com/maps/geo?q=Leicester%20Square,%20London
&output=csv&key=<API_KEY>

and you’ll get this output:

200,6,51.510605,-0.130728

Where:

• the first number is a code, that in this case (200) means that geocoding has been successfull (for a full list of status codes you can see here: [1])
• the second number gives a measure of geocoding accuracy (from 0 to 9 - maximum accuracy)
• 3rd and 4th numbers represent latitude and longitude of the geocoded address, so these are the coordinate we’ll use to retrieve the map through the static map service we’ve seen before

As you can see, there is an ‘output’ parameter within the geocode request, and this means that we can choose the output format we prefer for our needs. Supported formats are:

• xml
• kml (same as xml, but with different Content-Type)
• json (not really useful for mobile apps)
• csv (comma separated values)

Proxy server, usage limits

Since your Google Maps API key is bound to a specific URL, to access map services you should setup a proxy server that will receive HTTP requests from your mobile application and forward them to Google Maps REST URLs, giving back Google responses to mobile clients.

Also, be aware that there is a limit to the number of requests (both for static maps and geocode service) you can do each day. For personal uses they’re more than enough, anyway consider this point if you plan to develop commercial services.

Google Maps J2ME API and sample application

Now, you want code right? Here it is:

• a J2ME class to access Google Maps REST services: http://wiki.forum.nokia.com/index.php/J2ME_Google_Maps_API
• a sample application using Google Maps data: http://www.jappit.com/index.php?page=emulator&midlet=google_maps

Today’s code is related to file uploads using J2ME. We’ll use Http POST MultiPart requests to handle and transfer data from J2ME application to server; since there is no builtin support for MultiPart, we’ll have to build the request body by hand.

Code is limited to 1 class only (HttpMultipartRequest), that will be easy to include and easy in your code, just instatiate it with its constructor:

HttpMultipartRequest(String url, Hashtable params,
String fileField, String fileName,
String fileType, byte[] fileBytes)

and then send data to server (and get response) with its send() method. As you can see from the constructor, this implementation support also parameter passing, that will be posted to server together with the file bytes.

Detailed and explained code (with sample client and server code) is available here: HTTP Post multipart file upload with J2ME Wiki article. To directly download source code, click here.

Some days have passed since last J2ME tutorial, so here is a fresh new one!

Today we’ll see how parsing a RSS feed with J2me is easy using KXML library, a fast and small XML pull parser, expecially suited for constrained environments like mobile devices. A live sample, parsing the RSS feed of this blog, is available here.

The detailed explanation of source code is available on my Forum Nokia Wiki article: J2ME RSS Parser with KXml. If you’re interested only in plain source code, you can pick it up here (it includes also the sample midlet you find on the emulator page). To use KXmlRssParser class, you must simply do:

KXmlRssParser parser = new KXmlRssParser();
 
Vector rssItems = parser.parse(yourFeedURL);

and the parse() method will return the complete list of parsed Items, as instances of RssItem class. Source code is of course simplified, for the purpose of this tutorial, as it only considers title, link and description tags of each <item>, but once you understand KXml logic you can extend it, without much effort, to include other infos from RSS feed.

Other resources you might find useful:

• KXML JavaDocs: http://kxml.sourceforge.net/kxml2/javadoc/
• RSS 2.0 Specifications: http://cyber.law.harvard.edu/rss/rss.html

Since iPhone’s arrive in Italy seems to be near, here’s a first port of AnimaLogic, one of the first web runtime games!

You can try a first (very beta, as always :)) version here.