You can download the current FliKun version (for FlashLite 3.0) here: FliKun_3rd_edition_unsigned.sis (please read the notes at the end of this article).

So, let’s start from the beginning.

Flickr API

To upload photos to Flickr we’ll need to use Flickr API: this way we’ll be able to authenticate the user and upload/geotag photos using its REST services, all from within our application.

First thing we should do is to setup an API key for our service, going on the request page. Here you have to fill out the application details, with special care to the authentication method we want to use: suitable choices for our needs would be both desktop and mobile application authentications:

• With the first option the user will be redirected to a Flickr page, from within our application, where he should authenticate and grant necessary permissions to our application.
• With the second option we can let the user generate a mini-token from a dedicated page, using his desktop browser, and then tell him to insert this mini-token within in our application.

In both cases, we will get a token that will be used for all future uses of our application, so there would be no more need to authenticate the user after the first time.

KuneriLite Plugins

In our application, we will need to access these functionalities:

• Retrieve photos stored in phone’s gallery
• Make thumbs to show them in our application
• Start the GPS and retrieve user’s current location
• Upload stored photo on Flickr server

So, we’ll need to use the following KuneriLite plugins:

• GPS: we’ll use the start command to start GPS, and the read command to read current location
• File: with dir command we’ll be able to list files in phone’s gallery folders. We’ll use this also to store textual infos, like the user token
• Upload/Download: with this plugin we’ll upload the photos to Flickr website, using its API, and create the thumbs (with the resize command) to show them within our application

Get a token

We’ll use the desktop authentication method, so these are the steps required to authenticate the user, and to get his token:

• Get a frob, with the Flickr flickr.auth.getFrob method
• Generate the desktop authentication URL with the given frob
• Send the user to the generated URL, using the phone browser, where he should authenticate and grand permissions to our application
• When the user is back to our application, we will finally get his authentication token with the flickr.auth.getToken Flickr method

All these Flickr API calls need to be signed with an api_sig parameter, that is explained here: Flickr Authentication API page (in the Signing paragraph). To generate it in our FlashLite application, we’ll use the following function:

function getApiSignature(args:Object)
{
	var authSig:Array = new Array();
 
	for(var key:String in args)
	{
		authSig.push(key + args[key]);
	}
	authSig = authSig.sort();
 
	var apiSig:String = this._md5.hash(<API_SECRET> + authSig.join(''));
 
	return apiSig;
}

where <API_SECRET> is the API Secret associated to your API Key (you can see both of them on Flickr API Keys page).

If all has gone well, we will finally get the user token, that we must store somewhere (for example using SharedObject, or within a local file using KuneriLite file plugin).

Show phone gallery photos

Since we’ll use S60 3rd edition phones, we’ll search for photos in these folders: “C:\Data\Images\” and “E:\Images\”. Since on these phones photos will be stored in many subfolders, we’ll search within them, using “/s” argument within KuneriLite dir call. Also, we should avoid listing photo thumbs, that are stored
in subfolders named “_PAlbTN”, so it’ll be easy to spot out and avoid to get them.

Once we have the photo paths, we can use the KuneriLite resize command to resize them to our preferred size, and use those thumbs within our application. In doing this, we should care for the following points:

• It’s not possible to load more than 5 resources at once, so we should generate and load thumbs in a progressive manner, otherwise we will have lost calls (without any feedback or exception) within our application
• While loading a thumb in a MovieClip, we should take care not to remove the Clip while it’s loading (for example, because the user has navigated to another screen). Doing this we’ll avoid the issue described here.

Enter photo details and upload it!

Once the user has selected a photo, we should let him enter photo data (title, description and tags), and then let him choose if he wants to tag with his location the photo itself.

In this case, we can use the approach described in this other article to retrieve the current GPS location: Displaying gps position in flashlite using google static maps and kunerilite.

Once we have the GPS location coordinates, we can finally upload the photo to Flickr website with the upload API. Since the upload API itself requires, apart from the file itself, to send the other params within the POST body, we should use some sort of server proxy, since KuneriLite upload command does not allow to post them this way. What we could do is to send the textual parameters within the upload URL, and then let our proxy POST them to Flickr server.

Get FliKun!

