×
Namespaces

Variants
Actions

Series 40 6th Edition: Developing Java ME applications with force-sensitive joystick and Force Sensitive Joystick API

From Nokia Developer Wiki
Jump to: navigation, search
Article Metadata
Tested with
SDK: Series 40 6th Edition SDK
Devices(s): Nokia 6260 Slide, N97
CompatibilityArticle
Created: User:Technical writer 1 (25 Nov 2008)
Last edited: hamishwillee (09 Aug 2013)

Series 40 6th Edition extends the Nokia UI API with a new interface, the Force Sensitive Joystick API. Together with a force sensitive joystick, this new interface enables developing more sophisticated Java ME applications such as games and navigation applications with the MIDP low-level UI in Series 40. This article discusses these two components and what you need to know before you start developing joystick applications for Series 40.

Contents

Force-sensitive joystick in Series 40 6th Edition devices

Certain Series 40 6th Edition devices, such as the Nokia 6260 Slide (see the below picture) have a force-sensitive joystick, an input device which detects 360 degree scrolling movement and force input generated by the end-user.

The force-sensitive joystick enhances user experience in two ways: First, it is a one-button control as instead of five separate navigation keys (Up, Down, Left, Right, and Middle) which have been used as controls for Java ME- based games and applications in earlier Series 40 Edition devices. Second, this single button detects 360 degree scrolling movement at force-dependent speed, enabling for example brake, acceleration and steering in racing games, and providing therefore a richer and more dimensional end-user experience.

6260 Slide Image.PNG


Force Sensitive Joystick API in Series 40 6th Edition

Series 40 6th Edition devices which have a force-sensitive joystick can utilise the new Nokia UI API extension interface called Force Sensitive Joystick API. Java ME applications using this interface listen to joystick events generated by the end user. The usability of this interface can be checked by using System.getProperty("com.nokia.mid.ui.joystick_event") which returns "true" if the interface can be used.

The Force Sensitive Joystick API is an extension interface to the existing Nokia UI API (com.nokia.mid.ui). The API version with the extension is Nokia UI API 1.1a. To use this interface, the following import definition needs to be done in the source code:


import com.nokia.mid.ui.JoystickEventListener;


The new joystick interface consists of one method:


void joystickEvent(int x, int y) { 
 
// use x and y coordinates here
 
}

In the source code, the joystickEvent(int x, int y) method is called when the joystick sends an event to the listener interface, com.nokia.mid.ui.JoystickEventListener. The joystick sends an event every time its position or the force applied to it changes. These events are represented by x (horizontal) and y (vertical) vector components. In the centre position, the value for an (x, y) event is (0,0).

Since x and y coordinates are used as movement delta for determining both position and applied force, this sets certain limitations which should be noted especially from the user experience point of view. If, for example, the (-5,5) event is received, it means that the joystick is held in the left and up diagonal. Now, if the (-25,25) event is sent, it means that the joystick is still held in the same direction of (-5,5), regardless of more force applied for the new event.

The maximum and minimum values of x and y coordinates are -127 and 127.

Application development with Force Sensitive Joystick API

The Force Sensitive Joystick API can only be used with MIDP’s low-level user interface: If the MIDlet needs to receive joystick events, it must provide an implementation of the event listener interface from a Canvas class or subclass. The Canvas will continue to receive standard key / game key events. In addition, the joystick events are sent only if the Canvas is in visible state.

The following code snippet illustrates the basic usage of the Force Sensitive Joystick API.

 /* --------------------------------------------------
* JoystickTest.java
*
* Midlet for processing joystick commands
*
*------------------------------------------------- */

 
import javax.microedition.midlet.MIDlet;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.Graphics;
import com.nokia.mid.ui.FullCanvas;
import com.nokia.mid.ui.JoystickEventListener;
 
