Nokia New Asha Platform Developer Training

New Nokia Asha Platform
Developer Training
Create Amazing Apps for
Nokia Asha Phones
14.05.2013 Nokia Asha Training | Andreas Jakl, Mopius 1

Andreas Jakl
Twitter: @mopius
Trainer & app developer
– mopius.com
– nfcinteractor.com
Nokia: Technology Wizard
University of Hagenberg: Assistant Professor
Siemens / BenQ Mobile

Platforms
Developer Platform 2.0DP 1.1DP 1.06th Ed., FP16th Ed.6th Ed., Lite5th Ed., FP1 Nokia Asha
Software
Platform 1.0
Series 40

Nokia Asha Platform
Asha 501

Series 40 Full Touch
Asha 305
Asha 306
Asha 308
Asha 309
Asha 310
Asha 311

2 Mb 2 Mb 2 Mb
Asha 305, 306 Asha 308, 309, 310 Asha 311
2 Mb 2 Mb 4 Mb
-- -- 1 GHz
Capacitive
Multipoint-Touch
Resistive
Multipoint-Touch (2)
Capacitive
Jar Size
Java Heap
CPU
Screen
5 Mb*
Asha 501
3 Mb
--
Capacitive
* recommended

What’s New?
Nokia IDE for Java ME v2
App Framework
– Internationalization API (JSR-238)
– MIDlet lifecycle: startApp() / pauseApp() are called when sent to background
UI and graphics
– Image scaling API
– Gesture API: new double tap
– Category bar: additional use as toolbar for actions
Networking
– Network State API: SIM, network, WLAN change notifications

What’s New?
Multimedia
– Tuner, image encoding, image postprocessing
– Removed com.nokia.mid.sound.Sound (Nokia UI)
Security
– PKI support.
– Removed APDU / SATSA-APDU
Data Handling
– Contacts API: contact change notifications in phonebook (while MIDlet is active)
– File Select API: use native file browser to select files
– Phone Setting API: retrieve settings + change notifications: flight mode, data connection, silent mode, etc.
– Nokia Notifications API: subscribe + get payload of notifications

DEVELOPMENT
Java ME

Development
Both free IDEs
come with
extensive, generic
Java ME support
on board.

Nokia IDE for Java ME
Device SDK Manager
Integrated SDK + Toolchain
App Templates
JAD Editor

NetBeans
Fully integrated solution
– Integrates all aspects of mobile development
– Visual UI Designer
– Game Builder
– Localization, Preprocessing
– Web access
– Automated deployment
Maintained by Oracle
– http://www.netbeans.org/

Installation
Java JDK + JRE 7
– Update 17 (Later versions do not work – emulator: internal RMI registry port issues)
– 32 bit version (also on 64 bit OS)
– http://www.oracle.com/technetwork/java/javase/downloads/index.html
Nokia Asha SDK (includes Nokia IDE)
– https://www.developer.nokia.com/Develop/Java/Tools/
Optional: NetBeans 7 (All Edition!)
– http://netbeans.org/
Optional: Oracle Java ME SDK
– http://www.oracle.com/technetwork/java/javame/javamobile/download/sdk/index.html
!

NetBeans 7.3+
NetBeans 7.x experience
– Don’t choose Features on Demand
– Install Java SE + EE + ME
Run NetBeans as Administrator once
after Nokia SDK installation
– Integrates SDK docs
Install additional plug-ins
– Java ME SDK Tools
– LWUIT Resource Editor
– Java ME SDK Demos
– Visual Mobile Designer

PHONES & APIS
Understanding the Slang

Asha / Series 40 Phones
Filter by Series 40 Edition or
Java Runtime version (new phones)
developer.nokia.com/Devices

What does my phone support?
www.developer.nokia.com/Devices/

Versions
Asha Software
Platform
Developer
Platform
OS Version Phones
1.0 Asha Software Platform Asha 501
2.0.0 Series 40 Asha 305, 306, 308, 309, 310, 311
1.1.0 Series 40 Asha 200, 201, 302, 303
1.0.0 Series 40 Asha 202, 203; 301, C2-00, C2-02, C2-03, C2-
05, C2-06, X2-02, X2-05
Series 40 6th Edition, FP 1 Asha 300, C3-01, X3-02
Series 40 6th Edition C2-01, C3-00, X2-00, X2-01, 6303i, 7230,
6350, 6750, 3720, ...
Series 40 6th Edition Lite C1-01, C1-02
Series 40 5th Edition, FP1 2690, 3208, 6600i, 2730, 2700, 6208, 6600,
8800, ...
Series 40 5th Edition, FP1 Lite 2220, 2720, 2320, 2330, 5000...
Series 40 5th Edition 3610, 6263, 6555, 7500, 6267