This first release of FliKun is very (very!) alpha, so try it at your own risk jokes apart, there are still many points open (like the horrible graphics!), so expect new versions as soon as I’ve got the time to work more on it!

Download FliKun_3rd_edition_unsigned.sis (for FlashLite 3.0).

Currently known issues/bugs are:

• Sometimes upload fails, especially when using some special characters
• There is no upload progress bar (but will be added very soon)
• File upload fails (with error code -4) when photo size is bigger than approx 450 Kb (I’m currently working to solve this)

For any other bugs you may encounter, please leave comment on this post! Thanks

Finally note that, to use the GPS feature, you’ll need to sign the SIS file with a valid certificate.

The source code

FxBaseCanvas

First of all, we know that Canvas paint() method is protected, so, to access it from the class we’ll build, we must extend its visibility by extending Canvas class itself. We’ll do it by defining our FxBaseClass in this simple way:

import javax.microedition.lcdui.Canvas;
import javax.microedition.lcdui.Graphics;
import javax.microedition.lcdui.Canvas;
import javax.microedition.lcdui.Graphics;
 
public class FxBaseCanvas extends Canvas
{
	public void paint(Graphics g)
	{
	}
}

CanvasSlideFx

Now, we start building our CanvasSlideFx class, that will extend Canvas itself. We start defining some useful properties:

// time related properties
long startTime = 0;
long duration = 0;
 
// current state of the transition
boolean running = false;
 
// direction of sliding
int direction = LEFT;
 
// the previous and next Canvas instances
FxBaseCanvas fromCanvas = null;
FxBaseCanvas toCanvas = null;
 
// the current Display object
Display display = null;
 
// properties used to correctly place the 2 Canvas
int deltaX = 0;
int deltaY = 0;

Now, we define our class constructor, that will initialize coordinate properties according to the specified transition direction. The detailed argument list is:

• The current Display object, that will be used to retrieve the current displayed Canvas, and to set the next one
• The destination Canvas, that will extend the previously defined FxBaseCanvas class
• The transition direction (one of Canvas.UP, RIGHT, DOWN or LEFT)
• The transition duration, in milliseconds

public CanvasSlideFx(Display display, FxBaseCanvas toCanvas, int direction, long duration)
{
	this.display = display;
	this.fromCanvas = (FxBaseCanvas)display.getCurrent();
	this.toCanvas = toCanvas;
	this.direction = direction;
	this.duration = duration;
 
	switch(direction)
	{
	case UP:
		deltaY = - getHeight(); break;
	case RIGHT:
		deltaX = getWidth(); break;
	case DOWN:
		deltaY = getHeight(); break;
	case LEFT:
		deltaX = - getWidth(); break;
	}
}

Now, we define a startTransition() method, that will actually start the animation. To implement the animation itself, we let our class implement Runnable.

void startTransition()
{
	this.startTime = System.currentTimeMillis();
 
	running = true;
 
	new Thread(this).start();
}

And here’s the run() method implementation, that we must implement from Runnable interface. As long as the animation is running, we will repaint our animated Canvas, with a given interval of 50 milliseconds (but you can freely change this). When it finishes (so, running is false), we will exit the main loop and set the current Displayable to our toCanvas.

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

Finally, we have our paint() method, that will actually paint our transition. It will do this by painting both the source and the destination Canvas, translating them according to the transition direction, and to the elapsed time.

protected void paint(Graphics g)
{
	if(!running)
		startTransition();
 
	long diff = System.currentTimeMillis() - startTime;
 
	if(diff >= duration)
	{
		running = false;
 
		diff = duration;
	}
 
	int perc = (int)(100 * diff / duration);
 
	int dx = deltaX * perc / 100;
	int dy = deltaY * perc / 100;
 
	g.translate(dx, dy);
 
	fromCanvas.paint(g);
 
	g.translate(- deltaX, - deltaY);
 
	toCanvas.paint(g);
 
	g.translate(deltaX - dx, deltaY - dy);
}

How to use it?

Now we’ll see how to integrate the CanvasSlideFx within an existing code that already uses Canvas.
So, let’s assume that our application currently has, somewhere in its code, these lines:

MyCanvas firstCanvas = new MyCanvas();
 
Display.getDisplay(myMidlet).setCurrent(firstCanvas);
...
//and somewhere else
MyOtherCanvas secondCanvas = new MyOtherCanvas();
 