public class JoystickTest extends MIDlet
{
private Display display; // For current display of midlet
private JoystickCanvas canvas; // Full Canvas Class with functionality
private Form myform; // Form to show initial results
 
public JoystickTest()
{
display = Display.getDisplay(this);
myform = new Form("Test Form");
canvas = new JoystickCanvas();
}
/*
* At startup, this midlet will test whether the necessary
* functionality is supported on this device or not.
* @see javax.microedition.midlet.MIDlet#startApp()
*/

 
protected void startApp()
{
String val = System.getProperty("com.nokia.mid.ui.joystick_event");
if(val != null){
display.setCurrent( canvas );
}
else{
myform.append("Joystick event not supported on this device");
display.setCurrent( myform );
}
}
protected void pauseApp(){ }
 
protected void destroyApp( boolean unconditional )
{
notifyDestroyed();
}
 
}// end of class JoystickTest
 
/*--------------------------------------------------
* Class JoystickCanvas
*
* This class actually implements the JoystickEventListener interface
* and its functinality as a whole, using the FullCanvas class.
*-------------------------------------------------*/

class JoystickCanvas extends FullCanvas implements JoystickEventListener
{
 
private int height, y_pos; // height value along y-axis
private int width, x_pos; // width value along x-axis
private String coordinates; // x,y coordinates are converted to string to display on canvas.
private int H_MID, W_MID; // Midpoint of total height and total width.
 
/*--------------------------------------------------
* Constructor
*-------------------------------------------------*/

public JoystickCanvas()
{
height = y_pos = this.getHeight(); // Full height for this device (Nokia_6600 = 480 )
width = x_pos = this.getWidth(); // Full width for this device (Nokia_6600 = 320 )
H_MID = height / 2; // Half of this height 240
W_MID = width / 2; // Half of this widht 160
}
 
/*--------------------------------------------------
* Paint the text representing the key code
*-------------------------------------------------*/

protected void paint(Graphics graphics)
{
// Clear the background (to light grey)
graphics.setColor(200, 200, 200);
graphics.fillRect(0, 0, width, height);
 
// Drawing Axis lines on Canvas
drawAxes(graphics);
 
// Paint a red coloured box, each time with new x,y coordinates.
graphics.setColor(255,0,0);
graphics.fillRect((x_pos+ W_MID) ,(-y_pos+H_MID), 10, 10);
graphics.drawRect((x_pos+ W_MID) ,(-y_pos+H_MID), 10, 10);
 
// String representation of x,y coordinates is painted on canvas's left_bottom.
coordinates = "["+ x_pos +","+ y_pos +"]"; //320x480
graphics.drawString( coordinates, 0, height, Graphics.BOTTOM | Graphics.LEFT);
 
}
 
/* ----------------------------------------------------------
* This method will draw the horizontal and vertical axis
* in the middle of the screen by using height, width values.
* ---------------------------------------------------------- */

public void drawAxes(Graphics g){
 
g.setStrokeStyle(Graphics.DOTTED);
g.setColor(0,0,255); // blue coloured axes
g.drawLine(0, height/2, width - 1, height/2); // drawing horizontal line
g.drawLine(width/2, 0, width/2, height - 1); // drawing vertical line
}
 
/*--------------------------------------------------
* Joystick Event handler method.
*
* It fetches the x,y coordinates of current position
* and paints it on canvas using x_pos, y_pos.
*-------------------------------------------------*/

public void joystickEvent(int x, int y)
{
this.x_pos = x;
this.y_pos = y;
repaint();
}
 
}// End of JoystickCanvas

Testing Java ME applications with Force Sensitive Joystick API

In addition to the actual Nokia 6260 Slide device, Java applications with Force Sensitive Joystick API can be tested by using the Series 40 6th Edition SDK emulator.

Any USB-based joystick should suit for testing the API with the SDK emulator, preferably with a Windows XP supported plug-and-play convenience to make it work without any additional steps.

If plug-and-play is not available, vendor drivers needs to be installed as prerequisite to make the joystick work with the SDK emulator.


Related links

This page was last modified on 9 August 2013, at 05:30.
52 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×