CLDC MIDP 248
MSA
185
JTWI
75
File
82
BT
135
Medi
a
172
Web
RPC
172
Web
XML
177
SATS
AAPD
U
177
SATS
ACRY
PT
179
Locat
ion
184
3D
205
Mess
aging
211
Cont
ent
226
SVG
234
Came
ra
234
Audio
3D
234
Music
234
Imag
eE/P
234
Tune
r
238
I18N
256
Sens
or
Nokia
UI
IAP
Asha
1.0
1.1 2.1 - - 1.0 1.1 1.2 1.0 1.0 - 1.0 1.0.1 1.1 2.0 1.0.1 1.1 1.1 - - 1.1 1.1 1.6 1.2 1.7 beta
2.0.0 1.1 - 1.0 1.0 1.0 1.1 1.1 - - - 1.6 2.0
1.1.0 - - - - - 1.1 1.0
1.0.0 - - - - - 1.1b -
S40
6th,
FP1
- - - - - 1.1b -
S40
6th
√ - √ - - - - 1.1 -
S40
6th
Lite
- √ - - - - - - - - - -
S40
5th
FP1
√ - 1.1 - √ - 1.0 1.0 - - - - -
S40
5th
FP1 L
- √ - - - - - - - - - - - - - - -
S40
5th
√ - 1.1 1.0 1.0 - 1.1 - √ - 1.0 1.0 - - - - -

SDKs
www.developer.nokia.com/Develop/Java/Tools/Series_40_platform_SDKs/
1 emulator per SDK.
Install multiple SDKs for
more emulators.
www.developer.nokia.com/Develop/asha/java/downloads.xhtml

Phone Deployment
No Nokia Suite support for Asha 501 yet
– Over-the-air (OTA)
– Copy to MicroSD in Mass Storage mode
– Bluetooth:

USER INTERFACE - ESSENTIALS
Nokia Asha

UX Guidelines
Design
– Layouts
– Interaction patterns
– Icon templates
– developer.nokia.com/Design/

New Asha UX

Hardware Keys

Back Button

User Interface Layout

Screen Sizes
Touch-and-type Full touch Nokia Asha

Minimum Touch Area
59 x 59 px 55 x 55 px 47 x 47 px
Finger
Thumb

UI Comparison
Status bar
Header bar
Action button 1
Content area
Navigation bar
Back buttonCategory bar
View title
Action button 2
(options)
Status bar
Header bar
Content area
Toolbar
240 x 400 px
3:5 aspect ratio240 x 320 px
3:4 aspect ratio

USER INTERFACES
Developing

UI Strategies
Custom UI on Canvas LCDUI High-Level UI LWUIT Library

High Level UI
Display
CanvasScreen
TextBox FormList Alert
ChoiceGroup
DateField
TextField Gauge
ImageItem
StringItemChoice
(Interface)
ItemSpacer CustomItem
Command
Ticker Graphics
Displayable
Low Level UI
Draw the GUI yourself, own event handling. Used for games
and bigger commercial applications.
Completely pre-defined screen layouts
High Level UI
Appearance based on default phone UI
design, can not be influenced.
Arrange predefined controls on a screen.
LWUIT
UI Library draws UI directly using low level UI
drawing methods.

High Level UI
Display
CanvasScreen
TextBox FormList Alert
ChoiceGroup
DateField
TextField Gauge
ImageItem
StringItemChoice
(Interface)
One Display instance / MIDlet
Methods for
drawing to a
canvas
Available in all
sub-classes of
Displayable
ItemSpacer CustomItem
Command
Ticker Graphics
Displayable LWUIT

High Level UI: Forms
Individual items, automatically
arranged below each other. The
appearance depends on the
phone.
WTK Emulator Nokia 7710 Emulator

LWUIT
LightWeight User Interface Toolkit
– Inspired by Swing
– But designed for constrained devices
– Can be added to any Java ME application (embedded .jar)
– Drawing done in Java source code, without native peer rendering
Optimized version for Nokia!
Features (excerpt):
– Layouts
– Themes, fonts
– Animations & Transitions
– 3D / SVG integration (optional)
– Internationalization

Tantalum Mobile Toolset
Many common use cases
– HTTP Getters
– JSON, XML
– Worker Threads
– Logging
Licensing
– Free; Apache License
– Add source directly to your project
projects.developer.nokia.com/Tantalum

Remote Device Access
Enabling testing on real devices
Free for Nokia Developer users
Go to RDA: http://www.developer.nokia.com/Devices/Remote_device_access/
Watch introductory video: http://www.developer.nokia.com/Develop/Java/Videos/
http://www.youtube.com/watch?v=F1odix8k_fg