Display.getDisplay(myMidlet).setCurrent(secondCanvas);

where MyCanvas and MyOtherCanvas will likely extend Canvas.

Now here are the required steps to integrate transitions in our code:

1. First of all, we must make MyCanvas and MyOtherCanvas extend FxBaseCanvas instead of directly Canvas. So, we’ll have:

   public class MyCanvas extend FxBaseCanvas ...

2. Then, let’s say we want to animate the transition between firstCanvas and secondCanvas, we will remove the code:

   Display.getDisplay(myMidlet).setCurrent(secondCanvas);

   and replace it with:

   CanvasSlideFx fxCanvas = new CanvasSlideFx(
   	Display.getDisplay(myMidlet),
   	secondCanvas,
   	Canvas.LEFT,
   	500L
   );
    
   Display.getDisplay(myMidlet).setCurrent(fxCanvas);

3. and we’ve done it!

Resources and download

You can download the code explained in this article with the following links:

• FxBaseCanvas.java: our base class extending Canvas
• CanvasSlideFx.java: the class used to implement the sliding transition

I’ve recently hit the target of 500 posts on Forum Nokia Discussion Boards, and so I’ve acquired the Super Contributor title! Here’s the related post, but the best thing is absolutely the customizable avatar bonus, so here it is:

My design skills are not that good, don’t you think?

Meanwhile, also a new Forum Nokia Champion Champion of the Month has been proclamed, so kudos to Pankaj Nathani (already Forum Nokia Champion at the beginning of this year) for his great contributions and participation in Forum Nokia community! Keep up the good work!

Today we’ll see how to implement and and use text that changes multiple colors with a fading effect. You can see it in action here: J2ME text color fade effect in action.

So, let’s start defining our ColorFadeText class.

The code

We start defining the necessary properties:

//will hold the colors to fade
int[] colors = null;
 
//duration of a single fade
int fadeDuration = 0;
 
//effect start time
long startTime = 0;
 
//property used to check if effect has started
public boolean started = false;
 
//the text to be drawn
String text = null;

Now, we define the main constructor, that will accept the following arguments:

• the text to be drawn
• an int[] array containing the colors to fade into
• the duration of a single fade

public ColorFadeText(String text, int[] colors, int fadeDuration)
{
	if(colors.length == 0)
	{
		throw new IllegalArgumentException("You must define at least 1 color");
	}
	this.text = text;
	this.colors = colors;
	this.fadeDuration = fadeDuration;
}

The effect start() method will simply set the startTime value to current time and the started property to true

public void start()
{
	startTime = System.currentTimeMillis();
 
	started = true;
}

Then, we have the paint() method, that will be used to paint the text on the given Graphics instance:

public void paint(Graphics g, int x, int y, int anchor)
{
	if(started)
	{
		long diff = System.currentTimeMillis() - startTime;
 
		int module = (int)(diff % fadeDuration);
 
		int colorIndex = (int)(diff / fadeDuration) % colors.length;
 
		int midColor = midColor(
			colors[(colorIndex + 1) % colors.length],
			colors[colorIndex],
			module,
			fadeDuration
		);
 
		g.setColor(midColor);
	}
	else
	{
		g.setColor(colors[0]);
	}
 
	g.drawString(text, x, y, anchor);
}

The following utility method will be the one actually used to get the current text color:

static int midColor(int color1, int color2, int prop, int max)
{
	int red =
		(((color1 >> 16) & 0xff) * prop +
		((color2 >> 16) & 0xff) * (max - prop)) / max;
 
	int green =
		(((color1 >> 8) & 0xff) * prop +
		((color2 >> 8) & 0xff) * (max - prop)) / max;
 
	int blue =
		(((color1 >> 0) & 0xff) * prop +
		((color2 >> 0) & 0xff) * (max - prop)) / max;
 
	int color = red << 16 | green << 8 | blue;
 
	return color;
}

How to use it?

Using the ColorFadeText object is quite simple, since it’ll be very similar to use a common String. Just follow this plain steps.

1. Create a ColorFadeText instance

ColorFadeText text = new ColorFadeText(
	"I'M A FADING TEXT!",
	new int[]{0xff0000, 0x00ff00, 0x0000ff, 0xff00ff},
	1000
);

