When the MIDP 1.0 platform was introduced it had certain problems with regards to the user interface APIs. The MIDP 1.0 platform althaugh a good platform had certain drawbacks. Chief among them were lack of the following features: · There was no support for drawing in the full screen mode. · There was lack of support for sound generation. · There was no support for controlling the important user interface elements like backlight and vibrator. · There was a need for good quality image and graphic manipulation APIs. The MIDP 1.0 specification had only a basic set of APIs for the said purposes.
To eliminate these kinds of bottlenecks Nokia introduced the Nokia UI API 1.0. This API is supported by all Nokia built MIDP devices. Thus large pools of devices support this API. Althaugh I did not want to include manufacturer specific APIs in this text but my descision to include Nokia APIs was made when I found that Nokia UI APIs are supported by more than 60 devices in the market. Since Nokia has the largest share in mobile phone markets it is important for the developer to know even Nokia UI APIs. In fact if you want to develop good quality games in MIDP 1.0 for Nokia devices then the Nokia UI API is the best bet.
When working with Nokia UI API please keep in mind that since they are not a part of core MIDP or CLDC, they are not supported by general emulators and toolkits. But you can use the Nokia APIs from J2ME Wireless Toolkit by using the Nokia emulators. Just copy the Nokia emulators which you can download from the ‘Forum Nokia’ to the ‘devices’ directory under the ‘wtklib’ directory in the directory in which your toolkit is loaded. For example generally in case of J2ME WTK 1.04 the Nokia emulators should be copied to the following directory ‘C:\wtk104\wtklib\devices’.
The Nokia UI APIs contains the following two packages:
com.nokia.mid.ui.DeviceControl What is it?  The DeviceControl class provides us with methods to control some of the special features available in mobile devices like vibration and screen (LCD) backlight.
o Methods · public static void setLights(int num, int level) This method is used to activate and deactivate the lights on the device.
Parameters int num – This parameter indicates the number of the device light to control. Value 0 is assigned to the screen backlight. Currently only the screen backlight is supported.
int level – This parameter should be a value between 0 and 100. It indicates the brightness of the light. Not all devices support 100 variations in the brightness of the light. Some devices have only two levels. 0 sets one level and other values set the other level.
· public static void flashLights(long duration) This method is usesd for temporarily flashing the lights for a specific length of time. The time for flashing the lights is given in milliseconds in the duration parameter.
· public static void startVibra(int freq, long duration) This method is used for setting the vibration at a particular frequency for a particular time. The time duration for which the device should vibrate is given in milliseconds. This feature is very useful in action games.
· public static void stopVibra() This method is used for stoping the vibration. If the device is not vibrating this method has no effect.
public interface DirectGraphics what is it ?  The DirectGraphics class contains graphics extensions for MIDP Graphics. This interface supports the following features: · Polygon and triangles drawing · Images rotated · Image flipping · Alpha channel color support
o Field · public static final int FLIP_HORIZONTAL This field is a constant for horizontal image flipping.
· public static final int FLIP_VERTICAL This field is a constant for vertical image flipping.
· public static final int ROTATE_90 This field is a constant for rotating an image 90 degrees counter-clockwise.
· public static final int ROTATE_180. This field is a constant for rotating an image 180 degrees counter-clockwise.
· public static final int ROTATE_270 This field is a constant for rotating an image 270 degrees counter-clockwise.
The fields given below are used for working with pixels. · public static final int TYPE_BYTE_1_GRAY · public static final int TYPE_BYTE_1_GRAY_VERTICAL · public static final int TYPE_BYTE_2_GRAY. · public static final int TYPE_BYTE_4_GRAY · public static final int TYPE_BYTE_8_GRAY · public static final int TYPE_BYTE_332_RGB · public static final int TYPE_USHORT_4444_ARGB · public static final int TYPE_USHORT_444_RGB · public static final int TYPE_USHORT_1555_ARGB · public static final int TYPE_USHORT_565_RGB · public static final int TYPE_INT_888_RGB. · public static final int TYPE_INT_8888_ARGB
o Method
· public void setARGBColor(int argbColor) This method sets the color for subsequent drawing operations. The parameter for the color in this method takes the value in ARGB value format (0xAARRGGBB). The following are the meanings of alphabets in this format: · AA – Alpha information · RR – Red color Information · GG – Green color Information · BB – Blue color Information
· public void drawImage(javax.microedition.lcdui.Image img, int x, int y,int anchor, int manipulation) This method can be used for drawing an image to the graphics context. Common manipulations can all be done on the image with this method. The anchor point can be used for positioning the image.
· public void drawTriangle(int x1, int y1, int x2,int y2, int x3, int y3, int argbColor) This method can be used for drawing a closed triangle defined by coordinates given in the parameter. This method uses the color defined in the last parameter for drawing the triangle. This method does not change the current color of the system. · public void fillTriangle(int x1, int y1, int x2, int y2, int x3, int y3, int argbColor) This method can be used for drawing a filled triangle defined by coordinates given in the parameter. This method uses the color defined in the last parameter for filling the triangle. This method does not change the current color of the system. · public void drawPolygon(int[] xPoints, int xOffset, int[] yPoints, int yOffset,int nPoints, int argbColor) This method can be used for drawing a closed polygon defined by the arrays of the x and y coordinates. Each pair of x and y coordinates defines a point in the figure. This method uses the color defined in the last parameter for drawing the polygon. This method does not change the current color of the system. · public void fillPolygon(int[] xPoints, int xOffset, int[] yPoints, int yOffset, int nPoints, int argbColor). This method can be used for drawing a filled polygon defined by the arrays of the x and y coordinates. Each pair of x and y coordinates defines a point in the figure. The area inside the polygon is defined using the alternating rule. This method uses the color defined in the last parameter for filling the polygon. This method does not change the current color of the system.
· public void drawPixels(int[] pixels, boolean transparency, int offset, int scanlength, int x, int y, int width, int height, int manipulation, int format) This method copies or draws the pixel data directly to the graphics context or to a specific location from the array starting from the specified offset. Only int based formats are allowed for this method, if you pass any other format it will result in an IllegalArgumentException.
· public void drawPixels(byte[] pixels, byte[] transparencyMask, int offset, int scanlength, int x, int y, int width, int height, int manipulation, int format) This method copies or draws the pixel data directly to the graphics context or to a specific location from the array starting from the specified offset. Only byte based formats are allowed for this method, if you pass any other format it will result in an IllegalArgumentException.
· public void drawPixels(short[] pixels, boolean transparency, int offset, int scanlength, int x, int y, int width, int height, int manipulation, int format) This method copies or draws the pixel data directly to the graphics context or to a specific location from the array starting from the specified offset. Only short based formats are allowed for this method, if you pass any other format it will result in an IllegalArgumentException.
· public void getPixels(int[] pixels, int offset, int scanlength, int x, int y, int width, int height, int format) This method will copy the pixel values at a specific location to an int array. · public void getPixels(byte[] pixels, byte[] transparencyMask, int offset, int scanlength, int x, int y, int width, int height, int format) This method will copy the pixel values at a specific location to a byte array.
· public void getPixels(short[] pixels, int offset, int scanlength, int x, int y, int width, int height, int format) This method will copy the pixel values at a specific location to an array of shorts.
· public int getNativePixelFormat() This method returns the native pixel format of an implementation. The format returned by this method is the most efficient format supported by the drawPixels and getPixels methods of a specific implementation.
· public int getAlphaComponent() This method gets the alpha component of the current color which can range from 0 to 255.
public class DirectUtils extends java.lang.Object What is it?This class contains many useful methods. It contains methods for performing the following:o Conversion of standard lcdui classes to Nokia UI classes. o Conversion of Nokia UI classes to standard lcdui classes. o Creating different kinds of images. o Method · public static DirectGraphics getDirectGraphics(javax.microedition.lcdui.Graphics g) This method converts the standard javax.microedition.lcdui.Graphics object to a DirectGraphics object. No new object is created in the process. Thus when we will act on the DirectGraphics object the same Graphics object will be workd upon. · public static javax.microedition.lcdui.Image createImage(byte[] int imageOffsetimageData int imageLength) This method is very useful method. It can help us create a mutable image that can be constructed from the data stored in the specified byte array at the specified offset and length. The PNG format among others is supported by this method. · public static javax.microedition.lcdui.Image createImage(int width, int height, int ARGBcolor) The method will return a newly created mutable Image with specified dimension. All the pixels of the image will be of the specified ARGB color. Thus this method helps us create transparent images which are very useful in games.
public abstract class FullCanvas extends javax.microedition.lcdui.Canvas What is it?One of the biggest problems faced while developing games and applications on the mobile phones is small screen size. It is further compounded by the fact that we are not able to use the full screen in the MIDP 1.0 specification. To eliminate this problem Nokia has provided us with the FullCanvas class which provides us with a full screen painting area. The commands can not be added to this class. But we have a way out in form of catching the events generated by the soft keys. Thus this problem is not a major one. Constructor · protected FullCanvas() This constructor constructs a new FullCanvas object. This class being abstracted need to be sub classed. Fields· public static final int KEY_SOFTKEY1 This field stands for the key code constant for left softkey/first command button key. Value: -6 · public static final int KEY_SOFTKEY2 This field stands for the key code constant for right softkey/last command button key.Value: -7 · public static final int KEY_SEND This field stands for the key code constant for the Send key.Value: -10. · public static final int KEY_END This field stands for the key code constant for End key.Value: -11 · public static final int KEY_SOFTKEY3 This field stands for the key code constant for select key/middle softkey/second command button key. All devices do not contain this key. Value: -5. · public static final int KEY_UP_ARROW This field stands for the key code constant for up arrow key. Value: -1. · public static final int KEY_DOWNAR_ROW This field stands for the key code constant for down arrow key.Value: -2. · public static final int KEY_LEFT_ARROW This field stands for the key code constant for left arrow key. All devices do not contain this key. Value: -3
· public static final int KEY_RIGHT_ARROW This field stands for the Key code constant for Right arrow key. All devices do not contain this key. Value: -4.
Method · public void addCommand (javax.microedition.lcdui.Command cmd) Throws IllegalStateException. FullCanvas class does not support commands.
· public void setCommandListener(javax.microedition.lcdui.CommandListener l) Throws IllegalStateException. FullCanvas class does not support commands.
public class Sound extends java.lang.Object What is it ?  The Sound class gives us a simple API for playing tones and digitized audio files. This is a very important feature for the games.
o Constructor · public Sound(byte[] data, int type) This method initializes Sound object so that it is ready for playback.
· public Sound(int freq,long duration) This method initializes Sound object so that it is ready for playback. This constructor can be used for initializing a simple tone-based sound.
o Fields
· public static final int FORMAT_TONE · public static final int FORMAT_WAV · public static final int SOUND_PLAYING · public static final int SOUND_STOPPED · public static final int SOUND_UNINITIALIZED
o Methods · public void init(int freq, long duration) This method initializes Sound to play a simple beep. The first parameter stands for the frequency in Hz and the second one the time in milliseconds. Keep in mind that the value in the second parameter should be for less than 2 seconds for normal results.
· public void init(byte[] data, int type) This method initializes the Sound object based on the data in the byte array. The second parameter stands for the data format.
· public int getState() This method gets the current state of Sound.
· public void play(int loop) This method is used for playing a sound from the beginning. The value of 0 in the loop parameter will set the playback in the continous playback mode. Any other value means that the playback should be repeated the given number of times. Keep the value of the loop parameter as small for best results.
· public void stop() This method stops the sound playback. It also changes the state to SOUND_STOPPED.
· public void resume() This method can be used to continue the playback of a stopped sound object from the position it was stopped at. This method also changes the state to SOUND_PLAYING.
· public void release() This method releases audio resources reserved by this Sound object.
· public void setGain(int gain) This method sets the gain (volume) for the sound object. The value of gain is in the range of 0 and 255. A value of 0 means mute.
· public int getGain() This method gets the gain (volume) of the sound.
· public static int getConcurrentSoundCount(int type) This method gets the maximum number of concurrent sounds the device can play for a specific audio type.
· public static int[] getSupportedFormats() This method returns the supported audio formats as array of int.
· public void setSoundListener(SoundListener listener) This method can be used for registering a listener for playback state notifications. public interface SoundListener What is it?  The SoundListener interface can be used by the applications to receive events that indicate changes in the playback state of the Sound objects. Method · public void soundStateChanged(Sound sound, int event) This method is called when the playback state of a sound is changed. The following events can occur:
|
Mobile Technology > Java ME (J2ME) > Book - Mobile Phone Programming using Java ME (J2ME) > UNIT IV >