Code Examples
Installed to:
– C:NokiaExamplesNokia_Asha_SDK_1_0
Nokia IDE
– Nokia Hub → Nokia Series 40
Code Examples
Emulator / Help
– Help → MIDlet Samples
Online
– bit.ly/JavaMeExamples
Maps & LWUIT
– C:NokiaDevicesNokia_Asha_SDK_1_0plugins

CATEGORY BAR & BACK
Tabs & Tools

Java ME Commands
Command = semantic information about an action
(→ how can an action be executed?)
But no actual implementation of the action!
Contains:
– Short label
– Long label (optional)
– Type
– Priority
Nokia Asha Training | Andreas Jakl, Mopius 44
One of them will be displayed on the screen / in the menu,
depending on the available space
“Intention”of the command – e.g. for special placement on the
device: Ok, Back, Help, Screen, Item, etc.
For the order of commands, if more are mapped to the same
softkey. The lower the priority, the more important it is.
18.03.2013

Category Bar & Commands
No Category Bar
Primary action as button
Other commands in menu
Category Bar: Tab Bar
≤ 4 tabs
Primary action added to menu
Category Bar: Toolbar
New in Asha Platform:
items don’t stay selected
Full Touch Category Bar
Automatic back button.
≤ 15 tabs, no actions allowed
Primary action as icon (top right)
Other actions in menu (top left)

Do Not Combine Tabs & Actions
Tab Bar
Highlights current tab.
Category bar should
disappear when drilling
down.
Toolbar
Highlight only on touch down (3).
Affect entire view, not a single item within view.

CategoryBar Icons
New Asha Full Touch
Bounding Box 22 x 22 px 36 x 36 px
Icon Size 20 x 18 px 20 x 20 px
Color Gray White
Ready-made icons in
Nokia Icon Toolkit
http://bit.ly/NokiaIcons

IconCommand
Extends LCDUI Command class
– Adds: Icon
• Built-in system icon
• Own icon
– unselected
– [selected – if not specified: automatic
color highlight]

IconCommand
public class JavaFTMidlet extends MIDlet implements CommandListener, ElementListener {
private IconCommand cmdOk;
private IconCommand cmdHome;
public JavaFTMidlet() {
// Create icon command with pre-defined image
cmdOk = new IconCommand("Ok", Command.OK, 1, IconCommand.ICON_OK);
// Create icon command with custom image
try {
Image imgHome = Image.createImage("/categorybar_home_m_light.png");
cmdHome = new IconCommand("Home", imgHome, null, Command.SCREEN, 3);
} catch (IOException ex) {
}
}
}
Commands in Displayable Commands in CategoryBar

CategoryBar
// Add commands to the category bar
IconCommand[] iconCommands = {cmdHome, cmdInfo, cmdLike};
CategoryBar categoryBar = new CategoryBar(iconCommands, true); // Tabs
CategoryBar categoryBar = new CategoryBar(iconCommands, true,
CategoryBar.ELEMENT_MODE_RELEASE_SELECTED); // Actions
categoryBar.setVisibility(true); // Invisible by default
categoryBar.setElementListener(this);
public void notifyElementSelected(CategoryBar cb, int i) {
// From the ElementListener interface
// Commands coming from the Category Bar
Alert alert = new Alert("CategoryBar");
if (i == ElementListener.BACK) {
alert.setString("Back element"); // i == -1
} else {
alert.setString("Element: " + i);
}
display.setCurrent(alert);
}
Example: JavaTouch
either/or

Back on Platforms

Back Stepping
Historical navigation flow
Skipped elements
– Options / context menus
– Dialogs
– Notification Panel
– Pickers
Long-press closes current app

Back Behaviour
HW back key – must have
– App main level: exit app
– App sub level: back to upper hierarchy level
• Exception: within game – open pause menu
No SW back button allowed
– Exception: game – SW button same
behaviour as HW back key

Back Commands
Type“BACK”command: mapped to HW key
– Not visible on screen
CategoryBar: automatic back command
– Invisible on Asha Platform → mapped to HW key
cmdBack = new IconCommand("Back", Command.BACK, 3, IconCommand.ICON_BACK);
frmMain.addCommand(cmdHelp);

HW Key → Back Commands
No back command,
no category bar:
Default system dialog to
close the app.
Category bar in use
(also w/o own back command):
Callback to CategoryBar listener
with“back”code (-1).
Traditional back
command added:
Not visible on screen,
executed via HW key.

Exiting the App
3 options
– Long-press on back HW button
– Swiping out app
– Manually within app
public void exit() {
destroyApp(true);
notifyDestroyed();
}

ICONOGRAPHY
Activity Screen & Launcher Icon

Icon File
PNG Format
– 50 x 50 px square image
– Gradient background
Display
– Full square form on
activity screen
– Auto-cut to surround shape for
launcher icon