2. Start it…

text.start();

3. And then, in your Canvas paint() method, paint it, using the same arguments used by Graphics drawString() method (adding a reference to the Graphics instance of course):

text.paint(g,
	getWidth() / 2,
	2,
	Graphics.HCENTER | Graphics.TOP
);

Just a side note: since it’s an animated effect, you’ll need to repaint it quite frequently, so, for example, you can use a Thread to periodically call Canvas repaint() method.

Source code download

You can download source code of ColorFadeText, and of a sample Canvas that makes use of it:

• ColorFadeText.java: main class source code
• AnimatedTextCanvas.java: a Canvas using the ColorFadeText object

This article is also available on Forum Nokia Wiki: How to create a color fading text in Java ME.

And finally… here are the Winners!

• Overall Winner and Location Based Services (LBS): Den Grigorenko
• Flash Lite: Faisal Iqbal and Hayden Porter
• Web Runtime (WRT): Dou Yongwang

Also, special prizes (Nokia 6220 Classic Devices) were given to: Raheal Akhtar, David Caabeiro, Gerald Madlmayr, Felipe Andrade, Olympio Cipriano and… me I’m too happy!!

If you want to take a look at the impressive list of all articles submitted by developers for the whole contest, take a look here: 2008 Code Example Challenge article list.

Prerequisites

Get your own Google Maps API key

To use Google Maps services, you should have a Google Maps API key. If you do not have one, you can go here:

http://code.google.com/apis/maps/signup.html

and signup for your API key.

Download and install KuneriLite

KuneriLite is a tookit that extends FlashLite capabilites allowing applications to access native Symbian functionalities, like file writing, or reading GPS data.

To proceed in this tutorial, you must download and install KuneriLite: KuneriLite download page.

Create FlashLite application

Create your FlashLite movie

In this example, we’ll use FlashLite 2.1, but porting it to other (older or newer) FlashLite versions will be quite straightforward. So, after you’ve created an empty FlashLite movie, follow this simple steps:

• Create a Button by going to Insert -> New Symbol…
• enter GpsButton as name
• check the Export for ActionScript and Export in first frame checkboxes

• Now, design your Button as you prefer, for example placing a big “Find me!” label on it
• After you’ve finished designing your Button, place it on movie root, in the lower part of the stage, as in the attached screenshot, and give it startButton as Instance Name

Enter ActionScript code

On movie root, create a new layer called Actions, and open its ActionScript editor. We’ll start defining some properties:

// Enter your api key here
var apiKey = 'API_KEY';
 
//If you're using non-commercial version of KuneriLite, you'll not need to change this
var kuneriPath = 'http://127.0.0.1:1001/Basic/';

Now, we’ll define some useful functions that we’ll use in our code:

//We'll call this function when some KuneriLite related errors occur
function kuneriError(error:String)
{
	trace("KuneriLite error: " + error);
}
 
//This function will do all calls to KuneriLite servers
//and call the given handler passing response values as argument
function kuneriLoad(url, handler)
{
	var loader:LoadVars = new LoadVars();
 
	loader.onLoad = function()
	{
		handler(this);
	}
	trace("LOADING: " + url);
 
	loader.load(url);
}

Now, let’s code the Button-related logic. When the user presses the startButton we want to:

• start the GPS
• retrieve the current GPS position
• display a map centered in the retrieved GPS position

To get full infos about about KuneriLite GPS plugin, you can check the related Wiki page: http://wiki.kunerilite.net/index.php?title=GPS_plugin

We begin starting the GPS on gpsButton press, using the start klCommand:

startButton.onPress = function()
{
	kuneriLoad(kuneriPath + 'GPS?klCommand=start', gpsStarted);
}
function gpsStarted(res:LoadVars)
{
	if(res.klError == 0 || res.klError == -11)
	{
		trace("GPS started");
 
		kuneriLoad(kuneriPath + 'GPS?klCommand=read', gpsDataRead);
	}
	else
	{
		kuneriError("Error starting GPS!");
	}
}

The gpsStarted() handler will:

• check if there is no error (klError = 0) or if GPS is already started (klError = -11). For full errors list associated with GPS plugin, check KuneriLite Wiki page: http://wiki.kunerilite.net/index.php?title=GPS_plugin
• if there’s an error starting the GPS, call our kuneriError() function defined above
• if GPS is correctly started, it will make a second call to KuneriLite, this time to retrieve current GPS position (klCommand=read)

This second call to KuneriLite will call gpsDataRead() handler, defined below:

function gpsDataRead(res:LoadVars)
{
	if(res.klError == 0)
	{
		if(res.klPosLatitude != undefined)
		{
			var lat = res.klPosLatitude;
			var lng = res.klPosLongitude;
 
			trace("POSITION: " + lat + ", " + lng);
 
			loadMap(lat, lng);
		}
		else
		{
			kuneriLoad(kuneriPath + 'GPS?klCommand=read', gpsDataRead);
		}
	else
	{
		kuneriError("Error retrieving GPS position!");
	}
}

This handler, as above, will check if there is any error raised by KuneriLite and, if not, will check if latitude and longitude coordinates are available, by checking response klPosLatitude and klPosLongitude property values. If they’re not available, a new call to read klCommand is done, otherwise the following loadMap() function is called.

function loadMap(lat:Number, lng:Number)
{
	var mapClip:MovieClip = _root.createEmptyMovieClip('mapClip', _root.getNextHighestDepth());
 
	mapClip._x = 0;
	mapClip._y = 0;
 
	var mapWidth = 240;
	var mapHeight = 280;
 
	var loader:MovieClipLoader = new MovieClipLoader();
 
	var mapUrl:String = 'http://maps.google.com/staticmap?center=' +
		lat + ',' + lng + '&format=jpg&zoom=8&size=' +
		mapWidth + 'x' + mapHeight + '&key=' + apiKey;
 
	loader.loadClip(mapUrl, mapClip);
}

The above function:

• attaches a new empty movie clip to movie root
• places it to coordinates (0,0)
• use a MovieClipLoader to load a 240×280 map image, in jpeg format, in the empty clip

Done that, you can actually test your FlashLite movie

Test your FlashLite application

Test on PC

To test your application without deploying on real device, you must follow these simple steps:

• Start KuneriLite emulator with default settings (port: 1001, key: Basic)
• Start your FlashLite movie
• Press Find Me! and wait for your image to be loaded (of course, being an emulator, the GPS position will be not real :))

For more infos about KuneriLite Emulator, you can go here: KuneriLite Emulator Wiki page

Test on real device

To test your app on real device, you must package your SIS application using KuneriLite Wizard, following these steps:

• Export your FlashLite movie
• Create a new KuneriLite project
• Enter application name and other data, checking GPS from the available plugins
• Check “Use external player” option if you developed for a development player (2.x or 3.x) and would like to launch the application using one of those players
• It is also recommended to always check “Use stub” option
• Select the exported SWF as project Main SWF

Note: to use GPS you should sign your application, specifying certificate, key and password in KuneriLite Wizard interface. Otherwise, your application will not be able to access GPS functionalities.

For more infos about KuneriLite Wizard, you can go here: KuneriLite Wizard Beginner’s Guide

Source code and resources

• Download the FLA source of this tutorial here: KuneriGpsMap.zip (the downloadable version includes some code that could be useful to debug possible problems)
• For further resources about using Google Maps in mobile applications, you can check this other article: How to use Google Maps data in mobile applications
• This article is available also on Forum Nokia Wiki: Displaying GPS position using Google Maps images in FlashLite

As the previous one, this also is related to Google Maps usage in mobile applications, and you can read it here: How to use Google Maps data in mobile applications.

As its name says, It’s an introductory article on how to use Google Maps services, in particular the geocoding and static maps ones, from a mobile application, where standard Google Maps API code is not suitable (since it is thought for web based and Ajax’d apps). Its content does not focus on any particular programming language, but gives base guidelines to use those services using REST.

So… any kind of feedbacks is welcome!

And, to celebrate this event, I’ve added a brand new feature to my article that will allow you to:

• create larger tiled maps
• support map scrolling

How does it work?

You start instantiating a GoogleMaps object as usual:

GoogleMaps gMap = new GoogleMaps("API_KEY");

Then you get your map, for example geocoding a given address:

double[] coords = gMap.geocodeAddress("Leicester square, London");
 