Icon Toolkit
Templates for icons
– Photoshop
– Illustrator
– Inkscape (open source)
Pre-defined background colors
bit.ly/NokiaIcons

Icons
Assign icon
– Nokia IDE: JAD editor
– NetBeans: project
properties

Colors
Free to choose
– Fit to own brand
Pre-defined Nokia colors
– Used as categories for
system apps
www.developer.nokia.com/Resources/Library/Asha_UI/#!style/colour.html

LWUIT
Customized User Interface

LWUIT
Stylable UI Components
– From Oracle: lwuit.java.net
Optimized for Nokia
– Native look & feel
– Uses Nokia APIs for
functionality
– Better performance
– Integrated in Nokia Asha SDK
• Online: projects.developer.nokia.com/LWUIT_for_Series_40

What is LWUIT?
Lightweight UI Toolkit
– Widget library inspired by Swing but designed for constrained
devices such as mobile phones and set-top boxes
UI Library
– Easily customizable UI components: lists, table, calendar, button, etc.
Themes: customizable look & feel
Transitions, animations, layout management

LWUIT Example Apps
projects.developer.nokia.com/LWUIT_for_Series_40/wiki/ExampleApplications
– LWUIT Rlinks (Reddit)
– LWUIT Slide Puzzle
– LWUIT Tourist Attractions
– LWUIT CategoryBar Demo

INTERNATIONALIZATION
JSR-238

Internationalization
JSR-238
– Format data for locales
– Locale-aware string comparison
– Translation: manage app & device resources

Formatter
Locale-specific data
– dates, times, numbers, percentages,
currency
Generic message formatting
– placeholders {n} / {nn}
Asha Emulator
Supported locales
en
kn-IN
ta
ur
// Text definitions
String txtCurrency = "Currency: {0}";
// [...]
String txtTime = "Time: {0}";
// No parameter -> would use current locale (microedition.locale)
Formatter format = new Formatter("kn-IN");
frmMain.append(Formatter.formatMessage(txtCurrency, new String[] {format.formatCurrency(currency)}));
frmMain.append(Formatter.formatMessage(txtTime, new String[] {format.formatDateTime(dateTime, Formatter.TIME_LONG)}));
Example: InternationalDemo

String Comparator
Locale-aware string
comparison
– Levels to adapt sorting
order based on needs
– JSR238: level 1 – 3 &
identical
– Default: level 1

String Comparison
Asha Emulator
Supported locales
en
en-US
en-GB
he
he-IL
sk
sk-SK
cs
cs-CZ
es
es-ES
zh
zh-CN
ja
ja-JP
Test code
Test results
StringComparator strCmpEn1 =
new StringComparator("en", StringComparator.LEVEL1);
int result = strCmpEn1.compare("a", "A");
English Level 1 Level 2 Level 3 Identical
a – a 0 0 0 0
a – A 0 0 -5 -5
a – ä 0 -14 -14 -14
0 ... both texts are considered identical
Example: InternationalDemo

Translation
ResourceManager
– Assets (strings, images, etc.) in resource files
– Different .res files for locales
– Hierarchial matching
• Avoid duplication of common resources
• Automatic matching, removes:
variant → country → language component

Tools
Localization support in Nokia IDE / NetBeans
– *Not* JSR 238
– Custom class: works on any device
Asha SDK Help
– ResourceMaker cmd tool
– Not up-to-date
WTK 2.5
– Editor tool
– Old WTK version
(current: 3.2)
IDEs create custom
classes, don’t use JSR-
238

SETTINGS & NETWORK STATE API
Adapting to the Phone State

Phone Settings
Current state & change listener subscriptions
– Flight mode
– Data connection
– Background data connection
– Roaming data connection
– Vibrator mode
– Silent mode

Setting Detection
Retrieve setting
int settingState = Setting.getSetting(Setting.SETTING_FLIGHT_MODE);
ON
OFF
INVALID
DENY
ASK
ACCEPT
WIFIONLY
SETTING_FLIGHT_MODE
SETTING_DATA_CONNECTION
SETTING_BACKGROUND_DATA_CONNECTION
SETTING_ROAMING_DATA_CONNECTION
SETTING_VIBRATOR
SETTING_SILENT
Example: PhoneSettings
State changes available via listener

Network State
Monitor state of
– Network (home / roaming)
– SIM
– WLAN

Network State Detection
Retrieve status for SIM card
int networkState = NetworkState.getState(simCard);
NETWORK_STATE_NO_NETWORK
NETWORK_STATE_HOME
NETWORK_STATE_ROAMING
0
1

SIM State Detection
Retrieve status for SIM card
int simState = SIMState.getState(simCard);
SIM_STATE_READY
SIM_STATE_NOT_READY
SIM_STATE_NO_SIM
0
1

Network State Detection
Retrieve status for WLAN
int wlanState = WLANState.getState(simCard);
WLAN_STATE_CONNECTED
WLAN_STATE_NOT_CONNECTED

FILE SELECTION
Native file browser UI

File Selection
Native file browser UI to list + select files
– Images & documents for viewing / editing
– Files for uploading to web service & as
message attachments
– Audio or video clips for playback
Blocks calling thread
– Don’t use in event handling thread
(e.g., command action)
SDK Example: FileSelectExample

Launch File Dialog
Launch file selection (in own thread)
Example: SimpleFileSelect
// Launch file selection dialog
FileSelectDetail[] arrSelectedFiles = FileSelect.launch(
FileSelect.FILE_SYSTEM_ALL, FileSelect.MEDIA_TYPE_ALL, false);
FILE_SYSTEM_ALL
FILE_SYSTEM_EXTERNAL
FILE_SYSTEM_INTERNAL
… or specific start folder, e.g.,
System.getProperty("fileconn.dir.photos")
MEDIA_TYPE_ALL
MEDIA_TYPE_APPLICATION
MEDIA_TYPE_AUDIO
MEDIA_TYPE_PICTURE
MEDIA_TYPE_VIDEO
false: single-file
true: multi-file

File Selection Results
Print metadata of selected file(s)
if (arrSelectedFiles != null) {
// Show file meta data on the screen
for (int i = 0; i < arrSelectedFiles.length; i++) {
// Display name = file name
frmMain.append("Display name: " + arrSelectedFiles[i].displayName);
// MIME type, e.g., video/mp4 or image/png
frmMain.append("MIME type: " + arrSelectedFiles[i].mimeType);
// Size of the selected file in bytes
frmMain.append("Size: " + arrSelectedFiles[i].size);
// Full path to the file
frmMain.append("URL: " + arrSelectedFiles[i].url);
}
}
Example: SimpleFileSelect

NOTIFICATIONS
Push

Notification API
Push messages to user’s
phones
– Also when app is not
running
• Notification banner
• Caches up to 5 messages
per app (for up to 14 days)
– Payload ≤ 1.5 kB
SDK Example: NNAClientExample

Notifications – Sign Up
Register new service ID
– Creates service secret
– https://account.nnapi.ovi.com/cm/
Web/services.jsp
Environments
– Sandbox for testing
– Production available after 5 days
• Separate server for China

Notifications Flow – Client
Do you want
to receive
service X
related push
notifications?
App needs to ask
user for consent
App registers with
online push
service
App retrieves
client-specific
notification ID,
sends to own
notifications web
service
1 2
Your own custom web
service, manages notification
IDs from subscribed clients

Notifications Flow – Push
User gets push
notification
Notification bar
shows details
4
3 Sandbox testing in Developer Console: push
messages without need for own web service

Notifications Flow – Retrieve
User launches app
(e.g., through
notification bar).
App registers
online.
App gets cached
push notifications.
Note: user can
turn off
notifications for
apps.

EnvironmentSelector
App for device / emulator
– Swich between push servers
C:NokiaExamplesNokia_Asha_SDK_1_0NNAClientExampleEnvironmentSelector

Client Implementation
Open session
– 1 session / app
– Keep open for lifetime of app
Register app
– Callback: stateChanged(NotificationState.STATE_ONLINE)
NotificationSession session = NotificationSessionFactory.openSession(
main, // The MIDlet instance
"example.com", // Service ID (Deprecated, but still has to be provided)
"com.example", // Application ID
this); // NotificationSessionListener
session.registerApplication();
Developer Console

Client Implementation
Get Notification ID for this phone
– Callback: infoReceived(NotificationInfo info)
– Send this to your web service
Receive messages
session.getNotificationInformation();
public void messageReceived(NotificationMessage message) {
// Get data as string
String msgData = message.getPayload().getData();
}

Notification Service
Push via REST API (HTTPS)
– From own web service
– To Nokia Notification Server
www.developer.nokia.com/Resources/Library/Java/#!developers-guides/nokia-notifications/nokia-notifications-service-api-rest-api.html

Push Messages
Messages
– App running?
• No info banner, directly delivered
– Not running?
• ≤ 5 messages cached
• Customizable: info banner, alert
Delivery confirmations
– Not part of Nokia service
– Own app can contact own web service

Message Properties
Checked: delivered also when app is NOT running
Checked: user is alerted about new message
Notification title shown to the user
Not used / shown / accessible
MIME type of payload. Default: application/octet-stream
Not used. App icon shown instead
Maximum cache lifetime (≤ 14 days)
Raw payload to send to the app
Notification ID of the client to push to

RADIO TUNER

Tuner
AM / FM radio
– Tuning
– Seeking
– Squelch
– Stereo mode
– Signal strength query
– Presets
No RDS support
Advanced Multimedia Supplements (JSR-234)
SDK Example: AMMSTuner