Image mapImage = gMap.retrieveStaticImage(
	150, 150,
	coords[0], coords[1],
	12, "png"
);

Then, let’s say you want to scroll your map 100 pixels up, what you’ll do is:

double[] newCoords = gMap.adjust(
	coords[0], coords[1],
	0, -100, 12
);
 
Image newMapImage = gMap.retrieveStaticImage(
	150, 150,
	newCoords[0], newCoords[1],
	12, "png"
);

As you’ve seen, the adjust method takes these arguments:

• the current latitude and longitude
• the deltaX and deltaY, in pixels
• the current zoom level

and returns the new map center latitude and longitude coordinates.

You can check the full updated source code on Forum Nokia Wiki article: J2ME Google Maps API, and a full-featured example, with the scrolling feature, on the emulator page: J2ME Google Maps API in action.

Currently supported effects are visible on the emulator page, and are:

• BlindsFx
• ExplodeFx
• PuzzleFx
• ShakeFx
• SlideFx
• SpiralFx
• WaveFx
• WipeFx

How to use it?

Let’s start from a simple usage example. We start creating an Image, and then using it to create an AnimatedImage instance:

Image baseImage = Image.createImage("/base.png");
 
AnimatedImage animated = new AnimatedImage(baseImage);

Now, we have created an AnimatedImage, that is the base class that will allow us to apply effects to Images.

Now, we can create an effect (that will be a subclass of ImageFx) and apply it to our AnimatedImage:

ImageFx fx = new PuzzleFx(8, 8, ImageFx.TYPE_IN);
 
animated.setFx(fx);

In this example, we have chosen a PuzzleFx effect, that will show (or hide, depending on Fx type) our image piece by piece. As you can check on JavaDocs page for PuzzleFx class, first 2 arguments represent the horizontal and vertical pieces to split the Image into, while the last one is the type of the Fx itself.

Now, our AnimatedImage is ready to be animated. To start the animation, simply call the AnimatedImage start() method, passing as argument the effect duration in milliseconds:

animated.start(3000L);

About painting, you’ll simply have to call the paint() method, in a way that is really similar to Graphics drawImage():

animated.paint(g, 100, 100, Graphics.TOP | Graphics.LEFT);

Now, to begin using this library, you don’t really need any more infos. Just to point out some methods you can find useful in your app:

//stop() method will immediatly stop the FX
fx.stop();
 
//isRunning() method tells if the FX is running or not
fx.isRunning();
 
//isEnded() method tells if the FX animation is ended
fx.isEnded()
 
//and, if you want a looping effect, you can use
fx.setLooping(true);

Further information

You can library JAR file here: ImageFx.jar. Current version requires MIDP 2.0 and CLDC 1.1 to be used (a version compatible with CLDC 1.0 will be released as soon as I’ve got time :)).

Full API JavaDocs (still in early phase too :)) are also available here.

Forum Nokia Code Champ Winners!

This competition, launched by Nokia to promote the development of WebRuntime and Flash-based applications has finally announced his winners, and there are really cool applications!

CityLite of IdeasLite is a guide to night life in Latin American capitals, with informations about events, theaters, and a lot more. Really cool interface!

KuneriLite team also won the award for Europe/Middle East/Africa with their one-button voting system: Kuneri Easy Vote! Congratulations for their good work!

For the full list of winners, you can look here.

iPhone 3G is finally here!

After months of guessing and posting, Apple will finally announce, during San Francisco Apple WorldWide Developers Conference of June 9th, the 3G version of its iPhone. And it seems that it’ll arrive in Italy before the end of June branded by the two Carriers Tim and Vofafone.

While it’s definitely a good news that it’ll support HSDPA, it seems that we’ll not have a builtin GPS… too bad for all location-fanatics!

Jarpa, source code is out!

Jarpa is an absolutely interesting project aiming to extend FlashLite and Java ME feature by allowing them to intercommunicate, and so allowing developers to create hybrid applications that can take the best of both worlds.

Some days ago, Felipe Andrade has finally released Jarpa sourcecode, so developers can finally start to benefit of this framework, and for J2ME and FL-addicted like me, this is a GREAT news!

And, if you need one more reason to congratulate with Felipe for its great and extensive work, here is its Nokia Championship award!