Seek Radio Channels
Initialize radio
Start playing
Example: Radio
// Create generic Java ME player, with the specific radio URL
player = Manager.createPlayer("capture://radio");
// Construct player
player.realize();
// Get controller to control radio (seeking, specifying properties, etc.)
tuner = (TunerControl) player.getControl("javax.microedition.amms.control.tuner.TunerControl");
// Minimum frequency in FM band to start search
curFrequency = tuner.getMinFreq(TunerControl.MODULATION_FM);
// Start playing
player.start();
// Start search for the first station
curFrequency = tuner.seek(curFrequency, TunerControl.MODULATION_FM, true);

GESTURES
Touchscreen Interaction

Touch Gestures
Use in: Canvas-/CustomItem-based classes
– Optional: combine with Frame Animator API (kinetic scrolling)
Available since Touch & Type
– Tap: touch + release
– Double Tap: touch + release + touch + release (new in Asha Platform)
– Long Press (& repeated): touch + hold
– Drag: touch + drag
– Drop: touch + drag + touch down (“stop”) + release
– Flick: touch + drag + release while dragging
– Pinch: 2x touch + 2x drag + 2x touch down (“stop”) + 2x release (new in FullTouch)

Gesture Components
App
Java Runtime
GestureAction
RegistersRegisters
Gesture
Listener
Gesture
Interactive
Zone
Gesture
Registration
Manager

Gestures – Step 1
Create a GestureInteractiveZone
// Create a GestureInteractiveZone for all Gesture Types
GestureInteractiveZone giz = new GestureInteractiveZone( GestureInteractiveZone.GESTURE_ALL );
// Set bounding rectangle of zone
giz.setRectangle( x, y, width, height );

Gestures – Step 2
Define GestureListener
// Define a GestureListener
class GestureCanvas extends Canvas implements GestureListener {
protected void paint(Graphics g) { … }
public void gestureAction( Object container,
GestureInteractiveZone zone, GestureEvent event) {
...
}
}

Gestures – Step 3
Register the GestureInteractiveZone with the
GestureRegistrationManager
// Register for Gesture events
Canvas canvas = new GestureCanvas();
GestureRegistrationManager.register( canvas, giz );
GestureRegistrationManager.setListener( canvas, canvas );

Handling gestureAction()
Process values of registered gestures
public void gestureAction( Object container, GestureInteractiveZone zone,
GestureEvent event) {
switch( event.getType() ) {
case GestureInteractiveZone.GESTURE_TAP:
case GestureInteractiveZone.GESTURE_DOUBLE_TAP:
case GestureInteractiveZone.GESTURE_LONG_PRESS:
case GestureInteractiveZone.GESTURE_LONG_PRESS_REPEATED:
case GestureInteractiveZone.GESTURE_DRAG:
case GestureInteractiveZone.GESTURE_DROP:
case GestureInteractiveZone.GESTURE_FLICK:
case GestureInteractiveZone.GESTURE_PINCH:
}
}

GestureEvent
Methods
int getType() int getPinchCenterChangeX()
int getStartX() int getPinchCenterChangeX()
int getStartY() int getPinchCenterX()
int getDragDistanceX() int getPinchCenterY()
int getDragDistanceY() int getPinchDistanceChange()
float getFlickDirection() returns flick direction in radians int getPinchDistanceCurrent()
int getFlickSpeed() int getPinchDistanceStarting()
int getFlickSpeedX()
int getFlickSpeedY()

Gesture Flick Direction
getFlickDirection returns float which is the direction in radians

Using: Gestures
Register as gesture listener
– Zone: reacts to 1+ specified gestures
• Whole screen or rectangular area
• Overlap possible
– Received events → GestureListener
public class MainCanvas extends Canvas implements GestureListener {
private int curPinchDistance = -1;
public MainCanvas() {
// Set this as container (gesture source) and listener
GestureRegistrationManager.setListener(this, this);
// Register for pinch events in the whole canvas area
gestureZone = new GestureInteractiveZone(GestureInteractiveZone.GESTURE_PINCH);
GestureRegistrationManager.register(this, gestureZone);
}
Example: PaintApp

Using: Gestures
Handling gestures
– Executed in UI thread
• Lengthy operations (scaling image, etc.) → own thread!
– Parameters only valid during call (instances reused for next call-back)
public void gestureAction(Object container, GestureInteractiveZone gestureInteractiveZone, GestureEvent gestureEvent) {
int eventType = gestureEvent.getType();
switch (eventType) {
case GestureInteractiveZone.GESTURE_PINCH: // Pinch detected
curPinchDistance = gestureEvent.getPinchDistanceCurrent(); break;
case GestureInteractiveZone.GESTURE_RECOGNITION_START: /* ... */ break;
case GestureInteractiveZone.GESTURE_RECOGNITION_END: /* ... */ break;
}
}
Example: PaintApp

LOCATION
Positioning with Cell-Ids and GPS

Network-based Positioning Accuracy
500 m 2000 m 4000 m
Urban:
50% within 250 m
80% within 500 m
100 % hit rate
100 m
Sub – Urban:
50% within 600 m
80% within 1.5 km
80-90 % hit rate
Rural:
50% within 1500 m
80% within 3 km
60-90 % hit rate
WLAN:
Up to 30m precision in
urban areas
Cell-id precision offered across Asha range of phones Only on WLAN phones

Cell ID Positioning
Specify the acceptable location methods
Get corresponding location provider
//Specify the retrieval method to Online/Cell-ID
int[] methods = {(Location.MTA_ASSISTED | Location.MTE_CELLID | Location.MTE_SHORTRANGE | Location.MTY_NETWORKBASED)};
// Retrieve the location provider
LocationProvider provider = LocationUtil.getLocationProvider(methods, null);
// 50 seconds time-out
Location loc = provider.getLocation(50000);
// Get longitude and latitude
QualifiedCoordinates coordinates = loc.getQualifiedCoordinates();
double lat = coords.getLatitude();
double lng = coords.getLongitude();
Example: mapExample

Cell ID Positioning
Approximate location using cell ID
– Online: ~ 3-10 kB per request
– Phone sends current cell ID(s) to a web service
– Gets known location of cell ID in return
Using cell ID positioning
– Request generic LocationProvider through Nokia’s LocationUtil
– No continuous updates (Listener) → 1-time, synchronous requests
• Run in own thread
– Raw cell ID: com.nokia.mid.cellid system property *
* Series 40 5th Edition FP1 +: Manufacturer & Operator Domains. Java Runtime 1.0.0+: all domains

HERE MAPS
Nokia Maps →

Maps API Features
Supports local search
and places look-up by
category
Geo-coding &
Reverse Geo-coding:
coordinates
←→
street address
Routing between any
start and end point,
taking into
consideration
transport and traffic
preferences
Lets users send images
or URL in SMS
Message
Integrated KML to
show the content
on the map
without having to
recreate it
manually
Show maps as street
map, satellite or
terrain. Custom
content: markers,
polylines

Plans
Base, Free
Unlimited 2D Map Tiles
2.500 daily limit for each other feature
Core, $1500 / month
Unlimited 2D Map Tiles
10.000 daily limit for each other feature
Traffic Tile Service including Flow and
Patterns
Service Level Agreement (SLA)
- 2D Maps Tiles, served via CDN, in Normal, Mobile, Pedestrian, Satellite/Aerial, Grey
- 2D Static Maps
- Car Routing
- Pedestrian Routing
- Geocoding
- Reverse Geocoding
- Places Discovery and Search

Maps API
Latest version included in Nokia Asha SDK
– Documentation: developer.here.com/java
Always requires AppID and Token
– developer.here.com/web/guest/myapps
C:NokiaDevicesNokia_Asha_SDK_1_0pluginsmaps api

Maps Project Template
Create empty
project
– File → New →
Java ME MIDlet
– Select Map
MIDlet
Template

Add Maps Library to Projects
Nokia IDE
Project properties →
Java Build Path →
Add External JARs...
Select relevant Maps
API jar files
Ensure Libraries are
exported

Maps Libraries
Library File Use For JAR Size (kB)
maps-core Base lib – always required 139
maps-components Map components (info bubbles, buttons,
etc)
28
maps-gesture Adds gesture support (requires Gesture API
1.2+)
7
maps-kml Process + display KML data 32
places Places, (reverse) geocoding, sharing 95
routing Routing service 21

Using: Maps
public class MapMidlet extends MIDlet implements GeocodeRequestListener {
private MapCanvas mapCanvas;
public void startApp() {
// Set registered application ID and token
ApplicationContext.getInstance().setAppID("xxx");
ApplicationContext.getInstance().setToken("xxx");
// Create new Nokia Maps canvas
Display display = Display.getDisplay(this);
mapCanvas = new MapCanvas(display) {
public void onMapUpdateError(...) {}
public void onMapContentComplete() {}
};
mapCanvas.getMapDisplay().setZoomLevel(1, 0, 0);
// Show map on the screen
display.setCurrent(mapCanvas);
}
}
Example: mapExample
// Geocode an address
GeocodeRequest geocodeRequest = SearchFactory.getInstance().createGeocodeRequest();
geocodeRequest.geocode("Vienna, Austria", null, this);
// ... center map on the latitude and longitude
public void onRequestComplete(GeocodeRequest request, com.nokia.maps.common.Location[] locations) {
mapCanvas.getMapDisplay().setCenter(locations[0].getDisplayPosition());
}

Map Marker
Place markers on the map
– Pre-defined images
– Custom images
Example: mapExample
// Set marker to position
GeoCoordinate pos = new GeoCoordinate(48.20254, 16.3688, 0.0f);
// MapFactory instantiates objects on the map
MapFactory mapFactory = mapCanvas.getMapFactory();
// Create a standard marker at the specified position
MapStandardMarker marker = mapFactory.createStandardMarker(pos);
// Set visual type of the marker
marker.setShapeType(MapStandardMarker.BALLOON);
// Add the marker to our map
mapCanvas.getMapDisplay().addMapObject(marker);

– Multiple map types – conventional
street map, satellite and terrain
– Touch support – use touch to pan
and zoom the map
– Customizable markers – set color,
labels and images
– Polygons, polylines – set colors and
transparency levels
– Overlay support – set color/labels or
use custom images
– Download indicator – provided as a
standard UI component
Map View Features

(MapsVideo1)
2GNetworkLocation
2DifferentOperators

(MapsVideo2)
2GNetworkLocation
vs3GNetworkLocation

COMPATIBILITY
Running the same app on multiple phones

Compatibility?
Source & binary compatible
– xx years old Java ME apps run on
full touch phones!
Downwards compatibility
– Check API support of target phones
– Lowest common denominator:
→ Nokia Asha SDK compiled app
runs on old phones

Porting to Touch
All Java ME apps should run on full touch phone
– High-Level UI
• Adapts automatically
• Components include touch-support
• Check layout
• New UI components (CategoryBar, etc.) don’t have to be used
– Low-Level UI
• New screen size & aspect ratio (but: most Java apps already flexible here)
• Touch supported in Java ME since many years
New APIs for Internationalization, Multitouch, Pinch, CategoryBar & Sensors
– Only work on new phones
– Careful app design even keeps downwards compatibility

Porting
Non-touch
Touchandtype
Example: RpsGame
Fulltouch
Non-touch app
with high-level
UI (LCDUI):
automatically
adapts
Asha

Dynamic API Usage
Single code base for different phones
– Code that uses new APIs
• Externalize to extra class
– Check API support at runtime
• Instantiate class if supported
• Different methods for checking available

Example: Pinch Gesture
Gesture API
– Available in Touch & Type
– Full Touch adds Pinch gesture
– Query support at runtime
Example: PaintApp
// Pinch gesture
if (GestureInteractiveZone.isSupported(GestureInteractiveZone.GESTURE_PINCH)) {
// Gesture is supported - register class as listener
GestureRegistrationManager.setListener(this, this);
// Register for pinch gesture
gestureZone = new GestureInteractiveZone(GestureInteractiveZone.GESTURE_PINCH);
GestureRegistrationManager.register(this, gestureZone);
}

Example: Optional Multitouch
Encapsulate API using code to separate class
Check support and instantiate on demand
public class MultitouchManager implements MultipointTouchListener {
public MultitouchManager(MainCanvas canvas) {
MultipointTouch mpt = MultipointTouch.getInstance();
mpt.addMultipointTouchListener(this);
}
public void pointersChanged(int[] pointerIds) { /* ... */ }
}
if (System.getProperty("com.nokia.mid.ui.multipointtouch.version") != null) {
// API is supported: Can implement multipoint touch functionality
multiManager = new MultitouchManager(this);
useMultitouch = true;
}
protected void pointerPressed(int x, int y) {
if (!useMultitouch) {
// Handle touch event
// on single-touch phone
}
}
In MainCanvas class
(extends Canvas)
Hint: only handle
Canvas.pointerPressed()
on single touch phones
Example: PaintApp

Example: API Availability
No System property for the API version?
– Check Class availability
– ClassNotFoundException? → API not supported
// Virtual keyboard support
try {
// Check if class is available
Class.forName("com.nokia.mid.ui.VirtualKeyboard");
vkbManager = new VkbManager(this);
useVkb = true;
} catch (ClassNotFoundException e) {
// Class not available: running app on Java Runtime < 2.0.0 phone.
// -> no Virtual Keyboard API support.
useVkb = false;
} catch (Exception e) { }
Example: PaintApp

Need for Threads
Protected methods
– From commandAction()
• = event dispatch thread
• Asha Platform:
Throws SecurityException
“Blocking call performed in the event thread”
→ Call from extra thread!

THANK YOU!
Andreas Jakl
Twitter: @mopius
www.mopius.com

Nokia New Asha Platform Developer Training

More Related Content

Viewers also liked

Similar to Nokia New Asha Platform Developer Training

More from Andreas Jakl

Recently uploaded

Nokia New Asha Platform Developer Training