The Complete Guide to J2ME Polish

The Solution for
Professional Wireless Java Development
1
Table of Contents
Preamble.............................................................................................................................9
Introduction to J2ME Polish............................................................................................11
Installation......................................................................................................................11
An Example Application..................................................................................................11
Building the Application..................................................................................................11
Designing the Application with CSS...............................................................................12
Debugging and Logging.................................................................................................14
Easy Device-Optimizations with Preprocessing and the Device-Database....................15
Fun Fun Fun: The Game-Engine....................................................................................16
Extending J2ME Polish..................................................................................................17
Installation........................................................................................................................18
Requirements.................................................................................................................18
Installation of J2ME Polish.............................................................................................18
Updating J2ME Polish....................................................................................................18
Integrating J2ME Polish into Eclipse..............................................................................18
Integrating J2ME Polish into Borland's JBuilder.............................................................19
Integrating J2ME Polish into NetBeans..........................................................................20
NetBeans 3.6..........................................................................................................................20
NetBeans 4.x..........................................................................................................................20
NetBeans 5.x...........................................................................................................................21
Setup and Configuration of Ant......................................................................................21
Integrating J2ME Polish with an Existing Project...........................................................22
The Device Database.......................................................................................................23
vendors.xml....................................................................................................................23
groups.xml......................................................................................................................23
devices.xml.....................................................................................................................24
apis.xml..........................................................................................................................25
Extending the Devic Database.......................................................................................26
Device Capabilities.........................................................................................................26
The Build Process............................................................................................................28
Introduction....................................................................................................................28
Definition of the J2ME Polish-task.................................................................................28
Example.........................................................................................................................28
The <info>-Section.........................................................................................................31
The <deviceRequirements>-Section..............................................................................33
The <build>-Section.......................................................................................................36
Attributes of the build-Section.................................................................................................36
Elements of the build-Section.................................................................................................39
<sources>..........................................................................................................................39
<midlet> and <midlets>......................................................................................................40
2
<iappli>...............................................................................................................................40
<resources>.......................................................................................................................41
The <filter> Subelement..............................................................................................................................42
The <fileset> Subelement............................................................................................................................42
The <localization> Subelement...................................................................................................................43
The <copier> Subelement............................................................................................................................43
The antcall Resource Copier..................................................................................................................44
The renamer Resource Copier................................................................................................................44
The svgconverter Resource Copier........................................................................................................45
<compiler>.........................................................................................................................45
The <compilerargs> Subelement.................................................................................................................47
<obfuscator>......................................................................................................................48
The <keep> Subelement..............................................................................................................................49
The <parameter> Subelement......................................................................................................................49
Combining Several Obfuscators..................................................................................................................50
Specific Obfuscator Settings........................................................................................................................50
ProGuard................................................................................................................................................50
yGuard....................................................................................................................................................50
RetroGuard.............................................................................................................................................51
Zelix KlassMaster...................................................................................................................................51
DashO Pro..............................................................................................................................................51
JODE......................................................................................................................................................52
<variables> and <variable>................................................................................................52
<debug>.............................................................................................................................54
<jad>..................................................................................................................................55
Sorting and Filtering JAD attributes............................................................................................................56
<manifestFilter>.................................................................................................................57
<preprocessor>..................................................................................................................58
<java>................................................................................................................................59
<packager>........................................................................................................................60
The <emulator>-Section.................................................................................................61
Attributes of the <emulator>-Section......................................................................................62
The <parameter> Subelement................................................................................................63
Emulator-Settings in the Device Database and in the build.xml.............................................63
WTK Emulators..................................................................................................................63
Nokia Emulators.................................................................................................................64
Siemens Emulators............................................................................................................64
Motorola Emulators............................................................................................................64
Launching any Emulator with the GenericEmulator-Implementation.................................64
Automatic Resolving of Stack Traces and Exceptions............................................................65
Resource Assembling......................................................................................................67
Concepts........................................................................................................................67
Often Used Groups........................................................................................................67
Fine Tuning the Resource Assembling..........................................................................69
Localization.......................................................................................................................70
Concepts........................................................................................................................70
The <localization>-Element and Localized Resource Assembling.................................71
Managing Translations...................................................................................................71
The Locale Class....................................................................................................................71
3
Dynamic Translations..............................................................................................................72
Defining Translations...............................................................................................................73
Setting and Using Localized Variables....................................................................................74
Using Localized Attributes.......................................................................................................74
Coping with Dates and Currencies.................................................................................74
Common Traps...............................................................................................................75
Adjusting the JAR-name.........................................................................................................75
Using Quotation Marks and Other Special Characters in Translations..................................75
Invalid Locale Calls.................................................................................................................75
Localizing the J2ME Polish GUI.....................................................................................76
The World of Preprocessing............................................................................................78
Checking a Single Symbol with #ifdef, #ifndef, #else, #elifdef, #elifndef and #endif......78
Checking Several Symbols and Variables with #if, #else, #elif and #endif....................79
Using Variable-Functions for Comparing Values....................................................................81
Hiding Code...................................................................................................................82
Debugging with #debug, #mdebug and #enddebug......................................................82
Debug Levels..........................................................................................................................83
The Debug Utility Class..........................................................................................................84
Using Variables with #=..................................................................................................84
Variable-Functions..................................................................................................................85
Setting CSS Styles with #style.......................................................................................86
Exclude or Include Complete Files with #condition........................................................87
Defining Temporary Symbols or Variables with #define and #undefine.........................87
Inserting Code Fragments with #include........................................................................88
Analyzing the Preprocessing-Phase with #message and #todo....................................88
Handling Several Values in Variables with #foreach .....................................................89
Useful Symbols..............................................................................................................90
APIs and MIDP-Version..........................................................................................................90
J2ME Polish Symbols.............................................................................................................90
Useful Variables.............................................................................................................90
File Operations........................................................................................................................91
The J2ME Polish GUI.......................................................................................................92
Overview........................................................................................................................92
Activation of the GUI......................................................................................................92
Configuring the J2ME Polish GUI..................................................................................93
Using the GUI in Full-Screen-Mode........................................................................................93
Configuring Commands, Labels and Programming of the GUI..............................................95
The J2ME Polish GUI for Programmers.........................................................................96
Setting Styles..........................................................................................................................97
Using Dynamic and Predefined Styles....................................................................................98
Porting MIDP/2.0 Applications to MIDP/1.0 Platforms............................................................99
Programming Specific Items and Screens..............................................................................99
Programming the TabbedForm..........................................................................................99
The J2ME Polish GUI for Designers............................................................................102
A Quick Glance.....................................................................................................................102
4
Designing for Specific Devices or Device-Groups................................................................103
The Hierarchy of the “resources” Folder..........................................................................103
Groups..............................................................................................................................104
API- and Java-Platform-Groups.................................................................................................................104
BitsPerPixel-Groups...................................................................................................................................104
Dynamic, Static and Predefined Styles.................................................................................105
Static Styles......................................................................................................................106
Predefined Styles.............................................................................................................106
Dynamic Styles.................................................................................................................107
Extending Styles...................................................................................................................109
CSS Syntax...........................................................................................................................109
Structure of a CSS Declaration.............................................................................................109
Naming.............................................................................................................................110
Grouping of Attributes.......................................................................................................110
Referring to Other Styles..................................................................................................110
Comments........................................................................................................................110
Common Design Attributes....................................................................................................111
Structure of polish.css......................................................................................................111
Structure of a Style Definition...........................................................................................111
The CSS Box Model: Margins and Paddings...................................................................112
The Layout Attribute.........................................................................................................113
Colors...............................................................................................................................114
Predefined Colors.......................................................................................................................................114
The colors Section......................................................................................................................................115
How to Define Colors................................................................................................................................115
Alpha Blending...........................................................................................................................................116
Fonts.................................................................................................................................116
Bitmap-Fonts....................................................................................................................117
Creating Bitmap-Fonts...............................................................................................................................117
Using Bitmap-Fonts in the J2ME Polish GUI............................................................................................117
Using Bitmap-Fonts Directly ....................................................................................................................118
Labels...............................................................................................................................118
Backgrounds and Borders................................................................................................119
Before and After Attributes...............................................................................................119
Specific Design Attributes.....................................................................................................120
Backgrounds....................................................................................................................120
Simple Background....................................................................................................................................120
Round-Rect Background............................................................................................................................120
Image Background.....................................................................................................................................121
Circle Background.....................................................................................................................................122
Pulsating Background................................................................................................................................123
Pulsating Circle Background.....................................................................................................................123
Pulsating Circles Background....................................................................................................................124
Opening Background.................................................................................................................................124
Opening-Round-Rect Background.............................................................................................................125
Round-Tab Background.............................................................................................................................126
Smooth-Color Background....................................................................................................126
Tiger-Stripes Background......................................................................................................127
Ball-Games Background.......................................................................................................127
Borders.............................................................................................................................128
5
Simple Border............................................................................................................................................128
Round-Rect Border....................................................................................................................................129
Shadow Border...........................................................................................................................................129
Top, Bottom, Left and Right Border..........................................................................................................130
Circle Border..............................................................................................................................................130
Screens: List, Form and TextBox.....................................................................................131
Predefined Styles for Lists, Forms and TextBoxes.....................................................................................131
Additional Attributes for Screens...............................................................................................................131
Dynamic Styles for Screens.......................................................................................................................133
List........................................................................................................................................................133
Form.....................................................................................................................................................133
TextBox................................................................................................................................................133
Commands.................................................................................................................................................133
Example.....................................................................................................................................................134
View Types.......................................................................................................................136
Dropping View...........................................................................................................................................136
Shuffle View..............................................................................................................................................137
MIDP/2.0 View..........................................................................................................................................137
The StringItem: Text, Hyperlink or Button........................................................................137
The IconItem....................................................................................................................138
The ChoiceItem................................................................................................................138
The ChoiceGroup.............................................................................................................139
The Gauge.......................................................................................................................140
The TextField....................................................................................................................141
TextField-Commands.................................................................................................................................142
Direct Input Mode......................................................................................................................................142
The DateField...................................................................................................................144
The Ticker........................................................................................................................145
The Menu Bar...................................................................................................................145
The Extended Menu Bar..................................................................................................146
The TabbedForm..............................................................................................................148
The MIDP/2.0-Compatible Game-Engine......................................................................149
How It Works................................................................................................................149
Limitations....................................................................................................................149
Optimizations................................................................................................................149
Using a Fullscreen-GameCanvas ........................................................................................150
Backbuffer Optimization for the TiledLayer...........................................................................150
Splitting an Image into Single Tiles.......................................................................................151
Defining the Grid Type of a TiledLayer..................................................................................151
Using the Game-Engine for MIDP/2.0 Devices.....................................................................151
Porting a MIDP/2.0 Game to MIDP/1.0 Platforms........................................................152
Building the Existing Application...........................................................................................152
Adjusting the build.xml.....................................................................................................152
Managing the Resources.................................................................................................153
Building the Game............................................................................................................154
Porting the Game to MIDP/1.0..............................................................................................154
Necessary Source Code Changes...................................................................................154
Working Around the Limitations of the Game-Engine......................................................154
Pixel-Level Collision Detection.................................................................................................................154
6
Sprite Transformations...............................................................................................................................154
Using Preprocessing for Device Specific Adjustments....................................................156
Extending J2ME Polish..................................................................................................157
Integrating a Custom Obfuscator.................................................................................157
Preparations..........................................................................................................................157
Creating the Obfuscator Class..............................................................................................157
Integrating the Obfuscator into the build.xml........................................................................158
Configuring the Obfuscator with Parameters........................................................................158
Creating and Using Custom Preprocessing Directives.................................................159
Preparations..........................................................................................................................159
Creating the Preprocessor Class..........................................................................................159
Using the registerDirective()-Method...............................................................................159
Using the processClass()-Method....................................................................................160
Integrating the Preprocessor into the build.xml.....................................................................160
Configuring the Preprocessor with Parameters....................................................................161
Extending the J2ME Polish GUI...................................................................................161
Using Custom Items..............................................................................................................161
Initialisation.......................................................................................................................161
Interaction Modes.............................................................................................................161
Traversal...........................................................................................................................161
Using CSS for Designing the CustomItem.......................................................................162
Registering Custom CSS Attributes...........................................................................................................163
Backgrounds and Borders................................................................................................164
Adding a Custom Background..............................................................................................164
Creating the Client-Side Background-Class.....................................................................164
Creating the Server-Side Background-Class...................................................................166
Integrating the Custom Background.................................................................................167
Adding a Custom Border.......................................................................................................168
Creating the Client-Side Border-Class.............................................................................168
Creating the Server-Side Border-Class............................................................................169
Integrating the Custom Border.........................................................................................170
Contributing Your Extensions.......................................................................................171
Standalone Tools............................................................................................................172
The Binary Data Editor.................................................................................................172
The Font Editor.............................................................................................................173
Non-MIDP Platforms.......................................................................................................175
Developing for BlackBerry Devices..............................................................................175
Preparations..........................................................................................................................175
Converting JARs into CODs..................................................................................................175
Signing COD Files.................................................................................................................175
Using the J2ME Polish GUI on BlackBerry Devices.............................................................176
Developing Native BlackBerry Applications..........................................................................176
Troubleshooting.....................................................................................................................176
Deactivate Obfuscation....................................................................................................176
Library...............................................................................................................................176
Developing for Palm Devices.......................................................................................177
7
Preparations..........................................................................................................................177
Converting JARs into PRCs..................................................................................................177
Starting the Palm Simulator..................................................................................................178
Developing DoJa Applications with J2ME Polish..........................................................178
Preparations..........................................................................................................................178
J2ME Polish Setup................................................................................................................178
Optional JAM Attributes.........................................................................................................179
Developing DoJa Applications under Linux and Mac OS X..................................................179
Developing for MIDP and DoJa at the Same Time...............................................................180
Cooking Tips and How-Tos............................................................................................181
Building How-Tos..........................................................................................................181
How to Use Several Source Folders.....................................................................................181
How to Integrate Third Party APIs........................................................................................181
How to Integrate a Source Code Third Party API ...........................................................181
How to Integrate a Binary Third Party API ......................................................................182
How to Integrate a Device API ........................................................................................182
How to Use Several Obfuscators Combined........................................................................183
How to Minimize the Memory Footprint................................................................................183
polish.skipArgumentCheck and polish.debugVerbose.....................................................183
Image Load Strategy........................................................................................................183
Optimizing the "polish.css" File........................................................................................183
Using Optimal Resources................................................................................................184
Use Preprocessing...........................................................................................................184
Remove Debug Code.......................................................................................................186
General Optimization Tips................................................................................................186
How to Sign MIDlets with J2ME Polish.................................................................................186
GUI How-Tos................................................................................................................187
How to Use Tables................................................................................................................187
How to Apply the J2ME Polish GUI for Existing Applications...............................................187
How to Apply Different Designs to One Application..............................................................188
How to Change the Labels of Standard-Commands and Menu-Labels...............................189
How to Enable or Disable the Usage of the GUI for a Specific Device.................................189
Trouble Shooting..........................................................................................................190
Using Subfolders for Resources...........................................................................................190
Compile Error........................................................................................................................190
Preverify Error.......................................................................................................................190
Appendix.........................................................................................................................191
Introduction to Ant........................................................................................................191
How to Use Quotation-Marks in Attributes............................................................................192
How to Specify Properties on the Command Line................................................................193
Licenses.......................................................................................................................194
GNU GPL..............................................................................................................................194
Commercial Licenses............................................................................................................194
Contact............................................................................................................................195
8
Preamble
Preamble
J2ME developers face a serious problem: either they use only the lowest-common-denominator of
J2ME devices – the MIDP/1.0 standard – or they choose to support only a few handsets, for which
they optimize their applications with a lot of energy. The open source tool J2ME Polish promises a
solution to this problem – and more.
J2ME Polish is actually a whole collection of different tools for wireless Java programmers. The
tools range from standard build tools for compiling, preverifying and packaging the applications to a
sophisticated optional GUI which can be designed with simple CSS text-files.
Following tools are included:
! Build-Tools / J2ME Polish Task: preprocessing, resource assembling, localization, compilation,
preverification, obfucation and packaging of J2ME applications. You can optimize your
application for multiple devices and languages/locales at the same time. J2ME Polish can also
invoke any emulators for you.
! Device Database: An XML-based device database provides a convenient and portable way for
adjusting your application to different devices. Together with the powerful preprocessing
capabilities you can use this database directly in your application.
! Logging Framework: The logging framework can be used to enable or disable logging levels for
classes or complete packages just by modifying some settings in the central build.xml. Messages
which are given out with System.out.println() can be shown on real devices as well! Of course
you can disable all logging completely, so that no traces are left in the application. This saves
runtime as well as memory.
! Automatic Resource Assembling: All resources like images and soundfiles are assembled
automatically for you. You can use specific resources for vendors like Nokia or for devices which
support a specific format easily. You can even include resources on conditions, so that MIDI-
soundfiles are only included when the target-device does not support MP3 but supports the MIDI
format, for example.
! Localization: It's easy to create localized applications – just provide the translations and – if you
like – other locale specific resources and J2ME Polish will embed them into the application. In
contrast to all other solutions, localized applications do not have an overhead compared with
non-localized applications, since the translations are actually integrated on the source-code level.
! GUI: The standard J2ME widgets cannot be designed at all. With J2ME Polish you can use the
standard MIDP/1.0 as well as MIDP/2.0 widgets in your program and design them with simple
CSS-directives like “background-image: url( bg.png );”. Web-designers can now design
the application independently of programmers and designs can be adjusted easily for different
handsets. You can even use MIDP/2.0 widgets like the CustomItem on MIDP/1.0 phones!
! Utilities: Some often used components like the fast ArrayList or the TextUtil for managing
font-based texts can be used for solving day-to-day problems.
! Game-Engine: With the highly-optimized game-engine you can use the MIDP/2.0 API for
MIDP/1.0 devices as well. J2ME Polish takes care for the porting! You can also adjust the API,
e.g. by specifying that a backbuffer-optimization should be used for TiledLayer etc.
9
Preamble
! Stand-alone Tools: The binary data editor can be used for editing any structured binary data files
much more comfortable than a hex-editor. An often needed feature are level-data files, which are
easy to manage with the binary data editor. Another tool is the bitmap font editor, which can be
used for creating bitmap fonts out of any True Type fonts.
Obviously you can also extend and use the more advanced features of the J2ME Polish framework.
You can use your own widgets, add your own preprocessor, or integrate your own obfuscator with
ease.
Migrating to J2ME Polish is easy, since it is based on Ant. Ant is the standard for building Java
applications and is supported by all IDEs. You can invoke J2ME Polish either from within your IDE
of choice or from the command line.
I hope you find J2ME Polish useful and have fun with it!
Bremen/Germany, November 2005
Robert Virkus / Enough Software
10
Introduction to J2ME Polish
Introduction to J2ME Polish
This chapter introduces you to some of the possibilities of J2ME Polish. If you want to know
specific details, please refer to the following chapters.
Installation
J2ME Polish contains a graphical installer which can be
started by double-clicking the downloaded jar-File or by
calling “java -jar j2mepolish-[VERSION].jar” from the
command line, e.g. “java -jar j2mepolish-1.1.jar”.
An Example Application
For this introduction we use a simple application as an
example. The application just shows a simple menu which
is typical for many J2ME applications (listing 1). This is
the sample application which is included into the
J2ME Polish distribution.
Building the Application
To build the application with J2ME Polish we
need to create a file called “build.xml” which
controls the build process. This is a standard
Ant file, so most IDEs support the editing of
this file with syntax highlighting, auto
completion etc. Don't worry if you have never
worked with Ant before – although it can look quite scary at the beginning it is easy to master after
a while. The build.xml file is also included in the J2ME Polish distribution, the main parts of it are
shown in listing 2. To build the sample application, we need to right-click the build.xml within the
IDE and select “Execute”, “Run Ant...” or “make” depending on the IDE. The build process can
also be started from the command-line: enter the installation directory and type the “ant” command.
J2ME Polish now preprocesses, compiles, preverifies obfuscates and packages the code
automatically for a number of devices. The resulting application bundles can be found in the “dist”
11
J2ME Polish: Overview
Editions: GPL (for Open Source
products), Single License (199,-€ valid
for one J2ME application), Runtime
License (199,-€ valid for an arbitrary
number of applications which can only
be installed a 100 times), Enterprise
License (2990,-€ valid for any number
of applications). An additional
“Developer Seat” license needs to be
obtained for every developer (99,- € ).
Operating Systems: Windows, Linux,
Mac OS X
Prerequisites: Java Wireless Toolkit,
Ant
Build-Process: preprocessing, device-
optimization, resource assembling,
localization, device-database,
compiling, preverifying, obfuscating,
signing of MIDlets, creation of jar and
jad files
GUI: Design via CSS, 100% compatible
to the MIDP standard, optional.
Game-Engine: MIDP/2.0 game-API for
MIDP/1.0 devices.
www.j2mepolish.org
Listing 1: MenuMidlet.java
public class MenuMidlet extends MIDlet {
List menuScreen;
public MenuMidlet() {
super();
System.out.println("starting MenuMidlet");
this.menuScreen = new List("J2ME Polish",
List.IMPLICIT);
this.menuScreen.append("Start game", null);
this.menuScreen.append("Load game", null);
this.menuScreen.append("Help", null);
this.menuScreen.append("Quit", null);
this.menuScreen.setCommandListener(this);
System.out.println("intialisation done.");
}
protected void startApp() throws
MIDletStateChangeException {
System.out.println("setting display.");
Display.getDisplay(this).setCurrent(
this.menuScreen );
}
[...]
Introduction to J2ME Polish
folder after J2ME Polish finished the build.
To understand and control the build process,
we need to have a closer look at the
build.xml (listing 2):
At first the J2ME Polish Ant-task needs to
be defined with the <taskdef> construct.
The Ant-property “wtk.home” points to the
installation directory of the Wireless
Toolkit.
The J2ME Polish task has the three main-
sections “<info>”, “<deviceRequirements>”
and “<build>”. The <info>-element
specifies some general information about the
project like the name and the version. The
<deviceRequirements>-element is used to
select the devices for which the application
should be builded. The <build>-element is
the central controller of the actual build
process. This element controls whether the
J2ME Polish GUI should be used, what
MIDlets are used, which obfuscators should
be used, and so on. Here you can also define
additional variables and symbols which can
be used in the preprocessing step.
You can also use the additional section “<emulator>” for launching any WTK-based emulators from
within J2ME Polish.
Designing the Application with CSS
Even though the application just uses plain MIDP code, we can use the J2ME Polish GUI by setting
the “usePolishGui”-attribute of the <build>-element to true (listing 2). J2ME Polish then “weaves”
the necessary code and APIs into the application automatically. For specifying or changing the
design, the file “polish.css” in the folder “resources” needs to be created or changed (listing 3). As
you might have guessed, this file is included in the J2ME Polish distribution as well.
The “polish.css” file contains the style definitions for all items and screens of the application. First
we define the used colors in the “colors” section. By doing so we can later change the colors of the
complete application in one place.
The “title”-style is used for designing the screen-titles. The “focused”- style is used for designing
the currently focused item, e.g. of a form or a list.
As we have not used any #style preprocessing directives in the code, we need to use “dynamic”
style-selectors like “list” and “listitem” for designing the application. All settings specified in the
“list”-style are used for designing screens of the type “list”. And all settings specified in the
“listitem”- style are used for items which are embedded in a list.
12
Listing 2: build.xml
<project name="example" default="j2mepolish">
<property name="wtk.home" value="C:\wtk2.1">
<taskdef name="j2mepolish"
classname="de.enough.polish.ant.PolishTask"
classpath="import/enough-j2mepolish-
build.jar:import/jdom.jar:import/proguard.jar
"/>
<target name="j2mepolish">
<j2mepolish>
<info
name="SimpleMenu"
version="1.0.0"
description="A test project"
jarName="${polish.vendor}-${polish.name}-
example.jar"
jarUrl="${polish.jarName}"
</info>
<deviceRequirements>
<requirement name="JavaPackage"
value="nokia-ui" />
</deviceRequirements>
<build
fullscreen="menu"
usePolishGui="true"
<midlet class="MenuMidlet" name="Example"/>
</build>
</j2mepolish>
</target>
</project>
Introduction to J2ME Polish
All styles support the common attributes margin,
padding, layout, font, background and border as
well as the special attributes before and after. Most
items do also support specific attributes.
The “list”-style in the example utilizes the specific
attribute “columns” for specifying that a table with
two columns should be used for the list (figure 1).
Designs and
resources like
images and so on
can be adjusted to
different devices by
placing them into
the appropriate
subfolder of the
“resources” folder.
For using a different
design for Nokia
phones you can add
the file “resources/
Nokia/polish.css”
and for using a
special design for the Nokia/6600 phone you can
add the file “resources/Nokia/6600”, etc. The same
is true for other resources like images or sound-
files. The resource-assembling does work
independently of the usage of the J2ME Polish GUI
by the way.
When an application has more than one screen and
the screens should have different designs, one need
to use “static” styles. In contrast to dynamic styles,
static styles are added during the compilation phase
and are, therefore, faster and more memory-
efficient. Static styles, however, need changes in the
application-code:
For using a static style, the #style-preprocessing-
directive is used. This directive can be placed before any constructor of a screen or an item (and
some more places like the List-append()-methods) within the code.
public MenuMidlet() {
super();
System.out.println("starting MenuMidlet");
//#style mainScreen
this.menuScreen = new List("J2ME Polish", List.IMPLICIT);
//#style mainCommand
this.menuScreen.append("Start game", null);
//#style mainCommand
13
Listing 3: polish.css
colors {
bgColor: rgb(132,143,96);
brightBgColor: rgb(238,241,229);
brightFontColor: rgb(238,241,229);
fontColor: rgb( 30, 85, 86 );
}
title {
padding: 2;margin-bottom: 5;
font-face: proportional; font-size:
large; font-style: bold; font-color:
brightFontColor;
background: none; border: none;
layout: center | expand;
}
focused {
padding: 5;
background {
type: round-rect; arc: 8; color:
brightBgColor; border-color:
fontColor; border-width: 2;
}
font {
style: bold; color: fontColor;
size: small;
}
layout: expand | center;
}
list {
padding: 5; padding-left: 15; padding-
right: 15;
background {
color: transparent;
image: url( bg.png );
}
layout: expand | center | vertical-
center;
columns: 2;
}
listitem {
margin: 2; !"##$%&'()*(+",-&./0%#'
(%/%1*(2/%34,/5/.'(2/%36/5/.*(2/%34
(73851'(+/5#*(2/%347$91'(7:"55*
layout: center;
icon-image: url( icon%INDEX%.png );
icon-image-align: top;
;
Fig. 1: The designed sample
application.
Introduction to J2ME Polish
this.menuScreen.append("Load game", null);
//#style mainCommand
this.menuScreen.append("Help", null);
//#style mainCommand
this.menuScreen.append("Quit", null);
//#style mainCommand
this.menuScreen.setCommandListener(this);
System.out.println("intialisation done.");
}
Instead of using the “list” and the “listitem”-styles in the polish.css, you now need to use the styles
“mainCommand” and “mainScreen”. Since these are static styles, they need to start with a dot in the
polish.css file:
.mainScreen {
padding: 5; padding-left: 15; padding-
[...]
}
.mainCommand {
margin: 2; !"##$%&'()*(+",-&./0%#'
(<===>
;
With using the #style-preprocessing directive the code still remains 100% compatible to the MIDP
standard, so one use the native/standard GUI for very old devices while using the J2ME Polish GUI
for modern devices at the same time.
You can specify in the build.xml file what “resources” folder should
be used. This mechanism can be used to create different designs of
one application. Figure 2 shows the sample application with a
different design. This design is also included in the J2ME Polish
distribution and can be used when the “resDir”-Attribute is set to
“resources2” in the build.xml.
Debugging and Logging
Logging and debugging is complex and difficult task under J2ME.
On one hand logging messages need memory as well as computing
time and on the other hand there are no logging frameworks like
log4j available for J2ME. This is why J2ME Polish includes such a
framework with these features:
! Logging-levels like debug, info, warn, error etc. can be defined
for single classes or packages.
! User-defined levels can be used, too.
! Logging-messages can be viewed on real devices as well.
! Logging-messages which are not active, will not be compiled and use, therefore, no resources at
all.
! The complete logging can be deactivated.
! Simple System.out.println()-calls are used for logging.
The logging is controlled with the <debug> -element in the “build.xml” file :
14
Fig. 2: The same application with
another design. The background is
actually animated: it starts white
and dithers to the shown pink.
Introduction to J2ME Polish
?#1+0&(1%"+51@A3.01A(7B/CD/&E%F../.@A3.01A(G1.+/71@A2"571A(51G15@A1../.AH
<filter pattern="com.company.package.*" level="info" />
<filter pattern="com.company.package.MyClass" level="debug" />
?I#1+0&H
The “enable”-attribute defines whether logging should be activated at all. The
“showLogOnError”-attribute can be used for showing the log automatically, whenever an error has
been logged. This only works when the GUI of J2ME Polish is used, though. An error can be logged
just by appending the error object to a System.out.println()-call:
try {
callComplexMethod();
//#debug info
System.out.println( "complex method succeeded." );
} catch (MyException e) {
//#debug error
System.out.println( "complex method failed" + e ); // when showLogOnError is true
} // this will trigger the log
When the “verbose”-attribute is true, after each logging message the current time and the source-
code file as well line of the message will be added. This eases the location of errors especially when
obfuscation is used. The J2ME APIs of J2ME Polish will also specify details of errors whenever
they throw an exception, when the “verbose”-attribute is true. The “level“-attribute controls the
general logging-level which is used when no specific level has been assigned for a class. The
logging-levels are hierarchically ordered:
debug < info < warn < error < fatal < user-definiert
When a class has the logging-level “info” assigned, messages with a level of “warn”, “error” and so
on will also be logged, but no “debug” messages.
In the source code logging messages will be introduced with the #debug-preprocessing-directive,
which can specify the logging-level, e.g. “//#debug info”. When no level is specified the “debug”
level is assumed.
Easy Device-Optimizations with Preprocessing and the Device-Database
Device optimizations are mostly needed for the user interface of an application. The UI of
J2ME Polish adapts automatically to devices and can – thanks to the resource assembling – be
easily adjusted to different devices and device-groups.
There are however, other situations in which device optimizations are useful. With the help of the
preprocessing capabilities and device database of J2ME Polish, these optimizations are done easy
and without risking the portability of the application.
Often the preprocessing directives “#ifdef”, “#if” and “#=” are used for optimizations:
When an API is required for a specific functionality, just use the “polish.api.[api-name]” symbol,
which is defined for each supported API:
//#if polish.api.mmapi
// this device supports the Mobile Media API
[...]
//#else
// this support does not support the mmapi
[...]
//#endif
15
Introduction to J2ME Polish
One can differentiate between MIDP-versions with the “polish.midp1” and the “polish.midp2”
symbol:
//#if polish.midp2
// this device supports MIDP/2.0 standard
[...]
//#else
// this support does support the MIDP/1.0 standard
[...]
//#endif
To distinguish between the CLDC/1.0 and the CLDC/1.1 standard, the “polish.cldc1.0” and
“polish.cldc1.1” symbols can be used:
//#if polish.cldc1.1
float f = 1.2f;
[...]
//#endif
Several requirements can be combined, too:
//#if polish.api.mmapi || polish.midp2
// this device supports at least the basic Mobile Media API
[...]
//#endif
One can compare variables as well:
//#if polish.BitsPerPixel >= 12
// this device uses at least 12 bits per pixel.
//#endif
//#if polish.Vendor == Nokia
// this is a Nokia device
//#endif
Variables can be defined as well and be used within the source code. An URL could be defined in
the build.xml like this:
<variables>
<variable name="update-url" value="http://www.enough.de/update" />
</variables>
The defined variable can be used in the source code with the “#=”-directive:
//#ifdef update-url:defined
//#= public static final String UPDATE_URL = "${ update-url }";
//#else
// no variable definition was found, use a default-value:
public static final String UPDATE_URL = "http://default.com/update";
//#endif
Fun Fun Fun: The Game-Engine
The game-engine of J2ME Polish lets you use the Game-API of the MIDP/2.0 standard for
MIDP/1.0 devices as well. No changes in the source-code are necessary, since the necessary API is
weaved into the application automatically for MIDP/1.0 devices.
The complete API can be used: Sprite, GameCanvas, TiledLayer, LayerManager and Layer. The
16
Introduction to J2ME Polish
current limitations are that no pixel-level collision-detections and no sprite-transformations for non-
Nokia devices are supported (for Nokia devices sprite transformations are supported).
The game-engine can be optimized for several usage scenarios, you can specify that the backbuffer-
optimization should be used for the TiledLayer implementation, for example.
Extending J2ME Polish
J2ME Polish can be extended in several ways:
Build-Tools:
! Obfuscator: integrate your own (or a third party) obfuscator
! Preprocessing: add your own preprocessing directives
! You can also use the <java>-element to extend J2ME Polish
GUI:
! Backgrounds and Borders: custom borders or backgrounds enhance the possibilities
! Items: extend and use standard CustomItems – and design them using CSS
How these extensions are implemented is described in the “Extending J2ME Polish Chapter” on
page 157.
The <java>-element is described on page 59.
17
Installation
Installation
Requirements
To use J2ME Polish, following components need to be installed:
! Java 2 Standard Edition SDK 1.4 or higher, http://java.sun.com/j2se/1.4.2/index.jsp
! Java Wireless Toolkit, http://java.sun.com/products/j2mewtoolkit/index.html,
or http://mpowers.net/midp-osx/ for Mac OS X
! Favorite IDE, for example Eclipse 3.0, http://www.eclipse.org
! Ant 1.5 or higher, if not already integrated in the IDE, http://ant.apache.org
Installation of J2ME Polish
For installing J2ME Polish download the latest release and start the installation either by double-
clicking the file or by calling "java -jar j2mepolish-$VERSION.jar" from the command-line (where
$VERSION denotes the current version of J2ME Polish).
The installer of J2ME Polish contains a sample MIDlet application with two different designs. This
application is optimized for Nokia Series 60 devices, so it is recommended to have such an emulator
installed. The Nokia emulator can be retrieved from http://forum.nokia.com.
To build the sample application, run the included “sample/build.xml” from your favorite Java IDE
or call "ant" from the command-line, after you have switched to the “sample” directory. Call "ant
test j2mepolish" to skip the obfuscation and to include debug-information of the sample application.
Also the default emulator is launched with the application.
Updating J2ME Polish
When you want to update an existing installation, you do not need to re-install the whole package.
For saving bandwidth you can download just the update-package. This package contains the two
JAR-files “enough-j2mepolish-build.jar” and “enough-j2mepolish-client.jar” which need to be
copied into the "import"-folder of your installation directory.
Integrating J2ME Polish into Eclipse
To integrate J2ME Polish into Eclipse the easiest way is to copy one of the sample applications
(from the “samples” folder of your J2ME Polish installation) in your workspace, for example the
“menu” application. Then start Eclipse and create a new project called "application". Eclipse then
automatically integrates all source-files and sets the classpath. You should find the sample
application now in the Package-Explorer (package de.enough.polish.example).
If the sources have not been integrated automatically, set the source-directory of the project to the
“src” directory: Select “Project” -> “Properties...” -> “Java Build Path” -> “Source” and add the
source-folder “src” there.
When the classpath was not set correctly, please include the following jar-files from the
“${polish.home}/import” folder to your classpath: import/midp2.jar, import/enough-j2mepolish-
client.jar, import/mmapi.jar, import/nokia-ui.jar, import/wmapi.jar. Actually only the first two
18
Installation
libraries are needed for the sample application, but when the others are included, future
enhancements are easier to accomplish.
Optionally you can change the build-settings by modifying the file "build.xml" (which is located in
the root of the sample project). For example you can change the deviceRequirements if you want to.
The example is optimized to Nokia Series 60 devices.
You can now create the JAR and JAD files by right-clicking the “build.xml” file, selecting "Run
Ant" and running Ant in the next dialog. You will find the JAR and JAD files then in the "dist"
folder of the project. If you want to access them from within Eclipse, you might need to refresh your
project: Right-click the project and select "Refresh".
If the “Run Ant...” command is not shown, select the “build.xml” file, then open the Menu “Run”
and select “External Tools” -> “Run as” -> “Ant Build”.
After you have integrated the sample application into Eclipse, you will find following structure in
your project (assuming that your project is called “sample” and your workspace “workspace”):
Folder / File Description
workspace/ sample The applications project
workspace/sample/build.xml The controller of the build process
workspace/sample/resources Folder for all resources and design descriptions of the project
workspace/sample/resources/polish.css Basic design description
workspace/sample/build Temporary build folder, will be created automatically. Should not
be shared in CVS and similar systems.
workspace/sample/dist Folder for the ready-to-deploy applications. It will be created
automatically. Should not be shared in CVS and similar systems.
Integrating J2ME Polish into Borland's JBuilder
To integrate J2ME Polish into JBuilder it is best to copy the sample application (the “sample”
folder of your J2ME Polish installation) in your workspace. Then start JBuilder and create a new
project called "sample".
In the project-dialog select the appropriate path and confirm the “src” folder as the main source-
folder. Switch to the “Required Libraries” tab and select “Add...” and then “New...”. Enter “MIDP-
Development” or similar as the name of the library and add the files “enough-j2mepolish-client.jar”,
“midp2.jar”, “mmapi.jar”, “wmapi.jar” and “nokia-ui.jar” from the “${polish.home}/import” folder
to the library path.
Note: only the first two files are actually needed by the sample application, but if you later want to
explore the full possibilities of J2ME Polish you already have all important libraries included.
Now create the new project.
After the project has been created, you need to integrate the provided “build.xml” file: Select
“Wizard” -> “Ant” -> “Add...” and select the file “build.xml” in the project-root. Now the
“build.xml” is shown in the project-view. Important: you need to deactivate the Borland-compiler
19
Installation
for building the actual applications: Right-click the “build.xml” file, select “Properties...” and de-
select the “Use Borland Java compiler” check box.
You can now build the sample application by right-clicking the “build.xml” file and selecting
“Make”. You will find the created J2ME application files in the “dist” folder of your project, after
you have switched to the “File Browser” view.
Integrating J2ME Polish into NetBeans
NetBeans 3.6
For integrating J2ME Polish with NetBeans 3.6 mount the installation directory of your J2ME
Polish installation, right-click the "sample/build.xml" file and choose "Execute".
! Create a New Project: Go to "Project" -> "Project Manager" and select "New..." and call the new
project "j2mepolish".
! Mounting the Filesystem: Select "File" -> "Mount Filesystem..." -> "Local Directory" and select
the folder into which you have installed J2ME Polish.
Note: Don't navigate into the directory. Just select the J2ME Polish directory and click "Finish".
! Executing J2ME Polish: Open the mounted file-system (switch to the file-system-window by
pressing "Control-2"), locate the file "sample/build.xml", right-click it and select "Execute".
After the execution you will find the created applications in the "dist" folder.
! Mounting the Libraries: Open the mounted file-system, open the "import" directory and right-
click the "enough-j2mepolish-client" jar and select "Mount JAR". Do the same with the libraries
"midp2", "mmapi", "nokia-ui" and "wmapi".
! Open the Sample Application: You can now change the sample application, if you want to. You
can find it in the "sample/src" directory (in the package "de.enough.polish.example").
NetBeans 4.x
For integrating J2ME Polish with NetBeans 4.0 create a new project and copy the sample project
from ${polish.home}/sample into your new project with a file-manager. Right-click the build.xml
and choose "Run Target" > "j2mepolish" for running the example.
! Create a new project: Go to "File" -> "New Project" and select "Mobile" -> "Mobile
Application" as your project type. Give the project any name and choose any folder as the
project's home. De-select the "Create Hello MIDlet"-option and select "Finish" to create the
project.
! Copy the sample project: Navigate to the "${polish.home}/sample" directory with your file-
manager (e.g. Windows Explorer on Windows or Finder on Mac OS X). Select the "resources",
"resources2" and "src" folders as well as the "build.xml" file and copy all into the folder of your
NetBeans project. Overwrite any existing files.
! Return to NetBeans, right-click your new project in the "Projects" view and select "Refresh
Folders". You can now view the sample application in the "de.enough.polish.example" package.
! Right-click your project again and select "Properties". Go to "Build" and select "Libraries and
Resources". Select "Add Jar/Zip" and add the "${polish.home}/import/enough-j2mepolish-
20
Installation
client.jar" file to your project.
! Now switch to the "Files" view and right-click the "build.xml" file. Select "Run Target" >
"Advanced". Write "test, j2mepolish" in the following dialog, so that the "test" target is executed
first, followed by the "j2mepolish" target. J2ME Polish now executes and starts the WTK
emulator.
NetBeans 5.x
J2ME Polish provides NetBeans specific build scripts from J2ME Polish 1.3 Beta 3 onwards. You
can now just open any of the provided sample applications, delete the default build.xml script and
rename the build-netbeans.xml script to build.xml. You can from then on use the normal debugging,
build and compile facilities of NetBeans.
Integrating a sample application in NetBeans:
! Select File > Open Project... and select any sample application in ${polish.home}/samples. Just
select a folder like the menu folder and select Open.
! Now switch to the Files window by selecting Window > Files.
! In this window delete or rename the build.xml script which is in the base folder of the project.
! Now right-click the build-netbeans.xml script and rename it to build.xml. When the renaming
does not work, do it directly from the file system (e.g. Windows Explorer).
! From now on you can build, run, debug and compile with the normal NetBeans commands (e.g.
F5 for debugging). J2ME Polish is then used for building etc.
When you start a new project in NetBeans, just copy one of the sample build.xml scripts to your
project's folder. Then adjust the settings according to your needs.
Setup and Configuration of Ant
Ant only needs to be configured when it should be called from the command-line. Since Ant is
integrated in every modern Java-IDE, you just need to right-click the “build.xml”-file in your IDE
and choose “Run Ant...” (or similar).
After you have downloaded and installed Ant (http://ant.apache.org), you need to set your PATH-
environment variable, so that the “ant”-command can be found. If you have installed Ant into
“C:\tools\ant” then enter following command on your Windows-command-line (or your shell-
script):
SET PATH=%PATH%;C:\tools\ant\bin
You can change the PATH variable permanently in the System-Settings of Windows (Control Center
-> System -> Advanced -> Environment variables).
Now you need set the JAVA_HOME variable as well, e.g.:
SET JAVA_HOME=C:\j2sdk1.4.2
Under Unix/Linux/Mac OS X please use the “export” command instead of the “SET” command.
Now you should be able to issue following calls from the command-line (make sure that you are in
21
Installation
the “sample” folder of your J2ME Polish installation):
echo Just calling ant to build and obfuscate the example:
ant
echo Now calling ant with the test-property set to true, so the build is faster:
ant test j2mepolish
Integrating J2ME Polish with an Existing Project
You can use J2ME Polish for any existing project by copying the file "sample/build.xml" as well as
the "sample/resources" folder to the root-folder of the project. You then need to adjust the
"build.xml" and the "resources/polish.css" files.
Here are the required steps:
! Copy the "sample/build.xml" and the "sample/resources" folder to your project-root.
! Move your resources like images, sound-files etc into the “resources” folder of your project.
Remember that you cannot use subfolders for resources, since subfolders are used for the
automatic resource assembling of J2ME Polish (see page 67).
! Adjust the "build.xml" file: you need to specify your MIDlet class in the <midlet> element. You
might also want to adjust the <deviceRequirements> element, currently applications are build for
4 device-groups:
1) Nokia Series 60 ("Nokia/Series60"),
2) Nokia Series 60 with MIDP/2.0 ("Nokia/Series60Midp2"),
3) Any MIDP/1.0 phone("Generic/midp1"),
4) Any MIDP/2.0 phone ("Generic/midp2").
! If you want to use the J2ME Polish GUI, you need to make changes to the "resources/polish.css"
file.
Tip: use dynamic styles like "form" and "list" for a start. Have a look at the how-to explaining the
first steps for using the J2ME Polish GUI on page 187.
! If you do not want to use the J2ME Polish GUI, disable it by setting the "usePolishGui"-attribute
of the <build>-element to "false".
! Ensure that your Ant-setup is correct, do you have set the JAVA_HOME environment variable?
! Call “ant” within your project root to build your application.
22
The Device Database
The Device Database
All J2ME devices are defined in the file “devices.xml”. Every device has a vendor, which is defined
in the file “vendors.xml”. Every device can belong to an arbitrary number of groups, which are
defined in the file “groups.xml”. Libraries can be managed using the file “apis.xml”.
All these files are contained in the file “enough-j2mepolish-build.jar”, so when you do not find
them, extract them from the jar file into the root folder of the project.
vendors.xml
The vendors of J2ME devices are defined in vendors.xml. An example definition is:
?G1%#/.7H
?G1%#/.H
?%":1HJ/-$"?I%":1H
?21"30.17H?I21"30.17H
?,"!"+$5$38(%":1@A,/5/.7=2/,07A(G"501@AKL))))MMA(IH
?IG1%#/.H
?G1%#/.H
?%":1HN$1:1%7?I%":1H
?IG1%#/.H
?IG1%#/.7H
In this code 2 vendors are defined – Nokia and Siemens. Vendors can possess features and
capabilities, which are inherited by all devices of that vendor. These abilities can be used during the
preprocessing (compare chapter “The world of preprocessing”, page 78). Features are just a comma
separated list, whereas capabilities always have a name and a value.
You can define your own vendors in the custom-vendors.xml file. This allows you to use your own
vendors without needing to merge the vendors.xml file with each update of J2ME Polish. The
custom-vendors.xml file is loaded from the current project folder and – if that file doesn't exist –
from the J2ME Polish installation folder.
groups.xml
The device groups are defined in the file groups.xml. A device can be a member in any number of
groups.
?&./0!7H
?&./0!H
?%":1HJ/-$"4OP?I%":1H
?21"30.17H?I21"30.17H
?,"!"+$5$38(%":1@A,5"7717=20557,.11%A(
G"501@A,/:=%/-$"=:$#=0$=Q0556"%G"7A(IH
?,"!"+$5$38(%":1@AR"G"S",-"&1A(G"501@A%/-$"40$A(IH
?I&./0!H
?&./0!H
?%":1HN1.$17TK?I%":1H
?!".1%3HJ/-$"4OP?I!".1%3H
?,"!"+$5$38(%":1@AR"G"S5"32/.:A(
G"501@AUPMSIV=KA(IH
?I&./0!H
?I&./0!7H
23
The Device Database
The group “Nokia-UI” is used for devices which support the UI API of Nokia. The group
“Series60” extends this group. Any capabilities or features defined in the groups can be overridden
or completed by the device definitions.
You can define your own groups in the custom-groups.xml file. This allows you to use your own
groups without needing to merge the groups.xml file with each update of J2ME Polish. The
custom-groups.xml file is loaded from the current project folder and – if that file doesn't exist –
from the J2ME Polish installation folder.
devices.xml
In devices.xml all J2ME devices are defined.
?#1G$,17H
?#1G$,1H
?$#1%3$2$1.HU/3/./5"I$WXK?I$#1%3$2$1.H
?071.4"&1%3HUEY$WXK?I071.4"&1%3H
?,"!"+$5$38(%":1@AN/23C".1S5"32/.:=R"G"S5"32/.:A
G"501@AUPMSIZ=KA(IH
?,"!"+$5$38(%":1@A[".#C".1S5"32/.:=N,.11%N$91A
G"501@AVXKLVXKA(IH
?,"!"+$5$38(%":1@A[".#C".1S5"32/.:=\$37S1.S$L15A
G"501@AVTA(IH
?,"!"+$5$38(%":1@A[".#C".1S5"32/.:=6":1."]17/503$/%A
G"501@AXKKLZKKA(IH
?,"!"+$5$38(%":1@AN/23C".1S5"32/.:=R"G"S./3/,/5A
G"501@AOMS^(Y6S^(NND^([YYS^([YYSN^(N1.$"5A(IH
?,"!"+$5$38(%":1@AN/23C".1S5"32/.:=R"G"S",-"&1A
G"501@AC:"!$^(::"!$^(:/3/./5"45C3^(5/,"3$/%4"!$A(IH
?,"!"+$5$38(%":1@AN/23C".1S5"32/.:=[1"!N$91A
G"501@AV=V)(U\A(IH
?,"!"+$5$38(%":1@AN/23C".1S5"32/.:=U"LR".N$91A
G"501@A)KK(-+A(IH
?I#1G$,1H
?#1G$,1H
?$#1%3$2$1.HJ/-$"ITTKK?I$#1%3$2$1.H
?071.4"&1%3HJ/-$"TTKK?I071.4"&1%3H
?&./0!7HN1.$17TK?I&./0!7H
?21"30.17HB"76":1."?I21"30.17H
?,"!"+$5$38(%":1@AN,.11%N$91A(G"501@AVWTLZK_AIH
?,"!"+$5$38(%":1@A\$37S1.S$L15A(G"501@AVTAIH
?,"!"+$5$38(%":1@AR"G"S",-"&1A(G"501@A::"!$^(+3"!$^(C:"!$A(IH
?,"!"+$5$38(%":1@AR"G"S5"32/.:A(G"501@AUPMSIZ=KA(IH
?I#1G$,1H
?I#1G$,17H
In the example the Motorola Ident 730 and the Nokia 6600 are defined. Capabilities can be grouped
into hardware- and software-capabilities. This grouping is optional and will not be distinguished in
the preprocessing step, thus one cannot use the same name for a SoftwarePlatform and a
HardwarePlatform capability.
The identifier consists of the vendor and device-name. The structure is “[vendor]/[device-name]”.
The <features>-element defines preprocessing symbols. These can be checked in the source code for
example with “//#ifdef [symbol-name]“. Several features need to be separated by comma:
?21"30.17HB"7S/$%31.FG1%37^(B"7S/$%31.FG1%37?I21"30.17H
Groups can be defined explicitly with the <groups>-element. All group-names to which the device
24
The Device Database
belongs are in a comma separated list:
?&./0!7HN1.$17TK^(N/:1`./0!?I&./0!7H(defines 2 groups for the device. Groups can also be
defined indirectly by the capabilities of the device.
The <device>-Element supports the single attribute “supportsPolishGui”:
?#1G$,1(70!!/.37S/5$7B`0$@A3.01AH===
Normally it is calculated whether a device supports the J2ME Polish GUI: when it has a color depth
of at least 8 bits per pixel and a heap size of 500 kb or more, the device supports the GUI. The
“supportsPolishGui”-attribute overrides this calculation.
You can define your own devices in the custom-devices.xml file. This allows you to use your own
devices without needing to merge the devices.xml file with each update of J2ME Polish. The
custom-devices.xml file is loaded from the current project folder and – if that file doesn't exist –
from the J2ME Polish installation folder.
apis.xml
The file apis.xml defines some common libraries. You do not need to add every API you or your
device supports, but if a API is known under several names, it is advised to add that API to
apis.xml.
?"!$7H
?"!$H
?%":1HJ/-$"(O71.(P%31.2",1(aSP?I%":1H
?#17,.$!3$/%HYB1(J/-$"(O71.(P%31.2",1(aSP(!./G$#17
7/:1("#G"%,1#(#."C$%&(20%,3$/%"5$3$17=
?I#17,.$!3$/%H
?%":17H%/-$"40$^%/-$"0$^(%/-$"0$"!$?I%":17H
?2$517H%/-$"40$=b".^(%/-$"0$=9$!?I2$517H
?!"3BH$:!/.3I%/-$"40$=b".?I!"3BH
?I"!$H
?"!$H
?%":1H\5013//3B(aSP?I%":1(H
?#17,.$!3$/%HYB1(\5013//3B(aSP(!./G$#17
20%,3$/%"5$3$17(2/.(#"3"(1L,B"%&1(C$3B(/3B1.(+5013//3B(
#1G$,17=
?I#17,.$!3$/%H
?%":17H+3"!$^+34"!$^(+5013//3B^(+5013//3B4"!$?I%":17H
?2$517HbZ:14+3"!$=b".^(+5013//3B=9$!?I2$517H
?!"3BH$:!/.3IbZ:14+3"!$=b".?I!"3BH
?I"!$H
?I"!$7H
In the above example two libraries are defined. The <name> element describes the default name of a
library, whereas the <names> element defines other possible names of the library. The <files>
element defines the names of the library on the filesystem. The <path> element just defines the
default path. When that path is not found, J2ME Polish tries to find the API with the help of the
file-names defined in the <files> element.
You can define your own libraries in the custom-apis.xml file. This allows you to use your own
libraries without needing to merge the apis.xml file with each update of J2ME Polish. The custom-
apis.xml file is loaded from the current project folder and – if that file doesn't exist – from the J2ME
Polish installation folder.
25
The Device Database
Extending the Devic Database
You can extend the device database by either modifying the custom-devices.xml, custom-
vendors.xml, custom-groups.xml and custom-apis.xml. You can store these files either in the root
directory of your project (the same place where the build.xml file lives) or in the ${polish.home}-
directory. The advantage of storing the files in the installation directory of J2ME Polish is that you
always have the very same device definitions. The disadvantage is that you need to backup these
files when you upgrade your J2ME Polish installation.
Please consider to submit your changes to the J2ME Polish community by sending them to
j2mepolish@enough.de.
Device Capabilities
The device database of J2ME Polish supports a number of capabilities, which are useful for
preprocessing and the assembling of resources.
You can use capabilities with any name, but following categories are predefined:
Capability Explanation Preprocessing-Access Groups
BitsPerPixel Color depth: 1 is monochrome,
4 are 16 colors,
8 = 256 colors,
16 = 65.536 colors,
24 = 16.777.216 colors
Variable:
polish.BitsPerPixel,
Symbols:
polish.BitsPerPixel.1 or
polish.BitsPerPixel.4,
polish.BitsPerPixel.16 etc
At 8 bits per pixel for
example:
BitsPerPixel.4+
and
BitsPerPixel.8
ScreenSize Width times height of the
screen resolution in pixels, e.g.
“176 x 208”
Variables:
polish.ScreenSize,
polish.ScreenWidth,
polish.ScreenHeight
Symbols (example):
polish.ScreenSize.176x208
polish.ScreenWidth.176
polish.ScreenHeight.208
Respectively the screen-
size of the target device,
e.g. ScreenSize.176x208 or
ScreenSize.128x128
CanvasSize Width times height of an MIDP-
Canvas.
Like ScreenSize -
CameraResolution Resolution of the camera. Variables:
polish.CameraResolution,
polish.CameraWidth,
polish.CameraHeight
Symbols (example):
polish.CameraResolution.320x
200
polish.CameraWidth.320
polish.CameraHeight.200
-
JavaPlatform The supported Java platform.
Currently either MIDP/1.0 or
MIDP/2.0.
Variable: polish.JavaPlatform
Symbols:
polish.midp1 or
polish.midp2
midp1 or midp2
26
The Device Database
Capability Explanation Preprocessing-Access Groups
JavaConfiguration The supported Java
configuration. Currently either
CLDC/1.0 or CLDC/1.1.
Variable:
polish.JavaConfigiration
Symbols:
polish.cldc1.0 or
polish.cldc1.1
cldc1.0 or cldc1.1
JavaPackage Supported APIs, e.g. “nokia-ui,
mmapi”
Variables:
polish.api,
polish.JavaPackage
Symbols (example):
polish.api.nokia-ui
polish.api.mmapi
Respectively the name of
the supported API, e.g.
nokia-ui or mmapi (one
group for each supported
API).
Example: nokia-ui, mmapi
JavaProtocol Supported data exchange
protocols. All MIDP/1.0 devices
support the HTTP protocol. All
MIDP/2.0 devices support
additionally the HTTPS
protocol.
Variable:
polish.JavaProtocol
Symbols (example):
polish.JavaProtocol.serial
polish.JavaProtocol.https
-
HeapSize The maximum heap size, e.g.
“500 kb” or “1.2 MB”
Variable:
polish.HeapSize
-
MaxJarSize The maximum size of the
MIDlet-JAR-bundle, e.g. “100
kb” or “2 MB”
Variable:
polish.MaxJarSize
-
OS The operating system of the
device, e.g. “Symbian OS 6.1”
Variable:
polish.OS
-
VideoFormat The supported video formats of
the device, e.g. “3GPP, MPEG-
4”
Variable:
polish.VideoFormat
Symbols (examples):
polish.video.3gpp
polish.video.mpeg-4
polish.VideoFormat.3gpp
polish.VideoFormat.mpeg-4
One group for each
supported video format.
Example:
3gpp
mpeg-4
SoundFormat The sound formats which are
supported by the device, e.g.
“midi, wav”
Variable:
polish.SoundFormat
Symbols (examples):
polish.audio.midi
polish.audio.wav
polish.SoundFormat.midi
polish.SoundFormat.wav
One group for each
supported audio format.
Example:
midi
wav
27
The Build Process
The Build Process
Introduction
The build process creates “ready to deploy”, optimized application-bundles from the source code.
The process is controlled by the build.xml file, which is situated at the root of the project. This file
is a standard Ant file which is used to control the J2ME Polish-task. You can find a short
introduction to Ant in the appendix on page 191. The J2ME Polish-task is separated into the
sections “info”, “deviceRequirements” and “build”. During the build following steps are
accomplished:
" Selection of the supported devices
" Assembling of the resources
" Preprocessing of the source code, optimizing for the device
" Compilation of the application
" Obfuscation and shrinking of the compiled code
" Preverification
" Creation of the JAR and JAD files
Definition of the J2ME Polish-task
You need to define the J2ME Polish-task in the build.xml file:
?3"7-#12(%":1@AbZ:1!/5$7BA(,5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A(
,5"77!"3B@A$:!/.3I1%/0&B4bZ:1!/5$7B4
+0$5#=b".'$:!/.3Ib#/:=b".'$:!/.3I!./&0".#=b".AIH
Now you can use the 2ME Polish-Task under the name “j2mepolish”.
You need also define where to find the Wireless Toolkit by defining the Ant-property “wtk.home”:
?!./!1.38(%":1@AC3-=B/:1A(G"501@A6'cdYeZ=VA(IH
On a system without the Wireless Toolkit (like Mac OS X) you can still use J2ME Polish by
defining the preverify-attribute of the <build>-element instead of using the “wkt.home”-property.
Example
The following example shows a complete build.xml file:
?f44(YB$7(2$51(,/%3./57(3B1(+0$5#(!./,177=((((((((((((((((((((44H
?f44(YB1(:/73($:!/.3"%3(3".&13($7(3B1(bZ:1!/5$7B43".&13^((((((44H
?f44(CB$,B(,/%3./57(2/.(CB"3(#1G$,17(3B1("!!5$,"3$/%(7B/05#(((44H
?f44(+1(,.1"31#("%#(7/(/%=((((((((((((((((((((((((((((((((((((44H
?f44((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44H
?f44(P:!/.3"%3'(CB1%(8/0(B"G1(%/(d$.15177(Y//5-$3($%73"551#(((44H
?f44(8/0(%11#(3/(#12$%1(3B1(A!.1G1.$28A4"33.$+031(((((((((((((44H
?f44(/2(3B1(?+0$5#H4151:1%3(/2(3B1(RZUF(S/5$7B(3"7-=((((((((((44H
?f44((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44H
?f44(dB1%(8/0(,"55(a%3(2./:(3B1(,/::"%#45$%1^(8/0(,"%(((((((((44H
?f44(,"55(A"%3(3173(bZ:1!/5$7BA(3/(7-$!(3B1(/+207,"3$/%(((((((44H
28
}
for each selected
device
The Build Process
?f44("%#(3/(+0$5#(3B1(1L":!51(2/.(21C1.(B"%#7137=(((((((((((((44H
?f44(YB1(#12"053(3".&13(+0$5#7("%#(/+207,"317(3B1(1L":!51=((((44H
?f44((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44H
?f44(YB1(2055(#/,0:1%3"3$/%(,"%(+1(2/0%#("3(((((((((((((((((((44H
?f44(B33!'IICCC=bZ:1!/5$7B=/.&((((((((((((((((((((((((((((((((44H
?f44((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44H
?f44(["G1(20%f((((((((((((((((((((((((((((((((((((((((((((((((44H
?!./b1,3(
%":1@A1%/0&B4bZ:1!/5$7B41L":!51A(
#12"053@AbZ:1!/5$7BAH
?f44(YB1(C3-=B/:1(!./!1.38(7B/05#(!/$%3(3/(3B1(#$.1,3/.8((((((44H
?f44(,/%3"$%$%&(3B1(d$.15177(Y//5-$3=(((((((((((((((((((((((((44H
?!./!1.38(%":1@AC3-=B/:1A(G"501@A6'cdYeZ=VA(IH
?f44(M12$%$3$/%(/2(3B1(RZUF(S/5$7B(3"7-'((((((((((((((((((((((44H
?3"7-#12(%":1@AbZ:1!/5$7BA(,5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A(
,5"77!"3B@A$:!/.3I1%/0&B4bZ:1!/5$7B4
+0$5#=b".'$:!/.3Ib#/:=b".'$:!/.3I!./&0".#=b".'$:!/.3I.13./&0".#=b".AIH
?f44(+0$5#(3".&137^(1",B(3".&13(,"%(+1(,"551#(G$"(A"%3(<%":1>A^(
(((((1=&=(A"%3(,51"%A^(A"%3(%/3173(bZ:1!/5$7BA(/.(b073(A"%3A(2/.(
(((((,"55$%&(3B1(#12"05343".&13(44H
?3".&13(%":1@A3173A(H
?!./!1.38(%":1@A3173A(G"501@A3.01A(IH
?I3".&13H
?3".&13(%":1@A$%$3AH
(( ?!./!1.38(%":1@A3173A(G"501@A2"571A(IH
?I3".&13H
(
?f44(P%(3B$7(3".&13(3B1(RZUF(S/5$7B(3"7-($7(071#=(((((((((((((44H
?f44(P3(B"7(X(71,3$/%7'(((((((((((((((((((((((((((((((((((((((44H
?f44((((V=(YB1($%2/471,3$/%(#12$%17(7/:1(&1%1."5($%2/.:"3$/%((44H
?f44((((Z=(YB1(#1G$,1]1g0$.1:1%37471,3$/%(,B//717(3B1(#1G$,17(44H
?f44(((((((2/.(CB$,B(3B1("!!5$,"3$/%($7(/!3$:$91#=((((((((((((44H
?f44((((X=(YB1(+0$5#471,3$/%(,/%3./57(3B1(",30"5(+0$5#((((((((44H
?f44(((((((!./,177=(((((((((((((((((((((((((((((((((((((((((((44H
?3".&13(%":1@AbZ:1!/5$7BA(
#1!1%#7@A$%$3A
#17,.$!3$/%@AYB$7($7(3B1(,/%3./551.(2/.(3B1(RZUF(+0$5#(!./,177=A(
H
?bZ:1!/5$7BH
((((?f44(&1%1."5(7133$%&7(44H
?$%2/
(5$,1%71@A`SDA
(%":1@ARZUF(S/5$7BA
(G1.7$/%@AV=X=hA
(#17,.$!3$/%@Aa(7":!51(!./b1,3A
(G1%#/.J":1@AF%/0&B(N/23C".1A
($%2/O.5@AB33!'IICCC=bZ:1!/5$7B=/.&A
($,/%@A$,/%=!%&A
(b".J":1@Aij!/5$7B=G1%#/.;4ij!/5$7B=%":1;41L":!51=b".A(
(b".O.5@Aij!/5$7B=b".J":1;A
(,/!8.$&B3@A6/!8.$&B3(ZKKh(F%/0&B(N/23C".1=(a55(.$&B37(.171.G1#=A
(#151316/%2$.:@AM/(8/0(.1"558(C"%3(3/(-$55(:1kA(
IH
?f44(7151,3$/%(/2(70!!/.31#(#1G$,17(44H
29
The Build Process
?f44(P%(3B1(3173(:/#1(3B1("!!5$,"3$/%($7(+0$5#(/%58(2/.(3B1((44H
?f44(J/-$"IXT)K("%#(3B1(TTKK(!B/%17^(/3B1.C$71((44H
?f44(3B1(71,/%#(#1G$,1]1g0$.1:1%37(C$55(+1(071#($%731"#=(44H
?#1G$,1]1g0$.1:1%37($2@A3173AH
?.1g0$.1:1%3(%":1@AP#1%3$2$1.A(G"501@AJ/-$"IXT)K^(J/-$"ITTKKA(
IH
?I#1G$,1]1g0$.1:1%37H
?#1G$,1]1g0$.1:1%37(0%5177@A3173AH
?.1g0$.1:1%3(%":1@AP#1%3$2$1.A(G"501@AJ/-$"IN1.$17TK^(
J/-$"IN1.$17TKU$#!Z^(`1%1.$,I:$#!Z^(`1%1.$,I:$#!VA(IH
?f44(/%(,/05#(071(/3B1.(#1G$,17(2/.(.1"5(+0$5#7^(1=&=('
?/.H
?"%#H
?.1g0$.1:1%3(%":1@AR"G"S",-"&1A(G"501@A%/-$"40$A(
IH
?.1g0$.1:1%3(%":1@A\$37S1.S$L15A(G"501@AVTlA(IH
?I"%#H
?I/.H
(44H
?I#1G$,1]1g0$.1:1%37H
((((?f44(+0$5#(7133$%&7(44H
?+0$5#
(78:+/57@AFL":!51N8:+/5^(a%/3B1.FL":!51A
($:"&1D/"#N3."31&8@A2/.1&./0%#A
(20557,.11%@A:1%0A
(071S/5$7B`0$@A3.01A
(.17M$.@A.17/0.,17A
(H
((?f44(:$#5137(#12$%$3$/%(44H
((?:$#513(,5"77@A#1=1%/0&B=!/5$7B=1L":!51=U1%0U$#513A(%":1@AFL":!51A(
IH
((?f44(!./b1,34C$#1(G".$"+517(4(071#(2/.(!.1!./,177$%&((44H
((?G".$"+517H
( ?G".$"+51(%":1@A0!#"3140.5A(
G"501@AB33!'IICCC=1%/0&B=#1I0!#"31A(IH
?G".$"+51(%":1@A3$351A(G"501@ARZUF(S/5$7BA(IH
((?IG".$"+517H
((?f44(/+207,"3/.'(#/%m3(/+207,"31(CB1%(3B1(31734!./!1.38($7(3.01(44
H
( ((?/+207,"3/.(0%5177@A3173A(%":1@AS./`0".#A(IH
((?f44(#1+0&(7133$%&7'(/%58($%,50#1(#1+0&(7133$%&(CB1%(3B1(31734
(!./!1.38($7(3.01(44H
((?#1+0&($2@A3173A(7B/CD/&E%F../.@A3.01A(G1.+/71@A3.01A(
51G15@A1../.AH
?2$531.(!"331.%@A#1=1%/0&B=!/5$7B=1L":!51=nA(51G15@A#1+0&A(IH
?2$531.(!"331.%@A#1=1%/0&B=!/5$7B=0$=nA(51G15@AC".%A(IH
((?I#1+0&H
((?f44(071.(#12$%1#(RaM("33.$+0317(,"%("57/(+1(071#'(44H
((?b"#H
?"33.$+031(%":1@AJ/-$"4UPM51346"31&/.8A(G"501@A`":1A(
$2@A!/5$7B=&./0!=N1.$17hKA(IH
((?Ib"#H
?I+0$5#H
?IbZ:1!/5$7BH
?I3".&13H
?3".&13(%":1@A,51"%A(
(( ((#17,.$!3$/%@A"55/C7("(,51"%(+0$5#=(o/0(7B/05#(,"55(<"%3(,51"%>(CB1%1G1.(
30
The Build Process
8/0(:"#1(,B"%&17(3/(#1G$,17=L:5^(G1%#/.7=L:5(/.(&./0!7=L:5AH
?#15131(#$.@A+0$5#A(IH
?#15131(#$.@A#$73A(IH
?I3".&13H
?I!./b1,3H
In the first section the J2ME Polish-task and the location of the wireless-toolkit are defined,
followed by the build-targets “test”, “init”, “j2mepolish” and “clean”. The targets “test” and “init”
are responsible for entering the test mode.
If you call Ant without any arguments, the Ant-property “test” will be set to false in the “init”
target. If you call Ant with the arguments “test j2mepolish”, the test-property will be set to true.
This allows controlling the build-script without changing it. In the example the obfuscation step is
skipped when the test-property is true. Also the debug messages are only included when test is true.
You can force a complete rebuild by calling “ant clean”. This can be necessary after you made
changes in the device database or in rare cases when there is a compile error in the J2ME Polish
packages.
The <info>-Section
In the <info>-section general information about the project is defined.
?$%2/
((((5$,1%71@A`SDA
((((%":1@AN$:!51U1%0A
((((G1.7$/%@AV=X=hA
((((#17,.$!3$/%@Aa(3173(!./b1,3A
((((G1%#/.J":1@AF%/0&B(N/23C".1A
(((($%2/O.5@AB33!'IICCC=1%/0&B=#1I#$,3$/%".8A
(((($,/%@A$,/%=!%&A
((((b".J":1@Aij!/5$7B=G1%#/.;4ij!/5$7B=%":1;4ij!/5$7B=5/,"51;41L":!51=b".A(
((((b".O.5@Aij!/5$7B=b".J":1;A
((((,/!8.$&B3@A6/!8.$&B3(ZKKh(F%/0&B(N/23C".1=(a55(.$&B37(.171.G1#=A
((((#151316/%2$.:@AM/(8/0(.1"558(C"%3(3/(-$55(:1kA(
((((IH
The information giving here is used for setting the JAD- and MANIFEST-attributes. If you need to
set attribute which are not supported by the <info>-section, you can always use the <jad>-element,
which is a subelement of the <build>-section. The <info> element supports following attributes:
<info>
Attribute
Required Explanation
license Yes The license for this project. Either “GPL” when the source code of the
application is published under the GNU General Public License, or the
commercial license key, which can be obtained at www.j2mepolish.org.
name Yes The name of the project, the variable “MIDlet-Name” overrides this
setting. This variable can be used to localize the application.
version Yes The version of the project in the format [major].[minor].[build].
Example: G1.7$/%@pZ=V=VKp. The variable “MIDlet-Version”
overrides this setting.
31
The Build Process
<info>
Attribute
Required Explanation
description No The description of the project. A brief explanation about what this
application does should be given here. The variable “MIDlet-
Description” overrides the value given here, this van be used to localize
the application.
vendorName Yes The name of the vendor of this application. The variable “MIDlet-
Vendor” overrides this setting.
jarName Yes The name of the jar-files which will be created. Apart from the usual
J2ME Polish variables, the following variables are especially useful:
${polish.vendor}: The vendor of the device, e.g. Samsung or
Motorola
${polish.name}: The name of the device
${polish.identifier}: Vendor and device name, e.g. “Nokia/6600”
${polish.version}: The version of the project as defined above.
${polish.language}: The two letter ISO language-code, e.g. “en” or
“de”.
${polish.country}: The two letter ISO country-code, e.g. “US” or
“DE”. This can be empty when no country is defined in the current
locale.
${polish.locale}: The current locale, e.g. “en” or “de_DE”.
Example: jarName=¨Game-${polish.vendor}-${polish.name}-
${polish.locale}.jar¨ results into “Game-Nokia-6600-en.jar” for an
application which has been optimized for the Nokia/6600 and uses the
English locale.
jarUrl No The URL from which the jar file can be downloaded. This is either the
HTTP address, or just the name of the jar-file, when it is loaded locally.
When no jarUrl is defined, the jarName defined above is used. Apart
from the variables available for the jarName-attribute, you can use the
name of the jar-file as defined above:
jarUrl=¨http://www.enough.de/midlets/Game/${polish.vendor
}/${polish.name}/${polish.jarName}¨
infoUrl No The URL containing more information about the application. The
variable “MIDlet-Info-URL” overrides this setting, this van be used to
localize the application.
copyright No Copyright notice.
deleteConfirm No The text which is presented to the user when he tries to delete the
application. The variable “MIDlet-Delete-Confirm” overrides this
setting, this van be used to localize the application.
installNotify No A HTTP-URL, which should be called after the successful installation
of the application.. This can be useful for tracking how many
32
The Build Process
<info>
Attribute
Required Explanation
applications are installed, for example. The user can prevent the install-
notify, though. One can use the same variables as for the jarUrl-
attribute. The variable “MIDlet-Install-Notify” overrides this setting.
deleteNotify No A HTTP-URL, which should be called after the application has been
deleted from the device. See the explanation of installNotify. The
variable “MIDlet-Delete-Notify” overrides this setting.
dataSize No The minimum space which is needed on the device, e.g.
dataSize=¨120kb¨. The variable “MIDlet-Data-Size” overrides this
setting.
permissions No The permissions which are needed by this application, e.g.
°javax.microedition.io.Connector.http¨. The variable “MIDlet-
Permissions” overrides this setting.
optionalPermi
ssions
No The permissions which are useful for this application to work. The
variable “MIDlet-Permissions-Opt” overrides this setting.
profile No Normally J2ME Polish is using the JavaPlatform capability of the
current target device for determining the correct "MicroEdition-Profile"
setting. You can override this by hardcoding the profile for all target
devices. This is useful only in cases, when you determine device
capabilities during the runtime of the application and want to deliver
one application bundle for all target devices.
configuration No Normally J2ME Polish is using the JavaConfiguration capability of the
current target device for determining the correct "MicroEdition-
Configuration" setting. You can override this by hardcoding the
configuration for all target devices. This is useful only in cases, when
you determine device capabilities during the runtime of the application
and want to deliver one application bundle for all target devices.
The <deviceRequirements>-Section
The optional <deviceRequirements>-section is responsible for selecting the devices which are
supported by the application. When this section is omitted, the application will be optimized for all
known devices. Any device capabilities or features can be used for the device selection:
?#1G$,1]1g0$.1:1%37($2@A3173AH
?.1g0$.1:1%3(%":1@AP#1%3$2$1.A(G"501@AJ/-$"ITTKKA(IH
?I#1G$,1]1g0$.1:1%37H
?#1G$,1]1g0$.1:1%37(0%5177@A3173AH
?.1g0$.1:1%3(%":1@AR"G"S",-"&1A(G"501@A%/-$"40$A(IH
?.1g0$.1:1%3(%":1@A\$37S1.S$L15A(G"501@AhlA(IH
?I#1G$,1]1g0$.1:1%37H
In this example two alternative device-selections are defined – when the test-property is set to true
33
The Build Process
(by defining it with ?!./!1.38(%":1@A3173A(G"501@A3.01A(IH), only the upper
<deviceRequirements>-element is used and the second <deviceRequirements>-element is ignored.
The actual requirements are defined with the sub-elements <requirement>. Without any
clarification, all listed requirements need to be fulfilled by the device to be selected. There are <or>,
<and>, <not> and <xor> elements, which can be used to define the requirements very flexible.
deviceRequirements
-Attribute
Required Explanation
if No The name of the Ant-property which needs to be “true” or “yes”
to use this <deviceRequirements>.
unless No The name of the Ant-property which needs to be “false” or “no”
to use this <deviceRequirements>.
deviceRequirements
-Element
Required Explanation
requirement Yes The requirement which needs to be fulfilled by the device
and No Series of requirements, of which all need to be fulfilled.
or No Series of requirements, of which at least one needs to be fulfilled.
xor No Series of requirements, of which one needs to be fulfilled.
not No Series of requirements, of which none must be fulfilled.
The actual work is done by the <requirement> element:
requirement-
Attribute
Required Explanation
name Yes The name of the needed capability, e.g. “BitsPerPixel”.
value Yes The needed value of the capability, e.g. “4+” for a color depth or
at least 4 bits per pixel.
type No The class which controls this requirement. Either a class which
extends the
#1=1%/0&B=!/5$7B="%3=.1g0$.1:1%37=]1g0$.1:1%3(class, or
one of the base types “Size”, “Int”, “String”, “Version” or
“Memory”. Example:
?.1g0$.1:1%3(%":1@AU"LR".N$91A(G"501@AVKKl(-+A(
38!1@AU1:/.8A(IH
The <or>, <and>, <not> and <xor> elements can be nested in any manner:
?#1G$,1]1g0$.1:1%37H
?.1g0$.1:1%3(%":1@A\$37S1.S$L15A(G"501@AhlA(IH
?/.H
?.1g0$.1:1%3(%":1@AR"G"S",-"&1A(G"501@A%/-$"40$^(::"!$A(IH
34
The Build Process
?"%#H
?.1g0$.1:1%3(%":1@AR"G"S",-"&1A(G"501@A::"!$A(IH
?.1g0$.1:1%3(%":1@AR"G"S5"32/.:A(G"501@AUPMSIZ=KlA(IH
?I"%#H
?I/.H
?I#1G$,1]1g0$.1:1%37H
In this example each supported device must have a color depth of at least 4 bits per pixel.
Additionally the device needs to support either the Nokia-UI-API and the Mobile Media-API
(mmapi), or the Mobile Media-API and the MIDP/2.0 platform.
Instead of using such nested requirements, you can also use the "Term" requirement that allows you
to select devices with the same power like the #if preprocessing directive. The following example
includes the very same requirements like the above one – but only one "Term" requirement is used:
?#1G$,1]1g0$.1:1%37H
?.1g0$.1:1%3(%":1@AY1.:A(
G"501@Aq!/5$7B=\$37S1.S$L15(H@(hr("%#(qq!/5$7B="!$=%/-$"40$("%#(
!/5$7B="!$=::"!$r(/.(q!/5$7B="!$=::"!$("%#(!/5$7B=:$#!ZrrA(IH
?I#1G$,1]1g0$.1:1%37H
J2ME Polish provides several requirements that can be used "out of the box":
requirement-name Explanation
BitsPerPixel Needed color depth of the device: 1 is monochrome,
4 are 16 colors,
8 = 256 colors,
16 = 65.536 colors,
24 = 16.777.216 colors. Example:
“4+” for at least 4 bits per pixel or “16” for precisely 16 bits per pixel.
?.1g0$.1:1%3(%":1@A\$37S1.S$L15A(G"501@AhlA(IH
ScreenSize Required width and height of the display, e.g. “120+ x 100+” for a
resolution of at least 120 pixels horizontally and 100 pixels vertically.
?.1g0$.1:1%3(%":1@AN,.11%N$91A(G"501@AVZKl(L(VKKlA(IH
ScreenWidth The needed horizontal resolution of the display , e.g. “120+” for at least 120
pixels.
?.1g0$.1:1%3(%":1@AN,.11%d$#3BA(G"501@AVZKlA(IH
ScreenHeight The needed vertical resolution of the display, e.g. “100+” for at least 100
pixels.
?.1g0$.1:1%3(%":1@AN,.11%[1$&B3A(G"501@AVKKlA(IH
CanvasSize Required width and height of the MIDP-Canvas. Some devices do not allow
the usage of the complete screen.
?.1g0$.1:1%3(%":1@A6"%G"7N$91A(G"501@AVZKl(L(VKKlA(IH
JavaPlatform The needed platform, e.g. “MIDP/1.0” or “MIDP/2.0+”.
?.1g0$.1:1%3(%":1@AR"G"S5"32/.:A(G"501@AUPMSIZ=KlA(IH
JavaConfiguration The needed configuration, e.g. “CLDC/1.1+”.
?.1g0$.1:1%3(%":1@AR"G"6/%2$&0."3$/%@A(G"501@A6DM6IV=VlA(IH
JavaPackage Needed APIs, e.g. “nokia-ui, mmapi”:
?.1g0$.1:1%3(%":1@AR"G"S",-"&1A(G"501@A%/-$"40$^(::"!$A(IH
35
The Build Process
requirement-name Explanation
JavaProtocol Needed data exchange protocols, e.g. “serial, socket”:
?.1g0$.1:1%3(%":1@AR"G"S./3/,/5A(G"501@A71.$"5^7/,-13A(IH
HeapSize The needed heap size of the device, e.g. “200+ kb” or “1.1+ MB”
?.1g0$.1:1%3(%":1@A[1"!N$91A(G"501@AZKKl-+A(IH
Vendor The vendor of the device, e.g. “Nokia” or “Siemens”.
?.1g0$.1:1%3(%":1@As1%#/.A(G"501@AJ/-$"^(N/%8F.$,77/%A(IH
Identifier The identifier of the device, e.g. “Nokia/6600”.
?.1g0$.1:1%3(%":1@AP#1%3$2$1.A(G"501@AJ/-$"ITTKK^(
N/%8F.$,77/%IStKKA(IH
Feature A feature which needs to be supported by the device.
?.1g0$.1:1%3(%":1@AQ1"30.1A(G"501@AB"7S/$%31.FG1%37A(IH
Term A preprocessing term that needs to be fulfilled by the device. You can use
this flexible requirement just like the //#if-preprocessing directive in your
source code.
?.1g0$.1:1%3(%":1@AY1.:A(
G"501@A!/5$7B=::"!$(uu(f!/5$7B=$7s$.30"5(uu(q!/5$7B=s1%#/.(f@(
J/-$"rA(IH
The <build>-Section
With the <build>-section the actual build process is controlled:
?+0$5#
78:+/57@A7B/CN!5"7B^(a%/3B1.FL":!51N8:+/5A
20557,.11%@A:1%0A
071S/5$7B`0$@A3.01A
H
?f44(:$#5137(#12$%$3$/%(44H
?:$#513(,5"77@AU1%0U$#513A(%":1@AFL":!51A(IH
?f44(!./b1,34C$#1(G".$"+517(4(071#(2/.(!.1!./,177$%&((44H
?G".$"+517H
?G".$"+51(%":1@A0!#"3140.5A(
((((G"501@AB33!'IICCC=1%/0&B=#1I0!#"31A(IH
?IG".$"+517H
?f44(/+207,"3/.(7133$%&7'(#/(%/3(/+207,"31(CB1%(3173($7(3.01(44H
?/+207,"3/.(%":1@AS./`0".#A(071M12"053S",-"&1@A3.01A(0%5177@A3173A(IH
?f44(#1+0&(7133$%&7'(/%58(#1+0&(CB1%(3173($7(3.01(44H
?#1+0&($2@A3173A(
(G$70"5@A2"571A(G1.+/71@A3.01A(51G15@A1../.AH
?2$531.(!"331.%@A#1=1%/0&B=!/5$7B=#$,3=nA(51G15@A#1+0&A(IH
?2$531.(!"331.%@A#1=1%/0&B=!/5$7B=0$=nA(51G15@AC".%A(IH
?I#1+0&H
?I+0$5#H
Attributes of the build-Section
The build-section has following attributes:
36
The Build Process
build-Attribute Required Explanation
sourceDir No The path to the source directory. The default path is either
“source/src”, “source” or “src”. You can define several paths by
separating them with a colon ':' or a semicolon ';':
[path1]:[path2]. You can also include source-directories based on
conditions when the nested <sources>-element is used instead
(see below).
binaryLibraries or
binaryLibrary
No Either the name of the directory which contains binary-only
libraries or the name(s) of the libraries. Several libraries can be
separated by colons ':' or by semicolons ';'. When no path is
defined, the libraries will be searched within the “import” folder
by default. This mechanism can only be used for third party
APIs, which are not available on the phone itself. Device-APIs
are automatically included, after they have been defined in the
${j2mepolish.home}/apis.xml file. Please compare the how-
to about including APIs on page 181.
symbols No Project specific symbols, e.g. “showSplash” which can be
checked with “//#ifdef showSplash” in the source code. Several
symbols need to be separated by comma.
usePolishGui No Defines whether the J2ME Polish GUI should be used at all.
Possible values are “true”/”yes”, “false”/”no” or “always”. When
“true” is given the GUI will be used only for devices which have
the recommended capabilities (e.g. a color depth of at least 8
bits). When “always” is given, the GUI will be used for all
devices. Default value is “true”.
fullscreen No Defines whether the complete screen should be used for devices
which support a full screen mode. Currently these includes all
MIDP/2.0 devices as well as devices, which support the Nokia-
UI API. Possible values are either “no”, “yes” and “menu”. With
“yes” the complete screen is used but no commands are
supported. With “menu” commands can be used as well. Default
setting is “no”. Remember that you need to target a specific
device that has known Softkeys for this option. Otherwise always
the default (“unpolishable”) commands menu is used.
Alternatively the preprocessing-variable “polish.FullScreen” can
be set. This allows a finer grained control, since variables can
have conditions. Refer to the GUI chapter on page 93 for more
details.
imageLoadStrategy No The strategy for loading pictures. Possible values are either
“foreground” or “background”. The “foreground” strategy loads
images directly when they are requested. The “background”
strategy loads the images in a background-thread. With the
37
The Build Process
build-Attribute Required Explanation
background strategy the felt performance of an application can
be increased, but not all pictures might be shown right away
when the user enters a screen. The definition of the
imageLoadStrategy makes only sense when the J2ME Polish
GUI is used (usePolishGui=”true”). Default strategy is
“foreground”. When the “foreground” strategy is used, the
preprocessing symbol “!/5$7B=$:"&17=#$.1,3D/"#” will be
defined. When using the “background” strategy, the symbol
“!/5$7B=$:"&17=+",-&./0%#D/"#” is defined.
javacTarget No The target for the java-compiler. By default the “1.2” target is
used, unless a WTK 1.x or Mac OS X is used, in which case the
target “1.1” is used.
preverify No The path to the preverify executable of the Wireless Toolkit. The
program is usually within the “bin” folder of the Wireless
Toolkit. This can be used for defining a preverfying program
different from the standard WTK program.
polishDir No The directory containing the sources of J2ME Polish. This is
used by developers of the J2ME Polish GUI itself.
devices No Path to the devices.xml-file. Defaults to devices.xml in the
current folder or in enough-j2mepolish-build.jar.
groups No Path to the groups.xml-file. Defaults to groups.xml in the current
folder or in enough-j2mepolish-build.jar.
vendors No Path to the vendors.xml-file. Defaults to vendors.xml in the
current folder or in enough-j2mepolish-build.jar.
apis No Path to the apis.xml-file. Defaults to apis.xml in the current
folder or in enough-j2mepolish-build.jar.
midp1Path No Path to the MIDP/1.0 API. Defaults to “import/midp1.jar”.
midp2Path No Path to the MIDP/2.0 API. Defaults to “import/midp2.jar”.
workDir No The temporary build folder. Defaults to “build”.
destDir No The folder into which the “ready-to-deploy” application bundles
should be stored. Defaults to “dist”.
apiDir No The folder in which the APIs are stored, defaults to “import”.
resDir No The folder which contains all design definitions and other
resources like images, movies etc. By setting a different folder,
completely different designs can be demonstrated. Default folder
is “resources”. You can also use the <resources>-subelement
which allows to fine-tune the resource-assembling process as
well.
38
The Build Process
build-Attribute Required Explanation
obfuscate No Either “true” or “false”. Defines whether the applications should
be obfuscated. Defaults to “false”. Alternatively the nested
element “obfuscator” can be used (see below).
obfuscator No The name of the obfuscator. Defaults to “ProGuard”. Possible
values are “ProGuard”, “KlassMaster”, “Dasho”, “YGuard” or
“RetroGuard”. Alternatively the nested element “obfuscator” can
be used (see below).
compilerMode No When the compiler-mode is activated, J2ME Polish will not
package the application and only process one device. This mode
is useful for IDEs which support indirect compilation like
NetBeans for example. You can select “Run” in NetBeans and
NetBeans uses J2ME Polish as compiler, packages the
application and starts the emulator - this saves valuable time
during the development phase. Possible values are “true” or
“false”. The compiler mode is deactivated (“false”) by default.
compilerDestDir No The “compilerDestDir”-attribute defines where the compiled
(and obfuscated) classes should be stored. The default target
directory is “bin/classes”.
compilerModePrever
ify
No Defines whether J2ME Polish should preverify the compiled
classes as well. This is needed for using J2ME Polish as a
compiler for the EclipseME plugin. Possible values are “true” or
“false”. The preverifying is deactivated (“false”) by default.
encoding No The encoding for the generated JAD and MANIFEST files, this
defaults to "UTF8" like the standard mandates.
Elements of the build-Section
The build section supports several nested elements: <sources>, <midlet>, <midlets>, <resources>,
<obfuscator>, <variables>, <debug>, <jad>, <manifestFilter> , <preprocessor> and <java>.
<sources>
The <sources>-element can be used for a finer grained control of the source-directories. This can be
useful to include test classes, for example:
?7/0.,17H
?7/0.,1(#$.@A7/0.,1I7.,A(IH
?7/0.,1(#$.@A7/0.,1I3173A($2@A3173A(IH
?I7/0.,17H
sources-Attribute Required Explanation
if No The Ant-property which needs to be “true” for the nested source
directories to be used.
39
The Build Process
sources-Attribute Required Explanation
unless No The Ant-property which needs to be “false” for the nested source
directories to be used.
source-Attribute Required Explanation
dir Yes The directory containing Java source files.
if No The Ant-property which needs to be “true” for this source
directory to be used.
unless No The Ant-property which needs to be “false” for this source
directory to be used.
<midlet> and <midlets>
The <midlet>-element defines the actual MIDlet class:
?:$#513(,5"77@A#1=1%/0&B=!/5$7B=1L":!51=FL":!51U$#513A(IH
midlet-Attribute Required Explanation
class Yes The complete package and class-name of the MIDlet.
name No The name of the MIDlet. Default is the class-name without the
package: The MIDlet “com.company.SomeMidlet” is named
“SomeMidlet” by default.
icon No The icon of this MIDlet. When none is defined, the icon defined
in the <info>-section will be used.
number No The number of this MIDlet. This is interesting only for MIDlet-
suites in which several MIDlets are contained.
if No The Ant-property or preprocessing directive which needs to be
“true” for this MIDlet to be included.
unless No The Ant-property or preprocessing directive which needs to be
“false” for this MIDlet to be included.
The optional <midlets>-element is used as a container for several <midlet>-elements:
?:$#5137H
?:$#513(,5"77@A#1=1%/0&B=!/5$7B=1L":!51=FL":!51U$#513A(IH
?:$#513(%":1@ARZUF(S/5$7B(M1:/A(%0:+1.@AZA($,/%@A%/Z=!%&A
((,5"77@A#1=1%/0&B=!/5$7B=1L":!51=`0$M1:/U$#513A(IH
?I:$#5137H
<iappli>
The <iappli> or <doja> element defines the IApplication class of your DoJa release. This is only
applicable when you are targeting this platform (see page 178).
iappli-
Attribute
Require
d
Explanation
40
The Build Process
class Yes The complete package and class-name of the main IApplication.
if No
The Ant-property or preprocessing directive that needs to be/result "true"
for this iappli to be used.
unless No
The Ant-property or preprocessing directive that needs to be/result
"false" for this iappli to be used.
<resources>
?.17/0.,17
#$.@A.17/0.,17A
1L,50#17@An=3L3A
H
?2$51713(
#$.@A.17/0.,17I:053$:1#$"A(
$%,50#17@An=:!XA(
$2@A!/5$7B="0#$/=:!XA(
IH
?2$51713(
#$.@A.17/0.,17I:053$:1#$"A(
$%,50#17@An=:$#A(
$2@A!/5$7B="0#$/=:$#$("%#(%/3(!/5$7B="0#$/=:!XA(
IH
?2$51713(
#$.@A.17/0.,17I:053$:1#$"I$:"&17Iij!/5$7B=5"%&0"&1;A(
$%,50#17@An=!%&A(
IH
?5/,"5$9"3$/%(5/,"517@A#1^(1%A(0%5177@A3173A(IH
?5/,"5$9"3$/%(5/,"517@A1%A($2@A3173A(IH
?I.17/0.,17H
The <resources>-element can be used to fine tune the resources assembling as well as the
localization of the application. When it is used, the “resDir”-attribute of the <build>-section should
not be used. The <resources>-element supports following attributes:
resources-Attribute Required Explanation
dir No The directory containing all resources, defaults to the
“resources” folder.
defaultexcludes No Either “yes”/”true” or “no”/”false”. Defines whether typical
files should not be copied in the application-jar-bundle during
packaging. The files “polish.css”, “Thumbs.db”, any backup-
files (*.bak and *~) and the messages-files used in the
localization are excluded by default.
excludes No Additional files which should not be included in the JAR-files
can be defined using the “excludes”-attribute. Several files need
to be separated by comma. The star can be used to select several
files at once, e.g. “*.txt, readme*”.
41
The Build Process
resources-Attribute Required Explanation
locales No The locales which should be supported in a comma-separated
list. Alternatively the nested <localization>-element can be used.
The standard Java locale-abbreviations are used, e.g. “de” for
German, “en” for English and “fr_CA” for Canadian French.
filterZeroLengthFiles No Defines whether files with a length of 0 should also be filtered.
This is true by default, so any files with a length of 0 bytes will
not be copied, unless you activate this by setting
filterNullFiles="false". You can use this mechanism for
removing files for specific devices or device groups. Imagine the
situation where you have a image file in the resources directory.
You want to use that image on all devices except the
Vendor/DeviceName one. You can now remove that file for that
specific devices by placing a file with the same name but with a
length of 0 bytes into resources/Vendor/DeviceName.
The <resources> elements accepts the nested elements <filter>, <fileset>, <localization> and
<copier>:
The <filter> Subelement
Sometimes it is easier to exclude resources for specific devices rather than to include it for the other
devices. You can use any number of <filter> elements for this purpose. The following element
removes all *.mid files when the target device supports both MIDI as well as AMR files:
<filter excludes="*.mid" if="polish.audio.midi and polish.audio.amr" />
filter-Attribute Required Explanation
excludes Yes Defines which files should be excluded, e.g. “*.mid”. You can
also use regular expressions in this attribute.
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true for this filter to be used.
unless No The Ant-property which needs to be “false” or the preprocessing
term which needs result false for this filter to be used.
The <fileset> Subelement
The <fileset> behaves like any Ant fileset, but it offers the additional “if” and “unless”-attributes for
allowing a fine grained control. The most important attributes are:
fileset-Attribute Required Explanation
dir Yes The base directory of this fileset. This directory needs to exist
unless you use variables in it like ${polish.vendor},
${polish.name}, ${polish.language}, ${polish.country}
42
The Build Process
fileset-Attribute Required Explanation
and so on. You can use any J2ME Polish preprocessing variable
or Ant property in the dir attribute.
includes Yes Defines which files should be included, e.g. “*.mid”.
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true for this fileset to be included.
unless No The Ant-property which needs to be “false” or the preprocessing
term which needs result false for this fileset to be included.
The <localization> Subelement
With the <localization>-element the internationalization of the application can be controlled. It
supports following attributes:
localization-
Attribute
Required Explanation
locales Yes The locales which should be supported in a comma-separated
list. The standard Java locale-abbreviations are used, e.g. “de”
for German, “en” for English and “fr_CA” for Canadian French.
messages No The file which contains the translations. This defaults to
“messages.txt”.
dynamic No Defines whether dynamic translations should be enabled.
Dynamic translations can be changed during runtime but require
additional resources. This defaults to "false".
default No The default localization – this makes only sense when dynamic
translations are enabled.
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true for this localization to be used.
unless No The Ant-property which needs to be “false” or the preprocessing
term which needs result false for this localization to be used.
More information about localization can be found in the localization chapter on page 70.
The <copier> Subelement
Use the <copier>-element to transform the resources before they are packaged in the final JAR file.
You can chain several copiers together just by defining several <copier> elements.
copier-Attribute Required Explanation
name Yes,
unless
The name of the resource copier, e.g. “antcall”, “renamer” or
“svgconverter”. You can register your own resource copier in
43
The Build Process
copier-Attribute Required Explanation
class is
set
${polish.home}/custom-extensions with the type
“resourcecopier”.
class No The class that extends the
de.enough.polish.resources.ResourceCopier class.
classpath No The classpath that is used.
target No The target in your build.xml script that should be called when
using the “antcall” copier.
if No The Ant property which needs to be “true” or the preprocessing
term which needs result true for this copier to be used.
unless No The Ant property which needs to be “false” or the preprocessing
term which needs result false for this copier to be used.
The antcall Resource Copier
The “antcall” resource copier executes another target in your build.xml script for copying the
resources. You can use all (lowercase) J2ME Polish variables and properties of the current target
device as well as following specific properties:
! ${polish.resources.target}: contains the target directory, to which the resources need to be
copied
! ${polish.resources.files}: includes a comma separated list of the files that should be copied
! ${polish.resources.filePaths}: includes a semicolon (Windows) or colon (Unix) separated list of
the files that should be copied.
You can also specify your own properties by using nested <parameter> elements.
<copier name="antcall" target="copyresources">
<parameter name="MySettings" value="${polish.name}.settings" />
</copier>
The renamer Resource Copier
Use the “renamer” resource copier for modifying the file-names of the resources before they are
packaged in the final JAR. The following renamer removes all characters that are surrounded by
curly braces. You can use this for giving your resources meaningful names while using short names
in the JAR file. The file i0{ start game icon }.png will be renamed to i0.png, for example. This saves
some precious space.
<copier name="renamer">
<!-- use a regular expression for defining
name parts that should be changed:
-->
<parameter name="searchPattern" value="\{.*\}" />
<!-- define the replacement for the searchPattern here: -->
<parameter name="replacement" value="" />
</copier>
44
The Build Process
The svgconverter Resource Copier
Use the “svgconverter” for modifying SVG images of the resources before they are packaged in the
final JAR. The svgconverter allows you to provide only one icon or background image for a variety
of phones. It scales the SVG image to the appropriate size of the current target device and converts
it into a PNG image. For an background image you have to start naming your image
“bg”(“bg”+whatever+”.svg”), for an icon start with “icon”. The svgconverter then uses the defined
ScreenSize and IconSize of the target device for scaling such images. When the target device
does not specify these sizes the default size for icons is 15x15 and for backgrounds 128x160 pixels.
<copier name="svgconverter" />
<compiler>
The optional <compiler>-element can be used for specifying any compiler-arguments. J2ME Polish
normally calls the Java compiler normally with the appropriate classpath as well as bootclasspath
for the current target device. In some cases you might want to adjust the compiler settings, however,
so you can use the nested <compiler>-element. Along to all attributes of the standard <javac>-task,
the <compiler>-element also supports the "if" and "unless" attributes for selecting to appropriate
compiler setting:
compiler-Attribute Required Explanation
srcdir No Location of the java files, which defaults to the temporary
directory to which the preprocessed files are written.
destdir No Location to store the class files. This defaults to the temporary
build directory into which class files are written before they are
obfuscated.
includes No Comma- or space-separated list of files (may be specified using
wildcard patterns) that must be included; all .java files are
included when omitted.
includesfile No The name of a file that contains a list of files to include (may be
specified using wildcard patterns).
excludes No Comma- or space-separated list of files (may be specified using
wildcard patterns) that must be excluded; no files (except default
excludes) are excluded when omitted.
excludesfile No The name of a file that contains a list of files to exclude (may be
specified using wildcard patterns).
classpath No The classpath to use. J2ME Polish includes all supported
libraries of the current target device by default.
classpathref No The classpath to use, given as a reference to a path defined
elsewhere.
sourcepath No The sourcepath to use; defaults to the value of the srcdir
attribute. To suppress the sourcepath switch, use sourcepath="".
45
The Build Process
compiler-Attribute Required Explanation
sourcepathref No The sourcepath to use, given as a reference to a path defined
elsewhere.
bootclasspath No Location of bootstrap class files. J2ME Polish uses either the
platform specific library files for the bootclasspath, e.g.
midp1.jar or midp2-cldc11.jar.
bootclasspathref No Location of bootstrap class files, given as a reference to a path
defined elsewhere.
extdirs No Location of installed extensions.
encoding No Encoding of source files. (Note: gcj doesn't support this option
yet.)
nowarn No Indicates whether the -nowarn switch should be passed to the
compiler; defaults to off.
debug No Indicates whether source should be compiled with debug
information; defaults to off. If set to off, -g:none will be passed
on the command line for compilers that support it (for other
compilers, no command line argument will be used). If set to
true, the value of the debuglevel attribute determines the
command line argument. J2ME Polish only enables the
debugging when the <debug>-element is active for the current
target device.
debuglevel No Keyword list to be appended to the -g command-line switch.
This will be ignored by all implementations except modern and
classic(ver >= 1.2). Legal values are none or a comma-separated
list of the following keywords: lines, vars, and source. If
debuglevel is not specified, by default, nothing will be appended
to -g. If debug is not turned on, this attribute will be ignored.
optimize No Indicates whether source should be compiled with optimization;
defaults to off.
deprecation No Indicates whether source should be compiled with deprecation
information; defaults to off.
target No Generate class files for specific VM version (e.g., 1.1 or 1.2).
J2ME Polish uses 1.2 by default when the WTK 2.x is used. The
target can also be set with the "javacTarget"-attribute of the
<build>-element.
verbose No Asks the compiler for verbose output; defaults to no.
depend No Enables dependency-tracking for compilers that support this
(jikes and classic).
includeAntRuntime No Whether to include the Ant run-time libraries in the classpath;
defaults to false.
46
The Build Process
compiler-Attribute Required Explanation
includeJavaRuntime No Whether to include the default run-time libraries from the
executing VM in the classpath; defaults to no.
fork No Whether to execute javac using the JDK compiler externally;
defaults to no.
executable No Complete path to the javac executable to use in case of
fork="yes". Defaults to the compiler of the Java version that is
currently running Ant. Ignored if fork="no". Since Ant 1.6 this
attribute can also be used to specify the path to the executable
when using jikes, jvc, gcj or sj.
memoryInitialSize No The initial size of the memory for the underlying VM, if javac is
run externally; ignored otherwise. Defaults to the standard VM
memory setting. (Examples: 83886080, 81920k, or 80m)
memoryMaximumSi
ze
No The maximum size of the memory for the underlying VM, if
javac is run externally; ignored otherwise. Defaults to the
standard VM memory setting. (Examples: 83886080, 81920k, or
80m)
failonerror No Indicates whether the build will continue even if there are
compilation errors; defaults to true.
source No Value of the -source command-line switch; will be ignored by all
implementations prior to javac1.4 (or modern when Ant is not
running in a 1.3 VM) and jikes. If you use this attribute together
with jikes, you must make sure that your version of jikes
supports the -source switch. Legal values are 1.3, 1.4 and 1.5 –
by default, the "1.3" source switch will be used.
compiler No The compiler implementation to use. If this attribute is not set,
the value of the build.compiler property, if set, will be used.
Otherwise, the default compiler for the current VM will be used.
listfiles No Indicates whether the source files to be compiled will be listed;
defaults to no.
tempdir No Where Ant should place temporary files. This is only used if the
task is forked and the command line args length exceeds 4k.
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true for this compiler-setting to be used.
unless No The Ant-property which needs to be “false” or the preprocessing
term which needs result false for this compiler-setting to be used.
The <compilerargs> Subelement
You can specify additional command line arguments for the compiler with nested <compilerarg>
47
The Build Process
elements. These elements are specified like Command-line Arguments but have an additional
attribute that can be used to enable arguments only if a given compiler implementation will be used.
compilerargs-
Attribute
Required Explanation
value Either value, line,
file or path
A single command-line argument; can contain space
characters.
line Either value, line,
file or path
A single command-line argument; cannot contain space
characters.
file Either value, line,
file or path
The name of a file as a single command-line argument;
will be replaced with the absolute filename of the file.
path Either value, line,
file or path
A string that will be treated as a path-like string as a
single command-line argument; you can use ; or : as
path separators and Ant will convert it to the platform's
local conventions.
compiler No Only pass the specified argument if the chosen compiler
implementation matches the value of this attribute.
<obfuscator>
The optional <obfuscator>-element controls the obfuscating of the application bundle, which
decreases the jar-size and makes it difficult to reverse engineer the application.
?/+207,"3/.(%":1@AS./`0".#A(071M12"053S",-"&1@A3.01A(0%5177@A3173A(IH
obfuscator-Attribute Required Explanation
name No The name of the obfuscator which should be used. Defaults to
“ProGuard”. Possible values are “ProGuard”, “KlassMaster”,
“Dasho”, “YGuard” or “RetroGuard”.
useDefaultPackage No J2ME Polish can move all classes to the default package for you.
This includes the MIDlet-classes as well and can result in a
smaller jar-size. Please note that you are responsible for
preventing name-clashes of classes. You do not need to adjust
your <midlet>-settings, this is done automatically by J2ME
Polish. You need, however, adjust any <keep>-settings you have.
"useDefaultPackage" defaults to “false”. When the default
package is used, the preprocessing symbol
"polish.useDefaultPackage" is defined. You can use this to adjust
the loading of dynamic classes.
if No The name of the Ant-property, which needs to be “true” or “yes”,
when this <obfuscator> element should be used.
unless No The name of the Ant-property, which needs to be “false” or “no”,
48
The Build Process
obfuscator-Attribute Required Explanation
when this <obfuscator> element should be used.
class No The class which controls the obfuscator. Each class which
extends #1=1%/0&B=!/5$7B=/+207,"31=E+207,"3/.(can be
used. With this mechanism third party obfuscators can be
integrated easily (compare page 157).
classPath No The classpath for this obfuscator. This is useful for integrating a
third party obfuscator.
Any number of <obfuscator>-elements can be used in a project. All active obfuscators are
combined by J2ME Polish.
The <obfuscator> supports the subelements <keep> and <parameter>.
The <keep> Subelement
The <keep> element is used to define classes which are loaded dynamically (e.g. with
Class.forName(...) ) and should not be obfuscated:
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(%":1@AS./`0".#A(H
?-11!(,5"77@A,/:=,/:!"%8=#8%":$,=N/:1M8%":$,65"77A(IH
?-11!(,5"77@A,/:=,/:!"%8=#8%":$,=a%/3B1.M8%":$,65"77A(IH
?I/+207,"3/.H
keep-Attribute Required Explanation
class Yes The full name of the class which should not get obfuscated.
The used MIDlet classes do not need to be set with the <keep> element, since they are saved from
obfuscation automatically.
The <parameter> Subelement
The <parameter>-element is used to specify parameters for the obfuscator. This can be useful for
integrating third party obfuscators which require additional settings (see page 157):
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(%":1@AS./`0".#A(H
?-11!(,5"77@A,/:=,/:!"%8=#8%":$,=N/:1M8%":$,65"77A(IH
?-11!(,5"77@A,/:=,/:!"%8=#8%":$,=a%/3B1.M8%":$,65"77A(IH
?!".":131.(%":1@A7,.$!3Q$51A(G"501@A==I7,.$!37I/+207,"31=7,.$!3A(IH
?I/+207,"3/.H
parameter-Attribute Required Explanation
name Yes The name of the parameter.
value Yes The value of the parameter.
49
The Build Process
Combining Several Obfuscators
Several obfuscators can be combined just by specifying several <obfuscator> elements. When the
<keep> subelement is used, it only needs to be specified on of the <obfuscator> elements.
J2ME Polish will then use the obfuscated output of one obfuscator as input for the following
obfuscator.
Specific Obfuscator Settings
ProGuard
ProGuard is an excellent obfuscator, shrinker and optimizer by Eric Lafortune. It is freely availabe
under the GNU General Public License and can be downloaded from
http://proguard.sourceforge.net.
If you want to use ProGuard as an obfuscator, please make sure that the proguard.jar-file is listed in
the classpath of the J2ME Polish task-definition (build.xml):
?3"7-#12(%":1@AbZ:1!/5$7BA(
,5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A(
,5"77!"3B@Aij!/5$7B=B/:1;I$:!/.3I1%/0&B4bZ:1!/5$7B4
+0$5#=b".'ij!/5$7B=B/:1;I$:!/.3Ib#/:=b".'!"#$%&'()($*+,-&*#$./-#.$012.3)42.AIH
You can use ProGuard by setting the name-attribute of the <obfuscator>-element to “ProGuard”.
ProGuard 3.x offers an additional optimization of the bytecode, which is disabled by default. The
optimization can be enabled by setting the “optimize”-parameter to “true”:
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(%":1@AS./`0".#A(H
?!".":131.(%":1@A/!3$:$91A(G"501@A3.01A(IH
?I/+207,"3/.H
A text-file which lists all renaming operations is written to
build/[vendor]/[device]/[locale]/obfuscation-map.txt. This file is useful if you get
exceptions in the obfuscated application.
yGuard
The yGuard obfuscator by the yWorks GmbH is another interesting obfuscator and code-shrinker.
J2ME Polish includes the library-classes, which are licensed under the GNU Lesser General Public
License. The full obfuscator is freely available from http://www.yworks.de.
If you want to use yGuard as an obfuscator, please make sure that either the yguard-lib.jar or the
original yguard.jar is listed in the classpath of the J2ME Polish task-definition (build.xml):
?3"7-#12(%":1@AbZ:1!/5$7BA(
,5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A(
,5"77!"3B@Aij!/5$7B=B/:1;I$:!/.3I1%/0&B4bZ:1!/5$7B4
+0$5#=b".'ij!/5$7B=B/:1;I$:!/.3Ib#/:=b".'!"#$%&'()($*+,-&*#$./-5012.36%&7)42.AIH
The yGuard obfuscator can be used by setting the name-attribute of the <obfuscator>-element to
“YGuard”:
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(%":1@Ao`0".#A(IH
50
The Build Process
RetroGuard
RetroGuard is the basis of both yGuard and ProGuard and was developed by Retrologic
Systems/Mark Welsh. It is licensed under the GNU Lesser General Public License and is included
in J2ME Polish by default. It can be downloaded from http://www.retrologic.com.
You can use RetroGuard just by setting the “name”-attribute to “RetroGuard”:
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(%":1@A]13./`0".#A(IH
Zelix KlassMaster
KlassMaster is a commercial obfuscator available from Zelix Pty Ltd. A free evaluation version can
be requested at http://www.zelix.com.
The KlassMaster integration is based on the WTK-mechanism for calling obfuscators, therefore
both the ZKM.jar as well as the kenv.zip needs to be on the classpath:
?3"7-#12(%":1@AbZ:1!/5$7BA(
,5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A(
,5"77!"3B@Aij!/5$7B=B/:1;I$:!/.3I1%/0&B4bZ:1!/5$7B4
+0$5#=b".'ij!/5$7B=B/:1;I$:!/.3Ib#/:=b".'!"#$%&'()($*+,-&*#$./-89:)42.;!"</=)($*
+,-</=%&7-=+>?)@&#AIH
The KlassMaster-integration allows several parameters to be set:
" enableFlowObfuscation: the flow-obfuscation increases the security of the application, but the
application-size as well. It is deactivated by default, therefore. It can be activated by setting the
enableFlowObfuscation-parameter to “true”.
" ObfuscateFlowLevel: The obfuscation-flow level can also be set directly, e.g. “none” or
“aggressive”. This parameter takes precedent above the enableFlowObfuscation-parameter.
" ScriptFile: The file containing the full script can also be set. In that case please note that the
source-jar-file is always the “build/source.jar” and the target-file is the “build/dest.jar”.
The following example shows a possible invocation of KlassMaster:
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(%":1@Ae5"77U"731.A(H
?!".":131.(%":1@AE+207,"31Q5/CD1G15A(G"501@A%/%1A(IH
?I/+207,"3/.H
DashO Pro
DashO Pro is a commercial obfuscator by Preemptive Solutions. A free evaluation version can be
requested at http://www.preemptive.com.
When the DashO Pro obfuscator is used, either the Ant property “dasho.home” or the parameter
“DashoHome” needs to be given. The classpath does not need to be modified.
The DashO Pro obfuscator supports following parameters:
" DashoHome: needs to point to the installation directory of the DashO Pro obfuscator.
" Version: needs to correspond to the used version of DashO. The current default version is “3.1”.
" enableFlowObfuscation: when “true” is given, DashO will obfuscate the application flow as
well. This is deactivated by default.
51
The Build Process
" enableStringEncription: when “true” is given, Strings will be obfuscated by DashO as well.
Since this decreases the performance, it is deactivated by default.
" enableRenaming: when “true” is given, all possible classes will be renamed. This is activated by
default.
" enableOptimization: when “true” is given, the byte-code will be optimized by DashO. This
feature is activated by default.
" ConstantPoolTag: a tag which will be added to all processed classes. This is only visible when a
decompiler is used.
" ScriptFile: The file containing the full script can also be set. In that case please note that the
source-jar-file is always the “build/source.jar” and the target-file is the “build/dest.jar”.
A report about the renamed clases as well as methods will be written to
build/[vendor]/[device]/[locale]/obfuscation-map.txt. This file is useful for resolving
stacktraces in the obfuscated application.
This example shows the integration of DashO Pro:
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(%":1@AM"7B/A(H
?!".":131.(%":1@AM"7B/[/:1A(G"501@AIB/:1I071.IM"7BES./vX=VA(IH
?!".":131.(%":1@As1.7$/%A(G"501@AX=VA(IH
?I/+207,"3/.H
JODE
JODE is quite a powerful optimizer, shrinker and obfuscator by Jochen Hoenicke. It is licensed
under the GNU General Public License and is available at http://jode.sourceforge.net free of
charge.
If you want to use JODE, please make sure that the jode-jar-file is on the classpath:
?3"7-#12(%":1@AbZ:1!/5$7BA(
,5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A(
,5"77!"3B@Aij!/5$7B=B/:1;I$:!/.3I1%/0&B4bZ:1!/5$7B4
+0$5#=b".'ij!/5$7B=B/:1;I$:!/.3Ib#/:=b".'!"#$%&'()($*+,-&*#$./-A$3+6B)B)C6
#.+B)42.AIH
JODE supports the “ScriptFile”-parameter which can be used to specify the obfuscator-script.
Please note that the source-jar-file is always the “build/source.jar” and the target-file is the
“build/dest.jar”:
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(%":1@AR/#1A(H
?!".":131.(%":1@AN,.$!3Q$51A(G"501@A/+207,"31=b/7A(IH
?I/+207,"3/.H
When no script-file-parameter is present, J2ME Polish will create a default script. Depending on the
application and environment, several problems ranging from preverification/linking-errors to
NullPointerExceptions in the JODE-API can occur. Maybe someone with more experience with
JODE can provide help here – please get in touch with j2mepolish@enough.de.
<variables> and <variable>
The optional <variables>-element contains several variable definitions, which can be used for the
52
The Build Process
preprocessing. This mechanism can be used for example to define configuration values:
?G".$"+517($%,50#1a%3S./!1.3$17@A3.01AH
?G".$"+51(%":1@A0!#"3140.5A(G"501@AB33!'IICCC=1%/0&B=#1I0!#"31A(IH
?G".$"+51(%":1@A!/5$7B=Y$51#D"81.=7!5$3P:"&1A
((((G"501@A3.01A(
(((($2@A!/5$7B=s1%#/.(@@(J/-$"A(IH
?IG".$"+517H
variables-Attribute Required Explanation
includeAntProperties No Either “true” or “false”. When “true” all Ant-properties will be
included and can be used in the preprocessing. Defaults to
“false”.
The <variables>-element contains an arbitrary number of <variable>-elements, which define the
actual variables. Each variable needs the attributes name and value:
variable-Attribute Required Explanation
name Yes
unless
file is
used
The name of the variable.
value Yes
unless
file is
used
The value of the variable.
file No The file which contains several variable-definitions. In the file
the variable-names and -values are separated by equals-signs (=).
Empty lines and lines starting with a hash-mark (#) are ignored.
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true for this variable to be included.
unless No The Ant-property which needs to be “false” or the preprocessing
term which needs result false for this variable to be included.
Variables which have been defined in this way can be included into the source code with the “//#=”
preprocessing directive and can be checked with the “[variable-name]:defined” symbol:
IIw$2#12(0!#"3140.5'#12$%1#
IIw@(N3.$%&(0.5(@(Aij(0!#"3140.5(;A*
IIw1571
N3.$%&(0.5(@(AB33!'IICCC=#12"053=,/:I0!#"31A*
IIw1%#$2
Variables can also be compared, please refer to the description of the #if-directive on page 79 for
more information.
53
The Build Process
<debug>
The optional <debug>-element controls the inclusion of debugging messages for specific classes or
packages. The debugging messages will be activated or deactivated in the source code, so the
performance will not be decreased, when the debugging is deactivated.
?#1+0&(7B/CD/&E%F../.@A3.01A(G1.+/71@A2"571A(51G15@A1../.A($2@A3173A(H
?2$531.(!"331.%@A,/:=,/:!"%8=!",-"&1=nA(51G15@A$%2/A(IH
?2$531.(!"331.%@A,/:=,/:!"%8=!",-"&1=U865"77A(51G15@A#1+0&A(IH
?I#1+0&H
In the source code any debug messages must be accompanied by a //#debug-directive:
IIw#1+0&
N8731:=/03=!.$%35%qA$%$3$"5$9"3$/%(#/%1=Ar*
or
IIw#1+0&(C".%
N8731:=/03=!.$%35%qA,/05#(%/3(5/"#(7/:13B$%&===Ar*
or
IIw#1+0&(1../.
N8731:=/03=!.$%35%qA,/05#(%/3(5/"#(7/:13B$%&'(A(l(1r*
In the chapter “The world of preprocessing” on page 82 you will find more about the debugging
possibilities.
debug-Attribute Required Explanation
level No The general debug level which is needed for debug messages.
Possible values are “debug”, “info”, “warn”, “error”, “fatal” or a
user-defined level. Default level is “debug”, so all debugging
messages will be included.
verbose No Either “true” or “false”. When “true” the time, class-name and
line-number will be included in each debugging message.
Defaults to “false”. When the verbose mode is enabled, the
preprocessing symbol “polish.debugVerbose” will be defined.
In the verbose mode exceptions thrown by J2ME Polish will
contain useful information. Also the key-handling and
animation-handling will be monitored and error messages will be
given out.
showLogOnError No Either “true” or “false”. When “true” the log containing all
logging-messages will be shown when an exception is logged.
An exception is logged by printing out a message which is
followed by a plus and the exception variable:
IIw#1+0&(1../.
N8731:=/03=!.$%35%qA,/05#(%/3(5/"#(7/:13B$%&'(A(l(
1r*
The log can only be shown automatically, when the J2ME Polish
GUI is used.
54
The Build Process
debug-Attribute Required Explanation
if No The name of the Ant-property, which needs to be “true” or “yes”,
when this <debug> element should be used. When the <debug>
element is activated, the preprocessing symbol
“polish.debugEnabled” will be defined.
unless No The name of the Ant-property, which needs to be “false” or “no”,
when this <debug> element should be used.
For a finer control of the debugging process, the <debug>-element allows the sub-element <filter>,
which defines the debug-level for specific classes or packages.
filter-Attribute Required Explanation
pattern Yes The name of the class or of the package. When the pattern ends
with a star, all classes of that package will be included, e.g.
“com.company.mypackage.*”
level Yes The debugging level for all classes with the specified pattern.
Possible values are “debug”, “info”, “warn”, “error”, “fatal” or a
user-defined level.
<jad>
With the <jad>-element user-defined attributes can be added to the JAD
1
-file as well as the
MANIFEST-file which is contained in the created JAR-file. The <jad> element contains a number
of <attribute>-sub-elements which define the actual attributes:
?b"#H
(?"33.$+031(
%":1@AJ/-$"4UPM51346"31&/.8A(
G"501@A`":1A(
$2@A!/5$7B=&./0!=N1.$17hKA(
IH
(?"33.$+031(
%":1@AUPM5134S07B4VA(
G"501@A7/,-13'II'Wt^(,/:=70%=1L":!51=N":!516B"3^(nA(
$2@A!/5$7B=:$#!ZA(
IH
?Ib"#H
attribute-Attribute Required Explanation
name Yes
unless
file is
used
The name of the attribute, e.g. “Nokia-MIDlet-Category”
value Yes The value of the attribute.
1 Java Application Descriptor
55
The Build Process
attribute-Attribute Required Explanation
unless
file is
used
file No The file which contains several attribute-definitions. In the file
the attribute-names and -values are separated by colons (:).
Empty lines and lines starting with a hash-mark (#) are ignored.
target No Either “jad”, “manifest” or “jad, manifest”. An user-defined
attribute is added to both, the MANIFEST as well as the JAD, by
default. The specification says user-defined attributes should
only be added to the JAD file, but there are some devices out
there which expect these attributes in the MANIFEST as well.
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true for this attribute to be included.
unless No The Ant-property which needs to be “false” or the preprocessing
term which needs result false for this attribute to be included.
Attributes which are defined in this way can be loaded in the application with the
MIDlet.getAppProperty( String name ) method, which needs the name of the attribute as an
argument and returns the value of that argument. Often it is advisable to use the variable-
mechanism of J2ME Polish instead, since such values are actually hard-coded into the application
and are, therefore, much faster than the getAppProperty(...)-mechanism.
Sorting and Filtering JAD attributes
The JAD-attributes can filtered and sorted using the <jadFilter> subelement:
?b"#H
(?"33.$+031(
%":1@AJ/-$"4UPM51346"31&/.8A(
G"501@A`":1A(
$2@A!/5$7B=&./0!=N1.$17hKA(
IH
(?b"#Q$531.H
UPM5134J":1^(UPM5134s1.7$/%^(
UPM5134s1%#/.^(UPM5134R".4O]D^(UPM5134R".4N$91^(
UPM5134M17,.$!3$/%k^(UPM5134P,/%k^(UPM5134P%2/4O]Dk^
UPM5134M"3"4N$91k^(UPM5134n^(n
(?Ib"#Q$531.H
?Ib"#H
The <jadfilter> element contains all allowed attribute names in the desired order and separated by
commas. You can use different filters by using the "if" or "unless" attributes:
jadFilter-Attribute Required Explanation
if No The Ant-property which needs to be “true” or the preprocessing
56
The Build Process
jadFilter-Attribute Required Explanation
term which needs result true so that this filter is used.
unless No The Ant-property which needs to be “false” or the preprocessing
term which needs result false so that this filter is used.
Inside of the <jadfilter> element you can specify all allowed JAD-attributes in the desired order and
separated by commas. Following syntax is used:
jadFilter-Text Example Explanation
name
UPM5134J":1
The complete name of a required attribute.
name followed by
a questionmark
UPM5134P,/%k
The complete name of an optional attribute.
beginning of a
name followed by
a star
UPM5134n
All remaining attributes which names start with the given
sequence will be included at this position.
star
n
All remaining attributes will be included at this position. A
star can only positioned at the end of a filter.
An overview about allowed attributes can be found at
http://java.sun.com/j2me/docs/wtk2.0/user_html/Ap_Attributes.html.
<manifestFilter>
The manifest filter element can be used to sort and filter manifest attributes. Please note that the
first included attribute should always be the “Manifest-Version”-attribute. Otherwise the application
will most likely not work:
?:"%$2173Q$531.H
U"%$21734s1.7$/%^(UPM5134J":1^(UPM5134s1.7$/%^(UPM5134s1%#/.^
UPM5134V^(UPM5134Zk^(UPM5134Xk^(UPM5134hk^(UPM5134)k^(
U$,./F#$3$/%4S./2$51^(U$,./F#$3$/%46/%2$&0."3$/%^
UPM5134M17,.$!3$/%k^(UPM5134P,/%k^(UPM5134P%2/4O]Dk^
UPM5134M"3"4N$91k
?I:"%$2173Q$531.H
The <manifestFilter> element contains all allowed attribute names in the desired order and
separated by commas. You can use different filters by using the "if" or "unless" attributes:
manifestFilter-
Attribute
Required Explanation
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true so that this filter is used.
57
The Build Process
manifestFilter-
Attribute
Required Explanation
unless No The Ant-property which needs to be “false” or the preprocessing
term which needs result false so that this filter is used.
Inside of the <manifestFilter > element you can specify all allowed MANIFEST-attributes in the
desired order and separated by commas. Following syntax is used:
ManifestFilter-
Text
Example Explanation
name
UPM5134J":1
The complete name of a required attribute.
name followed by
a questionmark
UPM5134Zk
The complete name of an optional attribute.
beginning of a
name followed by
a star
UPM5134n
All remaining attributes which names start with the given
sequence will be included at this position.
star
n
All remaining attributes will be included at this position. A
star can only positioned at the end of a filter.
An overview about allowed attributes can be found at
http://java.sun.com/j2me/docs/wtk2.0/user_html/Ap_Attributes.html.
<preprocessor>
The <preprocessor> element can be used to integrate own or third party preprocessors. This can be
used for allowing new preprocessing directives for example (compare page 159).
?!.1!./,177/.
,5"77@A,/:=,/:!"%8=!.1!./,177=U8S.1!./,177/.A(
,5"77S"3B@A$:!/.3I!.1!./,177$%&=b".A(
H
(?!".":131.(
%":1@A7,.$!3Q$51A(
G"501@A==I7,.$!37I!.1!./,177=7,.$!3A(
IH
?I!.1!./,177/.H
preprocessor-
Attribute
Required Explanation
class Yes The class of the preprocessor.
classPath No The classpath for the preprocessor.
if No The name of the Ant-property, which needs to be “true” or “yes”,
when this <preprocessor> element should be used.
unless No The name of the Ant-property, which needs to be “false” or “no”,
58
The Build Process
preprocessor-
Attribute
Required Explanation
when this <preprocessor > element should be used.
The preprocessor can be configured using a number <parameter> subelements. Each <parameter>
subelement needs to define the attributes “name” and “value”.
<java>
The <java>-element can be used to extend J2ME Polish with any Java utility. It accepts all attributes
and nested elements like the Ant-<java>-element (compare
http://ant.apache.org/manual/CoreTasks/java.html) as well as the additional attribute “if”, “unless”
and “message”. J2ME Polish variables can be used in the nested <arg>-elements, so that the call can
be adjusted for the current device.
Each defined <java>-element is called after the successful creation of an application-bundle. A
possible use of the <java>-element is the signing of MIDlets, which is described in the signing-
how-to on page 186.
The following example calls the JadUtil.jar of the Wireless Toolkit for signing a JAD file:
<java jar="${wtk.home}/bin/JadTool.jar"
fork="true"
failonerror="true"
if="polish.midp2"
unless="test"
message="Adding signature for device ${polish.identifier}"
>
<arg line="-addjarsig"/>
<arg line="-keypass ${password}"/>
<arg line="-alias SignMIDlet"/>
<arg line="-keystore midlets.ks"/>
<arg line="-inputjad dist/${polish.jadName}"/>
<arg line="-outputjad dist/${polish.jadName}"/>
<arg line="-jarfile dist/${polish.jarName}"/>
</java>
Following variables can be used in the <arg>-element and the “message”-attribute:
variable Explanation
polish.vendor The vendor of the current device, e.g. “Siemens” or “Nokia”.
polish.name The name of the current device, e.g. “N-Gage”.
polish.identifier The identifier of the current device, e.g. “Siemens/SX1”.
polish.version The version of the application as defined in the info-section.
polish.jarName The name of the jar-file as defined in the info-section.
polish.jadName The name of the jad-file as defined in the info-section.
59
The Build Process
The most important attributes of the <java>-element are:
java-Attribute Required Explanation
classname either
classname
or jar
The name of the class which should be executed.
jar either
classname
or jar
The location of the jar file to execute (must have a Main-Class
entry in the manifest). Fork must be set to true if this option is
selected.
fork No If enabled triggers the class execution in another VM (disabled
by default).
message No A message which will be printed out on the standard output
when this <java>-element is executed. The message can contain
J2ME Polish variables, such as ${ polish.identifier }.
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true when this <java>-element should
be executed.
unless No The Ant-property which needs to be “false” or the
preprocessing term which needs result false when this <java>-
element should be executed.
The most important nested element is the <arg>-element:
arg-Attribute Required Explanation
line No A space-delimited list of command-line arguments.
Please refer to the Ant-documentation at http://ant.apache.org/manual/CoreTasks/java.html for more
information about the <java>-element.
<packager>
Usually the efficient internal J2ME Polish packager is used for creating the final application
bundles. For using a different packaging-program, the <packager>-element can be used:
?!",-"&1.
1L1,03"+51@Ab".A
".&0:1%37@A,G2U**ij!/5$7B=b".S"3B;**46**ij!/5$7B=!",-"&1M$.;**=A
IH
A much simpler but equally valid call is this:
?!",-"&1.(%":1@Ab".A(IH
A possible alternative might be the Open Source tool “7-Zip”, which can create smaller files
60
The Build Process
compared to the standard ZIP mechanism. This might result in problems on the actual device,
though, so use with care. The 7-Zip tool can be obtained free of charge at http://www.7-zip.org/.
The <packager>-element supports following attributes:
packager-Attribute Required Explanation
name Yes, unless
executable
or class is
defined
The name of the packager, e.g. “jar”, “antcall”, “7zip” or
“kzip”. You can register your own packager in
${polish.home}/custom-extensions.xml by using the “packager”
type.
target No The Ant target that should be used for the packaging step. Only
relevant when the “antcall” packager is used.
executable No The name of the program, e.g. “jar” or “7za.exe”.
arguments No The arguments for the packager when you have defined the
“executable” attribute. Several arguments can be separated by
using double-semicolons (;;). Any Ant-properties as well as
J2ME Polish variables can be used. Often needed variables are:
${polish.jarPath}: the full path to the jar-file which should
be created.
${polish.packageDir}: the directory which contains the
classes and the resources which should be “jared”.
class No The name of the class which extends the
de.enough.polish.jar.Packager class. This mechanism can
be used for extending the packaging capabilities of J2ME
Polish.
In that case further parameters can be set using nested
<parameter>-elements.
The <emulator>-Section
The <emulator>-element is responsible for launching any emulators after the application has been
build.
?1:05"3/.
C"$3@A3.01A
3.",1@A,5"77A
!.121.1%,17@A:81:05"3/.=!./!1.3$17A
71,0.$38M/:"$%@A3.0731#A
1%"+51S./2$51.@A3.01A
1%"+51U1:/.8U/%$3/.@A3.01A
1%"+51J13C/.-U/%$3/.@A3.01A
$2@A3173A
H
?!".":131.(%":1@A4xb":A(
G"501@A3."%7$1%3@B33!'II5/,"5B/73'_K_KIij!/5$7B=b"#J":1;A(IH
61
The Build Process
?I1:05"3/.H
In the above example the emulator is only started, when the “test”-property is “true”.
Attributes of the <emulator>-Section
The <emulator>-element supports following attributes:
emulator-Attribute Required Explanation
wait No Either “yes”/”true” or “no”/”false”. Defines whether the J2ME
Polish task should wait until the emulator is finished. This is
needed when any output should be shown on the Ant-output,
therefore wait defaults to “yes”.
trace No Defines if any virtual machine activities should be shown on
the output. Possible values are “class” for showing the loading
of classes, “gc” for activities of the garbage collection and “all”
for a very extensive output. Several values can be given when
they are separated by comma, e.g “class,gc”.
securityDomain No The MIDP/2.0 security-domain of the application: either
"trusted", "untrusted", "minimum" or "maximum". In “trusted”
and “maximum” mode all security sensitive activities are
allowed; in the “untrusted” mode the user will be questioned
before each security sensitive activity and in the “minimum”
mode any security sensitive activity will not be allowed.
enableProfiler No Either “yes”/”true” or “no”/”false”. When activated the
performance will be profiled during the execution of the
application. The results will be shown when the emulator itself
is closed.
enableMemoryMonit
or
No Either “yes”/”true” or “no”/”false”. When activated the
memory usage of the application will be shown.
enableNetworkMonit
or
No Either “yes”/”true” or “no”/”false”. When any network
activities are done, a monitor will show details of the sent and
received data.
preferences No The file which contains the emulator-preferences. When such a
file is used, the profiler and monitor settings are ignored. Please
consult the documentation of the Wireless Toolkit for detailed
information about the preferences file.
showDecompiledSta
ckTrace
No Either “yes”/”true” or “no”/”false”. Determines whether a
decompiled stack-trace should be shown, even when the source-
code position of an exception could be be located. The
automatic resolving of stack traces is discussed below.
if No The Ant-property which needs to be “true” when the
62
The Build Process
emulator-Attribute Required Explanation
<emulator>-element should be executed.
unless No The Ant-property which needs to be “false” when the
<emulator>-element should be executed.
The <parameter> Subelement
The <emulator>-element supports the nested subelement <parameter> for defining additional
command line parameters:
parameter-Attribute Required Explanation
name Yes The name of the parameter.
value Yes The value of the parameter, the value can use any J2ME Polish
or user-defined variable, the following variables are especially
useful:
${polish.jadName}: The name of the JAD-file
${polish.jadPath}: The absolute path of the JAD-file
${polish.jarName}: The name of the JAR-file
${polish.jarPath}: The absolute path of the JAR-file
${polish.classes.midlet-1}: The main MIDlet class
${polish.classes.midlet-2}: The second MIDlet class, if
any
${polish.classes.midlet-n}: The n
th
MIDlet class, if any
When only a command-line switch should be defined, just define
an empty value, e.g.
<parameter name="-Xsomething" value="" />
if No The Ant-property which needs to be “true” or the preprocessing
term which needs result true when this parameter should be used.
unless The Ant-property which needs to be “false” or the preprocessing
term which needs result false when this parameter should be
used.
Emulator-Settings in the Device Database and in the build.xml
J2ME Polish uses the device-database to determine the correct emulator. If an emulator cannot be
started, you can tell J2ME Polish how to launch it by modifying these settings.
WTK Emulators
For emulators which are integrated in the Wireless Toolkit the “Emulator.Skin”-capability is used
for determining the correct emulator. This is the name which can be found in the
63
The Build Process
“${wtk.home}/wtklib/devices” folder, e.g. “SonyEricsson_P900” etc. When no
“Emulator.Skin”-capability is found, the current default emulator will be started instead. When the
wrong emulator is started, please check if the “Emulator.Skin”-capability has been set in the
“${polish.home}/devices.xml” file. If that capability is missing, please report it also to
j2mepolish@enough.de so that the device database can be improved.
You can also set several skins, when several versions of an emulator do exist, for example.
J2ME Polish will then choose the the first emulator it finds. Additional skins are defined by the
capabilities “Emulator.Skin.2”, “Emulator.Skin.3” and so forth.
Nokia Emulators
For launching Siemens-emulators it might be necessary to define the “nokia.home”-property in the
build.xml. This property needs to point to the installation directory of the Nokia emulators and
defaults to “C:\Nokia” on Windows machines and to “${user.home}/Nokia” on Unix machines. For
many emulators it is sufficient to set the “Emulator.Class” and “Emulator.Skin”-capabilities of
the device in the “${polish.home}/devices.xml” file. The “Emulator.Class”-capability then needs
to be “NokiaEmulator” and the “Emulator.Skin”-capability needs to correspond with the name of
the emulator which can be found in the “${nokia.home}/Devices”-directory.
Some non-standard-emulators make it necessary the use the “GenericEmulator”-class instead. The
invocation of such emulators is explained below.
Siemens Emulators
For launching Siemens-emulators it might be necessary to define the “siemens.home”-property in
the build.xml. This property needs to point to the installation directory of the “Siemens Mobile
Toolkit” (SMTK) and defaults to “C:\siemens”. When a Siemens-emulator should be used, the
corresponding device-definition in the “${polish.home}/devices.xml” file needs to set the
“Emulator.Class”-capability to “SiemensEmulator” (this is the default for all Siemens-phones).
The “Emulator.Skin”-capability needs to specify the name of the emulator, which can be found in
the “${siemens.home}/SMTK/emulators”-directory.
Motorola Emulators
For launching Motorola-emulators it is necessary to define the “motorola.home”-property in the
build.xml. This property needs to point to the installation directory of the Motorola SDK, e.g.
“C:\program files\Motorola\SDK v.4.3 for J2ME”. Since Motorola-emulators do not support the
“Unified Emulator Interface”, the emulators are started by the “GenericEmulator”. See below for
more details.
Launching any Emulator with the GenericEmulator-Implementation
You can start any kind of emulator with the GenericEmulator class. You should set the
“Emulator.Class”-capability of the corresponding device-definition in the
“${polish.home}/devices.xml” file to “GenericEmulator”.
The “Emulator.Executable”-capability needs to define the program which should be started, e.g.
“java” or “${motorola.home}/EmulatorA.1/bin/emujava.exe”. This program is responsible for
starting the emulator.
64
The Build Process
You need also to define the command-line arguments for the emulator with the
“Emulator.Arguments”-capability. Command-line arguments are separated by two semicolons in a
row, e.g. “-Xdescriptor;;${polish.jadPath};;-classpath;;${polish.jarPath}”. As you can see in the
example, any J2ME Polish-variables as well as Ant-properties can be used within the emulator-
arguments. Often used is the “polish.jadPath”-variable, which contains the absolute path to the
JAD-file and the “polish.jarPath”-variable, which does the same for the JAR-file. Also useful is the
polish.classes.midlet-1 variable that contains the name of the first MIDlet class.
You should try to minimize the dependency on a specific system setup by using properties like
“motorola.home” or “nokia.home” in your settings. These properties can then be defined within the
corresponding build.xml file.
Please inform the J2ME Polish community about any emulators you have integrated, so that other
users can also benefit from your settings. Just send an email to j2mepolish@enough.de. Thanks!
Automatic Resolving of Stack Traces and Exceptions
J2ME Polish can resolve stack traces like “Exception at
com.company.MyClass.doSomething(+200)” automatically, when the free “jad” decompiler is
installed. This decompiler can be downloaded at http://www.kpdus.com/jad.html. Please adjust
the PATH environment variable, so that it includes the installation directory of jad or install the jad-
excecutable (jad.exe or jad) to the “${polish.home}/bin” folder.
When jad is installed correctly, J2ME Polish will resolve stack traces automatically. Instead of
seeing only the rather obscure stack trace package.class.method(+instructionoffset), an
additional message giving the source-location as well as the faulty source code is printed out, e.g.
“src/com/company/MyClass.java:97: int result = max / 0;”. If you execute J2ME Polish
from within an IDE, you can click on such a message and then edit the faulty code directly.
In cases when J2ME Polish is not able to locate the position in the source code, an extract of the
decompiled class-code will be shown instead. This extract will help you to identify the source of the
error. The following fragment gives an example of a decompiled class code:
world.animate(System.currentTimeMillis() - lastCycleTime);
// 87 169:aload_0
// 88 170:getfield #13 <Field World world>
// 89 173:invokestatic #17 <Method long System.currentTimeMillis()>
// 90 176:lload 4
// 91 178:lsub
// 92 179:invokevirtual #23 <Method void World.animate(long)>
In the first line the actual directive is given and in the following lines the binary equivalent
compiled java code is listed. The second number from the left is the number which is given in the
original error message (e.g. package.class.method(+179)).
When the “showDecompiledStackTrace”-attribute of the <emulator>-element is set to “true” or
“yes”, a decompiled code fragment will be given out for each stack-trace, even when the source-
code position could be located.
Please note that the source-code position can only be located, when the debugging-mode is
activated. This is done by setting the “enable”-attribute of the <debug>-element to “true”. In the
default-setup this is done when the “test”-target of the build.xml is called first:
65
The Build Process
“ant test j2mepolish”.
66
Resource Assembling
Resource Assembling
Concepts
During the build process resources like images, sound files etc. are assembled automatically for
each device.
Resources for all devices will be placed into the “resources” folder (when no other directory has
been specified in the <resources>-element or with the “resDir”-attribute of the <build>-element in
the “build.xml” file).
Resources for devices of specific vendors can be placed into the “resources/[vendor-name]” folder,
e.g. the “resources/Nokia” folder for Nokia devices. Resources for a specific device can be placed
into the “resources/[vendor-name]/[device-name]” folder, e.g. the folder “resources/Nokia/3650” for
Nokia/3650 devices.
For more general resources the groups can be used to which a device belongs to. High-color images
can be be put into the “resources/BitsPerPixel.16+” folder, for example. The groups can be used
very efficiently to include only those resources which are actually relevant for a specific device. A
device can belong to many different groups, which are defined either implicitly by the capabilities
of that device (compare the section “Device Capabilities” on page 26) or explicitly by setting the
<groups>-element of a device in the device-database.
All resources will be copied to the root of the application and more specific resources will overwrite
the common resources: If you have a picture named “hello.png” in the “resources” folder as well as
in the “resources/Nokia” and in the “resources/Nokia/6600” folder, the version in the “resources”
folder will be used for all non-Nokia devices, the version contained in the “resources/Nokia” folder
will be used for all Nokia devices, but the image “resources/Nokia/6600/hello.png” will be used for
the application which is build for the Nokia/6600 phone. In the application code you can load this
image from the root: Image.createImage( "/hello.png" ), no matter from where the resource
was copied from.
No subfolders can be used within an application, so it is not possible to load resources from a
subfolder within the application. Subfolders do add overhead to an application, this is why the usage
of subfolders is not allowed.
Instead of
// this is not allowed:
InputStream is = getClass().getResourceAsStream("/levels/level.map");
the following code needs to be used:
InputStream is = getClass().getResourceAsStream("/level.map"); // this is ok
Subfolders are merely used to differentiate between different devices and device groups.
Often Used Groups
For a complete list of groups please refer to the section “Device Capabilities” on page 26, the
HTML-documentation also lists all groups for each device contained in the device database. Here a
couple of examples:
67
Resource Assembling
Group Type Default Folder Explanation
ScreenSize.17
6x208
Screen resources/ScreenSize.1
76x208
Folder for different screen sizes of the target
devices, e.g. ScreenSize.176x208 or
ScreenSize.128x128 and so on.
ScreenSize.17
0+x200+
Screen resources/ScreenSize.1
70+x200+
Folder for devices with screens that are as large
or larger than the specified screen size. In the
example the screen needs to be at least 170
pixels wide and 200 pixel high so that resources
from that folder are included.
CanvasSize.17
6x208
Canvas resources/CanvasSize.1
76x208
Folder for different canvas sizes of the target
devices, e.g. CanvasSize.176x208 or
CanvasSize.128x128 and so on.
CanvasSize.1
70+x200+
Canvas resources/CanvasSize.1
70+x200+
Folder for devices with canvasses that are as
large or larger than the specified canvas size. In
the example the canvas needs to be at least 170
pixels wide and 200 pixel high so that resources
from that folder are included.
FullCanvasSi
ze.176x208
FullCan
vas
resources/FullCanvasSi
ze.176x208
Folder for different fullscreen-mode-canvas sizes
of the target devices, e.g.
FullCanvasSize.176x208 or
FullCanvasSize.128x128 and so on.
FullCanvasSi
ze.170+x200+
FullCan
vas
resources/FullCanvasSi
ze.170+x200+
Folder for devices with canvasses that are as
large or larger than the specified canvas size in
fullscreen-mode. In the example the canvas
needs to be at least 170 pixels wide and 200
pixel high in fullscreen-mode so that resources
from that folder are included.
Series60 Platform resources/Series60 Folder for Symbian Series 60 devices.
Series40 Platform resources/Series40 Folder for Symbian Series 40 devices.
midp1 Platform resources/midp1 When a device supports the MIDP/1.0 platform,
resources for this device can be placed into the
“resources/midp1” folder.
midp2 Platform resources/midp2 For devices supporting the MIDP/2.0 platform.
cldc1.0 Configu
ration
resources/cldc1.0 For devices supporting the CLDC/1.0
configuration.
cldc1.1 Configu
ration
resources/cldc1.1 For devices supporting the CLDC/1.1
configuration.
mmapi api resources/mmapi When a device supports the Mobile Media API,
resources which need this API can be placed
into the “resources/mmapi” folder.
68
Resource Assembling
Group Type Default Folder Explanation
motorola-lwt api resources/motorola-lwt For devices which support Motorola's
Lightweight Windowing Toolkit-API.
nokia-ui api resources/nokia-ui For devices which support Nokia's User
Interface API.
wav audio resources/wav For devices which support the WAV sound
format.
mp3 audio resources/mp3 For devices which support the MP3 sound
format.
amr audio resources/amr For devices which support the AMR sound
format.
midi audio resources/midi For devices which support the MIDI sound
format.
mpeg-4 video resources/mpeg-4 For devices which support the MPEG-4 video
format.
h.263 video resources/h.263 For devices which support the h.263 video
format.
3gpp video resources/3gpp For devices which support the 3GPP video
format.
BitsPerPixel.1
2+
colors resources/BitsPerPixel.
12+
For devices with a color depth of at least 12 bits
per color.
BitsPerPixel.1
6
colors resources/BitsPerPixel.
16
For devices with a color depth of exactly 16 bits
per color.

Fine Tuning the Resource Assembling
Sometimes it is necessary to adjust the resource assembling.
Imagine the situation where you have an application which uses MP3 soundfiles when the device
supports MP3, and MIDI soundfiles when the device supports MIDI. In the source code you can use
the preprocessing symbols “polish.audio.mp3” and “polish.audio.midi” to distinguish between these
cases:
//#ifdef polish.audio.mp3
// okay play the mp3 sound
//#elifdef polish.audio.midi
// play midi sound instead
//#endif
The situation is different in the resource assembling step, though. Obviously you can put all MP3-
files into the “resources/mp3” folder and all MIDI-files into the “resources/midi”-folder, so that
these resources are available when they are needed. But for devices which support both MP3 as well
as MIDI sound, the application will contain the MIDI files as well, even though only the MP3 files
69
Resource Assembling
are actually needed.
For such cases you can define file-sets in the build.xml which will be included when specific
conditions are fulfilled:
?.17/0.,17
#$.@A.17/0.,17A
1L,50#17@A.1"#:1nA(
H
?2$51713(
#$.@A.17/0.,17I:053$:1#$"A(
$%,50#17@An=:!XA(
$2@A!/5$7B="0#$/=:!XA(
IH
?2$51713(
#$.@A.17/0.,17I:053$:1#$"A(
$%,50#17@An=:$#A(
$2@A!/5$7B="0#$/=:$#$("%#(%/3(!/5$7B="0#$/=:!XA(
IH
?I.17/0.,17H
In the above example MIDI files are only included when two conditions are met:
1) The device supports MIDI sound
2) The device does not support MP3 sound.
The <resources>-element is a subelement of the <build>-section, look at page 41 for detailed
information about the supported attributes as well as the nested elements. An often used attribute is
the “exclude”-attribute which specifies any files which should not be included into the application
bundle. You can have readme-files for example with background information for designers. In the
above example all files starting with “readme” are excluded from the final application JAR file.
The <resources>-element is also responsible for the localization of the application, which is
discussed in the following chapter.
On a final note please remember not to use the “resDir”-attribute of the <build>-element when you
use the <resources>-element, since this will yield unpredictable results.
Localization
Concepts
Often applications should not only be marketed in one country or region, but in several ones. The
process of adjusting an application to a specific region is called localization.
J2ME Polish offers a very powerful framework for not only managing the obvious needed
translations, but also for adjusting any kind of resources like images or sounds to specific regions.
Even enhanced features like locale-aware date-formatting is no problem with J2ME Polish.
Traditionally localization involved loading the localized messages from a file during runtime and
retrieving these messages with Hashtable-keys. This significantly slows down a localized
application and also enlarges the application size. A unique feature of J2ME Polish is that the
translations are actually directly embedded into the source-code, so in most cases a localized
application has absolutely no overhead at all compared to a non-localized application – both in size
70
Localization
as well as in performance.
You can also enable dynamic translations that can be changed during the runtime of the application.
In that case any String-keys are converted into simple integer-keys during the preprocessing phase
so that translations can be retrieved as fast as possible.
The localization framework extends the concepts of the resource assembling, so that you can for
example provide one Nokia specific resource for each supported locale. The localization is
controlled by the <localization>-element, which is a subelement of the <resources>-element
(compare pages 67 and 41).
The <localization>-Element and Localized Resource Assembling
?.17/0.,17
#$.@A.17/0.,17A
1L,50#17@An=3L3A
H
?5/,"5$9"3$/%(5/,"517@A#1^(1%^(2.v6aA(0%5177@A3173A(IH
?5/,"5$9"3$/%(5/,"517@A1%A($2@A3173A(IH
?I.17/0.,17H
The <localization>-element is responsible for defining which locales should be supported. In the
above example the locales “de” (German) and “en” (English) are used, unless the test-mode is
active, in which case the application is only build for the English locale.
Locales are defined using the ISO standard of two lowercase letters for the language
2
(“en” for
English, “de” for German, “fr” for French and so on) and two optional uppercase letters for the
country
3
(“US” for USA, “DE” for Germany, “FR” for France and so on). Possible combinations
separate the language and the region with an underline. You can localize your application for French
speaking Canadians by supporting the locale “fr_CA” for example.
In each used resources-folder you can create a subfolder for a specific locale, e.g. “resources/en” for
general English resources and “resources/fr_CA” for resources for the French speaking Canadians.
The usual specification rules also apply here, so a more specific resource in “resources/Nokia/en”
will override a resource with the same name in “resources/Nokia” when the English locale is used.
Managing Translations
The Locale Class
The de.enough.polish.util.Locale class is used for the retrieval of translations. It offers three
distinct translation methods:
! static String get( String name ),
! static String get( String name, String parameter ), and
! static String get( String name, String[] parameters ).
The following code illustrates the usage of these methods:
import de.enough.polish.util.Locale;
2 ISO-639, compare http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
3 ISO-3166, compare http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
71
Localization
[...]
// getting a simple translation:
this.menuScreen.append( Locale.get( "menu.StartGame"), null);
// getting a translation with one parameter:
this.menuScreen.setTitle( Locale.get( "title.Main", userName ), null);
// getting a translation with several parameters:
String[] parameters = new String[2];
parameters[0] = userName;
parameters[1] = enemyName;
this.textField.setString( Locale.get("messages.Introduction", parameters ) );
You need to put the ${polish.home}/import/enough-polish-client.jar on the classpath of
your project to use the Locale-class in your IDE.
In the “resources/messages.txt” the above localizations need to be defined:
menu.StartGame=Start Tickle Fight
# the title of the main-screen with the user-name as the only parameter:
title.Main=Welcome {0}!
# the intro for a new game - with following parameters:
# {0}: the name of the player
# {1}: the name of the remote or computer player
messages.Introduction={1} threatens to tickle you!\n{0} against {1} is loading...
As you can see in the above example you can use parameters in the translations, the first parameter
is {0}, the second {1} and so on. You can also use any Java specific characters, e.g. “\t” for a tab
or “\"” for using a quotation mark.
The translations are embedded in the actual code during the preprocessing phase, if you have a look
at the preprocessed code, you will find following code:
import de.enough.polish.util.Locale;
[...]
// getting a simple translation:
this.menuScreen.append( "Start Tickle Fight", null);
// getting a translation with one parameter:
this.menuScreen.setTitle( "Welcome " + userName + "!", null);
// getting a translation with several parameters:
String[] parameters = new String[2];
parameters[0] = userName;
parameters[1] = enemyName;
this.textField.setString( Locale.get(0, parameters ) );
The translations for the first two Locale-methods are directly embedded into the source-code, so
there is no performance or size impact compared to a non-localized application at all for these kinds
of translations. Only for the third method a call to the Locale class is actually made, but in that call
the former String key “messages.Introduction” is transformed to a simple integer, thus saving
valuable bytes as well as ensuring a fast retrieval of the resource in question.
Dynamic Translations
You can also use dynamic translations that can be changed during the runtime of your application.
You have to activate dynamic translations by setting the "dynamic"-attribute of the <localization>-
72
Localization
element to "true":
?.17/0.,17
#$.@A.17/0.,17A
1L,50#17@An=3L3A
H
?5/,"5$9"3$/%(
#8%":$,@A3.01A
#12"053@A1%A
5/,"517@A#1^(1%^(2.v6aA(
IH
?I.17/0.,17H
You can now use the Locale class normally, the only difference to using static translations is that the
translations are not embedded into your source-code but rather retrieved dynamically from the
Locale class. For allowing a fast performance J2ME Polish converts all String-based keys into
simple integer-values, so that only a minimal overhead is present.
You can change the translations by calling Locale.loadTranslations( String url ). For each
supported locale J2ME Polish generates a [locale-name].loc file, e.g. "de.loc", "en.loc" or
"fr_CA.loc". You can switch to the German translation by calling Locale.loadTranslations(
"/de.loc" ), for example. Don't forget the slash character '/' at the start of the URL.
Defining Translations
All translations are by default defined in the messages.txt file. All default messages are defined in
“resources/messages.txt”, all German messages in “resources/de/messages.txt” and all
French Canadian resources in “resources/fr_CA/messages.txt”. You can also use the files
“resources/messages.txt”, “resources/messages_de.txt” and
“resources/messages_fr_CA.txt” if you prefer to have all translations in one folder. The name of
the messages-files can be adjusted with the “messages”-attribute of the <localization>-element by
the way.
The translations can be adjusted by the usual hierarchy of the resource assembling, so if you have
Nokia-specific translations, these can be defined in the “resources/Nokia/messages.txt” etc.
When an application is localized for the Nokia/6600 phone and the German (“de”) language, J2ME
Polish tries to find a translation in following places:
1. resources/Nokia/6600/de/messages.txt
2. resources/Nokia/6600/messages_de.txt
3. resources/[group-name]/de/messages.txt, e.g. resources/Series60/de/messages.txt
4. resources/[group-name]/messages_de.txt, , e.g. resources/Series60/messages_de.txt
5. resources/Nokia/de/messages.txt
6. resources/Nokia/messages_de.txt
7. resources/de/messages.txt
8. resources/messages_de.txt
When the translation is still not found the same hierarchy is searched again, but this time the default
73
Localization
messages.txt file is used. If the translation cannot be found, J2ME Polish will report the error and
stop the build. When also a region is specified (e.g. “fr_CA” for French Canadian), J2ME Polish
will first try to get a specific “fr_CA” message, e.g. from
“resources/Nokia/6600/fr_CA/messages.txt”, secondly the translation will be searched for the
language, e.g. “resources/Nokia/6600/fr/messages.txt”, before the translation is retrieved
from the default messages-file.
In the actual translation files you can insert comments by starting the line with a hash-mark (#).
Like in normal Java internationalization you can use parameters within the translations, which are
denoted by {0}, {1}, {2} and so on:
menu.StartGame=Start Tickle Fight
# the title of the main-screen with the user-name as the only parameter:
title.Main=Welcome {0}!
# the intro for a new game - with following parameters:
# {0}: the name of the player
# {1}: the name of the remote or computer player
messages.Introduction={1} threatens to tickle you!\n{0} against {1} is loading...
Setting and Using Localized Variables
You can set localized variables just by defining them in the appropriate messages-file. Variable-
definitions need to start with either “var:” or “variable:”:
var:VirtualCurrency=Nuggets
Such variables can also be used within the translations (of course normal variables can also be
used):
# The player has won some nuggets, {0} specifies the number of won nuggets:
messages.YouHaveWon=Congrats! You have won {0} ${polish.Vendor}-${VirtualCurrency}!
Naturally the variables can be used during the usual preprocessing in the Java source code as well:
//#= String virtualCurrency = "${VirtualCurrency}";
Using Localized Attributes
Some JAR- or MANIFEST-attributes need to be localized as well, e.g. the description of the
application. This can be done by defining such MIDlet-attributes in the appropriate messages-file:
MIDlet-Description=A game where you need to tickle your enemies!
MIDlet-Name=Tickle-Fight
Please compare the documentation of the <info>-section on page 31 for learning the names of the
MIDlet-attributes.
Coping with Dates and Currencies
The de.enough.polish.util.Locale class offers some help for dealing with localized content:
! static String formatDate( Calendar calendar ) formats a date specific to the current
locale, this method is also available for Date and long.
! static String LANGUAGE is a field holding the ISO language code.
74
Localization
! static String COUNTRY is a field holding the ISO country code. This is null when no country
is used in the current locale.
! static String DISPLAY_LANGUAGE is a field holding the localized language name, e.g.
“Deutsch” for German.
! static String DISPLAY_COUNTRY is a field holding the localized country name, e.g.
“Deutschland” for Germany. This is null when no country is used in the current locale.
! static String CURRENCY_SYMBOL is a field holding the symbol of the used currency, e.g. “$”
or “€”. This is null when no country is used in the current locale.
! static String CURRENCY_CODE is a field holding the three-letter code of the used currency,
e.g. “USD” or “EUR”. This is null when no country is used in the current locale.
Common Traps
Adjusting the JAR-name
You need to remember to adjust the JAR-name of the application in the <info>-section of the
build.xml, so that the locale is included, otherwise only the last localized application is actually
written to the “dist” folder. You can use the variables ${polish.locale} e.g. “fr_CA”,
${polish.language} e.g. “fr”, and ${polish.country} e.g. “CA” in the jarName-attribute.
An example jarName-attribute is the following:
?$%2/(<===>
b".J":1@Aij!/5$7B=G1%#/.;4ij!/5$7B=%":1;4ij!/5$7B=5/,"51;41L":!51=b".A(
Using Quotation Marks and Other Special Characters in Translations
You can use quotation marks as well as any special character if you escape them directly, usually
with a backslash-character “\” at the start, e.g.:
! Quotation marks: \"
! Tab: \t
! Backslash: \\
! and so on.
In the translations all standard Java escape sequences are supported.
Invalid Locale Calls
Please ensure that the key of the translation is always given directly instead of using a variable,
otherwise J2ME Polish will not be able to embed the translation correctly and you end up with
compile errors. The following example must not be used:
// never do this:
String key = "menu.StartGame";
this.menuScreen.append( Locale.get( key ), null);
Instead use the key directly in the call as in this example:
75
Localization
// this is just fine:
this.menuScreen.append( Locale.get( "menu.StartGame" ), null);
When you have several parameters, the parameters need to be given in a variable, otherwise J2ME
Polish is again unable to process the call correctly:
// never do this:
this.menuScreen.append( Locale.get( "game.StartMessage" ), new String[]{ userName,
enemyname } );
Instead define the parameters before the actual call:
// this is just fine:
String[] parameters = new String[]{ userName, enemyname };
this.menuScreen.append( Locale.get( "game.StartMessage" ), parameters );
Localizing the J2ME Polish GUI
The J2ME Polish GUI uses several texts, which can be localized using variables. The following
variables can be set either in the build.xml or within the messages.txt file:
Variable Default Explanation
polish.command.ok OK The label for the OK-menu-item, which is used Screen-
menus when the “menu”-fullscreen-mode is used.
polish.command.cancel Cancel The label for the Cancel-menu-item.
polish.command.select Select The label for the Select-menu-item, which is used by an
implicit or exclusive List or ChoiceGroup.
polish.command.mark Mark The label for the Mark-menu-item of a multiple List or
ChoiceGroup.
polish.command.unmark Unmark The label for the Unmark-menu-item of a multiple List or
ChoiceGroup.
polish.command.options Options The label for the menu when several menu-items are
available.
polish.command.delete Delete The label for the Delete-menu-item, which is used by
TextFields.
polish.command.clear Clear The label for the Clear-menu-item, which is used by
TextFields.
polish.title.input Input The title of the native TextBox which is used for the actual
input of text. This title is only used, when the corresponding
TextField-item has no label. When the TextField has a label,
that label is used as a title instead.
The following example shows the definition of some of these variables within a messages.txt file:
var:polish.command.cancel=Abbruch
76
Localization
var:polish.command.delete=Löschen
G".'!/5$7B=3$351=$%!03@F$%&"+1
This example shows the definition of some of these variables within the build.xml file. This
approach is useful when no complete localization/internationalization should be done:
<variable name="polish.command.cancel" value="Abbruch" />
<variable name="polish.command.delete" value="Löschen" />
<variable name="!/5$7B=3$351=$%!03" value="F$%&"+1" />
77
The World of Preprocessing
The World of Preprocessing
Preprocessing changes the source code before it is compiled. With this mechanism any device
optimization can be done easily. An example is the inclusion of the J2ME Polish GUI, which can be
included without any intervention of the developer.
Most preprocessing is triggered by directives, which use either symbols or variables. A symbol is
like a boolean value – either it is defined or the symbol is not defined. A variable, however, always
contains a value, which can be used or compared during the preprocessing.
Symbols and variables are defined in several files:
" build.xml: with the “symbols”-attribute of the <build>-element and with the <variables>-
element
" vendors.xml, groups.xml, devices.xml: symbols are defined by the <features>-element, whereas
variables are defined by the capabilities. Most capabilities also define symbols, see the section
“Capabilities” on page 26.
Preprocessing directives always start with a “//#” and often have one or more arguments. All
directives must not span several rows.
J2ME Polish supports all directives of the antenna preprocessor (antenna.sourceforge.net), by the
way. So if you migrate from antenna, you can keep your preprocessing directives.
Checking a Single Symbol with #ifdef, #ifndef, #else, #elifdef, #elifndef and #endif
Single symbols can be checked easily with the #ifdef directive:
IIw$2#12(!/5$7B=$:"&17=#$.1,3D/"#
P:"&1($:"&1(@(P:"&1=,.1"31P:"&1q(%":1(r*
IIw(.130.%($:"&1*
IIw1571
7,B1#051P:"&1q(%":1(r*
.130.%(%055*
IIw1%#$2
When the symbol “polish.images.directLoad” is defined, the code will be transformed to the
following:
IIw$2#12(!/5$7B=$:"&17=#$.1,3D/"#
P:"&1($:"&1(@(P:"&1=,.1"31P:"&1q(%":1(r*
.130.%($:"&1*
IIw1571
IIw(7,B1#051P:"&1q(%":1(r*
IIw(.130.%(%055*
IIw1%#$2
If, however, the symbol “polish.images.directLoad” is not defined, the transformation will be:
IIw$2#12(!/5$7B=$:"&17=#$.1,3D/"#
IIw(P:"&1($:"&1(@(P:"&1=,.1"31P:"&1q(%":1(r*
IIw(.130.%($:"&1*
IIw1571
7,B1#051P:"&1q(%":1(r*
.130.%(%055*
IIw1%#$2
Each #ifdef and #ifndef directive needs to be closed by the #endif directive.
78
The World of Preprocessing
If a variable is defined, it can be checked via //#ifdef [variable]:defined :
IIw$2#12(!/5$7B=N,.11%N$91'#12$%1#
Directive Meaning Explanation
//#ifdef [symbol] if [symbol] is defined The symbol named [symbol] needs to be
defined, when the next section should be
compiled.
//#ifndef [symbol] if [symbol] is not defined The symbol named [symbol] must not be
defined, when the next section should be
compiled.
//#else else When the previous section was false, the
following section will be compiled (and
the other way round).
//#elifdef [symbol] else if [symbol] is defined The symbol named [symbol] needs to be
defined and the previous section needs to
be false, when the next section should be
compiled.
//#elifndef [symbol] else if [symbol] is not defined The symbol named [symbol] must not be
defined and the previous section needs to
be false, when the next section should be
compiled.
//#endif end of the if-block End of every ifdef and ifndef block.
The #ifdef directives can be nested, of course. Other preprocessing directives can be included into
the sub-sections as well:
IIw$2#12(:8N8:+/5
IIw$2%#12(:8E3B1.N8:+/5
IIw#1+0&
N8731:=/03=!.$%35%qA/%58(:8N8:+/5($7(#12$%1#=Ar*
#/N/:13B$%&qr*
IIw1571
IIw#1+0&
N8731:=/03=!.$%35%qA:8N8:+/5("%#(:8E3B1.N8:+/5(".1(#12$%1#=Ar*
#/N/:13B$%&F571qr*
IIw1%#$2
IIw1%#$2
The #ifdef directive and its related directives are faster to process than the more complex #if
directives.
Checking Several Symbols and Variables with #if, #else, #elif and #endif
With each #ifdef directive only a single symbol can be checked. With the #if and #elif directives,
however, complex terms containing several symbols and variables can be evaluated:
IIw$2(071F%B"%,1#P%!03(uu(q!/5$7B=B"7S/$%31.FG1%37(yy(!/5$7B=:/071N0!!/.31#r
79
The World of Preprocessing
#/N/:13B$%&qr*
IIw1%#$2
#if directives can also be nested and contain other preprocessing directives like the #ifdef directives.
#if and #ifdef directives can also be mixed:
IIw$2(f+"7$,P%!03(uu(q!/5$7B=B"7S/$%31.FG1%37(yy(!/5$7B=:/071N0!!/.31#r
#/N/:13B$%&qr*
IIw$2(!/5$7B=\$37S1.S$L15(H@(_
#/N/:13B$%&6/5/.205qr*
IIw1571
#/N/:13B$%&M055qr*
IIw1%#$2
IIw15$2#12(#/d$5#N3022
#/d$5#N3022qr*
IIw1%#$2
Directive Meaning Explanation
//#if [term] if [term] is true The specified term must be true, when the
next section should be compiled.
//#else else When the previous section was false, the
following section will be compiled (and
the other way round).
//#elif [term] else if [term] is true The specified term needs to be true and
the previous section needs to be false,
when the next section should be compiled.
//#endif end of the if-block End of every if block.
In the terms the boolean operators &&, ||, ^ and ! can be used. Complex terms can be separated
using normal parenthesizes “(“ and “)”. The term arguments for boolean operators are symbols,
which are true when they are defined and false otherwise.
Variables can be checked with the comparator ==, >, <, <= and >=. Arguments for the comparators
are variables or constants.
A term can include comparators and boolean operators, when the sections are separated by
parenthesizes.
Boolean Operator Meaning Explanation
&& or “and” and Both arguments/symbols need to be defined:
true && true = true
true && false = false && true = false && false = false
|| or “or” or At least one argument/symbol must be defined:
true || true = true || false = false || true = true
false || false = false
^ or “xor” exclusive
or (xor)
Only and at least one argument/symbol must be defined:
true • false = false • true = true
true • true = false • false = false
80
The World of Preprocessing
Boolean Operator Meaning Explanation
! or “not” not The argument/symbol must not be defined:
! false = true
! true = false
Comparator Meaning Explanation
==
equals The left and the right argument must be equal, integers and strings can
be compared:
8 == 8 = true
Nokia == Nokia = true
IIw$2(!/5$7B=\$37S1.S$L15(@@(_
IIw$2(!/5$7B=G1%#/.(@@(J/-$"
!=
not equals The left and the right argument must not be equal, integers and strings
can be compared:
8 != 8 = false
Nokia != Sony-Ericsson = true
IIw$2(!/5$7B=\$37S1.S$L15(f@(_
IIw$2(!/5$7B=G1%#/.(f@(J/-$"
> greater The left argument must be greater than the right one. Only integers can
be compared:
8 > 8 = false
16 > 8 = true
IIw$2(!/5$7B=\$37S1.S$L15(H(_
< smaller The left argument must be smaller than the right one. Only integers
can be compared:
8 < 8 = false
8 < 16 = true
IIw$2(!/5$7B=\$37S1.S$L15(?(_
>= greater or
equals
The left argument must be greater than - or equals - the right one. Only
integers can be compared:
8 >= 8 = true
16 >= 8 = true
IIw$2(!/5$7B=\$37S1.S$L15(H@(_
<= smaller or
equals
The left argument must be smaller than - or equals - the right one.
Only integers can be compared:
8 <= 8 = true
8 <= 16 = false
IIw$2(!/5$7B=\$37S1.S$L15(?@(_
Using Variable-Functions for Comparing Values
Some variables have not only different values but also store them in different ways. An example are
memory values like the HeapSize which is sometimes defined in kilobytes and sometimes in
megabytes. In such situation functions can be used:
IIw$2(ij(+8317q(!/5$7B=[1"!N$91(r(;(H(VKZhKK
In the above example the heapsize is compared using the bytes-function. When a function should
be used, a dollar-sign and curly parenthesizes needs to embrace the call. The bytes-function will
81
The World of Preprocessing
return -1 when the given memory-value is “dynamic”, so it might be necessary to test for both
values:
IIw$2(q(ij(+8317q(!/5$7B=[1"!N$91(r(;(H(VKZhKK(r(/.(q!/5$7B=[1"!N$91(@@(#8%":$,r
Functions can also be used for fixed values:
IIw$2(ij(+8317q(!/5$7B=[1"!N$91(r(;(H(ij(+8317q(VKK(-+(r(;
You will find more information about using functions at the “Using Variables” section on page 85.
Hiding Code
Code sections can be temporarily commented out, to avoid problems in the IDE. A typical problem
are several return statements:
IIw$2#12(!/5$7B=$:"&17=#$.1,3D/"#
P:"&1($:"&1(@(P:"&1=,.1"31P:"&1q(%":1(r*
IIw(.130.%($:"&1*
IIw1571
7,B1#051P:"&1q(%":1(r*
.130.%(%055*
IIw1%#$2
In this example the first return statement is hidden with a “//# “ directive. When the first #ifdef
directive is true, the corresponding code will be made visible again. The space after the # sign is
important for the correct handling of such comments.
Debugging with #debug, #mdebug and #enddebug
To include debugging information in a J2ME application is not without problems. The main
problem is that any debugging slows down an application unnecessarily. Another problem is that
nobody wants the debugging information in an application which should be deployed “in the wild”.
With J2ME Polish debugging statements can be included into the applications without having the
above disadvantages.
The #debug directive is used to include a single line of debugging information:
IIw#1+0&
N8731:=/03=!.$%35%qA#1+0&&$%&($7(1%"+51#(2/.(3B$7(,5"77=Ar*
You can define what debugging level is used by adding the debugging-level to the #debug directive.
When no level is specified the “debug” level is assumed.
IIw#1+0&($%2/
N8731:=/03=!.$%35%qA3B1($%2/(#1+0&&$%&(51G15($7(1%"+51#(2/.(3B$7(,5"77=Ar*
The #mdebug (multi-line debug) directive can be used to use multiple lines of debugging
information. It must be finished with the #enddebug directive:
IIw:#1+0&(1../.
1=!.$%3N3",-Y.",1qr*
N8731:=/03=!.$%35%qA0%"+51(3/(5/"#(7/:13B$%&'(A(l(1(r*
IIw1%##1+0&
The above example actually results in the same code as:
82
The World of Preprocessing
IIw#1+0&(1../.
N8731:=/03=!.$%35%qA0%"+51(3/(5/"#(7/:13B$%&'(A(l(1(r*
Directive Explanation
//#debug [level] The next line is only compiled when the debugging setting for the class in
which the debugging information is enabled for the specified level. When
no level is specified, the “debug” level is assumed.
//#mdebug [level] The next lines up to the #enddebug directive will be compiled only when
the debugging setting for the class in which the debugging information is
enabled for the specified level. When no level is specified, the “debug”
level is assumed. Instead the preprocessing symbols “polish.debug.debug”,
“polish.debug.info”, “polish.debug.warn” etc can be used with the #ifdef
directive.
//#enddebug Marks the end of the #mdebug section.
//#ifdef, //#if The preprocessing symbols “polish.debug.debug”, “polish.debug.info”,
“polish.debug.warn” etc can be used instead of the #mdebug directive:
//#if polish.debug.info
if (argument == null) {
System.out.println(°argument is null!¨);
}
//#endif
Debug Levels
Following debug levels are predefined:
“debug”, “info”, “warn”, “error” and “fatal”. The specific level for a class can be defined with the
<debug> element of the J2ME Polish-task:
?#1+0&(7B/CD/&E%F../.@A3.01A(G1.+/71@A2"571A(51G15@A1../.A($2@A3173A(H
?2$531.(!"331.%@A,/:=,/:!"%8=!",-"&1=nA(51G15@A$%2/A(IH
?2$531.(!"331.%@A,/:=,/:!"%8=!",-"&1=U865"77A(51G15@A#1+0&A(IH
?I#1+0&H
Please see the section <debug> in the chapter “The Build Process” for further information. The
levels are weighted, meaning that the debug level is lower than the info level, which is in turn lower
than the error level and so forth:
debug < info < warn < error < fatal < user-defined
Thus when the info level is activated for a class, all debugging information with the level “warn”,
“error”, “fatal” and with a user-defined level will also be compiled.
User specific debugging levels can be useful for accomplishing specific tasks. For example a level
“benchmark” could be defined to allow the measurement of the performance:
IIw#1+0&(+1%,B:".-
5/%&(73".3Y$:1(@(N8731:=,0..1%3Y$:1U$5$7qr*
,"556/:!51LU13B/#qr*
IIw#1+0&(+1%,B:".-
83
The World of Preprocessing
N8731:=/03=!.$%35%qA,/:!51L(:13B/#(3//-(<A(l(qN8731:=,0..1%3Y$:1U$5$7qr(4(
73".3Y$:1r(l(A>(:7=Ar*
The Debug Utility Class
The utility class de.enough.polish.util.Debug can also be used directly for debugging. Especially its
showLog()-method can be useful in some circumstances when the “showLogOnError”-attribute is
not sufficient.
?#1+0&(7B/CD/&E%F../.@A3.01A(G1.+/71@A2"571A(51G15@A1../.A($2@A3173A(H
?2$531.(!"331.%@A,/:=,/:!"%8=!",-"&1=nA(51G15@A$%2/A(IH
?2$531.(!"331.%@A,/:=,/:!"%8=!",-"&1=U865"77A(51G15@A#1+0&A(IH
?I#1+0&H
You can make the debug information available in your MIDlet class with the following code:
&*#$./(#1=1%/0&B=!/5$7B=03$5=M1+0&*
#17%&DED%2''E:5:FG%+/E+H/+>3'E:FG%+/E"
IIw$2#12(!/5$7B=#1+0&F%"+51#
#.&?2/+(6/::"%#(5/&6:#(@(>+<(6/::"%#q(A7B/C(5/&A^(6/::"%#=N6]FFJ^(VK(r*
IIw1%#$2
#.&?2/+(N,.11%(:"$%N,.11%*
#.&?2/+(N,.11%(#$7!5"8*
<===>
#17%&D(U8UPM513qr(j
<===>
IIw$2#12(!/5$7B=#1+0&F%"+51#
/(&'=:"$%N,.11%="##6/::"%#q(/(&'=5/&6:#(r*
IIw1%#$2
;
#17%&D(?$&3(,/::"%#a,3$/%q6/::"%#(,:#^(M$7!5"8"+51(7,.11%(r(j
<===>
IIw$2#12(!/5$7B=#1+0&F%"+51#
&I(q,:#(@@(/(&'=5/&6:#r(j
M1+0&=7B/CD/&q(/(&'=#$7!5"8(r*
;
IIw1%#$2
;
In the above example the MIDlet “MyMIDlet” adds a command to its main screen when the
debugging mode is enabled. When this is the case, the preprocessing symbol
“polish.debugEnabled” will be defined. The user can then select the “show log” command to see
view all logging messages. When the user selects the “return” command from the log-screen, he
will return to the screen which has been shown before.
Please make sure, that you have added the “import/enough-j2mepolish-client.jar” to the classpath of
your project, when using the Debug-class.
Debug-Method Explanation
Debug.showLog( Display display ) Shows the log containing all messages. When another
message is added while the log is shown, the log will be
updated.
Using Variables with #=
You can add the contents of variables with the #= directive:
84
The World of Preprocessing
IIw@(!.$G"31(N3.$%&(0.5(@(Aij(73".340.5(;A*
When the variable is not defined, the above example would throw an exception during the
preprocessing step of the build process. You can use the “[variable]:defined” symbol, which is set
for every known variable:
IIw$2#12(73".340.5'#12$%1#
IIw@(!.$G"31(N3.$%&(0.5(@(Aij(73".340.5(;A*
IIw1571
#.&?2/+EN3.$%&(0.5(@(AB33!'IIVtZ=VT_=VKV=VKVA*
IIw1%#$2
This is especially useful for setting configuration values, which can change easily, like Web-URLs
and so on.
The name of the variable needs to be surrounded by a Dollar-Sign followed by curly parenthesizes
(${variable-name}), just like referring to Ant-properties in the build.xml.
Variables can be defined in the <variables>-element in the build.xml. Other variables are defined in
the devices.xml, vendors.xml and groups.xml by the capabilities of the devices, vendors and groups.
These files are located in the installation directory of J2ME Polish.
Variable-Functions
You can use functions like “uppercase” to change the values. A function is used within the curly
parenthesizes and surrounds the variable-name by normal parenthesizes:
IIw$2#12(73".340.5'#12$%1#
IIw@(!.$G"31(N3.$%&(0.5(@(Aij(5/C1.,"71q73".340.5r(;A*
IIw1571
#.&?2/+EN3.$%&(0.5(@(AB33!'IIVtZ=VT_=VKV=VKVA*
IIw1%#$2
When using function you do not necessarily need a variable – you can also use a direct value. This
can be handy when handling with memory values for example:
IIw$2(ij(+8317q(!/5$7B=[1"!N$91(r(;(H(ij(+8317qVKK(-+r(;
Following functions can be used:
Function Explanation
uppercase Translates the given value into uppercase. “abc” becomes “ABC” for example.
lowercase Translates the given value into lowercase. “ABC” becomes “abc” for example.
bytes Calculates the number of bytes of the given memory value. “1 kb” becomes 1024
for example. The memory-value “dynamic” results in -1.
kilobytes Calculates the (double) number of kilobytes of the given memory value. The value
will contain a point and decimal places. “512 bytes” becomes “0.5” for example,
“1024 bytes” becomes “1” and so on.
megabytes Calculates the (double) number of megabytes of the given memory value.
gigabytes Calculates the (double) number of gigabytes of the given memory value.
85
The World of Preprocessing
Setting CSS Styles with #style
CSS styles are used for the design of the application. The styles are defined in the file polish.css in
the resources folder of the project. The developer can control which styles are used for specific
Items by using the #style directive:
IIw73851(,//5^(2./738^(#12"053
N3.$%&P31:(0.5(@(%1C(N3.$%&P31:q(%055^(AB33!'IIVtZ=VT_=VKV=VKVA(r*
In the above example one of the styles “cool”, “frosty” or “default” is used for the new item. The
style “frosty” is only used when the style “cool” is not defined. The style “default” is only used,
when neither the style “cool” nor the style “frosty” is defined. The style “default” is special, since it
is always defined, even when the designer does not define it explicitly. The #style directive needs at
least one style name as argument. The style is deemed optional when the style ends with a question
mark. In that case it will only be used when it is defined:
IIw73851(,//5k
N3.$%&P31:(0.5(@(%1C(N3.$%&P31:q(%055^(AB33!'IIVtZ=VT_=VKV=VKVA(r*
The styles mentioned here can be defined in the “resources/polish.css” file. In that file the names of
custom styles need to start with a dot. In the above example you can define the styles “.cool”,
“.frosty” or “default”. The “default” style is a predefined style and its name must not, therefore, start
with a dot.
Styles are only used, when the J2ME Polish GUI is used. This can be triggered with the
“usePolishGui” attribute of the <build> element in the build.xml.
Using #style directive improves the performance of the application, since dynamic styles need some
processing time. Dynamic styles design items by their position in screens, see section “Dynamic
Styles” on page 107.
Styles can be set for all items-constructors and for many methods:
Insertion Point Example Explanation
Item constructors
IIw73851(,//5^(2./738^(#12"053
N3.$%&P31:(0.5(@(%1C(N3.$%&P31:q(
%055^(AB33!'IIVtZ=VT_=VKV=VKVA(r*
IIw73851(,//5
P:"&1P31:($:&(@(%1C(P:"&1P31:q(
%055^($,/%P:"&1^(
P:"&1P31:=DaoEOYvMFQaODY^(%055(r*
The #style directive can be
placed before any item
constructor.
Item.
setAppearanceMode
()
IIw73851(/!1%D$%-
0.5=713a!!1"."%,1U/#1q(
P31:=[oSF]DPJe(r*
The #style directive can be
placed before calling the
setAppearanceMode-method of
an Item. Please note, that this
method is only available in
J2ME Polish.
List.append()
IIw73851(,B/$,1
5$73="!!1%#q(AN3".3A^(%055((r*
The #style directive can be
placed before adding a list
element.
86
The World of Preprocessing
Insertion Point Example Explanation
List.insert()
IIw73851(,B/$,1
5$73=$%71.3q(Z^(AN3".3A^(%055((r*
The #style directive can be
placed before inserting a list
element.
List.set()
IIw73851(,B/$,1
5$73=713q(Z^(AN3".3A^(%055((r*
The #style directive can be
placed before setting a list
element.
ChoiceGroup.appen
d()
IIw73851(,B/$,1
&./0!="!!1%#q(A6B/$,1(VA^(%055((r*
The #style directive can be
placed before adding an
element to a ChoiceGroup.
ChoiceGroup.insert(
)
IIw73851(,B/$,1
&./0!=$%71.3q(Z^(A6B/$,1(XA^(%055(
r*
The #style directive can be
placed before inserting an
element to a ChoiceGroup.
ChoiceGroup.set()
IIw73851(,B/$,1
&./0!=713q(Z^(A6B/$,1(XA^(%055((r*
The #style directive can be
placed before setting an element
of a ChoiceGroup.
Form constructor
IIw73851(:"$%N,.11%
Q/.:(2/.:(@(%1C(Q/.:q(AU1%0A(r*
II($%(70+,5"7717(/2(Q/.:'
IIw73851(:"$%N,.11%
70!1.q(AU1%0A(r*
Use the #style directive before
a Form-constructor or before
calling super() in subclass-
constructors.
List constructor
IIw73851(:"$%N,.11%
D$73(5$73(@(%1C(D$73q(AU1%0A^(
D$73=PUSDP6PY(r*
II($%(70+,5"7717(/2(D$73'
IIw73851(:"$%N,.11%
70!1.q(AU1%0A(^(D$73=PUSDP6PY(r*
Use the #style directive before
a List-constructor or before
calling super() in subclass-
constructors.
Exclude or Include Complete Files with #condition
The #condition directive can be used to prevent the usage of complete files, when a condition is not
met:
IIw,/%#$3$/%(!/5$7B=071S/5$7B`0$
When in the above example the J2ME Polish GUI is not used (and thus the symbol
polish.usePolishGui is not defined), the file will not be included into the application bundle for the
current device. Conditions can use the same operators and comparators like the #if directive.
Defining Temporary Symbols or Variables with #define and #undefine
You can temporarily define and undefine symbols with the #define directive. This can be used to
evaluate a complex if-term only once and then referring a simple symbol instead of using the
complex term again:
87
The World of Preprocessing
IIw$2(f+"7$,P%!03(uu(q!/5$7B=B"7S/$%31.FG1%37(yy(!/5$7B=:/071N0!!/.31#r
IIw#12$%1(3:!=,/:!51LP%!03
IIw1%#$2
You can later just check the temporary defined symbol:
IIw$2#12(3:!=,/:!51LP%!03
#/N/:13B$%&6/:!51Lqr*
IIw1%#$2
Directive Explanation
//#define [symbol] Defines the specified symbol. You can never define the symbol “false”.
//#undefine [symbol] Removes the specified symbol from the pool of defined symbols. You can
never undefine the symbol “true”.
Please note that you should rely on a defined or undefined symbol only in the same source-file
where you defined or undefined that symbol. It is advised that you start the names of defined
symbols with “tmp.”, so that you always know that this is a temporary symbol.
You can temporarily define and undefine variables with the #define as well. When the expression
after the #define directive contains the equals-sign, the left part will be taken as the variable name,
and the right part as the variable value:
IIw$2(f:177"&1'#12$%1#
IIw#12$%1(:177"&1(@([155/(C/.5#
IIw1%#$2
You can later just use the defined variable normally:
IIw@(N3.$%&(:177"&1(@(zij(:177"&1(;p*
Directive Explanation
//#define
[name]=[value]
Defines the specified variable with the given value.
//#undefine [name] Removes the specified variable.
Inserting Code Fragments with #include
You can insert complete code fragments with the #include directive:
IIw$%,50#1(ij!/5$7B=7/0.,1;I$%,50#17I:8$%,50#1=b"G"
Within the file-name you can use all defined variables. A useful variable is especially
“polish.source”, which points the base directory of the file, which is currently preprocessed. I you
use only relative names, please bear in mind, that the base directory is the root of your project (or to
be more precise: the directory which contains the build.xml file).
Analyzing the Preprocessing-Phase with #message and #todo
Sometimes the preprocessing itself is rather complex. The #message directive can help to
88
The World of Preprocessing
understand the process by printing out messages during the build-process:
IIw$2(f+"7$,P%!03(uu(q!/5$7B=B"7S/$%31.FG1%37(yy(!/5$7B=:/071N0!!/.31#r
IIw#12$%1(3:!=,/:!51LP%!03
IIw:177"&1(,/:!51L($%!03($7(1%"+51#
IIw1571
IIw:177"&1(,/:!51L($%!03($7(#$7"+51#
IIw1%#$2
Within each message any variables can be used. If a variable is not defined, the variable-definition
will be included in the message.
IIw:177"&1(07$%&(3B1(0!#"3140.5(ij0!#"3140.5;=
The above example results in the message “MESSAGE: using the update-url
http://update.company.com.” being given out, when the variable “update-url” has the value
“http://update.company.com”. When this variable is not defined, the message “MESSAGE: using
the update-url ${update-url}.” will be printed out instead.
The #todo directive works very similar like the #message directive, but it adds the name of the
source-code and the line in which the #todo-directive is embedded before the actual message (e.g.
“TODO: MyMidlet line 12: Implement pauseApp()”).
Handling Several Values in Variables with #foreach
The #foreach directive can be used for processing a variable which has several values separated by
comma. An example is the “polish.SoundFormat”-variable which lists all supported audio-
formats of a device, e.g. “midi, amr, mp3”.
The #foreach directive defines a temporary loop-variable and ends with the “#next [loop-var-name]”
directive:
//#foreach [loop-var-name] in [variable-name]
...[any directives and code]...
//#next [loop-var-name]
The following example illustrates this:
N3.$%&(2/.:"3*
IIw2/.1",B(2/.:"3($%(!/5$7B=N/0%#Q/.:"3
2/.:"3(@(Aij(5/C1.,"71q(2/.:"3(r(;A*
N8731:=/03=!.$%35%q(AYB1("0#$/42/.:"3(A(l(2/.:"3(l(A($7(70!!/.31#(+8(3B$7(
#1G$,1=A(r*
IIw%1L3(2/.:"3
You can use any number and any kind of code and preprocessing directives within the #foreach-loop
itself. So you can even use nested #foreach loops, for example. The code-fragment within the
#foreach-loop will be copied into the preprocessed source-code as many time as there are values. In
the above example it would be copied three times, since in the example three formats are supported.
This copying process has two implications:
1. Any variables should be defined outside of the loop (but they can be set and used within the
loop, of course), and
89
The World of Preprocessing
2. When the application is debugged or compiled, breakpoints or errors can point to the wrong
source-code lines.
If you keep these implications in mind you have another powerful directive at your hand.
Useful Symbols
APIs and MIDP-Version
Please refer to the section “Capabilities” in the chapter “The Device Database” for standard
preprocessing symbols.
For each API the device supports a corresponding symbol “polish.api.[name]” is defined:
polish.api.mmapi when the Mobile Media API is supported, or
polish.api.nokia-ui when the device supports the Nokia UI API.
When the device supports the MIDP/2.0 platform, the symbol “polish.midp2” is defined,
otherwise the symbol “polish.midp1”.
When a device supports the CLDC/1.0 standard, the symbol “polish.cldc1.0” is defined. When
the CLDC/1.0 standard is supported, the symbol “polish.cldc1.1” is defined instead.
J2ME Polish Symbols
Depending on the settings in the build.xml different symbols will be defined. Please compare the
“The Build Section”, page 36.
! polish.usePolishGui is defined when the GUI of J2ME Polish is used for the current device.
! polish.debugEnabled is defined when the logging of messages and the debug-mode is
enabled.
! polish.debugVerbose is defined when the debug-mode is enabled and is set to “verbose”.
When the verbose mode is enabled, thrown exceptions should contain a detailed message.
! polish.skipArgumentCheck can be defined in the symbols-attribute of the <build>-element
within the “build.xml” file. When this symbol is defined, all GUI classes of J2ME Polish will not
check the input variables. This is useful for minimizing the memory footprint when an
application is stable.
Useful Variables
Please refer to the section “Capabilities” on page 26 for standard preprocessing variables.
Other variables include:
! polish.animationInterval defines the interval in milliseconds for animations. This defaults
to 100 ms, but you can change this value within the <variables> element of the <build>-section.
! polish.classes.fullscreen defines the name of the fullscreen-class, when the device
supports such a class. For devices which support the Nokia UI API this variable contains
“com.nokia.mid.ui.FullCanvas”. Following example illustrates the usage:
#17%&D(27'/.2D/(D%2''(U86"%G"7(
IIw$2(!/5$7B=071Q055N,.11%(uu(!/5$7B=,5"7717=20557,.11%'#12$%1#
90
The World of Preprocessing
IIw#12$%1(3:!=2055N,.11%
IIw@(1L31%#7(ij!/5$7B=,5"7717=20557,.11%;
IIw1571
+H/+>3'(6"%G"7
IIw1%#$2
! polish.Vendor defines the vendor of the current device, e.g. “Siemens” or “Nokia”:
IIw$2(!/5$7B=s1%#/.(@@(J/-$"
! polish.Identifier defines the identifier of the current device, e.g. “Nokia/6600”.
! polish.classes.midlet-1 defines the first MIDlet of the current suite.
! polish.classes.midlet-2 defines the second MIDlet of the current suite, if there is any.
! polish.classes.midlet-n defines the n
th
MIDlet of the current suite, if there is any.
File Operations
The variable polish.source points the current source directory. This is useful for //#include
directives.
91
The J2ME Polish GUI
The J2ME Polish GUI
Overview
The J2ME Polish GUI
4
provides a very powerful and efficient way to design the user interface of
wireless Java applications. It has several unique features which ease the usage significantly:
! The J2ME Polish GUI is compatible with the standard MIDP GUI, so the programmer does not
need to learn a new API.
! The necessary code is weaved into the application automatically by J2ME Polish, so that no
specific import-statements need to be used and that even existing applications can use the GUI
without any modifications.
! The GUI is designed using simple text-files, which reside outside of the actual application source
code. The web-standard CSS
5
is used for the design, so that web-designers can now work on the
design of J2ME applications without the help of programmers, while the programmers can
concentrate on the business logic. Also the design can be changed at any time without changing
the source code.
! All designs can be adjusted easily to different devices, vendors, device-groups or even locales.
! All elements of the MIDP/2.0 GUI are supported – even on MIDP/1.0 devices. So MIDP/2.0
specific items like a POPUP ChoiceGroup or a CustomItem can be used on MIDP/1.0 phones as
well.
The drawback of the J2ME Polish GUI is the increased size of the application package. You should
calculate up to 30 kb additional space for the GUI, depending on what GUI-elements and what
designs are used. Modern devices
like Symbian based devices (Nokia,
Siemens and many other vendors)
support application-sizes up to
several megabytes, so the additional
size is most often no problem. The
situation is, however, different on
some older devices like Nokia's old
“Series 40”-models, which only
accepted applications with a size of
up to 64 kb. For such devices the
GUI is usually not used even when
the GUI is activated, unless the usage
is forced.
Activation of the GUI
The GUI can be activated by the setting the “usePolishGui”-attribute of the <build>-element in the
4 GUI stands for Graphical User Interface
5 CSS: Cascading Style Sheets
92
Fig. 3: An example design of a
normal List-Screen.
Fig. 4: The same application with
another design. The background is
actually animated: it starts white
and dithers to the shown pink.
The J2ME Polish GUI
build.xml file. J2ME Polish will then weave the necessary code automatically into the application.
The attribute accepts the values “yes”/”true”, “no”/”false” and “always”. When “true” or “yes” is
given, the GUI will be used, unless a target-device has not the recommended capabilities (i.e. a
maximum JAR size above 100kb and at least a color-depth of 8 bits per color). For such devices the
normal MIDP-GUI is then used. When the attribute is set to “always”, the GUI will be used for all
target-devices, even when they do not have the recommended capabilities.
The following example activates the GUI for most devices:
?+0$5#
071S/5$7B`0$@A3.01A
<===>
Alternatively you can enable the J2ME Polish GUI by defining the preprocessing variable
“polish.usePolishGui”. This is useful if the GUI should be activated for selected devices only. The
following example activated the GUI only for Nokia/Series 60 devices:
?+0$5#
78:+/57@A7B/CN!5"7B^(a%/3B1.FL":!51N8:+/5A
20557,.11%@A:1%0A
071S/5$7B`0$@A2"571A
H
?f44(",3$G"31(3B1(`OP(2/.(J/-$"IN1.$17(#1G$,17((44H
?G".$"+517H
?G".$"+51( %":1@A!/5$7B=071S/5$7B`0$A(
(((( G"501@A3.01A(
$2@A!/5$7B=&./0!=N1.$17TKA(IH
?IG".$"+517H
<===>
?I+0$5#H
Configuring the J2ME Polish GUI
The GUI can be configured quite extensively by modifying the build.xml file.
Using the GUI in Full-Screen-Mode
The J2ME Polish GUI can use the complete screen on MIDP/2.0 devices as well as on MIDP/1.0
devices which provide proprietary methods for using a fullscreen-mode.
The full-screen mode can be activated with the “fullscreen”-attribute of the <build>-element:
?+0$5#
071S/5$7B`0$@A3.01A
20557,.11%@A:1%0A
<===>
The attribute can have the values “yes”/”true”, “no”/”false” or “menu”. When commands are used
by the application, the “menu”-mode needs to be used. In that case the menu-bar will be rendered
by J2ME Polish and the menu can be designed with CSS (e.g. by setting the menubar-color-
attribute or using the “menu” style).
Alternatively the “polish.FullScreen”-preprocessing variable can be set, which accepts the same
values as the the “fullscreen”-attribute. This can be used for a fine grained control. Siemens-
devices do accept commands even in the normal fullscreen-mode, so there is no need to use the
93
The J2ME Polish GUI
menu-mode for such devices:
?+0$5#
071S/5$7B`0$@A3.01A
20557,.11%@A:1%0A
H
((?G".$"+517H
(((((?G".$"+51(
%":1@A!/5$7B=Q055N,.11%A(
G"501@A817A
$2@A!/5$7B=G1%#/.(@@(N$1:1%7A
(((((IH
((?G".$"+517H
((<===>
Some MIDP/2.0 devices do not support the “menu” mode, since they do not forward key-events
when a soft-key is pressed. J2ME Polish determines whether a device supports the “menu” mode by
evaluating the device database. When the “hasCommandKeyEvents”-feature is set, the device
supports the pure MIDP/2.0 “menu” mode. Additionally the capabilities “key.LeftSoftKey” and
“key.RightSoftKey” can be set to define the key-codes for the soft-keys (these are the values,
which are reported to the “keyPressed”-method of a Canvas). When no keys are defined, the value
“-6” is assumed for the left soft key, and the value “-7” for the right soft key.
<device
supportsPolishGui="true">
<identifier>Siemens/CX65</identifier>
<features>hasCommandKeyEvents</features>
<capability name="ScreenSize" value="132x176"/>
<capability name="key.LeftSoftKey" value="-1" />
<capability name="key.RightSoftKey" value="-4" />
</device>
94
Fig. 1: The "menu" and the normal fullscreen-mode on the Siemens CX65
The J2ME Polish GUI
Configuring Commands, Labels and Programming of the GUI
Preprocessing variables and symbols can be used for changing the appearance or logic of the J2ME
Polish GUI.
Preprocessing Symbol Explanation
polish.skipArgumentCheck When this symbol is defined, method arguments will not be checked.
This improves the runtime performance and the size of the
application a bit.
Preprocessing Variable Default Explanation
polish.animationInterval 100 Defines the interval in milliseconds for
animations. This defaults to 100 ms.
polish.classes.ImageLoader - Usually J2ME Polish loads all images from the
JAR file using the Image.createImage( String
url ) method. This works fine for most
situations, but sometimes images should be
retrieved from the RMS or the internet. In such
cases you can define the
“polish.classes.ImageLoader” variable. The given
class (or static field of a class) needs to implement
the javax.microedition.lcdui.Image
loadImage( String url ) throws
IOException method, which is responsible for
retrieving the image.
polish.ChoiceGroup.suppres
sMarkCommands
false A multiple List or ChoiceGroup adds the
commands “Mark” and “Unmark” by default to the
menu. The names of the commands can be
changed easily, compare page 76. If you want to
suppress the commands completely, the
“polish.ChoiceGroup.suppressMarkCommands”-
variable has to be set to “true”.
polish.ChoiceGroup.suppres
sSelectCommand
false An implicit or popup ChoiceGroup or List do
usually have a “Select”-command which also can
be deactivated.
polish.TextField.suppressCo
mmands
false A TextField and TextBox do contain the “Delete”
as well as the “Clear”-commands by default.
polish.command.ok OK The label for the OK-menu-item, which is used
Screen-menus when the “menu”-fullscreen-mode
is used.
polish.command.cancel Cancel The label for the Cancel-menu-item.
polish.command.select Select The label for the Select-menu-item, which is used
95
The J2ME Polish GUI
Preprocessing Variable Default Explanation
by an implicit or exclusive List or ChoiceGroup.
polish.command.mark Mark The label for the Mark-menu-item of a multiple
List or ChoiceGroup.
polish.command.unmark Unmark The label for the Unmark-menu-item of a multiple
List or ChoiceGroup.
polish.command.options Options The label for the menu when several menu-items
are available.
polish.command.delete Delete The label for the Delete-menu-item, which is used
by TextFields.
polish.command.clear Clear The label for the Clear-menu-item, which is used
by TextFields.
polish.title.input Input The title of the native TextBox which is used for
the actual input of text. This title is only used,
when the corresponding TextField-item has no
label. When the TextField has a label, that label is
used as a title instead.
polish.usePolishGui - Can be used for activating the Polish GUI only for
selected devices.
polish.FullScreen - Can be used for selectively activating the
FullScreen mode. Possible values are “true”,
“false” or “menu”.
The following example demonstrates some configuration options:
?f44(78:+/5'(#/%m3(,B1,-(:13B/#4!".":131.7'((44H
?+0$5#
071S/5$7B`0$@A3.01A
20557,.11%@A:1%0A
78:+/57@A!/5$7B=7-$!a.&0:1%36B1,-A
H
((?G".$"+517H
?f44(70!!.177(U".-IO%:".-(,/::"%#7(2/.(6B/$,1`./0!7("%#(D$737'((44H
(((((?G".$"+51( %":1@A!/5$7B=6B/$,1`./0!=70!!.177U".-6/::"%#7A(
G"501@A3.01A(IH
?f44(70!!.177(M15131I651".(,/::"%#7(2/.(Y1L3\/L17("%#(Y1L3Q$15#7'((44H
(((((?G".$"+51( %":1@A!/5$7B=Y1L3Q$15#=70!!.1776/::"%#7A(
G"501@A3.01A(IH
?f44(071(/C%($:"&1(5/"#1.($:!51:1%3"3$/%'((44H
(((((?G".$"+51( %":1@A!/5$7B=,5"7717=P:"&1D/"#1.A(
G"501@A,/:=,/:!"%8=bZ:1=P:"&1D/"#1.A(IH
((?G".$"+517H
((<===>
The J2ME Polish GUI for Programmers
Using the J2ME Polish GUI is quite simple actually. Since the J2ME Polish GUI is compatible with
96
The J2ME Polish GUI
the MIDP-standard, neither import-statements nor the actual code needs to be changed.
Setting Styles
You should use the #style-preprocessing-directive for applying the desired design-styles. This
directive can be used in front of any Item-constructor and before some other methods:
Insertion Point Example Explanation
Item constructors
IIw73851(,//5^(2./738^(#12"053
N3.$%&P31:(0.5(@(%1C(N3.$%&P31:q(
%055^(AB33!'IIVtZ=VT_=VKV=VKVA(r*
IIw73851(,//5
P:"&1P31:($:&(@(%1C(P:"&1P31:q(
%055^($,/%P:"&1^(
P:"&1P31:=DaoEOYvMFQaODY^(%055(r*
The #style directive can be
placed before any item
constructor.
Item.
setAppearanceMode
()
IIw73851(/!1%D$%-
0.5=713a!!1"."%,1U/#1q(
P31:=[oSF]DPJe(r*
The #style directive can be
placed before calling the
setAppearanceMode-method of
an Item. Please note, that this
method is only available in
J2ME Polish.
List.append()
IIw73851(,B/$,1
5$73="!!1%#q(AN3".3A^(%055((r*
The #style directive can be
placed before adding a list
element.
List.insert()
IIw73851(,B/$,1
5$73=$%71.3q(Z^(AN3".3A^(%055((r*
The #style directive can be
placed before inserting a list
element.
List.set()
IIw73851(,B/$,1
5$73=713q(Z^(AN3".3A^(%055((r*
The #style directive can be
placed before setting a list
element.
ChoiceGroup.appen
d()
IIw73851(,B/$,1
&./0!="!!1%#q(A6B/$,1(VA^(%055((r*
The #style directive can be
placed before adding an
element to a ChoiceGroup.
ChoiceGroup.insert(
)
IIw73851(,B/$,1
&./0!=$%71.3q(Z^(A6B/$,1(XA^(%055(
r*
The #style directive can be
placed before inserting an
element to a ChoiceGroup.
ChoiceGroup.set()
IIw73851(,B/$,1
&./0!=713q(Z^(A6B/$,1(XA^(%055((r*
The #style directive can be
placed before setting an element
of a ChoiceGroup.
Form constructor
IIw73851(:"$%N,.11%
Q/.:(2/.:(@(%1C(Q/.:q(AU1%0A(r*
II($%(70+,5"7717(/2(Q/.:'
IIw73851(:"$%N,.11%
70!1.q(AU1%0A(r*
Use the #style directive before
a Form-constructor or before
calling super() in subclass-
constructors.
97
The J2ME Polish GUI
Insertion Point Example Explanation
List constructor
IIw73851(:"$%N,.11%
D$73(5$73(@(%1C(D$73q(AU1%0A^(
D$73=PUSDP6PY(r*
II($%(70+,5"7717(/2(D$73'
IIw73851(:"$%N,.11%
70!1.q(AU1%0A(^(D$73=PUSDP6PY(r*
Use the #style directive before
a List-constructor or before
calling super() in subclass-
constructors.
The following example uses the “.mainMenu”-style for the design of the form:
import javax.microedition.lcdui.Form;
public class MainMenu extends Form {
public MainMenu( String title ) {
//#style mainMenu
super( title );
...
}
}
The “.mainMenu”-style then needs to be defined within the “resources/polish.css”-file, e.g.:
.mainMenu {
background-image: url( bg.png );
columns: 2;
}
You can also use several style-names in a #style-directive. In this case the first found directive is
used:
import javax.microedition.lcdui.Form;
public class MainMenu extends Form {
public MainMenu( String title ) {
//#style mainMenu, screen
super( title );
...
}
}
When none of the provided style-definitions is found, the build will report this error and abort the
processing.
Using Dynamic and Predefined Styles
When dynamic styles are used, you do not even have to set the #style-directives. In this case the
designs do depend on the classes. All Forms are designed with the “form”-style for example. Using
dynamic styles can be a fast way to check out the GUI for existing applications, but this requires
additional memory and runtime. You should, therefore, use normal “static” styles for the final
application.
Predefined styles are used by default for some elements. So is the “title”-style responsible for the
appearance of Screen-titles for example.
Please refer to the documentation on page 105 for more information on static, dynamic and
98
The J2ME Polish GUI
predefined styles.
Porting MIDP/2.0 Applications to MIDP/1.0 Platforms
When you use the J2ME Polish GUI you can use MIDP/2.0
widgets like a POPUP ChoiceGroup or a CustomItem on
MIDP/1.0 devices as well without any restrictions.
Source code adjustments are only necessary when MIDP/2.0-
only features are used, which are outside of the scope of the
J2ME Polish GUI, e.g. Display.flashBacklight(int).
The MIDP/2.0 call Display.setCurrentItem( Item ) is supported
by the J2ME Polish GUI for both MIDP/2.0 as well as
MIDP/1.0 devices.
When a specific call is not supported by a target-device, the
build-process will be aborted with a compile error. Usually that
error then needs to be surrounded by an appropriate #if-
preprocessing directive, e.g.:
//#ifdef polish.midp2
this.display.flashBacklight( 1000 );
//#endif
Please have a look at the chapter “Using Custom Items” on page 161 for more information on
custom items.
Programming Specific Items and Screens
In general the J2ME Polish GUI is fully compatible to the MIDP/2.0 UI standard. There are,
however some enhancement that are not available in the MIDP/2.0 standard.
Programming the TabbedForm
The TabbedForm is a form that separates the included GUI elements on several tabs. You can use
any Form methods like setItemStateListener( .. ) in the TabbedForm. The implementation offers
some additional methods for configuring its tabs:
directive can be used in front of any Item-constructor and before some other methods:
Method Example Explanation
TabbedForm( String
title, String[]
tabNames, Image[]
tabImages )
IIw73851(:8Y"++1#Q/.:
Y"++1#Q/.:(2/.:(@(%1C(Y"++1#Q/.:q(
A[155/A^(%1C(N3.$%&<>(jAQ$.73(
Y"+A^(A"%/3B1.(3"+A;^(%055(r*
Creates a new TabbedForm.
append( int
tabIndex, Item item )
2/.:="!!1%#q(Z^(:8N3.$%&P31:(r*
Adds the item to the specified
tab. The first tab has got the
index 0.
set( int tabIndex, int
2/.:=713q(Z^(V^(:8N3.$%&P31:(r*
Sets the item to the specified
99
Useful Preprocessing Symbols
! polish.midp1 /
polish.midp2 indicates the
current MIDP platform.
! polish.cldc1.0 /
polish.cldc1.1 indicates the
current configuration.
! polish.usePolishGui is
enabled when the GUI of J2ME
Polish is used.
! polish.api.mmapi is defined
when the Mobile Media API is
supported by the current device.
! polish.api.nokia-ui is
defined when the Nokia UI API
is supported by the current
device.
The J2ME Polish GUI
Method Example Explanation
itemIndex, Item item
)
index on the given tab.
delete( int tabIndex,
Item item )
2/.:=#15131q(Z^(:8N3.$%&P31:(r*
Deletes the given item from the
specified tab.
The following listing demonstrates the usage of the TabbedForm:
package de.enough.polish.demo;
import javax.microedition.lcdui.Choice;
import javax.microedition.lcdui.ChoiceGroup;
import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.DateField;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.StringItem;
import javax.microedition.lcdui.TextField;
import javax.microedition.lcdui.Item;
import javax.microedition.lcdui.ItemStateListener;
import de.enough.polish.ui.TabbedForm;
public class TabbedFormDemo implements ItemStateListener {
private TextField nameField;
public TabbedFormDemo( DemoMidlet midlet, Display display, Command
returnCmd ) {
String[] tabNames = new String[]{ "Input", "Choice", "Connection",
"Test", "Settings", "Internet" };
//#style tabbedScreen
TabbedForm form = new TabbedForm("TabbedDemo", tabNames, null );
//#style label
StringItem label = new StringItem( null, "name:" );
form.append( 0, label );
//#style input
this.nameField = new TextField( null, "Robert", 30, TextField.ANY |
TextField.INITIAL_CAPS_WORD );
form.append(0, this.nameField);
//#style label
label = new StringItem( null, "birthday:" );
form.append( 0, label );
//#style input
DateField birthdate = new DateField( null, DateField.DATE );
form.append( 0, birthdate );
//#style label
label = new StringItem(null, "What kind of animals do you like:");
form.append( 1, label );
//#style multipleChoice
ChoiceGroup choice = new ChoiceGroup( null, Choice.MULTIPLE );
//#style choiceItem
choice.append("dogs", null);
100
The J2ME Polish GUI
//#style choiceItem
choice.append("cats", null);
//#style choiceItem
choice.append("birds", null);
form.append(1, choice);
//#style label
label = new StringItem(null, "Connection:");
form.append( 2, label );
//#style multipleChoice
choice = new ChoiceGroup( null, Choice.MULTIPLE );
//#style choiceItem
choice.append("ISDN", null);
//#style choiceItem
choice.append("DSL", null);
//#style choiceItem
choice.append("Cable", null);
form.append(2, choice);
form.addCommand(returnCmd);
form.setCommandListener(midlet);
form.setItemStateListener( this );
display.setCurrentItem( choice );
}
public void itemStateChanged(Item item) {
if (item instanceof TextField) {
TextField field = (TextField) item;
System.out.println("Item State Changed: " +
field.getString() );
} else {
System.out.println("Item State Changed: " + item );
}
}
}
101
The J2ME Polish GUI
The J2ME Polish GUI for Designers
J2ME Polish includes an optional Graphical User Interface, which can be designed using the web-
standard Cascading Style Sheets (CSS). So every web-designer can now design mobile applications
thanks to J2ME Polish! This chapter will explain all details of the design possibilities, no prior
knowledge about CSS is required.
6
The GUI is compatible with the javax.microedition.ui-classes,
therefore no changes need to be made in the source code of the application. The GUI will be
incorporated by the preprocessing mechanism automatically, unless the “usePolishGui”-attribute of
the <build> element is set to false in the build.xml file.
A Quick Glance
All design settings and files are stored in the “resources” directory of the project, unless another
directory has been specified.
7
The most important file is polish.css in that directory. All design
definitions can be found here. The design definitions are grouped in “styles”. A style can be
assigned to any GUI item like a title, a paragraph or an input field. Within a style several attributes
and its values are defined:
.myStyle {
font-color: white;
font-style: bold;
font-size: large;
font-face: proportional;
background-color: black;
}
In this example the style called “myStyle” defines some font values and the color of the background.
Any style contains a selector as well as a number of attributes and its values:
Each attribute-value pair needs to be finished with a semicolon. The style declaration needs to be
finished by a closing curved parenthesis. The selector or name of style is case-insensitive, so
“.MySTYle” is the same as “.myStyle”.
Apart from the polish.css file, you can put images and other contents into the resources-folder.
Sub-folders are used for styles and content for specific devices and groups. You can put all resources
for Nokia devices into the “Nokia” folder and resources for Samsung's E700 into the
“Samsung/E700” folder. This is described in more detail in the “Designing Specific Devices and
Device-Groups” section.
You can specify styles directly for GUI items with the #style preprocessing directive in the source
code. Alternatively you can use the dynamic names of the GUI items, e.g. “p” for text-items, “a” for
hyperlinks or “form p” for all text-items which are embedded in a form. The possible combinations
as well as the predefined style-names are discussed in the section “Dynamic, Static and Predefined
6 Refer to http://www.w3schools.com/css/ for an excellent tutorial of CSS for web pages.
7 You can specify the directory with the “resDir” attribute of the <build> element in the build.xml file. This can be
used to create completely different designs for one application.
102
.myStyle { font-color: white; }
selector/name attribute value
Fig. 2: Structure of a style
The J2ME Polish GUI
Styles”.
Styles can extend other styles with the extends-keyword, e.g. “.myStyle extends baseStyle {}”. This
process is described in the section “Extending Styles”.
J2ME Polish supports the CSS box model with margins, paddings and content. Other common
design settings include the background, the border and font-settings. These common settings are
described in the section “Common Design Attributes”. Attributes for specific GUI items as well as
the details of the different background and border types are discussed in the section “Specific
Design Attributes”.
Designing for Specific Devices or Device-Groups
Sometimes the design needs to be adapted to a specific device or a group of devices. You can easily
use specific pictures, styles etcetera by using the appropriate sub folders of the “resources” folder.
The Hierarchy of the “resources” Folder
In the resources folder itself you put all resources and design definitions which should be valid for
all devices. The resources will copied into the root folder of the application.
In the folder named like the vendor of a device (e.g. “Nokia”, “Samsung” or “Motorola”) you put all
resources and design definitions for devices of that vendor.
In the folder named like the explicit and implicit groups of a device you add the resources and
design definitions for these device-groups. An explicit group is for example the “Series60” group,
implicit groups are defined by the supported APIs of a device and the BitsPerPixel capability of
devices. You can add a small movie for all devices which support the Mobile Media API (mmapi)
by putting that movie into the “resources/mmapi” folder. Or you can add colored images for all
devices which have at least a color depth of 8 bits per pixel by putting these images into the
“resources/BitsPerPixel8+” folder.
Last but not least you can use device specific resources and design definitions by putting them into
the “resources/[vendor]/[device]” folder, e.g. “resources/Nokia/6600” or
“resources/Samsung/E700”.
Any existing resources will be overwritten by more specific resources:
1. At first the basic resources and definitions found in the “resources” folder will be used.
2. Secondly the vendor-specific resources will be used, e.g. “resources/Nokia”.
3. Thirdly the group-specific resources will be used, e.g. “resources/mmapi”, “resources/Series60”,
“resources/BitsPerPixel.8+” or “resources/BitsPerPixe.16”.
4. The resources and settings in the device specific folder will overwrite all other resources and
settings. The device specific folder is for example the folder “resources/Nokia/6600” for the
Nokia/6600 phone or the folder “resources/Samsung/E700” for Samsung's E700.
When you add the polish.css file for a specific vendor, group or device, you do not need to repeat all
styles and attributes from the more basic settings. You need to specify the more specific setting
only. When you want to change the color of a font, you just need to specify the “font-color”
attribute of that style. No other attributes or styles need to be defined. This is the cascading
103
The J2ME Polish GUI
character of the Cascading Style Sheets of J2ME Polish.
This example illustrates the cascading character of polish.css:
In “resources/polish.css” you define the style “myStyle”:
.myStyle {
font-color: white;
font-style: bold;
font-size: large;
font-face: proportional;
background-color: black;
}
You can change the font-color of that style for all Nokia devices with the following declaration in
“resources/Nokia/polish.css”:
.myStyle {
font-color: gray;
}
You can specify another font-size and font-color for the Nokia 6600 phone with these settings in
“resources/Nokia/6600/polish.css”:
.myStyle {
font-color: red;
font-size: medium;
}
Groups
Every device can have explicit and implicit groups. Explicit groups are stated by the <groups>
element of the device in the file devices.xml
8
. Implicit groups are defined by the capabilities of the
device: Each supported API results in an implicit group and the BitsPerPixel capability results in
several groups.
API- and Java-Platform-Groups
A device can support different APIs and Java-platforms.
When the device supports the MIDP/1.0 standard, it belongs to the “midp1”-group, otherwise it
belongs to the “midp2”-group. So you can specify the layout of MIDP/1.0 devices in
“resources/midp1/polish.css”. And you can use specific images or other resources for MIDP/2.0
devices in the folder “resources/midp2”. The supported platform of a device can be specified in the
devices.xml file with the <JavaPlatform> element. Alternatively this setting can be specified in the
file groups.xml for specific groups.
For each supported API an implicit group is created. When the device supports the Mobile Media
API (mmapi), it belongs to the “mmapi”-group. When the device supports the Nokia-UI API, it
belongs to the “nokia-ui” group. The name of the implicit group is defined by the <symbol>
element of the API in the file apis.xml.
BitsPerPixel-Groups
Every device display has a specific color depth which is specified by the BitsPerPixel-capability of
that device in the devices.xml file. Depending on how many bits per pixel are supported, the device
8 devices.xml can either be found in the root folder of the project or in the import/enough-j2mepolish-build.jar file.
104
The J2ME Polish GUI
belongs to different groups:
Bits per Pixel Colors Groups
1 2
1
= 2 (b/w) BitsPerPixel.1
4 2
4
= 16 BitsPerPixel.4
BitsPerPixel.4+
8 2
8
= 256 BitsPerPixel.8
BitsPerPixel.8+
BitsPerPixel.4+
12 2
12
= 4.096 BitsPerPixel.12
BitsPerPixel.12+
BitsPerPixel.8+
BitsPerPixel.4+
16 2
16
= 65.536 BitsPerPixel.16
BitsPerPixel.16+
BitsPerPixel.12+
BitsPerPixel.8+
BitsPerPixel.4+
18 2
18
= 262.144 BitsPerPixel.18
BitsPerPixel.18+
BitsPerPixel.16+
BitsPerPixel.12+
BitsPerPixel.8+
BitsPerPixel.4+
24 2
24
= 16.777.216 BitsPerPixel.24
BitsPerPixel.24+
BitsPerPixel.18+
BitsPerPixel.16+
BitsPerPixel.12+
BitsPerPixel.8+
BitsPerPixel.4+
So you can put images for phones with at least 16 colors into the “resources/BitsPerPixel.4+” folder.
And you can specify settings for true color devices in the file
“resources/BitsPerPixel.24/polish.css”.
Dynamic, Static and Predefined Styles
J2ME Polish distinguishes between dynamic, static and predefined styles:
! Predefined styles are used by the GUI for several items like screen-titles.
! Static styles are defined in the source code of the application with the #style preprocessing
directive.
105
The J2ME Polish GUI
! Dynamic styles are used for items according to their position on the screen.
Static Styles
The easiest styles are the static ones. The programmer just needs to tell the designer the style names
and what they are used for (that is for what kind of items or screens) and the designer defines them
in the appropriate polish.css file. Static styles always start with a dot, e.g. “.myStyle”.
Static styles are faster than dynamic styles. It is therefore recommended to use static styles whenever
possible.
Predefined Styles
Predefined styles are static styles which are used by the J2ME Polish GUI. In contrast to the normal
“user-defined” static styles their names do not start with a dot, e.g. “title” instead of “.title”.
Following predefined styles are used:
Style Description
title The style of screen-titles. For MIDP/2.0 devices the native
implementation is used by default, unless the preprocessing variable
“polish.usePolishTitle” is defined with “true”:
<variable name="polish.usePolishTitle" value="true"
unless="polish.Vendor == Nokia" />
You can also use custom styles for specific Screens or ChoiceGroups by
using the “title-style”-attribute (compare page 131).
focused The style of a currently focused item. This style is used in Lists, Forms
and for Containers like the ChoiceGroup. You can also use custom
styles for specific Screens or ChoiceGroups by using the “focused-
style”-attribute (compare page 131).
menu This style is used for designing the menu bar in the full screen mode.
The full screen mode can be triggered by the “fullScreenMode” attribute
of the <build> element in the build.xml (with
fullScreenMode=”menu”). In the menu style you can also define which
style is used for the currently focused command with the “focused-
style”-attribute, e.g. “focused-style: menuFocused;”. In this case you
need to define the static style “.menuFocused” as well.
menuItem The style used for the menu items (the commands) of a screen. When
menuItem is not defined, the “menu” style is used instead.
label This style is used for the menu the label of any item. One can specify
another label-style by defining the CSS-attribute “label-style” in the
appropriate style, which refers to another style.
info The style that is used for displaying additional information in a screen.
Currently this is only used for showing the current input mode when the
“direct input mode” of a TextField or a TextBox is enabled. Compare
106
The J2ME Polish GUI
Style Description
page 142 for more information.
default The style which is used by the J2ME Polish GUI when the desired
predefined style is not defined. The default style is always defined, even
when it is not explicitly defined in the polish.css file.
tabbar This style designs the tab-bar of a TabbedForm.
activetab Designs the currently active tab of a TabbedForm.
Inactivetab Designs all tabs but the currently selected one of a TabbedForm.
The names of predefined styles must not be used for static styles, so you must not use a static style
with the name “.title” etc.
Dynamic Styles
Dynamic styles can be used to apply styles to items without using #style directives in the source
code. With dynamic styles the designer can work completely independent of the programmer and
try out new designs for GUI items which have not yet an associated static style. You can also check
out the power and possibilities of the J2ME Polish API without changing the source code of an
existing application at all.
Obviously, dynamic styles need a bit more memory and processing time than static styles. It is
recommended, therefore, to use static styles instead for finished applications.
Dynamic styles do not start with a dot and use the selectors of the items they want to design:
Texts use either “p”, “a”, “button” or “icon”. Screens use the name of the screen, e.g. “form”, “list”
or “textbox”.
p {
font-color: black;
font-size: medium;
background: none;
}
form {
margin: 5;
background-color: gray;
border: none;
font-size: medium;
}
You can also design only items which are contained in other items or screens:
The style “form p” designs all text-items (of the class StringItem) which are contained in a form:
form p {
font-color: white;
font-size: medium;
}
Static styles and dynamic styles can be used together, you can design all hyperlinks
9
in the screen
9 StringItems which have the appearance mode Item.HYPERLINK
107
The J2ME Polish GUI
with the style “.startScreen” for example with the following style declaration:
.startScreen a {
font-color: blue;
font-size: medium;
font-style: italic;
}
Items and screens have specific selectors for dynamic styles:
Item-Class Selector Explanation
StringItem p StringItem shows text. The “p” selector is used, when the
item has the appearance mode PLAIN.
a The “a” selector is used, when the item has the appearance
mode HYPERLINK.
button The “button” selector is used, when the item has the
appearance mode BUTTON.
ImageItem img Shows an image.
Gauge gauge Shows a progress indicator.
Spacer spacer Is used for showing an empty space. The usage of the Spacer
item is discouraged, since the spaces can be set for all items
with the margin and padding attributes.
IconItem icon Shows an image together with text.
TextField textfield Allows textual input from the user.
DateField datefield Allows the input of dates or times from the user.
ChoiceGroup choicegroup Contains several choice items.
ChoiceItem listitem Shows a single choice. The selector “listitem” is used, when
this item is contained in an implicit list.
radiobox The selector “radiobox” is used when the list or choice group
has the type “exclusive”.
checkbox The selector “checkbox” is used when the list or choice group
has the type “multiple”.
popup The selector “popup” is used when the choice group has the
type “popup”.
Screen-Class Selector Explanation
List list Shows several choice items.
Form form Contains different GUI items.
TextBox textbox Contains a single textfield.
108
The J2ME Polish GUI
Extending Styles
A style can extend another style. It inherits all the attributes of the extended style. With this
mechanism a lot of writing work can be saved:
.mainScreen {
margin: 10;
font-color: black;
font-size: medium;
font-style: italic;
background-color: gray;
}
.highscoreScreen extends mainScreen {
font-color: white;
background-color: black;
}
In the above example the style “highscoreScreen” inherits all attributes of the “mainScreen” style,
but “font-color” and “background-color” are specified differently.
Circle inheritance is not allowed, so the following example results in a build error:
.baseScreen extends highscoreScreen { /* this extends is invalid! */
margin: 5;
font-color: white;
}
.mainScreen extends baseScreen {
margin: 10;
font-color: black;
font-size: medium;
font-style: italic;
background-color: gray;
}
.highscoreScreen extends mainScreen {
font-color: white;
background-color: black;
}
The above example would be valid, when the style “baseScreen” would not extend the
“highscoreScreen”-style.
CSS Syntax
Following rules do apply for CSS styles:
Structure of a CSS Declaration
Every style starts with the selector followed by an opening curved parenthesis, a number of
attribute-value pairs and a closing curved parenthesis.
The selector can consist of several item-names and contain an “extends” clause.
109
.myStyle { font-color: white; }
selector/name attribute value
Fig. 3: Structure of a style
The J2ME Polish GUI
Each attribute-value pair needs to be finished by a semicolon.
Naming
Styles can use any names, as long as they consist of alphanumeric and underline (_) characters only.
Names are not case-sensitive. Static styles need to start with a dot. Static styles must not use the
names of dynamic or predefined styles. All Java keywords like “class”, “int” or “boolean” etcetera
are not allowed as style names.
Grouping of Attributes
Attributes can be grouped for easier handling:
.mainScreen {
font-color: black;
font-size: medium;
font-style: italic;
font-face: system;
}
The above code is equivalent with the following:
.mainScreen {
font {
color: black;
size: medium;
style: italic;
face: system;
}
}
The grouping makes the declarations better readable for humans.
Referring to Other Styles
When another style is referred, the dots of static styles do not need to be written. Styles can be
referred in attributes or after the extends keyword in the selector of a style.
Comments
Comments can be inserted at any place and start with “/*” and stop with “*/”. Everything between
these boundaries is ignored:
/* this style designs the main screen: */
.mainScreen {
/* defining the color of a font: */
font-color: black;
/* sizes are small, medium and large: */
font-size: medium;
/* styles are plain, bold, italic or underlined: */
font-style: italic;
/* the face can either be system, proportional or monospace: */
font-face: system;
}
110
The J2ME Polish GUI
Common Design Attributes
Structure of polish.css
The polish.css file can contain different sections:
" colors: The colors-section contains the definition of colors.
" fonts: The fonts-section contains font definitions.
" backgrounds: The backgrounds-section contains background definitions.
" borders: The borders-section contains definition of borders.
" rest: The rest of polish.css contains the actual style definitions.
The defined colors, fonts, backgrounds and borders can be referenced in the actual style definitions.
This makes changes very easy, since you need to change the value only in one position.
Structure of a Style Definition
Each style can contain different “sections”:
" margin: The gap between items
" padding: The gap between the border and the content of an item
" font: The used content-font and its colors
" layout: The layout of the items.
" background: The definition of the item's background
" border: The definition of the item's border
" before and after: Elements which should be inserted before or after the items.
" specific attributes: All attributes for specific GUI items.
An example of such a complete style definition is the following:
/* this style designs the currently focused element in a list, form etc: */
focused {
/* margins and paddings: */
margin: 2;
margin-left: 5;
margin-right: 10;
padding: 1;
padding-vertical: 2;
/* font */
font {
color: blue;
size: medium;
face: system;
}
/* layout is centered: */
layout: center;
/* background: */
background-color: gray;
/* no border: /*
border: none;
111
The J2ME Polish GUI
/* before: add an image: */
before: url( arrow.png );
/* after: add another image: */
after: url( leftArrow.png );
/* no specific attributes are used in this example*/
}
The CSS Box Model: Margins and Paddings
All GUI items support the standard CSS box model:
The margin describes the gap to other GUI items. The padding describes the gap between the border
of the item and the actual content of that item. So far no different border-widths (for left, right, top
and bottom) can be set with J2ME Polish. Since this is a more bizarre and seldom used feature, not
much harm is done.
The margin- and padding-attributes define the default gaps for the left, right, top and bottom
elements. Any margin has the default value of 0 pixels, whereas any padding defaults to 1 pixel.
Next to the left, right, top and bottom padding, J2ME Polish also knows the vertical and the
horizontal paddings. These define the gaps between different content sections. The gap between the
label of an item and the actual content is defined by the horizontal padding. Another example is the
icon, which consists of an image and a text. Depending on the align of the image, either the vertical
or the horizontal padding fills the space between the icon-image and the icon-text.
In the following example, the top, right and bottom margin is 5 pixels, whereas the left margin is
10 pixels:
.myStyle {
margin: 5;
margin-left: 10;
font-color: black;
}
Percentage values can also be used. Percentage values for top, bottom and vertical attributes relate
to the height of the display. Percentage values for left, right and horizontal attributes relate to the
width of the display:
112
margin-top
m
a
r
g
i
n
-
l
e
f
t

m
a
r
g
i
n
-
r
i
g
h
t
border
padding-top
p
a
d
d
i
n
g
-
l
e
f
t

p
a
d
d
i
n
g
-
r
i
g
h
t
padding-bottom
content
The J2ME Polish GUI
.myStyle {
padding-left: 2%;
padding-right: 2%;
padding-vertical: 1%;
font-color: black;
}
When the device has a width of 176 pixels, a padding of 2% results into 3.52 pixels, meaning
effectively a padding of 3 pixels. At a display height of 208 pixels a vertical padding of 1% results
into a padding of 2.08 pixels or effectively 2 pixels. Please note that the capability “ScreenSize” of
the device needs to be defined when you use percentage values.
The Layout Attribute
The layout attribute defines how the affected item should be aligned and laid out. Possible layout
values are for example left, right or center. All layout values of the MIDP/2.0 standard can be used:
Layout Alternative Names Explanation
left - The affected items should be left-aligned.
right - The affected items should be right-aligned.
center horizontal-center,
hcenter
The affected items should be centered horizontally.
expand horizontal-expand,
hexpand
The affected items should use the whole available
width (i.e. should fill the complete row).
shrink horizontal-shrink,
hshrink
The affected items should use the minimum width
possible.
top - The affected items should be top-aligned.
bottom - The affected items should be bottom-aligned.
vcenter vertical-center The affected items should be centered vertically.
vexpand vertical-expand The affected items should use the whole available
height (i.e. should fill the complete column).
vshrink vertical-shrink The affected items should use the minimum height
possible.
newline-after - Items following an item with a newline-after layout
should be placed on the next line. Currently the
newline settings will be ignored, since every item
will be placed on a new line.
newline-before - The affected items should always start on a new line
(when there are any items in front of it). Currently
the newline settings will be ignored, since every
item will be placed on a new line.
plain default, none No specific layout should be used, instead the
default behavior should be used. Such a layout does
113
The J2ME Polish GUI
Layout Alternative Names Explanation
not need to be defined explicitly, but it can be useful
to overwrite a basic setting.
Layout values can also be combined, using either the “||”, “|”, “or“ or “and“ operators. All operators
result in the same combination. An item can be centered and using the whole available width with
following example:
.myStyle {
layout: center | expand;
}
This is equivalent with:
.myStyle {
layout: center || expand;
}
And equivalent with:
.myStyle {
layout: center and expand;
}
And equivalent with:
.myStyle {
layout: center or expand;
}
And equivalent with:
.myStyle {
layout: hcenter | hexpand;
}
And equivalent with:
.myStyle {
layout: horizontal-center | horizontal-expand;
}
Colors
Colors can be defined in the colors section and in each attribute which ends on “-color”, e.g. “font-
color”, “border-color” etc.
Predefined Colors
The 16 standard windows colors are predefined:
Color Hex-Value Example Color Hex-Value Example
white
#FFFFFF
yellow
#FFFF00
black
#000000
maroon
#800000
114
The J2ME Polish GUI
Color Hex-Value Example Color Hex-Value Example
red
#FF0000
purple
#800080
lime
#00FF00
fuchsia
#FF00FF
blue
#0000FF
olive
#808000
green
#008000
navy
#000080
silver
#C0C0C0
teal
#008080
gray
#808080
aqua
#00FFFF
Another predefined color is “transparent”, which results in an transparent area. “transparent” is only
supported by some GUI elements like the menu-bar of a full-screen menu.
The colors Section
The colors section of the polish.css file can contain colors, which can be referenced in the styles,
fonts, border and background sections. You can even overwrite the predefined colors to confuse
other designers!
colors {
bgColor: #50C7C7;
bgColorLight: #50D9D9;
gray: #7F7F7F;
}
How to Define Colors
A color can be defined in many different ways:
.myStyle {
font-color: white; /* the name of the color */
border-color: #80FF80; /* a rgb hex value */
start-color: #F00; /* a short rgb-hex-value - this is red */
menu-color: #7F80FF80; /* an alpha-rgb hex value */
background-color: rgb( 255, 50, 128 ); /* a rrr,ggg,bbb value */
fill-color: rgb( 100%, 30%, 50% ); /* a rgb-value with percentage */
label-color: argb( 128, 255, 50, 128 ); /* a aaa, rrr, ggg, bbb value */
}
Color names refer to one of the predefined colors or a color which has been defined in the colors-
section:
color: black; or color: darkBackgroundColor;
The hex-value defines a color with two hexadecimal digits for each color (RRGGBB). Additionally
the alpha blending-component can be added (AARRGGBB).
color: #FF000; defines red. color: #7FFF0000; defines a half transparent red.
The shortened hex-value defines a color by a RGB-value in hexadecimal. Every digit will be
doubled to retrieve the full hex-value:
color: #F00; is equivalent with color: #FF0000;
color: #0D2; is equivalent with color: #00DD22; and so on.
115
The J2ME Polish GUI
A rgb-value starts with “rgb(“ and then lists the decimal value of each color from 0 up to 255:
color: rgb( 255, 0, 0 ); defines red. color: rbg( 0, 0, 255); defines blue and so on.
Alternatively percentage values can be used for rgb-colors:
color: rgb( 100%, 0%, 0% ); defines red as well as color: rgb( 100.00%, 0.00%, 0.00% )
;.
Alpha-RGB colors can be defined with the argb()-construct:
color: argb( 128, 255, 0, 0 ); defines a half transparent red. For the argb-construct
percentage values can be used as well.
Alpha Blending
Colors with alpha blending can be defined with hexadecimal or argb-definitions (see above). An
alpha value of 0 results in fully transparent pixels, whereas the value FF (or 255 or 100%) results in
fully opaque pixels. Some devices support values between 0 and FF, which results in transparent
colors. Colors with a specified alpha channel can only be used by specific GUI items. Please refer to
the documentation of the specific design attributes.
Fonts
Many GUI-Items have text elements, which can be designed with the font-attributes:
Attribute Possible Values Explanation
color Reference to a color or direct declaration
of the color.
Depending on the number of colors the
device supports, colors can look
differently on the actual device.
bitmap The name of the bitmap font. The
extension “.bmf” is not needed.
With the “bitmap”-attribute a bitmap-
font can be used instead of the system,
proportional and monospace fonts.
Please note that bitmap-fonts cannot be
changed in neither size, color or style.
Compare the following section for a
detailed discussion of bitmap-fonts.
face system (default, normal) The default font-face which is used
when the font-face or label-face
attribute is not set.
proportional A proportional face. This is on some
devices actually the same font-face as
the system-font.
monospace A font-face in which each character has
the same width.
size small The smallest possible font.
medium (default, normal) The default size for texts.
large (big) The largest possible font size.
116
The J2ME Polish GUI
Attribute Possible Values Explanation
style plain (default, normal) The default style.
bold A bold thick style.
italic (cursive) A cursive style.
underlined Not really a style, just an underlined
text.
An example font specification:
.myStyle {
font-color: white;
font-face: default; /* same as system or normal */
font-size: default; /* same as medium or normal */
font-style: bold;
}
The same specification can also be written as follows:
.myStyle {
font {
color: white;
style: bold;
}
}
In the font-definition the above face and size attributes can be skipped, since they only define the
default behavior anyhow.
Bitmap-Fonts
Bitmap-Fonts can be used instead of the usual predefined fonts for any text elements like titles,
StringItems, etc.
Creating Bitmap-Fonts
Bitmap-Fonts can be created out of any True Type Fonts (*.ttf) using the
${polish.home}/bin/fonteditor executable. In some cases it might be beneficial to optimize the
created PNG image manually for decreasing the size of the image and making manual adjustments.
The created bitmap-fonts-files (*.bmf) can also be fine-tuned using the binary data editor
${polish.home}/bin/binarydataeditor. Just select the File -> “open in binary
editor”-command.
The created bitmap-font needs to be copied into the “resources” folder of the project.
Using Bitmap-Fonts in the J2ME Polish GUI
The created bitmap-fonts can be used for any text-based items in the J2ME Polish GUI. They can be
integrated using the “font-bitmap”-attribute. The “.bmf” extension does not need to be given. In the
following example the “china.bmf” font is used for the currently focused item:
focused {
font-bitmap: china;
background-color: yellow;
117
The J2ME Polish GUI
layout: center | expand;
}
Using Bitmap-Fonts Directly
The bitmap-fonts can also be used directly in the program-code with the help of the
de.enough.polish.util.BitMapFont class. Please compare the JavaDoc documentation for more
information.
This example uses a bitmap-font for displaying a text:
import de.enough.polish.util.*;
public class MyScreen extends Canvas {
private BitMapFont bitMapFont = BitMapFont.getInstance( °/china.bmf¨ );
private BitMapFontViewer textViewer;
public MyScreen() throws IOException {
this.textViewer = this.bitMapFont.getViewer( °Hello World!¨ );
...
}
...
public void paint( Graphics g ) {
int x = 20;
int y = 50;
this.viewer.paint( x, y, g );
}
}
Labels
All GUI-Items can have a label, which is designed using the pre-defined style “label”. One can
specify another-style by using the “label-style”-attribute:
.myStyle {
font {
color: white;
style: bold;
}
label-style: myLabelStyle;
}
.myLabelStyle {
font-style: bold;
font-color: green;
background-color: yellow;
}
It is often advisable to use separate items for labels and contents. In that way you can get a clean
design by using a table, in which all labels are placed on the left side and all input-fields etc on the
right side. Tables are defined by using the “columns”-attribute of the corresponding screen,
compare the Screens-description on page 131.
When you want to have a line-break after each label, just add the “newline-after”-value to the
layout:
label {
font-style: bold;
font-color: green;
background: none;
118
The J2ME Polish GUI
layout: left | newline-after;
}
Backgrounds and Borders
Each style can define a specific background and border. There are many different types of
backgrounds and borders available, of which some are even animated.
A specification of a simple background and border is the following example:
.myStyle {
background-color: white;
border-color: gray;
border-width: 2;
}
This example creates a white rectangular background with a gray border, which is 2 pixel wide.
.myStyle {
background {
type: pulsating;
start-color: white;
end-color: pink;
steps: 30;
}
}
The above example creates a background which color is constantly changing between white and
pink. 30 color shades are used for the animation.
When no background or border should be used, the “none” value can be set:
.myStyle {
background: none;
border: none;
}
If more complex types should be used, the background- or border-type needs to be specified
explicitly. The following example illustrates this for an background, which colors change all the
time:
The available background- and border-types are explained in detail in the section “Specific Design
Attributes”.
Before and After Attributes
The before and after attributes can be used to insert content before or after GUI items which have
the specified style.
The following example adds a heart picture after the actual GUI items. The “focused” style is a
predefined style which is used for lists, forms, and so on.
focused {
119
The J2ME Polish GUI
after: url( heart.png );
background: none;
border-type: round-rect;
border-arc: 6;
border-color: yellow;
border-width: 2;
layout: left | expand;
font-color: black;
}
Currently only images can be included.
Specific Design Attributes
Many GUI items support specific CSS attributes.
Backgrounds
There are many different background-types which make use of specific CSS attributes. When
another background than the default simple background or the image background should be used,
the background-type attribute needs to be declared.
When no background at all should be used, the background: none; declaration can be used.
Simple Background
The simple background just fills the background with one color. When no background type is
specified, the simple background is used by default, unless the “background-image” attribute is set.
In the later case the image background will be used.
The simple background supports the color attribute:
Attribute Required Explanation
color Yes The color of the background, either the name of the color or a direct
definition.
The following styles use a yellow background:
.myStyle {
background-color: yellow;
}
.myOtherStyle {
background-color: rgb( 255, 255, 0 );
}
Round-Rect Background
The round-rect background paints a rectangular background with round edges. It supports following
attributes:
Attribute Required Explanation
type Yes The type needs to be “round-rect” or “roundrect”.
120
Fig. 4: The after attribute in
action.
The J2ME Polish GUI
Attribute Required Explanation
color No The color of the background, either the name of the color or a direct
definition. The default color is white.
arc No The diameter of the arc at the four corners. Defaults to 10 pixels, when
none is specified.
arc-width No The horizontal diameter of the arc at the four corners. Defaults to the arc-
value, when none is specified.
arc-height No The vertical diameter of the arc at the four corners. Defaults to the arc-
value, when none is specified.
This example creates a purple background with an arc diameter of 6 pixels:
.myStyle {
background {
type: round-rect;
color: purple;
arc: 6;
}
}
The following example uses a different horizontal arc diameter:
.myStyle {
background-type: round-rect;
background-color: purple;
background-arc: 6;
background-arc-width: 10;
}
Image Background
The image background uses an image for painting the background. This background type is used by
default when no type is set and the “background-image” attribute is set. The background supports
following attributes:
Attribute Required Explanation
type No When used needs to be “image”.
color No The color of the background, either the name of the color, a direct
definition or “transparent”. The default color is white. This color can
only be seen when the image is not big enough.
image Yes The URL of the image, e.g. “url( background.png )”
anchor No The anchor of the image – when not specified the image will be centered
("horizontal-center | vertical-center"). You can use a combination of
"top", "vertical-center" (="vcenter"), "bottom" and "left", "horizontal-
center" (= "hcenter" = "center"), "right". E.g. "top | left".
repeat No Either “repeat”, “no-repeat”, “repeat-x”/“repeat-horizontal” or “repeat-
121
The J2ME Polish GUI
Attribute Required Explanation
y”/“repeat-vertical”. Determines whether the background should be
repeated, repeated horizontally or repeated vertically. Default is no
repeat.
padding-
horizontal
No The horizontal gap between tiles, can be negative for overlapping the
tiles. Defaults to 0. Is only applicable when the repeat mode is activated.
padding-
vertical
No The vertical gap between tiles, can be negative for overlapping the tiles.
Defaults to 0. Is only applicable when the repeat mode is activated.
overlap No Defines whether the tiles should overlap over the actual background-area
when they don't fit exactly into the actual background-area. Either
“true”/“yes” or “no”/“false”. Defaults to false. Is only applicable when
the repeat mode is activated.
The following style uses the image “gradient.png” as a background:
.myStyle {
background-image: url( gradient.png );
background-anchor: top | center;
background-color: rgb( 69, 81, 77 );
}
This style uses the image “heart.png” as a repeated background:
.myStyle {
background-image: url( heart.png );
background-repeat: repeat;
}
Circle Background
The circle background paints a circular or elliptical background. It supports following attributes:
Attribute Required Explanation
type Yes The type needs to be “circle”.
color No The color of the background, either the name of the color or a direct
definition. Defaults to “white”.
diameter No With the “diameter” attribute it can be ensured that always a circle and
never an ellipse is painted. The diameter then defines the diameter of the
circle.
The following example uses a green circle background with a diameter of 20 pixels:
.myStyle {
background-type: circle;
background-color: green;
background-diameter: 20;
}
122
The J2ME Polish GUI
Pulsating Background
The pulsating background animates the color of the background. The color is changing from a start-
color to an end-color. It supports following attributes:
Attribute Required Explanation
type Yes The type needs to be “pulsating”.
start-color Yes The color of the background at the beginning of the animation sequence.
end-color Yes The color of the background at the end of the animation sequence.
steps Yes Defines how many color-shades between the start- and the end-color
should be used.
repeat No Either “yes”/”true” or “no”/”false”. Determines whether the animation
should be repeated. Defaults to “yes”.
back-and-
forth
No Either “yes”/”true” or “no”/”false. Determines whether the animation
sequence should be running backwards to the start-color again, after it
reaches the end-color. When “no” is selected, the animation will jump
from the end-color directly to the start-color (when repeat is enabled).
Defaults to “yes”.
The following style starts with a white background and stops with a yellow background:
.myStyle {
background {
type: pulsating;
start-color: white;
end-color: yellow;
steps: 15;
repeat: false;
back-and-forth: false;
}
}
Pulsating Circle Background
The pulsating circle background paints a circular or background which size constantly increases and
decreases. It supports following attributes:
Attribute Required Explanation
type Yes The type needs to be “pulsating-circle”.
color No The color of the background, either the name of the color or a direct
definition. Defaults to “white”.
min-
diameter
Yes The minimum diameter of the circle.
max-
diameter
Yes The maximum diameter of the circle.
123
The J2ME Polish GUI
The following example uses a green pulsating circle background with a minimum diameter of 20
pixels and a maximum diameter of 40 pixels:
.myStyle {
background-type: pulsating-circle;
background-color: green;
background-min-diameter: 20;
background-max-diameter: 40;
}
Pulsating Circles Background
The pulsating circles background paints an animated background of ever-growing circles. It
supports following attributes:
Attribute Required Explanation
type Yes The type needs to be “pulsating-circles”.
first-color Yes The first circle-color, either the name of the color or a direct definition.
second-
color
Yes The second circle-color, either the name of the color or a direct
definition.
min-
diameter
Yes The minimum diameter of the circle.
max-
diameter
Yes The maximum diameter of the circle.
circles-
number
Yes The number of circles which should be painted.
step No The number of pixels each circle should grow in each animation phase.
Float-values like “1.5” are also allowed. This defaults to “1” pixel.
The following example uses the pulsating circles background with a dark and with a bright color:
.myStyle {
+",-&./0%#(j
38!1'(!057"3$%&4,$.,517*
2$.734,/5/.'(+&6/5/.*
71,/%#4,/5/.'(+.$&B3\&6/5/.*
:$%4#$":131.'(K*
:"L4#$":131.'(XKK*
,$.,5174%0:+1.'(_*
731!'(Z=)*
;
}
Opening Background
The opening background paints an animated background which height starts small and then
increases whenever it changes the position. Its primary use is for the “focused”-style. It supports
following attributes:
124
The J2ME Polish GUI
Attribute Required Explanation
type Yes The type needs to be “opening”.
color Yes The background color, either the name of the color or a direct definition.
start-height No The height of the background immediately after it has changed its
position. This defaults to 1 pixel.
steps No The number of pixels by which the height should be increased in each
animation step. This defaults to 4 pixels. When the height is as big as the
normal background-height, the animation is stopped.
The following example uses the opening background:
.myStyle {
+",-&./0%#(j
38!1'(/!1%$%&*
,/5/.'(+&6/5/.*
73".34B1$&B3'(Z*
731!7'(h*
;
}
Opening-Round-Rect Background
The opening round rectangle background paints an animated background which height starts small
and then increases whenever it changes the position. Its primary use is for the “focused”-style. It
supports following attributes:
Attribute Required Explanation
type Yes The type needs to be “opening-round-rect”.
color Yes The background color, either the name of the color or a direct definition.
start-height No The height of the background immediately after it has changed its
position. This defaults to 1 pixel.
steps No The number of pixels by which the height should be increased in each
animation step. This defaults to 4 pixels. When the height is as big as the
normal background-height, the animation is stopped.
border-
width
No The width of the border, defaults to 0 (no border).
border-color No The color of the border, defaults to black.
arc No The diameter of the arc at the four corners. Defaults to 10 pixels, when
none is specified.
arc-width No The horizontal diameter of the arc at the four corners. Defaults to the arc-
value, when none is specified.
arc-height No The vertical diameter of the arc at the four corners. Defaults to the arc-
value, when none is specified.
125
The J2ME Polish GUI
The following example uses the opening-round-rect background:
.myStyle {
+",-&./0%#(j
38!1'(/!1%$%&4./0%#4.1,3*
,/5/.'(+&6/5/.*
73".34B1$&B3'(Z*
731!7'(h*
+/.#1.4C$#3B'(Z*
+/.#1.4,/5/.'(#".-\&6/5/.*
;
}
Round-Tab Background
The round-tab background paints a rectangular background where the top edges are rounded. It
supports following attributes:
Attribute Required Explanation
type Yes The type needs to be “round-tab”
color No The color of the background, either the name of the color or a direct
definition. The default color is white.
arc No The diameter of the arc at the four corners. Defaults to 10 pixels, when
none is specified.
arc-width No The horizontal diameter of the arc at the four corners. Defaults to the arc-
value, when none is specified.
arc-height No The vertical diameter of the arc at the four corners. Defaults to the arc-
value, when none is specified.
This example creates a purple background with an arc diameter of 6 pixels:
.myStyle {
background {
type: round-tab;
color: purple;
arc: 6;
}
}
The following example uses a different horizontal arc diameter:
.myStyle {
background-type: round-tab;
background-color: purple;
background-arc: 6;
background-arc-width: 10;
}
Smooth-Color Background
The smooth-color background paints an gradient background. It supports following attributes:
Attribute Required Explanation
126
The J2ME Polish GUI
color Yes
The color of the background, either the name of the color or a direct
definition.
gradient-
color
Yes
The color for the gradient, either the name of the color or a direct
definition.
stroke No The default value is 0.For effects set stroke 1.
This example creates a red background with an gradient to yellow:
.myStyle {
background {
type: smooth-color;
color: red;
gradient-color: yellow;

}
}
Tiger-Stripes Background
The tiger-stripes background paints an background with randomized numbers of Stripes. It supports
following attributes:
Attribute Required Explanation
color Yes
The color of the background, either the name of the color or a direct
definition.
stripes-
color
Yes
The color for the stripes, either the name of the color or a direct
definition.
number Yes The posible number of stripes that can be displayed.
This example creates a red background with an maximum of 25 black stripes:
.myStyle {
background {
type: tiger-stripes;
color: red;
stripe-color: black;
number: 25;
}
}
Ball-Games Background
The ball-games background paints an animated background with an number of sprites which
moving through the background. It supports following attributes:
127
The J2ME Polish GUI
Attribute Required Explanation
color Yes
The color of the background, either the name of the color or a direct
definition.
number Yes The number of sprites that were displayed.
border-color Yes The border color from the background.
image Yes The image for the sprite.
image-
width
Yes The width for the sprite.
image-
height
Yes The height for the sprite.
This example creates blue background with 5 sprites.The sprites include the given
image(player.png):
.myStyle {
background {
type: ball-games;
image: url( player.png );
image-width: 15;
image-height: 15;
color: blue;
number: 5;
border-color: green;

}
}
Borders
There are many different border-types which make use of specific CSS attributes. When another
border than the default simple border should be used, the border-type attribute needs to be declared.
When no border at all should be used, the border: none; declaration can be used.
Simple Border
The simple border paints a rectangle border in one color. The type attribute does not need to be set
for the simple border, since this is the default border. The only supported attributes are the color and
the width of the border:
Attribute Required Explanation
color Yes The color of the border, either the name of the color or a direct
definition.
width No The width of the border in pixels. Defaults to 1.
128
The J2ME Polish GUI
The following style uses a black border which is 2 pixels wide:
.myStyle {
border-color: black;
border-width: 2;
}
Round-Rect Border
The round-rect border paints a rectangular border with round edges. It supports following attributes:
Attribute Required Explanation
type Yes The type needs to be “round-rect” or “roundrect”.
color Yes The color of the border, either the name of the color or a direct
definition.
width No The width of the border in pixels. Defaults to 1.
arc No The diameter of the arc at the four corners. Defaults to 10 pixels, when
none is specified.
arc-width No The horizontal diameter of the arc at the four corners. Defaults to the arc-
value, when none is specified.
arc-height No The vertical diameter of the arc at the four corners. Defaults to the arc-
value, when none is specified.
This example creates a 2 pixels wide purple border with an arc diameter of 6 pixels:
.myStyle {
border {
type: round-rect;
color: purple;
width: 2;
arc: 6;
}
}
The following example uses a different horizontal arc diameter:
.myStyle {
border-type: round-rect;
border-color: purple;
border-width: 2;
border-arc: 6;
border-arc-width: 10;
}
Shadow Border
The shadow border paints a shadowy border. Following attributes are supported:
129
The J2ME Polish GUI
Attribute Required Explanation
type Yes The type needs to be “shadow”, “bottom-right-shadow” or “right-
bottom-shadow”.
color Yes The color of the border, either the name of the color or a direct
definition.
width No The width of the border in pixels. Defaults to 1.
offset No The offset between the corner and the start of the shadow. Defaults to
1 pixel, when none is specified.
Currently only a “bottom-right-shadow” is supported, so the border is painted below the item and
right of the item.
The following example uses a green shadow border:
.myStyle {
border-type: shadow;
border-color: green;
border-width: 2;
border-offset: 2;
}
Top, Bottom, Left and Right Border
These border paints a simple border on one side the corresponding item. Following attributes are
supported:
Attribute Required Explanation
type Yes The type needs to be “top”, “bottom”, “left” or “right”.
color Yes The color of the border, either the name of the color or a direct
definition.
width No The width of the border in pixels. Defaults to 1.
The following example uses a green border on the bottom of the title:
title {
border-type: bottom;
border-color: green;
border-width: 2;
}
Circle Border
The circle border paints a round or elliptical border and supports following attributes:
Attribute Required Explanation
type Yes The type needs to be “circle”.
130
The J2ME Polish GUI
Attribute Required Explanation
color No The color of the border, either the name of the color or a direct
definition. Defaults to “black”.
width No The width of the border in pixels. Defaults to 1.
stroke-style No Either “solid” or “dotted”. Defines the painting style of the border.
Defaults to “solid”.
The following example uses a green circle border with a two pixel wide dotted line:
.myStyle {
border-type: circle;
border-color: green;
border-width: 2;
border-stroke-style: dotted;
}
Screens: List, Form and TextBox
Predefined Styles for Lists, Forms and TextBoxes
All screens have a title and one or several embedded GUI items. In a Form or List one item is
usually focused. Screens can also have a designable menu, when the application uses a full-screen-
mode
10
. Some of the used styles can also use additional attributes.
Style-Name Add. Attributes Explanation
title - The title of a screen.
focused - The style of the currently focused item in the screen.
menu The style of the full-screen menu.
focused-style The name of the style for the currently focused menu item.
menubar-color The background color of the menu-bar. Either the name or
the definition of a color or “transparent”. Defaults to
“white”.
label-color, label-
face, label-size,
label-style
The font of the menu-commands (like “Select” or
“Cancel”). Default color is “black”, default font is the
system font in a bold style and medium size.
menuItem - The style for the commands in the menu. When not
defined, the menu-style will be used.
Please refer to page 145 for more information about designing the menu bar.
Additional Attributes for Screens
Each screen itself can have some additional attributes:
10 The fullscreen-mode can be activated by setting the <build> attribute “fullscreen” to either “menu” or “yes” in the
build.xml file.
131
The J2ME Polish GUI
Attribute Required Explanation
focused-style No The name of the style for the currently focused item. Defaults
to the predefined “focused” style.
title-style No The name of the custom style for the title of the screen. This
defaults to the predefined “title” style.
view-type No The view-type can be used for defining very different and even
animated views of the items in a screen. An example is the
“dropping” view-type in which the contained items seem to fall
from the top to their positions. Please note that not all view-
types support the “columns” and “columns-width”-attributes.
columns No The number of columns. This can be used to layout the items in
a table. Defaults to 1 column.
columns-width No Either “normal”, “equal” or the width for each column in a
comma separated list (e.g. “columns-width: 60,60,100;”).
Defaults to “normal”, meaning that each column uses as much
space as the widest item of that column needs.
The “equal” width leads to columns which have all the same
width.
The explicit list of column-widths results in the usage of those
widths.
menubar-color No The color of the menu-bar. This overrides the settings in the
predefined style “menu”. This attribute is only used, when the
“menu” fullscreen setting is activated in the “build.xml” file.
scrollindicator-color No The color of the element which is shown when the screen can
be scrolled. The default color is “black”.
show-text-in-title No An attribute for Lists only, which can be either “true” or
“false”. When “true” is given, only the image-elements of the
List will be shown and the text-elements will be used as titles.
The title will be updated with each new selection.
foreground-image No The URL of a image that should be painted at the very front of
the screen, e.g. "url( mascot.png )".
foreground-x No The x-position of the foreground image in pixels from the the
left border.
foreground-y No The y-position of the foreground image in pixels from the the
top border.
132
The J2ME Polish GUI
The following example uses some of these additional attributes:
list {
background-image: url( bg.png );
columns: 2;
columns-width: equal;
focused-style: .listFocusStyle; /* this style needs
to be defined, too */
}
TextBoxes also support a direct input mode and all CSS-attributes of the
text-field, please compare the discussion on page 142 for more
information.
Dynamic Styles for Screens
Dynamic styles can be used when no styles are explicitly set in the application code (compare page
107).
List
A list uses the dynamic selector “list” and always contains choice-items. The selector of these items
depends on the type of the list. An implicit list contains a “listitem”, a multiple list contains a
“checkbox” and an exclusive list contains a “radiobox”.
list {
background-color: pink;
}
defines the background color for screens of the type “List”.
listitem { /* you could also use °list listitem¨ */
font-style: bold;
}
defines the font style for the items in an implicit list.
Form
A form uses the dynamic selector “form” and can contain different GUI items.
form {
background-color: pink;
}
defines the background color for screens of the type “Form”.
form p {
font-style: bold;
}
defines the font style for normal text items in a “Form”.
TextBox
A TextBox uses the dynamic selector “textbox” and contains a single “textfield” item.
Commands
A multiple List or ChoiceGroup adds the commands “Mark” and “Unmark” by default to the menu.
133
Fig. 5: Using columns instead
of a normal list.
The J2ME Polish GUI
The names of the commands can be changed easily, compare page 76. If you want to suppress the
commands completely, the “polish.ChoiceGroup.suppressMarkCommands”-variable has to be set:
<variable name="polish.ChoiceGroup.suppressMarkCommands" value="true"/>
The same holds true for the “Select” command in implicit and popup Lists and ChoiceGroups:
<variable name="polish.ChoiceGroup.suppressSelectCommand" value="true"/>
A TextBox or TextField adds the “Clear”- and “Delete”-commands to the menu by default. The
names of these commands can be changed easily, compare page 76. If you want to suppress the
commands completely, the “polish.TextField.suppressCommands”-variable has to be set:
<variable name="polish.TextField.suppressCommands" value="true"/>
Example
The following example designs the main menu of an application, which is implemented using a List.
colors {
pink: rgb(248,39,186);
darkpink: rgb(185,26,138);
}
menu {
margin-left: 2;
padding: 2;
background {
type: round-rect;
color: white;
border-width: 2;
border-color: yellow;
}
focused-style: .menuFocused;
menubar-color: transparent;
menufont-color: white;
}
menuItem {
margin-top: 2;
padding: 2;
padding-left: 5;
font {
color: black;
size: medium;
style: bold;
}
layout: left;
}
.menuFocused extends .menuItem {
background-color: black;
font-color: white;
layout: left | horizontal-expand;
after: url(heart.png);
}
title {
134
The J2ME Polish GUI
padding: 2;
margin-top: 0;
margin-bottom: 5;
margin-left: 0;
margin-right: 0;
font-face: proportional;
font-size: large;
font-style: bold;
font-color: white;
background {
color: darkpink;
}
border: none;
layout: horizontal-center | horizontal-expand;
}
focused {
padding: 2;
padding-vertical: 3;
padding-left: 3;
padding-right: 3;
padding-top: 10;
padding-bottom: 10;
background-type: round-rect;
background-arc: 8;
background-color: pink;
border {
type: round-rect;
arc: 8;
color: yellow;
width: 2;
}
font {
style: bold;
color: black;
size: small;
}
layout: expand | center;
}
list {
padding-left: 5;
padding-right: 5;
padding-vertical: 10;
padding-horizontal: 10;
background {
color: pink;
image: url( heart.png );
}
columns: 2;
columns-width: equal;
layout: horizontal-expand | horizontal-center | vertical-center;
}
listitem {
margin: 2; /* for the border of the focused style */
padding: 2;
padding-vertical: 3;
padding-left: 3;
135
The J2ME Polish GUI
padding-right: 3;
padding-top: 10;
padding-bottom: 10;
background: none;
font-color: white;
font-style: bold;
font-size: small;
layout: center;
icon-image: url( %INDEX%icon.png );
icon-image-align: top;
}
View Types
View-types can be used for animating Forms, Lists, ChoiceGroups or even menus. There are several
view-types available, which are usually defined in a screen-style, e.g.:
.mainScreen {
padding-left: 5;
padding-right: 5;
view-type: dropping;
}
You can use either a (predefined) name of the view-type or the fully qualified class-name of that
type, which needs to extend the de.enough.polish.ui.ContainerView class.
Dropping View
The dropping view shows an animation of dropping and bouncing items. It is activated by
specifying the “dropping” view-type and supports following additional attributes:
Attribute Required Explanation
droppingview-speed No The speed in pixels per animation-step. The default speed is 10.
droppingview-repeat-
animation
No Defines whether the animation should be repeated each time
the screen is shown. Possible values are “true” and “false”.
This defaults to “false”.
droppingview-
maximum
No The maximum bouncing-height in pixels. This defaults to 30.
droppingview-
damping
No The value by which the maximum is decreased for each
following item. By having a damping, the top items seem to
bounce higher than lower ones. The default damping is 10.
droppingview-
maxperiode
No The maximum allowed number of bounces. This defaults to 5.
.mainScreen {
padding-left: 5;
padding-right: 5;
view-type: dropping;
droppingview-speed: 15;
droppingview-damping: 5;
droppingview-maxperiode: 2;
}
136
The J2ME Polish GUI
Shuffle View
The shuffle view animates the items by moving them from the left and right side into their final
target-position. It is activated by specifying the “shuffle” view-type and supports following
additional attributes:
Attribute Required Explanation
shuffleview-speed No The speed in pixels per animation-step. The default speed is 10.
shuffleview-repeat-
animation
No Defines whether the animation should be repeated each time
the screen is shown. Possible values are “true” and “false”.
This defaults to “false”.
.mainScreen {
padding-left: 5;
padding-right: 5;
view-type: shuffle;
shuffleview-speed: 15;
}
MIDP/2.0 View
The MIDP/2.0 view arranges the items just like the MIDP/2.0 standard encourages it: the items are
all lined up into one row until there is not enough space anymore or until an item with a "newline-
after" or "newline-before" layout is inserted. It is activated by specifying the “midp2” view-type
and supports no additional attributes.
.mainScreen {
padding-left: 5;
padding-right: 5;
view-type: midp2;
}
The StringItem: Text, Hyperlink or Button
Texts have no specific attributes, but the padding-vertical attribute has a special meaning:
Attribute Required Explanation
padding-vertical No The space between the lines when there the text contains line-
breaks.
Depending on the appearance mode
11
of the text, either the “p”, the “a” or the “button” selector is
used for dynamic styles:
Dynamic Selector Explanation
p The “p” selector is used for normal texts.
a The “a” selector is used for hyperlinks.
11 The appearance mode can be set in the application code with Item.setAppearanceMode( int ).
137
The J2ME Polish GUI
Dynamic Selector Explanation
button The “button” selector is used for buttons.
See the general explanation of dynamic styles on page 107 for more details.
The IconItem
Icons can only be used directly. Icons support following additional attributes:
Attribute Required Explanation
icon-image No The URL of the image, e.g. “icon-image: url(icon.png);”.
The keyword %INDEX% can be used for adding the position
of the icon to the name, e.g.
“icon-image: url(icon%INDEX%.png);”. The image used
for the first icon will be “icon0.png”, the second icon will use
the image “icon1.png” and so on. Defaults to “none”.
icon-image-align No The position of the image relative to the text. Either “top”,
“bottom”, “left” or “right”. Defaults to “left”, meaning that the
image will be drawn left of the text.
This example uses the attributes for designing all icons:
icon {
background: none;
font-color: white;
font-style: bold;
icon-image: url( %INDEX%icon.png );
icon-image-align: top;
}
When the icon-item has a “right” image align and the layout is set to “horizontal-expand”, the image
will be drawn directly at the right border of the item (with a gap specified by the padding-right
attribute). Otherwise the image will be drawn right of the text with the specified horizontal padding.
The ChoiceItem
The ChoiceItem is used in lists and in choice groups. It supports following additional attributes:
Attribute Required Explanation
icon-image No The URL of the image, e.g. “icon-image: url(icon.png);”.
The keyword %INDEX% can be used for adding the position
of the item to the name, e.g.
“icon-image: url(icon%INDEX%.png);”. The image used
for the first item will be “icon0.png”, the second item will use
the image “icon1.png” and so on.
icon-image-align No The position of the image relative to the text. Either “top”,
“bottom”, “left” or “right”. Defaults to “left”, meaning that the
138
The J2ME Polish GUI
Attribute Required Explanation
image will be drawn left of the text.
choice-color No The color in which the check- or radio-box will be painted.
Defaults to black.
checkbox-selected
radiobox-selected
No The URL of the image for a selected item. This will be used
only when the type of the list or of the choice group is either
exclusive or multiple. Default is a simple image drawn in the
defined choice-color.
checkbox-plain
radiobox-plain
No The URL of the image for a not-selected item. This will be
used only when the type of the list or of the choice group is
either exclusive or multiple. Default is a simple image drawn in
the defined choice-color. When “none” is given, no image will
be drawn for not-selected items. Only the image for selected
items will be drawn in that case.
Depending on the type of the corresponding list or choice group, different dynamic selectors are
used by a choice item:
Type of List or
ChoiceGroup
Selector
implicit listitem
exclusive radiobox
multiple checkbox
popup popup
The ChoiceGroup
A choice group contains several choice items. It supports the “focused-style” attribute:
Attribute Required Explanation
focused-style No The name of the style for the currently focused item.
columns No The number of columns. This can be used to layout the items in
a table. Defaults to 1 column.
columns-width No Either “normal”, “equal” or the width for each column in a
comma separated list (e.g. “columns-width: 60,60,100;”).
Defaults to “normal”, meaning that each column uses as much
space as the widest item of that column needs.
The “equal” width leads to columns which have all the same
width.
139
The J2ME Polish GUI
Attribute Required Explanation
The explicit list of column-widths results in the usage of those
widths.
view-type No The view-type used for this choice group. Please compare the
discussion of view-types on page 136.
popup-image No The URL to the image which should be shown in the closed
popup-group. Per default a simple dropdown image will be
used.
popup-color No The color for the arrow in the dropdown-image of a closed
popup-group. Defaults to black.
popup-background-
color
No The color for the background in the dropdown-image of a
closed popup-group. Defaults to white.
An multiple ChoiceGroup adds the commands “Mark” and “Unmark” by default to the menu. The
names of the commands can be changed easily, compare page 76. If you want to suppress the
commands completely, the “polish.ChoiceGroup.suppressMarkCommands”-variable has to be set:
<variable name="polish.ChoiceGroup.suppressMarkCommands" value="true"/>
The same holds true for the “Select” command:
<variable name="polish.ChoiceGroup.suppressSelectCommand" value="true"/>
The Gauge
A Gauge shows a progress indicator. It supports following additional attributes:
Attribute Required Explanation
gauge-image No The URL of the image, e.g. “gauge-image:
url(progress.png);”. When no gauge-width is defined, the
width of this image will be used instead.
gauge-color No The color of the progress bar. Defaults to blue.
gauge-width No The width of the gauge element in pixels. When no width is
defined, either the available width or the width of the provided
image will be used.
gauge-height No The height of the gauge element in pixels. Defaults to 10.
When an image is provided, the height of the image will be
used.
gauge-mode No Either “chunked” or “continuous”. In the continuous mode only
the gauge-color will be used, whereas the chunked mode
intersects the indicator in chunks. The setting is ignored when
an image is provided. Default value is “chunked”.
140
The J2ME Polish GUI
Attribute Required Explanation
gauge-gap-color No The color of gaps between single chunks. Only used in the
“chunked” gauge-mode or when a gauge with an indefinite
range is used. In the latter case the provided color will be used
to indicate the idle state. Default gap-color is white.
gauge-gap-width No The width of gaps in pixels between single chunks. Only used
in the “chunked” gauge-mode. Defaults to 3.
gauge-chunk-width No The width of the single chunks in the “chunked” gauge-mode.
gauge-show-value No Either “true” or “false”. Determines whether the current value
should be shown. This defaults to true for all definite gauge
items.
gauge-value-align No Either “left” or “right”. Defines where the current value of the
gauge should be displayed. Defaults to “left”, that is left of the
actual gauge item.
The following example shows the use of the gauge attributes:
.gaugeStyle {
padding: 2;
border-color: white;
gauge-image: url( indicator.png );
gauge-color: rgb( 86, 165, 255 );
gauge-width: 60;
gauge-gap-color: rgb( 38, 95, 158 );
/* these setting are ignored, since an image is provided:
gauge-height: 8;
gauge-mode: chunked;
gauge-gap-width: 5;
gauge-chunk-width: 10;
*/
}
When the Gauge item is used with an indefinite range, the gauge-gap-color will be used to indicate
the idle state. When the “continuous running” state is entered and an image has been specified, the
image will “fly” from the left to the right of the indicator.
The TextField
A TextField is used to get user input. You can choose whether the native input methods or a direct
input mode should be used. When the native mode is activated, a new input screen will pop up for
the user and special input modes like T9 or handwriting recognition can be used. When the direct
input mode is used instead, no extra screen will be shown and J2ME Polish accepts the entered
character directly. Please compare the following subsection “Direct Input Mode” for more
information.
The TextField supports following additional attributes:
141
The J2ME Polish GUI
Attribute Required Explanation
textfield-width No The minimum width of the textfield-element in pixels.
textfield-height No The minimum height of the textfield-element in pixels.
Defaults to the height of the used font.
textfield-direct-input No Defines whether the direct input mode should be activated.
Possible values are either “false” or “true”. By default the
direct input mode is deactivated (“false”).
textfield-caret-color No The color of the caret which indicates the editing position. This
defaults to the color of the used font.
textfield-caret-char No The character which indicates the editing position. This
defaults to “|”.
textfield-show-length No Determines whether the length of the entered text should be
shown during the editing of this field. This has an effect only
when the direct input mode is used.
The following example shows the use of the TextField attributes:
.inputStyle {
padding: 2;
background-color: white;
border-color: black;
textfield-height: 15;
textfield-width: 40;
textfield-direct-input: true;
textfield-caret-color: red;
textfield-caret-char: >;
textfield-show-length: true;
}
TextField-Commands
A TextField adds the “Clear”- and “Delete”-commands to the menu by default. The names of these
commands can be changed easily, compare page 76. If you want to suppress the commands
completely, the “polish.TextField.suppressCommands”-variable has to be set:
<variable name="polish.TextField.suppressCommands" value="true"/>
You can also deactivate the "Clear" command singly:
<variable name="polish.TextField.suppressClearCommand" value="true"/>
Last but not least it is also possible to deactivate the "Delete" command singly:
<variable name="polish.TextField.suppressDeleteCommand" value="true"/>
Direct Input Mode
The direct input mode can be activated for TextFields as well as for TextBoxes using the CSS-
attribute “textfield-direct-input” or by defining the preprocessing-variable
“polish.TextField.useDirectInput” in the build.xml file:
142
The J2ME Polish GUI
<variable name="polish.TextField.useDirectInput" value="true"/>
When the direct input mode is used, no extra screen will be used for editing the text and all
designing possibilities of J2ME Polish can be used. When the TextField is used within a Form, the
associated ItemStateListener will be notified after each change of the text.
On stylus-based devices, this mode should not be used since these devices often rely on native input
methods like handwriting recognition. This can be ensured by setting the preprocessing variable
only for devices which have no pointer-events:
<variable name="polish.TextField.useDirectInput" value="true"
if="!polish.hasPointerEvents"/>
The direct input should not be used for editing longs texts (i.e. TextBoxes), since T9 and similar
input helpers cannot be used in this mode.
The user can change the input mode from lowercase (“abc”) to initial-letter uppercase (“Abc”) to
uppercase (“ABC”) and to numeric (“123”). The current input mode is shown below the title in an
extra StringItem. This item can be designed using the predefined CSS-style “info”:
info {
padding-right: 10;
background: none;
border-color: black;
font-style: plain;
font-face: proportional;
font-size: small;
font-color: fontColor; /* a color defined in the °colors¨ section */
layout: right;
}
The info-item can be deactivated globally by setting the “polish.TextField.showInputInfo”-variable
to “false”:
<variable name="polish.TextField.showInputInfo" value="false" />
Next to using the CSS-attributes “textfield-caret-color”, “textfield-caret-char” and “textfield-show-
length” the behavior of the direct input mode can be adjusted using several preprocessing variables.
Especially the available character can be changed, which can be necessary for localizing the direct
input.
Following variables can be set:
Variable Default Explanation
polish.TextField.InputT
imeout
“1000” The timeout in milliseconds after which a chosen character
is inserted into the text automatically.
polish.TextField.showI
nputInfo
“true” Defines whether the box showing the current input mode
(e.g. “123”, “Abc”, “abc”, “ABC”) should be shown at all.
You can deactivate the box globally by setting the
“polish.TextField.showInputInfo” variable to “false”.
polish.key.ChangeInput
ModeKey
Varying The key which is used for changing the input mode
between lowercase (“abc”), uppercase (“ABC”), initial-
143
The J2ME Polish GUI
Variable Default Explanation
letter uppercase (“Abc”) and numeric (“123”). On Sony-
Ericsson devices Canvas.KEY_STAR (42), on Motorola
devices Canvas.KEY_NUM0 (48) and on all other devices
Canvas.KEY_POUND (35) is used.
polish.TextField.charac
tersKey1
“.,!?:/@_-
+1”
The characters which are available when the key “1” is
pressed.
polish.TextField.charac
tersKey2
“abc2” The characters which are available when the key “2” is
pressed. It might be useful to add local specific umlauts
here.
polish.TextField.charac
tersKey3
“def3” The characters which are available when the key “3” is
pressed.
polish.TextField.charac
tersKey3
“ghi4” The characters which are available when the key “4” is
pressed.
polish.TextField.charac
tersKey5
“jkl5” The characters which are available when the key “5” is
pressed.
polish.TextField.charac
tersKey6
“mno6” The characters which are available when the key “6” is
pressed.
polish.TextField.charac
tersKey7
“pqrs7” The characters which are available when the key “7” is
pressed.
polish.TextField.charac
tersKey8
“tuv8” The characters which are available when the key “8” is
pressed.
polish.TextField.charac
tersKey9
“wxyz9” The characters which are available when the key “9” is
pressed.
polish.TextField.charac
tersKey0
“ 0” The characters which are available when the key “0” is
pressed. On Motorola devices this key is used for switching
the input mode.
polish.TextField.charac
tersKeyStar
“.,!?:/@_-+” The characters which are available when the key “*” is
pressed. On Motorola devices this key is used for entering
spaces (“ ”).
polish.TextField.charac
tersKeyPound
(none) The characters which are available when the key “#” is
pressed. On Sony-Ericsson devices this key is used for
entering spaces (“ ”).
The DateField
A DateField is used to enter date or time information. Currently the input is done with the use of the
native functions, so that special input modes can be used (like T9 or handwriting recognition). The
DateField supports following additional attributes:
144
The J2ME Polish GUI
Attribute Required Explanation
datefield-width No The minimum width of the datefield-element in pixels.
datefield-height No The minimum height of the datefield-element in pixels.
Defaults to the height of the used font.
The appearance of the datefield can also be adjusted using the preprocessing variable
“polish.DateFormat”, which can be defined in the <variables> section of the J2ME Polish task:
" <variable name="polish.DateFormat" value="us" />: The US standard of MM-DD-
YYYY is used, e.g. “12-24-2004”.
" <variable name="polish.DateFormat" value="de" />: The German standard of
DD.MM.YYYY is used, e.g. “24.12.2004”.
" <variable name="polish.DateFormat" value="fr" />: The French standard of
DD/MM/YYYY is used, e.g. “24/12/2004”.
" All other settings: The ISO 8601 standard of YYYY-MM-DD is used, e.g. “2004-12-24”.
The DateFormat also supports the generic values “dmy” (day-month-year), “mdy” (month-day-year)
or “ymd” (year-month-day). Along with the polish.DateFormatSeparator-variable and the
polish.DateFormatEmptyText-variable one can use any custom date format:
<variable name="polish.DateFormat" value="ymd"/>
<variable name="polish.DateFormatSeparator" value="/"/>
<variable name="polish.DateFormatEmptyText" value="Select Date"/>
The Ticker
A Ticker scrolls a text over the current screen. In J2ME Polish the ticker is situated right above the
menu-bar on the bottom of a screen. Following attribute is supported:
Attribute Required Explanation
ticker-step No The number of pixels by which the ticker is shifted at each
update. Defaults to 2 pixels.
The Menu Bar
In the menu bar the commands reside that have been added to a screen. This bar can be designed
using the predefined “menu” style. The font-settings in this style are used to render the actual
commands, and the CSS attrbute “:1%0+".4,/5/.” defines the color of the menu-bar. The color
can have any setting including “transparent”, which is useful when the background of the
corresponding screen should be shown. The “:1%0+".4,/5/.” defaults to white by the way. When
this attribute is also defined in a screen-style, it will override the setting in the “menu” style for the
corresponding screen. Let me demonstrate:
menu {
padding: 5;
background: none;
/* The design of the commands in the menu-bar: */
145
The J2ME Polish GUI
font-style: bold;
font-face: proportional;
font-size: small;
font-color: red;
/* The color of the menubar background: */
menubar-color: black;
}
.myScreenStyle {
background-image: url( bg.png );
/* use a transparent menubar for screens with this style,
so that the bg.png image is shown in the menubar as well: */
menubar-color: transparent;
}
When there is more than one item available in the menu, an “Options” menu will be shown
automatically, which opens the real menu when pressed (like shown in the following figures).
The items in the opened menu are designed using the predefined “menuitem” style. The background
and the border of the opened menu is designed using the “menu” style. You can change the names of
the “Options”, “Select” and “Cancel” commands by the way, this is explained in the localization
chapter on page 76.
The Extended Menu Bar
You can use the extended menu bar in cases when the design possibilities of the
normal menu bar are not sufficient for you. In contrast to the normal menu bar,
the extended menu bar is a full blown item and can, therefore, be designed just
like any other item. The price for using the extended menu bar is to have an
additional 2 kb class file in your JAR.
For using the extended menu-bar instead of the normal one, you need to set the
"polish.MenuBar.useExtendedMenuBar" preprocessing variable to "true" in the
<variables>-section of the build.xml file:
<variables>
<variable
name="polish.MenuBar.useExtendedMenuBar"
value="true"
/>
</variables>
The menu bar can be designed using the predefined styles "menubar", "leftcommand" and
"rightcommand":
Style Description
menubar This design of the menu-bar itself.
leftcommand Designs the left command ("Options", "Select" and user-defined
commands). Accepts all attributes of the IconItem.
rightcommand Designs the right command ("Cancel" and user-defined BACK or
146
Fig. 6: Using images
in the extended menu
bar.
The J2ME Polish GUI
Style Description
CANCEL commands). Accepts all attributes of the IconItem.
The menubar-style offers following additional attributes:
Attribute Required Explanation
menubar-options-
image
No Defines the image-URL for the options-image of the extended
menubar.
menubar-select-
image
No Defines the image-URL for the select-image of the extended
menubar.
menubar-cancel-
image
No Defines the image-URL for the cancel-image of the extended
menubar.
menubar-show-
image-and-text
No Determines whether the text should be shown as well in the
menubar, when an image has been defined for the
corresponding action. Defaults to "false".
The following example demonstrates the design of the extended menu-bar:
menubar {
margin-top: 0;
margin-bottom: 0;
margin-left: 2;
margin-right: 2;
padding: 0;
background: none;
menubar-options-image: url( options.png );
/*
menubar-select-image: url( checked.png );
menubar-cancel-image: url( cancel.png );
menubar-show-image-and-text: true;
*/
}
leftcommand {
padding-horizontal: 4;
padding-bottom: 0;
font-color: fontColor;
font-style: bold;
background: none;
}
rightcommand {
padding-horizontal: 4;
padding-bottom: 0;
font-color: fontColor;
font-style: bold;
background: none;
;
147
The J2ME Polish GUI
The TabbedForm
The tabbed form can be designed like any Form and accepts the very same CSS-attributes.
Additionally the predefined styles "tabbar", "activetab" and "inactivetab" can be used to design the
additional elements of a tabbed form.
Style Description
tabbar This style designs the tab-bar of a TabbedForm.
activetab Designs the currently active tab of a TabbedForm.
inactivetab Designs all tabs but the currently selected one of a TabbedForm.
You can set the color of the scrolling indicator within the tabbar-style with the tabbar-scrolling-
indicator-color attribute:
tabbar {
background-color: white;
layout: expand;
padding-bottom: 0;
tabbar-scrolling-indicator-color: black;
}
activetab {
background-type: round-tab;
background-color: silver;
background-arc: 8;
font-color: white;
padding-left: 10;
padding-right: 8;
}
inactivetab {
padding-left: 6;
padding-right: 4;
margin-left: 2;
margin-right: 2;
background-type: round-tab;
background-color: gray;
background-arc: 8;
font-color: silver;
}
148
The MIDP/2.0-Compatible Game-Engine
The MIDP/2.0-Compatible Game-Engine
Even though MIDP/2.0 is the future, the market is crowded with MIDP/1.0 devices. J2ME Polish
offers a nifty solution for those developers who want to support both platforms with the advanced
MIDP/2.0 technology.
All classes of the javax.microedition.lcdui.game-package can be used normally:
Class Explanation
GameCanvas The GameCanvas class provides the basis for a game user interface.
Layer A Layer is an abstract class representing a visual element of a game.
LayerManager The LayerManager manages a series of Layers.
Sprite A Sprite is a basic visual element that can be rendered with one of several
frames stored in an Image; different frames can be shown to animate the
Sprite.
TiledLayer A TiledLayer is a visual element composed of a grid of cells that can be
filled with a set of tile images.
With this game-engine it is possible to program a game with one source code for MIDP/2.0 as well
as MIDP/1.0 devices without changing anything within the source code!
How It Works
The J2ME Polish build-tool identifies the usage of the MIDP/2.0 game API and “weaves” the
necessary wrapper classes into the code. The obfuscation step then removes all unnecessary
functionality to ensure that only the needed parts are actually included into the application. The
J2ME Polish game-engine only needs about 5 to 6 kb extra space in the resulting JAR package,
when all classes are used.
Limitations
For technical reasons the collision detection works only with collision rectangles, which should be
set tightly for Sprites therefore. A pixel-level collision detection is not supported.
When a class extends the GameCanvas class, it should call the super-implementations, when one of
the methods keyPressed(int), keyReleased(int) or keyRepeated(int) is overridden.
The transformation of Sprites is currently only supported for Nokia devices, otherwise the
transformations will be ignored.
Optimizations
The TiledLayer and the GameCanvas implementations have several optional optimizations, which
can be triggered by defining specific variables in the “build.xml” file (compare the variables section
on page 52).
149
The MIDP/2.0-Compatible Game-Engine
Using a Fullscreen-GameCanvas
The GameCanvas normally uses the “fullscreen”-attribute of the <build>-element to determine
whether it should use a fullscreen-canvas (compare page 36). This behavior can be overridden with
defining the “polish.GameCanvas.useFullScreen” variable. Allowed value are “yes”, “no” and
“menu”. Please note that the “menu” mode (which should be used when commands are added to the
GameCanvas) is only supported when the J2ME Polish GUI is used. Another limitation of the
“menu” mode is that the paint()-method of the GameCanvas cannot be overridden.
Variable Explanation
polish.GameCanvas.useFullSc
reen
Defines whether the fullscreen mode is used, overrides the
“fullscreen”-attribute of the <build>-element. Possible values are
“yes”, “no” or “menu”.
The following example enables the fullscreen mode for the GameCanvas:
?G".$"+51(%":1@A!/5$7B=`":16"%G"7=071Q055N,.11%A(G"501@A817A(IH
This example shows how to override the paint()-method, even though the J2ME Polish GUI and the
“menu” fullscreen mode is used:
public class MyGameCanvas extends GameCanvas {
...
//#if polish.usePolishGui && polish.classes.fullscreen:defined
//# public void paintScreen( Graphics g)
//#else
public void paint( Graphics g)
//#endif
{
// implement the paint method
...
}
}
Backbuffer Optimization for the TiledLayer
The backbuffer optimization uses a buffer, to which the tiles are only painted when they have
changed. This can result in a significant higher frames per second throughput, since the complete
layer needs to be painted only seldomly.
The drawback of the backbuffer optimization is that it uses more memory and that no transparent
tiles can be used. So when memory is an issue or when the tiled layer is not used as the background,
it is recommended not to use the backbuffer optimization.
Variable Explanation
polish.TiledLayer.useBackBuff
er
Defines whether the backbuffer optimization should be used,
needs to be ”true” to enable the optimization.
polish.TiledLayer.Transparent The color which is used for tiles which should transparent. This
150
The MIDP/2.0-Compatible Game-Engine
Variable Explanation
TileColor defaults to black.
The following example enables the backbuffer optimization:
?G".$"+51(%":1@A!/5$7B=Y$51#D"81.=Y."%7!".1%3Y$516/5/.A(G"501@AKLMKMKKKA(IH
?G".$"+51(%":1@A!/5$7B=Y$51#D"81.=071Y$51\",-\0221.A(G"501@A3.01A(IH
Splitting an Image into Single Tiles
A tiled layer can be drawn significantly faster when the base image is split into single tiles. This
optimization needs a bit more memory compared to a basic tiled layer. Also the transparency of tiles
is lost when the device does not support the Nokia UI API (all Nokia devices do support this API).
Variable Explanation
polish.TiledLayer.splitImage Defines whether the base image of a TiledLayer should be split
into single tiles. Needs to be “true” to enable this optimization.
The following example enables the single tiles optimization:
?G".$"+51(%":1@A!/5$7B=Y$51#D"81.=7!5$3P:"&1A(G"501@A3.01A(IH
Defining the Grid Type of a TiledLayer
The J2ME Polish implementation uses a byte-grid, which significantly decrease the memory
footprint, but which also limits the number of different tiles to 128. For cases where more different
tiles are used, one can define the type to either “int”, “short” or “byte”.
Variable Explanation
polish.TiledLayer.GridType Defines the type of the used grid in TiledLayer. This defaults to
“byte”. Possible values are “int”, “short” or “byte”.
The following example uses a short-grid, which allows the usage of 32767 different tiles instead of
128 different tiles:
?G".$"+51(%":1@A!/5$7B=Y$51#D"81.=`.$#Y8!1A(G"501@A7B/.3A(IH
Using the Game-Engine for MIDP/2.0 Devices
You can use the J2ME Polish implementation for MIDP/2.0 devices as well. This can make sense
because some vendor implementations are buggy or have sluggish performance. When the game-
engine should be used for MIDP/2.0 devices as well, you need to define the preprocessing variable
“polish.usePolishGameApi”:
151
The MIDP/2.0-Compatible Game-Engine
Variable Explanation
polish.usePolishGameApi Defines whether the J2ME Polish game-engine should be used on
MIDP/2.0 devices as well. Possible values are “true” or “false”.
The following example uses the game-engine for Nokia MIDP/2.0 devices as well:
?G".$"+51(%":1@A!/5$7B=071S/5$7B`":1a!$A(G"501@A3.01A($2@A!/5$7B=G1%#/.(@@(
J/-$"A(IH
Porting a MIDP/2.0 Game to MIDP/1.0 Platforms
Building the Existing Application
In the first step we use J2ME Polish for building the game. We need to copy and adjust the
build.xml file from the provided sample-application of J2ME Polish and we might need to adjust
the handling of resources.
Adjusting the build.xml
To build the existing game we need to copy the sample-build.xml file, which resides in the
“sample” subdirectory of the J2ME Polish installation, into the the root directory of the game.
The build.xml includes all the necessary information about the project like the MIDlet-classes, the
target-devices, the version of the game and so on. Many IDEs support syntax highlighting and auto-
completion for this file, but it can also be edited with any decent text-editor.
The J2ME Polish task is divided in 3 subsections: <info>, <deviceRequirements> and <build>.
The <info>-section contains general information about the project:
?$%2/
((5$,1%71@A`SDA
((%":1@ARZUF(S/5$7BA
((G1.7$/%@AV=X=hA
((#17,.$!3$/%@Aa(7":!51(!./b1,3A
((G1%#/.J":1@AF%/0&B(N/23C".1A
(($%2/O.5@AB33!'IICCC=bZ:1!/5$7B=/.&A
(($,/%@A#/3=!%&A
((b".J":1@Aij!/5$7B=G1%#/.;4ij!/5$7B=%":1;41L":!51=b".A(
((b".O.5@Aij#1!5/840.5;ij!/5$7B=b".J":1;A
((,/!8.$&B3@A6/!8.$&B3(ZKKh(F%/0&B(N/23C".1=(a55(.$&B37(.171.G1#=A
((#151316/%2$.:@AM/(8/0(.1"558(C"%3(3/(-$55(:1kA(
IH
This information can be changed arbitrarily. The name of the application can also contain the name
and vendor of the target-device. The above example “${polish.vendor}-${polish.name}-
example.jar” results in the name “Nokia-6600-example.jar”, when the application is build for the
Nokia/6600 device for example. The above property “${deploy-url}” is defined above in the
sample build.xml script and is usually empty.
In the following <deviceRequirements>-section the target-devices are selected. Since we want to
build the application for a MIDP/2.0 device first, we enter any MIDP/2.0 capable device into the
requirements, e.g. “Nokia/6600” or “Nokia/Series60Midp2”. The “Series60Midp2” device is a
152
The MIDP/2.0-Compatible Game-Engine
virtual device representing a typical Series 60 phone with MIDP/2.0 support. Such is phone
supports additionally the Mobile Media API (mmapi) and the Wireless Messaging API (wmapi).
The device selection is very flexible and can select all MIDP/2.0 devices which support the Mobile
Media API as well, for example. For keeping this example easy to manage, we use only the selection
by the device's identifier:
?#1G$,1]1g0$.1:1%37H
((?.1g0$.1:1%3(%":1@AP#1%3$2$1.A(G"501@AJ/-$"IN1.$17TKU$#!ZA(IH
?I#1G$,1]1g0$.1:1%37H
The <build>-section controls the actual build process. For keeping this example easy, we choose not
to use the GUI of J2ME Polish and set the “usePolishGui” attribute to “false”. We also need to
adjust the <midlet>-subelement and enter the full name of our game-class:
?+0$5#
((071S/5$7B`0$@A2"571A
((.17M$.@A.17/0.,17A
((C/.-M$.@Aij#$.=C/.-;A
H
((?f44(:$#5137(#12$%$3$/%(44H
((?:$#513(,5"77@A#1=1%/0&B=!/5$7B=1L":!51=U1%0U$#513A(%":1@AFL":!51A(IH
?I+0$5#H
The <build>-section has many subelements and can automate many tasks from the inclusion of the
debugging framework to the signing of the application. These settings are outside of the scope or
this article, though.
Managing the Resources
J2ME Polish manages the inclusion of resources automatically for you. Just copy all resources
which are needed in any case into the “resources” folder of your project (create it first if
necessary).
You can then use the subfolders for including resources only for devices which can use these
resources. For example you can place MIDI soundfiles into the “resources/midi” folder and 3gpp
video files into the “resources/3gpp” folder. This results in smaller application bundles, since
unnecessary resources will not be included at all.
More specific resources are included instead of general resources. You could keep low-color images
into the general “resources” folder and use the “resources/BitsPerPixel.16+” folder for using
high-color versions of these images for devices which support at least 16 bits per pixel (65.536
colors). The same principle can be used for including specific resources for all devices of a specific
vendor (e.g. “resources/Sony-Ericsson” or “resources/Nokia”) or even for specific devices
(e.e. “resources/Nokia/6600”).
This powerful automatic resource assembling of J2ME Polish is the reason why no subfolders can
be used within the application code. All resources are copied into the base-folder of the application.
So instead of Image.createImage("images/sprite.png") you need to use
Image.createImage("sprite.png") within the source code. This has the extra benefit of saving
space within the final jar-file as well as heap-size in the game.
153
The MIDP/2.0-Compatible Game-Engine
Building the Game
Now all settings necessary for building the game with J2ME Polish have been made, so now call
“ant” on the command-line from within the base folder or we can right-click the build.xml file
within the IDE and select “Run Ant”, “make” or similar.
J2ME Polish will now preprocess, compile, obfuscate, preverify and package the game
automatically. When the above settings will be used, we will find the files “Nokia-
Series60Midp2-example.jar” and “Nokia-Series60Midp2-example.jad” in the “dist” folder
of the project after the build.
The game should now be tested with an emulator or a real
device, to make sure everything works as expected.
Porting the Game to MIDP/1.0
After the successful transition to J2ME Polish, porting a game
to MIDP/1.0 is very easy.
Necessary Source Code Changes
Subclasses of GameCanvas need to call the super-
implementations of any overridden keyPressed(int) and
keyReleased(int)-methods, so that the J2ME Polish game-
engine knows about these keys.
When there is a compile error stating that a
javax.microedition.lcdui.game-class cannot be found,
please ensure that you use import-statements rather than fully
qualified class-names in your source-code:
Instead of MyGameCanvas extends
javax.microedition.lcdui.game.GameCanvas the
import-statement is needed:
import javax.microedition.lcdui.game.GameCanvas;
MyGameCanvas extends GameCanvas
Working Around the Limitations of the Game-Engine
Pixel-Level Collision Detection
Pixel-level collision detection cannot be used on MIDP/1.0
platforms, so we need to set tight collision rectangles for the
sprites.
Sprite Transformations
Another limitation of J2ME Polish is that sprite-transformations are only supported for Nokia
devices so far. This means that for other devices transformed sprite-images are needed. These can be
easily included by putting them in the “resources/NoSpriteTransformations” folder. We can
adjust the handling of sprite-transformations by using the preprocessing of J2ME Polish:
//#if !(polish.midp2 || polish.supportSpriteTransformation)
154
Checklist for Porting
! All resources needs to be loaded
from the base directory, e.g.
Image.createImage(“/sprite.png”)
! Use import-statements instead of
full-qualified class-names in the
source code
! Use preprocessing for adjusting
the source code to specific
devices, e.g.
//#if polish.midp2 ||
polish.api.mmapi
! Use the automatic resource
assembling for using specific
resources for the target-devices.
! Set tight collision rectangles,
since pixel-level collision
detection cannot be used on
MIDP/1.0 devices
! Sprite-transformations are only
supported for devices which
support Nokia's UI-API, so
transformed PNGs need to be
used for other devices.
! The super-implementation of
keyPressed() and keyReleased()
should always be called first,
when such methods are
overridden.
The MIDP/2.0-Compatible Game-Engine
private final static int MIRROR_SEQUENCE = new int[]{3,4,7,5};
//#endif
[...]
//#if polish.midp2 || polish.supportSpriteTransformation
this.sprite.setTransform( Sprite.TRANS_MIRROR );
//#else
this.sprite.setFrameSequence( MIRROR_SEQUENCE );
//#endif
In the above example we use call the transform(int)-method of the sprite only when the device either
uses the MIDP/2.0 platform or supports sprite transformation. Otherwise the frame-sequence
MIRROR_SEQUENCE will be used instead.
A similar adjustment can be needed during the instantiation of the sprite, when the transformed
image has different frame-dimensions:
//#if polish.midp2 || polish.supportSpriteTransformation
int frameWidth = 10;
int frameHeight = 8;
//#else
//# int frameWidth = 6;
//# int frameHeight = 8;
//#endif
this.sprite = new Sprite( spriteImage, frameWidth, frameHeight );
For an even more flexible approach you can use preprocessing variables. These variables can be
defined in the <variables>-subelement of the build.xml file:
?G".$"+517H
((?G".$"+51(
%":1@A!5"81.=2.":1M$:1%7$/%7A(
G"501@AVK^(_A(
$2@A!/5$7B=70!!/.3N!.$31Y."%72/.:"3$/%(yy(!/5$7B=:$#!ZA((
((IH
((?G".$"+51(
%":1@A!5"81.=2.":1M$:1%7$/%7A(
G"501@AT^(_A(
0%5177@A!/5$7B=70!!/.3N!.$31Y."%72/.:"3$/%(yy(!/5$7B=:$#!ZA((
((IH
((?G".$"+51(
%":1@A!5"81.=2.":1M$:1%7$/%7A(
G"501@AT^(TA(
$2@A!/5$7B=$#1%3$2$1.(@@(J/-$"IWZVKA((
((IH
?IG".$"+517H
In the above example the frame-dimensions are set to 10x8 for devices which support either the
MIDP/2.0 or the sprite transformation. The dimension 6x8 are used for all other devices. For the
Nokia/7210 phone the special value of 6x6 is used.
In the source-code a default-value should always be used for cases in which the variables are not set:
//#if player.frameDimensions:defined
//#= this.sprite = new Sprite( spriteImage, ${player.frameDimensions} );
//#else
this.sprite = new Sprite( spriteImage, 10, 8 );
//#endif
By using this approach the resources can later be changed without needing to change the source-
155
The MIDP/2.0-Compatible Game-Engine
code.
Using Preprocessing for Device Specific Adjustments
You can use J2ME Polish's preprocessing capabilities for further adjustments of the game. A typical
situation is that the MMAPI is used for sound playback. Not all MIDP/1.0 phones do support this
API however. In these cases the MMAPI code needs to be hidden from such devices:
//#if polish.midp2 || polish.api.mmapi
// ...
Player audioPlayer = Manager.createPlayer
( inputStream, Aaudio/midiA );
// ....
//#elif polish.api.nokia-ui
// ...
Sound sound = new Sound( data,
Sound.FORMAT_WAV );
// ...
//#endif
You might need to adjust the GUI as well. When you are using
J2ME Polish's advanced GUI, you can even use MIDP/2.0
features like CustomItems and ItemCommandListener on
MIDP/1.0 devices. When the J2ME Polish's GUI is not used,
however, any MIDP/2.0 GUI code needs to be hidden from the
MIDP/1.0 game:
//#if polish.midp2 || polish.usePolishGui
MyCustomItem item = new MyCustomItem();
this.form.append( item );
//#endif
Another common issue is the usage of a fullscreen-mode. The
setFullScreenMode(boolean)-method of the Canvas-class is only available on MIDP/2.0 devices.
For MIDP/1.0 devices, the fullscreen-mode can be activated by defining the preprocessing-variable
“polish.GameCanvas.useFullScreen” (see below), but the setFullScreenMode(boolean)-
method can still be used for MIDP/2.0 devices:
//#if polish.midp2
setFullScreenMode( true );
//#endif
You can use a multitude of preprocessing symbols and variables. Which of these are available
depends on the device and the current setup. Please compare J2ME Polish's device-database and the
preprocessing documentation on page 78 for further information.
156
Useful Preprocessing Symbols
! polish.supportSpriteTra
nsformation indicates that
MIDP/1.0 Sprite transformations
are supported for the current
device.
! polish.api.mmapi is defined
when the Mobile Media API is
supported by the current device.
! polish.api.nokia-ui is
defined when the Nokia UI API
is supported by the current
device.
! polish.midp1 /
polish.midp2 indicates the
current MIDP platform.
! polish.cldc1.0 /
polish.cldc1.1 indicates the
current configuration.
! polish.usePolishGui is
enabled when the GUI of J2ME
Polish is used.
Extending J2ME Polish
Extending J2ME Polish
J2ME Polish can be extended quite simply and in several ways.
Build-Tools:
! Obfuscator: integrate your own (or a third party) obfuscator
! Preprocessing: add your own preprocessing directives
! You can also use the <java>-element to extend J2ME Polish
GUI:
! Backgrounds and Borders: custom borders or backgrounds enhance the possibilities
! Items: extend and use standard CustomItems – and design them using CSS
The <java>-element is described on page 59, whereas the other extensions are discussed in this
chapter .
Integrating a Custom Obfuscator
For integrating another obfuscator, you need to first create a class which extends the
de.enough.polish.obfuscate.Obfuscator class. Secondly you need to integrate your obfuscator in the
“build.xml” file.
Preparations
Create a new project in your IDE and set the classpath so that it includes the “enough-j2mepolish-
build.jar”, which can be found in the “import” folder of the installation directory. Also include the
“ant.jar” file from your Ant-installation into the classpath.
Creating the Obfuscator Class
Create a new class which extends de.enough.polish.obfuscate.Obfuscator and implement the
“obfuscate” method:
/**
* Obfuscates a jar-file for the given device.
*
* @param device The J2ME device
* @param sourceFile The jar-file containing the projects classes
* @param targetFile The file to which the obfuscated classes should be copied to
* @param preserve All names of classes which should be preserved,
* that means not renamed or removed.
* @param bootClassPath A path to the library containing either the MIDP/1.0
* or MIDP/2.0 environment.
* @throws BuildException when the obfuscation failed
*/
public abstract void obfuscate( Device device,
File sourceFile,
File targetFile,
String[] preserve,
Path bootClassPath )
throws BuildException;
You can make use of following protected variables:
157
Extending J2ME Polish
" de.enough.polish.LibraryManager libraryManager: a manager for device-APIs
" java.io.File libDir: the path to the “import” folder
" org.apache.tools.ant.Project project: the Ant project in which the obfuscator is embedded
If you need further configuration settings, you can add them with the <parameter> construct, which
is discussed below.
To call the obfuscator, you typically need to accomplish these tasks in the “obfuscate”-method:
1. Set the classpath for the given device: You can get the device-specific APIs by calling
device.getClasspath() which returns a String array containing the locations of the device-
API-Jars. The usual behavior is to set the classpath for the obfuscator to the given bootClassPath
and the device-specific APIs.
2. Specify which classes should be spared from obfuscation: the classes specified by the preserve-
array should not be obfuscated at all. These always include the MIDlet classes and maybe some
other classes which are loaded with the Class.forName()-mechanism.
3. Start the obfuscator: set the input to the provided sourceFile and the output to the specified
targetFile. Both of these files are Jars.
When there is an exception, abort the build by throwing a org.apache.tools.ant.BuildException
explaining the details why the obfuscation was aborted.
Integrating the Obfuscator into the build.xml
You can integrate any thirdparty obfuscator with the usual <obfuscator>-element in the build.xml
file (compare page 48).
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A(
,5"77@A,/:=,/:!"%8=/+207,"31=U8E+207,"3/.A
,5"77S"3B@A==I/+207,"3/.4!./b1,3I+$%I,5"7717A
H
?-11!(,5"77@A,/:=,/:!"%8=#8%":$,=N/:1M8%":$,65"77A(IH
?-11!(,5"77@A,/:=,/:!"%8=#8%":$,=a%/3B1.M8%":$,65"77A(IH
?!".":131.(%":1@A7,.$!3Q$51A(G"501@A==I7,.$!37I/+207,"31=7,.$!3A(IH
?I/+207,"3/.H
The “class”-attribute needs to be set to the new class. The classPath-attribute can be used for
pointing out the location of the obfuscator. This is only needed when the obfuscator is not on the
Ant-classpath.
Configuring the Obfuscator with Parameters
The obfuscator can be configured using <parameter>-subelements in the build.xml. For each
<parameter> a corresponding “set[parameter-name]”-method needs to be implemented, which either
needs to have one File parameter, one boolean or one String parameter:
?!".":131.(%":1@A7,.$!3Q$51A(G"501@A==I7,.$!37I/+207,"31=7,.$!3A(IH
For the using the above parameter, the obfuscator needs to implement either the public method
setScriptFile( File file ) or the public method setScriptFile( String value ). When a
method with a File-parameter is used, relative file paths are resolved relative to the location of the
build.xml file (or to be more precise relative to the project.getBaseDir() location). The file given as
158
Extending J2ME Polish
a parameter in the set-method uses an absolute path in that case.
Creating and Using Custom Preprocessing Directives
You can easily use your own preprocessing directives by extending the
de.enough.polish.preprocess.CustomPreprocessor class and by integrating your preprocessor with
the <preprocessor>-element in the “build.xml” file.
Preparations
Create a new project in your IDE and set the classpath so that it includes the “enough-j2mepolish-
build.jar”, which can be found in the “import” folder of the installation directory. Also include the
“ant.jar” file from your Ant-installation into the classpath.
Creating the Preprocessor Class
Create a new class which extends de.enough.polish.preprocess.CustomPreprocessor.
Using the registerDirective()-Method
The easiest way to use custom directive is by registering them with the “registerDirective”-method:
/**
* Adds a directive which is searched for in the preprocessed source codes.
* Whenever the directive is found, the appropriate method
* process[directive-name] is called.
* When for example the preprocessing directive "//#hello" should be processed,
* the subclass needs to implement the method
* processHello( String line, StringList lines, String className ).
* <pre>
* registerDirective("hello");
* // is the same like
* registerDirective("//#hello");
* </pre>
*
* @param directive the preprocessing directive which should be found.
* The directive needs to contain at least 2 characters (apart from
* the beginning "//#").
* The "//#" beginning is added when not specified.
* @throws BuildException when the corresponding method could not be found.
*/
protected void registerDirective( String directive ) throws BuildException
When for example the directive “date” is registered, the public method processDate( String
line, de.enough.polish.util.StringList lines, String className ) needs to be
implemented.
You can make use of following protected variables:
" de.enough.polish.preprocess.Preprocessor preprocessor: the main preprocessor
" de.enough.polish.preprocess.BooleanEvaluator booleanEvaluator : an evaluator for complex
terms which can be used in the #if-directive.
If you need further configuration settings, you can add them with the <parameter> construct, which
is discussed below.
In the processing method the line in which the preprocessing directive was found is usually
159
Extending J2ME Polish
changed. When the line is changed, please make sure that the preprocessing-directive is be removed
from the changed line, so that the following preprocessing can continue without errors.
When there is an exception, abort the build by throwing a org.apache.tools.ant.BuildException
explaining the details why the preprocessing was aborted.
This example should illustrate the usage of the registerDirective()-method:
package com.company.preprocess;
import org.apache.tools.ant.BuildException;
import de.enough.polish.preprocess.CustomPreprocessor;
import de.enough.polish.util.StringList;
import java.util.Date;
public class MyPreprocessor extends CustomPreprocessor {
public MyPreprocessor() {
super();
registerDirective("date");
}
public void processDate( String line, StringList lines, String className ) {
int directiveStart = line.indexOf( "//#date");
String argument = line.substring( directiveStart + "//#date".length() ).trim();
int replacePos = argument.indexOf("${date}");
if (replacePos == -1) {
throw new BuildException(className + " at line "
+ (lines.getCurrentIndex() + 1)
+ ": Unable to process #date-directive: found no ${date} sequence in line ["
+ line + "." );
}
String result = argument.substring(0, replacePos )
+ ( new Date().toString() )
+ argument.substring( replacePos + "${date}".length() );
lines.setCurrent(result);
}
}
Using the processClass()-Method
For more complex situations, you can override the processClass()-method which allows you to
process the whole java-file in one go:
/**
* Processes the given class.
*
* @param lines the source code of the class
* @param className the name of the class
*/
public void processClass( StringList lines, String className ) {
while (lines.next()) {
String line = lines.getCurrent();
// now process the line...
}
}
Integrating the Preprocessor into the build.xml
You can integrate your preprocessor with the usual <preprocessor>-element in the build.xml file
(compare page 58).
?!.1!./,177/.(
160
Extending J2ME Polish
,5"77@A,/:=,/:!"%8=!.1!./,177=U8S.1!./,177/.A
,5"77S"3B@A==I!.1!./,177/.4!./b1,3I+$%I,5"7717A
H
?!".":131.(%":1@A7,.$!3Q$51A(G"501@A==I7,.$!37I!.1!./,177=7,.$!3A(IH
?I!.1!./,177/.(H
The “class”-attribute needs to be set to the new class. The classPath-attribute can be used for
pointing out the location of the preprocessor. This is only needed when the preprocessor is not on
the Ant-classpath.
Configuring the Preprocessor with Parameters
The preprocessor can be configured using <parameter>-subelements in the build.xml. For each
<parameter> a corresponding “set[parameter-name]”-method needs to be implemented, which either
needs to have one File parameter, one boolean or one String parameter:
?!".":131.(%":1@A7,.$!3Q$51A(G"501@A==I7,.$!37I/+207,"31=7,.$!3A(IH
For the using the above parameter, the preprocessor needs to implement either the public method
setScriptFile( File file ) or the public method setScriptFile( String value ). When a
method with a File-parameter is used, relative file paths are resolved relative to the location of the
build.xml file (or to be more precise relative to the project.getBaseDir() location). The file given as
a parameter in the set-method uses an absolute path in that case.
Extending the J2ME Polish GUI
Using Custom Items
You can integrate custom items to J2ME Polish by extending the
javax.microedition.lcdui.CustomItem class.
Initialisation
J2ME Polish calls the getPrefContentWidth()-method first with an open height (-1). Then the
getPrefContentHeight()-method is called with the actual granted width. When the width had to be
adjusted, the custom item will be notified again with the setSize(width. height)-method.
Please note that the Display.getColor( int ) and Font.getFont( int ) are only available on MIDP/2.0
devices. Such calls should be surrounded by #ifdef-directives:
//#ifdef polish.midp2
Font font = Font.getFont( Font.FONT_STATIC_TEXT );
//#else
//# Font font = Font.getDefaultFont();
//#endif
Interaction Modes
The J2ME Polish implementation supports the interaction modes KEY_PRESS,
TRAVERSE_HORIZONTAL and TRAVERSE_VERTICAL.
Traversal
When the custom item gains the focus for the first time, the traverse-method will be called with the
CustomItem.NONE direction. Subsequent calls will include the direction (either Canvas.UP,
161
Extending J2ME Polish
DOWN, LEFT or RIGHT).
Using CSS for Designing the CustomItem
When the CSS-styles should be used for designing the CustomItem, please make sure that the
project-classpath contains the “enough-j2mepolish-client.jar”, which can be found in the “import”
folder of the J2ME Polish installation directory.
When the J2ME Polish GUI is used, the preprocessing-symbol “polish.usePolishGui” is defined.
This can be used when the CustomItem should be used in the J2ME Polish GUI as well in a plain
MIDP/2.0 based UI:
//#ifdef polish.usePolishGui
import de.enough.polish.ui.*;
//#endif
There are several ways to integrate a CSS-style into the CustomItem:
1. Defining a static style before the super-constructor is called:
public MyItem( String label ) {
//#style myitem
super( label );
}
2. Allowing the setting of the style in a second constructor:
//#ifdef polish.usePolishGui
public MyItem( String label, Style style ) {
super( label, style );
}
//#endif
3. Specifying the name of the dynamic style:
//#ifdef polish.useDynamicStyles
protected String createCssSelector() {
return "myitem";
}
//#endif
The second variant is the most flexible one and is encouraged, therefore. When the item MyItem is
now used within the code, the appropriate style can specified with the #style directive:
//#style coolStyle
MyItem coolItem = new MyItem( label );
For reading the specific style settings, the method setStyle( Style ) needs to be overridden:
//#ifdef polish.usePolishGui
public void setStyle( Style style ) {
//#if true
// the super-call needs to be hidden:
//# super.setStyle( style );
//#endif
this.font = style.font;
this.fontColor = style.fontColor;
// now read specific attributes:
//#ifdef polish.css.myitem-color
Integer colorInt = style.getIntProperty( "myitem-color" );
if (colorInt != null) {
162
Extending J2ME Polish
this.color = colorInt.intValue();
} else {
this.color = 0xFF0000;
}
//#else
this.color = 0xFF0000;
//#endif
}
//#endif
The setStyle()-method will be called before the preferred content width and height is requested,
when the CustomItem has a style associated with it.
Please note that the variable needs to be called “style” or needs to end with “style”, so that J2ME
Polish can process all styles correctly. This is required, since instead of String-based attribute-names
numerical short-values will be used in the actual code. This approach significantly reduces the
runtime-performance and minimizes the heap-usage.
There are 3 different ways to retrieve a property from a style:
! style.getProperty( String name ) returns either a String representing that value or null
when the property is not defined.
! style.getIntProperty( String name ) returns either an Integer representing that value or
null when the property is not defined. You can use this method only when you have registered
the corresponding attribute in the file custom-css-attributes.xml. The attribute-type needs to
be either “integer” or “color”.
! style.getBooleanProperty( String name ) returns either a Boolean representing that value
or null when the property is not defined. You can use this method only when you have registered
the corresponding attribute in the file custom-css-attributes.xml. The attribute-type needs to
be “boolean”.
Registering Custom CSS Attributes
You will find the custom-css-attributes.xml file in the installation directory of J2ME Polish. This
file can be used to register CSS attributes which are used in your CustomItems.
The registration of these attributes is only required when either the style.getIntProperty(
String name )- or the style.getIntProperty( String name )-method is used in the
setStyle( Style )-method of the CustomItem. The registration is encouraged nevertheless, since
future-versions of J2ME Polish might use this information for an embedded CSS editor.
Each attribute is represented by an <attribute>-element with following attributes:
Attribute Required Explanation
name Yes The name of the attribute, e.g. “icon-image”.
description No A description of this attribute.
type No The type of the attribute. Either “string”, “integer”, “color”,
“boolean” or “style”. Defaults to “string”. When the
getIntProperty()-method is used, the type needs to be either
163
Extending J2ME Polish
Attribute Required Explanation
“integer” or “color”. When the getBooleanProperty()-method is
used, the type needs to be “boolean”.
appliesTo No A comma-separated list of class-names for which this attribute
can be applied.
default No The default-value of this item.
values No A comma-separated list of allowed values for this attribute.
The following example defines a simple attribute:
?"33.$+031
%":1@A2/,071#473851A
38!1@A73851A
"!!5$17Y/@AN,.11%^(Q/.:^(D$73^(6B/$,1`./0!A
#17,.$!3$/%@AYB1(%":1(/2(3B1(73851(2/.(3B1(,0..1%358(2/,071#($31:=A
#12"053@A2/,071#A
IH
Backgrounds and Borders
Background and border settings will be enforced by J2ME Polish, the CustomItem merely needs to
paint its contents. It is advisable, therefore, that a background is only painted, when the J2ME
Polish-GUI is not used:
//#ifndef polish.usePolishGui
// draw default background:
g.setColor( this.backgroundColor );
g.fillRect( 0, 0, this.width, this.height );
//#endif
Adding a Custom Background
For adding a new background, please create a new project called “background-project” and make
sure that the files “enough-j2mepolish-build.jar”, “enough-j2mepolish-client.jar” and the
“midp2.jar” are on the classpath of the project. These files can be found in the “import” folder of
the J2ME Polish installation directory.
Each background needs two implementation classes: one class for the client-side which is
responsible for the actual painting and another one for the server-side which is responsible for
creating the client-background-class and reading the parameters from the CSS definitions.
As an example we create and integrate an animated background, which paints a “pulsating” circle.
Please note that this background is now directly available in J2ME Polish from version 1.0 onwards.
Creating the Client-Side Background-Class
For using a new background, just create a new class which extends the
de.enough.polish.ui.Background class.
We are starting with a simple background, which paints a filled out circle. For the constructor we
164
Extending J2ME Polish
only need one parameter – the desired color of the circle:
//#condition polish.usePolishGui
package com.company.backgrounds;
import javax.microedition.lcdui.Graphics;
import de.enough.polish.ui.Background;
public class PulsatingCircleBackground extends Background {
private final int color;
public PulsatingCircleBackground( int color ) {
super();
this.color = color;
}
public void paint(int x, int y, int width, int height, Graphics g) {
g.setColor( this.color );
g.fillArc( x, y, width, height, 0, 360 );
}
}
The paint method is used to render the background and needs to be implemented by all subclasses
of Background. The #condition-directive at the top ensures that the PulsatingCircleBackground is
included only when the GUI of J2ME Polish is actually used.
This background is useful, but a bit boring, so we add an animation to it: the background-diameter
should grow and shrink constantly. For doing this we need to override the animate()-method, which
is used to implement animations. When this method returns “true”, a repaint will be triggered
resulting in a call of the paint()-method. With returning false the background indicates that no
repaint is necessary.
public class PulsatingCircleBackground extends Background {
private final int color;
private final int maxDiameter;
private final int minDiameter;
private int currentDiameter;
private boolean isGrowing = true;
public PulsatingCircleBackground( int color, int minDiameter, int maxDiameter ) {
super();
this.color = color;
this.minDiameter = minDiameter;
this.maxDiameter = maxDiameter;
this.currentDiameter = minDiameter;
}
public void paint(int x, int y, int width, int height, Graphics g) {
g.setColor( this.color );
int centerX = x + width / 2;
int centerY = y + height / 2;
int offset = this.currentDiameter / 2;
x = centerX - offset;
y = centerY - offset;
g.fillArc( x, y, this.currentDiameter, this.currentDiameter, 0, 360 );
}
public boolean animate() {
165
Extending J2ME Polish
if (this.isGrowing) {
this.currentDiameter++;
if (this.currentDiameter == this.maxDiameter) {
this.isGrowing = false;
}
} else {
this.currentDiameter--;
if (this.currentDiameter == this.minDiameter) {
this.isGrowing = true;
}
}
return true;
}
}
The implementation uses the field “currentDiameter”, which is either decreased or increased in each
run of the animate()-method. The constructor now has two additional parameters: the minimum
diameter and the maximum diameter for the circle.
Creating the Server-Side Background-Class
For converting CSS-style information into the appropriate background object, we need to implement
a converter class which extends de.enough.polish.preprocess.BackgroundConverter.
This class reads the provided CSS information and creates the source-code for creating a new
instance:
//#condition false
package com.company.backgrounds;
import java.util.HashMap;
import org.apache.tools.ant.BuildException;
import de.enough.polish.preprocess.BackgroundConverter;
import de.enough.polish.preprocess.Style;
import de.enough.polish.preprocess.StyleSheet;
public class PulsatingCircleBackgroundConverter extends BackgroundConverter {
public PulsatingCircleBackgroundConverter() {
super();
}
protected String createNewStatement(
HashMap background,
Style style,
StyleSheet styleSheet )
throws BuildException {
String minDiameterStr = (String) background.get( "min-diameter");
if (minDiameterStr == null) {
throw new BuildException("Invalid CSS: the pulsating-circle
background needs the attribute [min-diameter].");
}
String maxDiameterStr = (String) background.get( "max-diameter");
if (maxDiameterStr == null) {
throw new BuildException("Invalid CSS: the pulsating-circle
background needs the attribute [max-diameter].");
}
// now check if these diameters have valid values:
int minDiameter = parseInt("min-diameter", minDiameterStr);
int maxDiameter = parseInt("max-diameter", maxDiameterStr);
if (maxDiameter <= minDiameter ) {
166
Extending J2ME Polish
throw new BuildException("Invalid CSS: the [min-diameter] attribute
of the pulsating-circle background needs to be smaller than the [max-diameter].");
}
if (minDiameter < 0 ) {
throw new BuildException("Invalid CSS: the [min-diameter] attribute
of the pulsating-circle background needs to be greater or equals 0.");
}
// okay, the min- and max-diameter parameters are okay:
return "new com.company.backgrounds.PulsatingCircleBackground( "
+ this.color + ", " + minDiameterStr + ", " + maxDiameterStr + ")";
}
}

In the method “createNewStatement” we read the provided values from the HashMap. To parse
these values we can the helper-method parseInt( String attributeName, String
attributeValue ), parseFloat( String attributeName, String attributeValue ),
parseColor( String colorValue ) and getUrl( String url ).
In our example we want to use the attribute “color”, “min-diameter” and “max-diameter”. The color
value is parsed by the super-class already and can be accessed with “this.color”. In case no color
has been defined, the background color defaults to white. When a required value is missing or a
value is set wrong, we throw a BuildException explaining the details of what went wrong. When
everything is okay, we return a String in which a new instance of our background is created.
We included the #condition “false”, so that this file is never included in the J2ME application. This
is useful when the same source folder is used for the client-background-class as well as the server-
background-class.
Integrating the Custom Background
To use our background, we need to ensure that the classes can be found and to use it in the
polish.css file:
At first we make sure, that the classpath includes our background-project. The easiest way is to do
this in the definition of the J2ME Polish task within the build.xml:
?3"7-#12(
%":1@AbZ:1!/5$7BA(
,5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A(
,5"77!"3B@A$:!/.3I1%/0&B4bZ:1!/5$7B4+0$5#=b".'$:!/.3Ib#/:=b".'(
$:!/.3I!./&0".#=b".'==I+",-&./0%#4!./b1,3I+$%I,5"7717A
IH
Secondly we need to inform J2ME Polish about the additional source-folder.We do this by
specifying the “srcDir”-attribute of the <build>-element in the build.xml. Several directories can be
specified by separating them with colons:
?bZ:1!/5$7BH
((((<===>
?+0$5#
78:+/57@AFL":!51N8:+/5^(a%/3B1.FL":!51A
$:"&1D/"#N3."31&8@A+",-&./0%#A
20557,.11%@A:1%0A
071S/5$7B`0$@A3.01A
7.,M$.@A7/0.,1I7.,'==I+",-&./0%#4!./b1,3I7/0.,1I7.,A
H
((((<===>
167
Extending J2ME Polish
?I+0$5#H
?IbZ:1!/5$7BH
Thirdly and lastly we need to use the new background in the “resources/polish.css” file of our
application. As the type we need to define the SERVER-side converting class:
focused {
padding: 5;
background {
type: com.company.backgrounds.PulsatingCircleBackgroundConverter;
color: white;
min-diameter: 20;
max-diameter: 70;
}
font {
style: bold;
color: fontColor;
size: small;
}
layout: expand | center;
}
Now we can build the application by
calling Ant to check the result:
Adding a Custom Border
Adding a custom border requires the same steps as for creating a custom background. Instead of
extending the Background class, we need to extend the de.enough.polish.ui.Border class. For the
server-side the de.enough.polish.preprocess.BorderConverter needs to be extended.
Please note that borders currently do not support the animate()-method, so if you want to use
animated borders, you need to implement them with a Background class.
For this example we create a project called “border-project” and add the files “enough-j2mepolish-
build.jar”, “enough-j2mepolish-client.jar” and the “midp2.jar” to the classpath of the project. These
files can be found in the “import” folder of the J2ME Polish installation directory. Please note that
this border is now directly available in J2ME Polish from version 1.0 onwards.
Creating the Client-Side Border-Class
We create a border which should draw a round border around items. The color, width and stroke-
style of the border should be customizable:
//#condition polish.usePolishGui
package com.company.borders;
168
Extending J2ME Polish
import javax.microedition.lcdui.Graphics;
import de.enough.polish.ui.Border;
public class CircleBorder extends Border {
private final int strokeStyle;
private final int color;
private final int borderWidth;
public CircleBorder( int color, int width, int strokeStyle ) {
super();
this.color = color;
this.borderWidth = width;
this.strokeStyle = strokeStyle;
}
public void paint(int x, int y, int width, int height, Graphics g) {
g.setColor( this.color );
boolean setStrokeStyle = (this.strokeStyle != Graphics.SOLID );
if (setStrokeStyle) {
g.setStrokeStyle( this.strokeStyle );
}
g.drawArc( x, y, width, height, 0, 360 );
if (this.borderWidth > 1) {
int bw = this.borderWidth;
while (bw > 0) {
g.drawArc( x + bw, y + bw, width - 2*bw, height - 2*bw, 0, 360
);
bw--;
}
}
if (setStrokeStyle) {
g.setStrokeStyle( Graphics.SOLID );
}
}
}
The #condition-directive ensures that this class is only used when the GUI of J2ME Polish is
actually used. In the paint()-method the border is rendered to the screen. When a different stroke-
style than Graphics.SOLID is used, we set that style and reset the style in the end of the paint()-
method. This is a J2ME Polish specific convention, since the Graphics.DOTTED stroke style is
hardly ever used.
Creating the Server-Side Border-Class
The server side border class reads the CSS-attributes from the polish.css file and creates the code
for initializing a new border. The class needs to extend the
de.enough.polish.preprocess.BorderConverter class:
//#condition false
package com.company.borders;
import java.util.HashMap;
import org.apache.tools.ant.BuildException;
import de.enough.polish.preprocess.BorderConverter;
import de.enough.polish.preprocess.Style;
import de.enough.polish.preprocess.StyleSheet;
169
Extending J2ME Polish
public class CircleBorderConverter extends BorderConverter {
public CircleBorderConverter() {
super();
}
protected String createNewStatement(
HashMap border,
Style style,
StyleSheet styleSheet )
throws BuildException
{
String strokeStyle = (String) border.get("stroke-style");
String strokeStyleCode;
if (strokeStyle != null) {
if ("dotted".equals(strokeStyle)) {
strokeStyleCode = "javax.microedition.lcdui.Graphics.DOTTED";
} else {
strokeStyleCode = "javax.microedition.lcdui.Graphics.SOLID";
}
} else {
strokeStyleCode = "javax.microedition.lcdui.Graphics.SOLID";
}
return "new de.enough.polish.extensions.CircleBorder( "
+ this.color + ", " + this.width + ", " + strokeStyleCode + ")";
}
}
The BorderConverter already parses the color and width of the border. The color defaults to black
and the width defaults to 1. So we only need to parse the desired stroke-style. Unless “dotted” is
defined, we assume that the Graphics.SOLID stroke-style should be used.
There are some helper methods for parsing the CSS-attributes: parseInt( String
attributeName, String attributeValue ), parseFloat( String attributeName, String
attributeValue ), parseColor( String colorValue ) and getUrl( String url ).
We included the #condition “false”, so that this file is never included in the J2ME application. This
is useful when the same source folder is used for the client-background-class as well as the server-
background-class.
Integrating the Custom Border
To use our background, we need to ensure that the classes can be found and to use it in the
polish.css file:
At first we make sure, that the classpath includes our border-project. The easiest way is to do this in
the definition of the J2ME Polish task within the build.xml:
?3"7-#12(
%":1@AbZ:1!/5$7BA(
,5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A(
,5"77!"3B@A$:!/.3I1%/0&B4bZ:1!/5$7B4+0$5#=b".'$:!/.3Ib#/:=b".'(
$:!/.3I!./&0".#=b".'==I+/.#1.4!./b1,3I+$%I,5"7717A
IH
Secondly we need to inform J2ME Polish about the additional source-folder.We do this by
specifying the “srcDir”-attribute of the <build>-element in the build.xml. Several directories can be
specified by separating them with colons:
170
Extending J2ME Polish
?bZ:1!/5$7BH
((((<===>
?+0$5#
78:+/57@AFL":!51N8:+/5^(a%/3B1.FL":!51A
$:"&1D/"#N3."31&8@A+",-&./0%#A
20557,.11%@A:1%0A
071S/5$7B`0$@A3.01A
7.,M$.@A7/0.,1I7.,'==I+/.#1.4!./b1,3I7/0.,1I7.,A
H
((((<===>
?I+0$5#H
?IbZ:1!/5$7BH
Thirdly and lastly we need to use the new background in the “resources/polish.css” file of our
application. As the type we need to define the SERVER-side converting class:
focused {
padding: 5;
background: none;
border {
type:
com.company.borders.CircleBackgroundConverter;
width: 2;
color: fontColor;
stroke-style: dotted;
}
font {
style: bold;
color: fontColor;
size: small;
}
layout: expand | center;
}
Now we can build the application by calling Ant to check the result:
Contributing Your Extensions
Please consider to contribute your extensions to the J2ME Polish project. In an open source world,
everyone can participate from the work of others.
Do note, however, that J2ME Polish is used commercially as well. Please get in touch with
j2mepolish@enough.de to discuss your contribution.
We need the code and a complete documentation of your extension. Preferably the extension is
documented in English, but German is also accepted. It is recommended to use the JavaDoc-
conventions within the code for the basic documentation. The J2ME Polish project adheres to the
normal Java style conventions. For distinguishing local from instance variables, please use the
“this” operator for accessing instance variables. This behavior can be enforced in Eclipse by setting
the compiler-option “unqualified access to instance variables”.
171
Standalone Tools
Standalone Tools
J2ME Polish includes standalone tools for
specialized tasks in the
${polish.home}/bin folder.
The Binary Data Editor
Use the binary-editor for creating and
modifying binary data like level data files. It
can also generate the Java/J2ME code for
loading that data for you.
Please load the specification-file
“level.definition” and the data-file
“level1.data” from the “bin”-folder for
getting a working example setup like shown in the following figure.
With the BinaryEditor you can easily adjust any kind of structured binary files like
for example level data. The structure of the data is kept outside of the data-files
themselves and has the extension “.definition”. You can load definition-files with
the “Open Definition” command or dragging and dropping the file on either the
start-script or the editor like shown in following figure.
In each definition you will have several entries which can have arbitrary names like
172
Fig. 8: The binary editor in action.
Fig. 7: The ${polish.home}/bin folder on Mac OS X.
Standalone Tools
“playerX”, “playerY” and so on. You can also define the type of each data-entry. There are
predefined types available, but you can also combine your own types out of the basic types using
“Edit -> Add Custom Type”.
Type Values Explanation
byte -128..+128 Standard Java byte value.
unsigned
byte
0..255 Positive 8 bit value.
short -32,768..+32,767 Standard Java short value (uses 2 bytes).
unsigned
short
0..2
16
-1 (65,535) Positive 16 bit value.
int -2
31
..2
31
-1 Standard Java int value (uses 4 bytes).
long -2
63
..2
63
-1 Standard Java long value (uses 8 bytes).
boolean true, false One byte representing true (1) or false (0).
ASCII-
String
Text A string consisting of ASCII characters with a max-length of 255
characters. The ASCII-String uses length + 1 bytes in the data
file.
UTF-String Text Standard Java String.
PNG-Image Image A PNG image. Such images should usually be the last entry in a
definition file, unless you generate your own code for loading the
images.
Each data entry also has a “count” value, which determines how often the entry is repeated. You can
insert “static” numbers here, but you can also be a bit more flexible by using a calculation. In the
calculation you can use any entry which is listed before the affected entry. So far you can only use
simple terms using one operation on a number of entries. In this way you can for example define
first a number of columns and a number of rows and then use “columns * rows” for calculating the
number of cells of a table structure. Just click into the respective “count” field to start the editor for
changing the count-value of the entry.
The BinaryEditor can also generate the J2ME code for loading data files with the current definition
– just select “Code -> Generate Code”.
The Font Editor
The font editor is used to generate bitmap (*.bmf) fonts out of any True Type (*.ttf) fonts. Such
bitmap fonts can be used by the J2ME Polish GUI with the font-bitmap CSS-attribute or directly
with the de.enough.polish.util.BitMapFont utiliy class.
173
Standalone Tools
Since the font-editor does no yet optimize the generated font-images, you might want to optimize
the images outside of the editor: Just select “File -> Save PNG-Image As...” and edit the image in
your favorite image editing program, e.g. The Gimp. You might also want to use PNG-image
optimizer like PNG-Crush (http://pmt.sourceforge.net/pngcrush/) or PNG-Out
(http://advsys.net/ken/utils.htm#pngout). When you're done, just reload the PNG-image by selecting
“File -> Open PNG-Image”.
You can also fine-tune every aspect of the bitmap-font by opening it in the BinaryEditor: select
“File -> Open in Binary Editor” to do so.
174
Fig. 9: The font editor in action.
Non-MIDP Platforms
Non-MIDP Platforms
J2ME Polish can be adjusted to support several platforms that support more than the normal MIDP
profile. The key for this support is the ${polish.home}/platforms.xml file, inclusion of platform
specific (boot) classpaths, and the automatic invocation of preprocessors, postcompilers, finalizers
and so on.
BlackBerry and Palm platforms are supported out of the box.
Developing for BlackBerry Devices
The BlackBerry platform of Research in Motion is quite popular for business applications. Normal
MIDlets as well as BlackBerry specific applications can be developed with J2ME Polish.
Preparations
For transforming and signing the JAR files to the BlackBerry proprietary COD format, the
BlackBerry Java Development Environment (JDE) needs to be installed. The JDE can be
downloaded from http://www.blackberry.com/developers. On Unix systems it can be installed using
Wine.
In your build.xml script you then need to define the blackberry.home property which points to the
installation folder of the JDE:
<property
name="blackberry.home"
location="C:/Program Files/Research In Motion/BlackBerry JDE 4.0.2"
/>
Converting JARs into CODs
When you target BlackBerry devices like the BlackBerry/7100t device and have set the
blackberry.home property, J2ME Polish will automatically invoke the rapc compiler for
converting the JAR file into a COD file in the finalize step of the build process.
Remember that resources should be less than 64 kb in size, otherwise the rapc process will abort the
processing. You can use the “jar” packager for compressing the resources a bit better than the
internal J2ME Polish jar mechanism: <packager name="jar" />.
Signing COD Files
J2ME Polish can also automate the requesting of signatures during the build process. Signatures are
required for accessing some Blackberry specific security sensitive APIs and require a certificate. In
order to get a certificate, you need to register with BlackBerry first. In your Ant build.xml script you
then need to define the “blackberry.certificate.dir” property:
<property name="blackberry.certificate.dir" location="resources/certificates"/>
In case the sigtool.csk and sigtool.db files are not included in the same location like the certificates,
you also need to define the “blackberry.sigtool.dir” property:
<property name="blackberry.sigtool.dir" location="resources/sigtool"/>
175
Non-MIDP Platforms
When you specify the password as well, J2ME Polish uses this for requesting the signatures without
manual intervention. For such cases the password needs to contain only ASCII characters, otherwise
J2ME Polish can't include the password automatically.
<property name="blackberry.certificate.password" value="secret"/>
Using the J2ME Polish GUI on BlackBerry Devices
The J2ME Polish GUI can be used normally on BlackBerry devices as well. In order to make most
of the System, J2ME Polish converts your MIDlet into a native BlackBerry UiApplication. This
allows J2ME Polish to process trackwheel events and so on correctly. Also native InputFields are
used for the text input.
The successful conversion requires that your MIDlet uses a public constructor.
Developing Native BlackBerry Applications
You can also develop native BlackBerry applications by defining the blackberry.main variable
that contains the name of the class that extends net.rim.device.api.system.Application.
<variable name="blackberry.main" value="com.company.product.ProductApplication"
/>
Please note that the currently provided BlackBerry library does not contain all available classes,
compare the following Troubleshooting section.
Troubleshooting
Deactivate Obfuscation
You should deactivate obfuscation for BlackBerry devices, since the rapc compiler already removes
any unneeded fields, classes etc. Also you can get verification errors on the BlackBerry devices
when you enable the obfuscation. You can skip the obfuscation for test builds as well as for
BlackBerry devices with this definition:
<obfuscator name="ProGuard" unless="test || polish.blackberry" />
Library
J2ME Polish includes the ${polish.home}/import/blackberry-4.0.jar library which contains the most
important packages that are additionally available on BlackBerry devices. If you use BlackBerry
specific classes in your application you might encounter compiler problems, because currently not
all available classes are included in the default library. In such cases you can copy the JAR provided
by the JDE from ${blackberry.home}/lib/net_rim_api.jar to ${polish.home}/import/blackberry-
4.0.jar. Since this file contains unresolved class dependencies you need to use a JDK 1.4.x and must
not use a 1.5 JDK.
176
Non-MIDP Platforms
Developing for Palm Devices
Palm handhelds also support J2ME applications when the IBM WebSphere Everyplace Micro
Environment (WEME) has been installed. MIDP applications can be installed normally over the air
(OTA) as any other application. If you want to install applications directly via the USB connection
or if you want to use the complete screen size, the JAR file has to be converted into the proprietary
PRC format.
Preparations
The Palm converter and simulator can be downloaded from http://www.palmos.com/dev/tech/java.
When you extract the WEME tools you will find additional libraries in the Tools/lib folder. You
need to adjust the CLASSPATH environment variable of your system to include those libraries or
you need to copy them to ${java.home}/lib.
In your build.xml script you then need to define the palm.weme.home property that points to the
folder into which you have extracted the WEME tools:
<property
name="palm.weme.home"
location="C:/Program Files/Palm/WEME57"
/>
Converting JARs into PRCs
J2ME Polish automatically converts JAR files into the Palm PRC format when you target Palm
devices. You can fine tune the conversion process by adding following Ant properties or J2ME
Polish variables to the build.xml script:
Name Default Explanation
palm.vendorId A 4 character long vendor ID. When no ID is defined, an ID will
be created automatically.
palm.smallIcon URL of the file that contains a small application icon.
palm.largeIcon URL of the file that contains a large application icon.
palm.splash URL of the file that contains a splash image.
palm.enableHighRes true Enable the high resolution mode, so that your application can
use the complete available screen.
palm.enableDebug false Enables the debug mode of the Palm. In this mode all
System.out.println() message are stored on the memory card.
palm.enableInstall false Automatically installs the generated PRC file on the connected
Palm handheld.
The following example adds a splash image to the application and defines a vendor ID:
<variable name="palm.largeIcon" value="resources/native/splash.jpg" />
<variable name="palm.vendorId" value="ENSW" />
177
Non-MIDP Platforms
When you target only a generic device like the Generic/multi one, you can invoke the converter by
adding the jar2prc finalizer to the <build> section of your build.xml script:
<finalizer name="jar2prc" />
Starting the Palm Simulator
As with many other vendors you can start the Palm simulator by using the <emulator> section. You
need to define the Ant property palm.simulator.home that points to the folder that contains the
PalmSim.exe executable:
<property
name="palm.simulator.home"
location="C:/Program Files/Palm/Simulator"
/>
Developing DoJa Applications with J2ME Polish
DoJa is the Japanese J2ME standard created by NTT DoCoMo that also uses CLDC as its
foundation. This standard provides similar capabilities as the MIDP platform. J2ME Polish includes
a DoJa sample application in ${polish.home}/samples/doja.
Preparations
You can download DoJa emulators from the DoJa Developer Network at http://www.doja-
developer.net. There are currently two versions of DoJa for the international market: 1.5 and 2.5.
J2ME Polish already includes libraries for both versions. In Japan DoJa 4.0 is the current standard.
In your IDE you need to include either ${polish.home}/import/doja-1.5.jar or
${polish.home}/import/doja-2.5.jar to the classpath of your project.
J2ME Polish Setup
In your build.xml script you might need to specify the doja.home Ant property in case you have not
installed the DoJa SDK to either C:\jDKDoJa2.5 or C:\iDK.
You then need to adjust your device requirements, so that your application is build for DoJa devices.
J2ME Polish includes some virtual devices like the DoJa/os15 or DoJa/os25 ones:
<deviceRequirements>
<requirement name="Identifier" value="DoJa/os25" />
</deviceRequirements>
Last but not least you need to specify your IApplication class with the <iappli> element inside
of the <build> element:
<build>
<iappli class="tetris.Tetris" />
<obfuscator name="ProGuard" />
<!-- ... -->
</build>
You can now build your application and launch the emulator, e.g. by calling ant emulator from the
command line. J2ME Polish creates the JAR file without a Manifest and a JAM instead of a JAD
descriptor.
178
Non-MIDP Platforms
Optional JAM Attributes
Several JAM attributes are optional, so you can set them by specifying Ant properties or J2ME
Polish variables in your build.xml script. In the following example a scratchpad size of 5,120 bytes
(= 5 KB) is reserved:
<variables>
<variable name="doja.SPsize" value="5120" />
</variables>
The following table lists the available optional attributes.
Name Explanation
doja.AppParam
Any startup parameters. These can be retrieved using
com.nttdocomo.ui.IApplication.getArgs(). Multiple parameters
should be separated by a space.
doja.ConfigurationVer
The J2ME configuration version, e.g. CLDC-1.0
doja.ProfileVer
The i-mode Java Application runtime environment profile version. e.g.
DoJa-1.5oe
doja.SPsize
The size of the ScratchPad in bytes.
doja.UseNetwork
Set to http for applications which use network functionality.
doja.TargetDevice
Set to a model name if the application is targeted to a particular
model. Example setting: X430i,Y430i
Do not set this key for applications targeted to all models.
doja.LaunchAt
To launch the i-mode Java Application automatically at a specified
time, set the time here.
doja.AppTrace
When the value is set to on, any information output with
System.out.println() or System.err.println() will be
displayed after the i-Appli is terminated.
doja.DrawArea
The size of the i-mode Java Application drawing area, e.g. 120x130
doja.GetUtn
Declares that the i-mode Java Application refers to the handset
identification code and IC chip information on its SIM or UIM card.
Example setting: terminalid,userid
This information can be retrieved using the
com.nttdocomo.util.Phone.getProperty() method.
Developing DoJa Applications under Linux and Mac OS X
You can build DoJa applications without restrictions under Linux and Mac OS X with J2ME Polish.
The DoJa Emulator/SDK is only needed for starting the emulator.
The easiest way is to install the DoJa emulator under Windows and then copy the complete folder
into your Unix file system, since the installer won't work together with wine. J2ME Polish will use
179
Non-MIDP Platforms
wine then automatically for executing the emulator under Unix systems. Remember to specify the
doja.home Ant property in your build.xml script.
Developing for MIDP and DoJa at the Same Time
Since both MIDP and DoJa use the Connected Limited Device Configuration as their foundation,
you can share some code between your DoJa and your MIDP release of your application. You can
use the polish.midp and polish.doja preprocessing symbols for distinguishing between your
releases. You can exclude a source file for the DoJa release by specifying that it requires an MIDP
device, for example. Just use the appropriate #condition preprocessing directive in your Java
source file:
//#condition polish.midp
Of course you can also use these symbols in #if directives to branch within an utility class for
example:
//#if polish.midp
// store the data in a record store:
RecordStore store = RecordStore.openRecordStore( "name", true );
// ...
//#elif polish.doja
// store data in the scratch pad:
Connection con = Connector.open("scratchpad:///0; pos=0", Connector.WRITE );
// ...
//#endif
Remember that you need to do this for your import statements as well.
180
Cooking Tips and How-Tos
Cooking Tips and How-Tos
Building How-Tos
How to Use Several Source Folders
You can use several source folders by defining the “source”-attribute of the <build>-element in the
“build.xml” file. Just separate the folders with colons or semicolons:
?+0$5#
20557,.11%@A:1%0A
071S/5$7B`0$@A3.01A
7/0.,1M$.@A7/0.,1I7.,'==I1L31%7$/%7I7/0.,1I7.,A
H
In the above example the “source/src” folder of the current project and the “source/src” folder of the
“extensions” project are included. The notation is OS-independent by the way. So you can separate
different source-paths with either a colon ':' or a semicolon ';' and you can separate folders with a
slash '/' or a backslash '\'.
You can also use the nested <sources>-element for including source-directories based on conditions.
In this example the directory “source/test” is only included when the Ant-property “test” is true:
?+0$5#
20557,.11%@A:1%0A
071S/5$7B`0$@A3.01A
H
?7/0.,17H
?7/0.,1(#$.@A7/0.,1I7.,A(IH
?7/0.,1(#$.@A7/0.,1I3173A($2@A3173A(IH
?I7/0.,17H
===
How to Integrate Third Party APIs
Sometimes a third party API is needed in a project. You have to distinguish between APIs which are
available as source code, and APIs which are available in binary-only form. Another case are APIs
which are already pre-installed on specific devices. Depending on the type of the API different
actions are required for integrating the API. Please do not forget to add the library to the classpath
of your project within your IDE. This is, however, out of the scope of this how-to.
How to Integrate a Source Code Third Party API
When a third party API is available in source code, you can integrate it by modifying the
“sourceDir” attribute of the <build>-element in the “build.xml” file. Consider the case where your
normal application code is placed in the “source/src” directory and the source code of the third
party API in the “source/thirdparty” folder. You can now add the third party API by setting the
“sourcDir” attribute to “source/src:source/thirdparty”:
?+0$5#
$:"&1D/"#N3."31&8@A+",-&./0%#A
20557,.11%@A:1%0A
071S/5$7B`0$@A3.01A
.17M$.@A.17/0.,17ZA
181
Cooking Tips and How-Tos
7/0.,1M$.@A7/0.,1I7.,'7/0.,1I3B$.#!".38A
H
The notation is OS-independent by the way. So you can separate different source-paths with either a
colon ':' or a semicolon ';' and you can separate folders with a slash '/' or a backslash '\'.
How to Integrate a Binary Third Party API
When a third party API is only available in binary form, they can be integrated with the
“binaryLibraries” attribute of the <build>-element in the “build.xml” file. This attribute can point to
jar- or zip-files or to a directory containing third party libraries (either jar-files, zip-files or class-
files). Several libraries can be separated by colons ':' or semicolons ';'. When the libraries are
situated in the “import” folder, only the name of the libraries need to be given (instead of specifying
the full path).
In the following example the binary library “tinyline” is integrated. The corresponding library file
“tinylinegzip.zip” is situated in the “import” folder:
?+0$5#
$:"&1D/"#N3."31&8@A+",-&./0%#A
20557,.11%@A:1%0A
071S/5$7B`0$@A3.01A
.17M$.@A.17/0.,17ZA
+$%".8D$+.".$17@A3$%85$%1&9$!=9$!A
H
In this example all libraries which are situated in the “thirdparty” folder are integrated:
?+0$5#
$:"&1D/"#N3."31&8@A+",-&./0%#A
20557,.11%@A:1%0A
071S/5$7B`0$@A3.01A
.17M$.@A.17/0.,17ZA
+$%".8D$+.".$17@A3B$.#!".38A
H
The notation is OS-independent by the way. So you can separate different source-paths with either a
colon ':' or a semicolon ';' and you can separate folders with a slash '/' or a backslash '\'.
How to Integrate a Device API
Many devices provide additional APIs, which are pre-installed on the devices. A popular example is
Nokia's UI-API which provides additional graphic and sound functions. When a device supports a
specific API, this is noted with the “JavaPackage” capability of that device in the “devices.xml” file
(this file is visible only when you have chosen to install the “external device database” during the
installation of J2ME Polish).
Assuming that you want to use API “phonebook”, the corresponding library file “phonebook.jar” or
“phonebook.zip” just needs to be copied into the “import” folder (in the J2ME Polish installation
directory or in your project root directory). It will then be used automatically for the devices which
support the “phonebook” API.
You can modify the “apis.xml” file (this is again only visible when you have chosen to install the
“external device database”) for specifying different library-names, paths or aliases. This is described
182
Cooking Tips and How-Tos
in more detail on page 25.
How to Use Several Obfuscators Combined
You can combine several obfuscators just by adding several <obfuscator>-elements to your
“build.xml” file. Please note that combining RetroGuard and ProGuard actually results in bigger
classes than when ProGuard is used alone. Find more information about the <obfuscator>-element
on page 48. Find more information about integrating other obfuscators on page 157.
How to Minimize the Memory Footprint
There are several possibilities for minimizing the memory-footprint of J2ME Polish:
polish.skipArgumentCheck and polish.debugVerbose
Define the preprocessing-symbol "polish.skipArgumentCheck", by setting the “symbols” attribute
of the <build>-element in the “build.xml” file. When this symbol is defined, no method-arguments
will be checked by the J2ME Polish GUI. This is usually fine when the application is stable. You
should also skip the checking of arguments in the application by testing the
"polish.skipArgumentCheck"-symbol in the application code:
public void doSomething( int index ) {
//#ifndef polish.skipArgumentCheck
// check the argument only when the "polish.skipArgumentCheck" is not defined:
if (index < 0 || index > this.maxIndex ) {
//#ifdef polish.debugVerbose
throw new IllegalArgumentException("Invalid index [" + index "].");
//#else
//# throw new IllegalArgumentException();
//#endif
}
//#endif
}
The above example also uses the "polish.debugVerbose" symbol for determining if a meaningful
exception should be thrown. By giving verbose information only in cases when it is requested, some
memory can be saved, too. You can set and unset the "polish.debugVerbose" symbol by modifying
the “verbose” attribute of the <debug>-element. This is described in more detail on page 54.
Image Load Strategy
When you use the J2ME Polish GUI, select the "foreground" image loading strategy for removing
the overhead of loading images in a background thread. The “imageLoadStrategy” attribute of the
<build>-element can either be “foreground” or “background”, compare page 36.
Optimizing the "polish.css" File
When you use the J2ME Polish GUI, you should not use default-values in your
“resources/polish.css” file. Forms and Lists do not use a table layout by default, for example. In that
case you should not set the “columns”-attribute to “1”, since this is the default behavior anyhow. It
is better not to use the “columns” attribute at all in this case. More information about special
attributes can be found on page 120.
Another optimization is to define often used backgrounds, fonts and borders in the appropriate
183
Cooking Tips and How-Tos
section of the “resources/polish.css” file. In that case you can just refer to the instances:
backgrounds {
myBackground {
type: round-rect;
color: gray;
arc: 15;
border-color: black;
border-width: 2;
}
}
title {
background: myBackground;
/** skipping other attributes **/
}
focused {
background: myBackground;
/** skipping other attributes **/
}
This is described in more detail on page 111.
A third optimization is not to use dynamic styles. This requires the usage of the #style-directive in
the application code. Find more information about static and dynamic styles on page 105. More
information about the #style-directive can be found on page 86.
Find more information about the J2ME Polish GUI from page 102 onwards.
Using Optimal Resources
Use the resource assembling of J2ME Polish for using only those resources which are actually
required by the application. For example it does not make sense to add MIDI-soundfiles for devices
which do not support such files. Better put them into the “resources/midi” folder.
It is also not good to use high-color images for handsets which do not support such images. Better
create optimized versions of such images. This saves memory and has the additional bonus that you
do not need to depend on the dithering of the device, which often results into awkward graphics. So
put 4096-colors images into the “resources/BitsPerImage.12” folder and 65k-colors images into the
“resources/BitsPerImage.16+” folder.
The assembling of resources is described in more details on page 67. When you use the J2ME
Polish GUI you can also use device-optimized designs. This is described on page 103.
Use Preprocessing
With preprocessing you can make amazing adjustments to specific devices without wasting memory
and without losing the portability of an application.
Consider for example this “SplashScreen” solution, which shows a startup logo. This screen should
be derived from Nokia's FullScreenCanvas when this class is available. In a classic solution you
would need to test if Nokia's API is available and to load a Nokia-specific version of the
SplashScreen class:
public class MyMidlet extends MIDlet {
[...]
public void showSplashScreen() {
Displayable splashScreen;
184
Cooking Tips and How-Tos
try {
// check if this is a Nokia-device:
splashScreen = Class.forName(°MyNokiaSplashScreen¨).newInstance();
} catch (Exception e) {
// no Nokia API is available, load the classic splash screen:
splashScreen = new MySplashScreen();
}
this.display.set( screen );
}
}
public class MySplashScreen extends Canvas {
public void paint( Graphics g) {
[...]
}
}
public class MyNokiaSplashScreen extends com.nokia.mid.ui.FullCanvas {
public void paint( Graphics g) {
[...]
}
}
With the preprocessing capabilities and the integrated device database of J2ME Polish there is an
easier and much more memory efficient solution available:
public class MySplashScreen
//#if polish.api.nokia-ui
extends com.nokia.mid.ui.FullCanvas
//#else
//# extends Canvas
//#endif
{
public void paint( Graphics g) {
[...]
}
}
Another example is the playback of sound. In a classical environment you would need to check the
supported formats at runtime and then decide which one should be used. Using preprocessing and
the device database this is much easier and no checks during the runtime are necessary:
public void playMusic() {
Player player;
//#if polish.audio.mpeg
player = Manager.createPlayer( Class.getResourceAsStream(°title.mp3¨),
°audio/mpeg¨ );
player.start();
//#elif polish.audio.amr
player = Manager.createPlayer( Class.getResourceAsStream(°title.amr¨),
°audio/amr¨ );
player.start();
//#elif polish.audio.wav
player = Manager.createPlayer( Class.getResourceAsStream(°title.wav¨),
°audio/wav¨ );
player.start();
//#elif polish.audio.midi
player = Manager.createPlayer( Class.getResourceAsStream(°title.midi¨),
°audio/midi¨ );
player.start();
//#else
//# return;
185
Cooking Tips and How-Tos
//#endif
}
With the help of preprocessing you can shift the runtime checks to the compile phase.
Remove Debug Code
When the application should be shipped any debug code should be removed from the project. The
easiest way is to use the #debug and #mdebug preprocessing directives. The debugging can then be
controlled with the <debug>-element in the “build.xml” file. This is described in more detail in the
introduction to J2ME Polish on page 14.
General Optimization Tips
Some other useful tips for minimizing the memory footprint of an application are also available:
Do not use pure Object Orientated Programming. OOP is great, but it has some drawbacks, notably
the runtime and memory implications. Try to minimize the usage of classes and interfaces. Try to
use preprocessing whenever it makes sense. Check if you really need methods for accessing
variables. Sometimes it is better is better to declare them protected or even public and to access
them directly.
If you have text which is displayed only seldom, consider to move them into a properties file.
How to Sign MIDlets with J2ME Polish
Signing MIDlets can be automated using the <java>-subelement of the <build>-element.
Keys can be generated using the Java-keytool, e.g.:
> keytool -genkey -alias SignMIDlet -keystore midlets.ks -keyalg RSA
For testing purposes no certificate needs to be purchased and imported. Such MIDlets cannot be
installed on real devices, however.
When an appropriate certificate was purchased and imported into the keystore named “midlets.ks”
with the key “SignMIDlet”, the following two <java>-elements need to be added to the <build>-
element:
<java jar="${wtk.home}/bin/JadTool.jar"
fork="true"
failonerror="true"
if="polish.midp2"
unless="test"
message="Adding signature for device ${polish.identifier}"
>
<arg line="-addjarsig"/>
<arg line="-keypass ${password}"/>
<arg line="-alias SignMIDlet"/>
<arg line="-keystore midlets.ks"/>
<arg line="-inputjad dist/${polish.jadName}"/>
<arg line="-outputjad dist/${polish.jadName}"/>
<arg line="-jarfile dist/${polish.jarName}"/>
</java>
<java jar="${wtk.home}/bin/JadTool.jar"
fork="true"
failonerror="true"
186
Cooking Tips and How-Tos
if="polish.midp2"
unless="test"
message="Adding certificate for device ${polish.identifier}"
>
<arg line="-addcert"/>
<arg line="-alias SignMIDlet"/>
<arg line="-keystore midlets.ks"/>
<arg line="-inputjad dist/${polish.jadName}"/>
<arg line="-outputjad dist/${polish.jadName}"/>
?Ib"G"H
In the above example the signing is skipped when the test-mode is active or when the current device
does not support the MIDP/2.0 standard. It is assumed that the “midlets.ks” keystore is situated in
the same directory as the “build.xml” file.
Please note that the password needs to be specified as a property. This can be done within the
“build.xml” file or alternatively (for the more security conscious folks) on the command-line with
the -Dpassword=[value] option:
> ant -Dpassword=secret
In Mac OS X Wireless Toolkit the “JadTool.jar” is not available. It can be installed together with
J2ME Polish. In that case the path to the JadTool needs to be changed to
“${polish.home}/bin/JadTool.jar” in the above example.
GUI How-Tos
How to Use Tables
A table can be used for any any Form, List or ChoiceGroup. The table is activated by setting the
“columns” attribute and optionally the “columns-width” attribute in the “resources/polish.css” file:
form {
padding: 5;
background-color: yellow;
columns: 2;
columns-width: 40, 100;
}
In the above example the dynamic style “form” is used for designing all Form screens. Form
elements will be added from left to right and from top to bottom of the table. The left column will
be 40 pixels wide, whereas the right column will use 100 pixels.
Find more information in the chapter “Specific Design Attributes” on page 120.
How to Apply the J2ME Polish GUI for Existing Applications
If an existing application should be “polished up” you should insert #style preprocessing directives
within the application to allow a fine grained design.
//#style mainScreen
List mainScreen = new List( "Main Menu", List.IMPLICIT );
//#style mainScreenItem
mainScreen.append( "Start Game", null );
187
Cooking Tips and How-Tos
You then need to use static styles in the “polish.css” file. Static styles can have almost any
alphanumerical name and need to start with a dot:
.mainScreen {
padding: 5;
background-color: yellow;
columns: 2;
columns-width: 40, 100;
}
In the last step you should refine your designs by adjusting them for different handsets. If you want
to make adjustments for the Sony-Ericsson P900 for example, you need to create the file
“resources/Sony-Ericsson/P900/polish.css”. In this file you can change any settings which you have
done in the basic “resources/polish.css” file. Remember that you only need to specify attributes
which are different, this makes subsequent changes easier.
Find more information on designing for specific devices on page 103.
How to Apply Different Designs to One Application
You can alter the appearance of an application easily by using different resources like images, sound
files and design-definitions. You can use one application source code for creating several different
applications with this technique. The “dir”-attribute of the <resources>-element in the “build.xml”
file defaults to the “resources” folder, but you can change this to any other folder. Alternatively you
can also set the “resDir”-attribute of the <build>-element, when no <resources>-element is used.
Best practice is to create one Ant-<target> for each end-application in the “build.xml” file. In each
target the <j2mepolish>-task is copied and changes are made to the “dir”-attribute of the
<resources>-element and to the “workDir”-attributes of the <build>-element:
<target name="girlgame" >
<j2mepolish>
<info
jarName="${polish.vendor}-${polish.name}-girl.jar"
<===>(IH
<deviceRequirements > [...]
<build
resDir="resources/girl"
workDir="build/girl"
[...]
>
<resources
dir="resources/girl"
/>
[...]
</build>
</j2mepolish>
?I3".&13H
<target name="boygame" >
<j2mepolish>
<info
jarName="${polish.vendor}-${polish.name}-boy.jar"
<===>(IH
<deviceRequirements > [...]
<build
workDir="build/boy"
[...]
>
188
Cooking Tips and How-Tos
<resources
dir="resources/boy"
/>
[...]
<variable name="player-width" value="12" >
<variable name="player-height" value="12" >
</build>
</j2mepolish>
?I3".&13H
You can even define or alter <variables> to make further adjustments with the help of
preprocessing. You could define sprite-dimensions for example each or some of the <j2mepolish>-
tasks:
<variable name="player-width" value="12" >
<variable name="player-height" value="12" >
These variables then can be used within the application with the use of preprocessing:
//#ifdef player-width:defined
//#= int width = ${player-width};
//#else
int width = 10;
//#endif
//#ifdef player-height:defined
//#= int height = ${player-height};
//#else
int height = 10;
//#endif
Sprite player = new Sprite( playerImage, width, height );
Find more information on the <build> element on page 36. For more information about
preprocessing, please refer to page 78.
How to Change the Labels of Standard-Commands and Menu-Labels
The labels of the standard menu-commands can be changed by setting variables either in the
build.xml file or within the localization-messages.txt file.
This example changes the “Cancel” command to “Abbruch” (German for cancel):
?G".$"+517H
?G".$"+51(%":1@A!/5$7B=,/::"%#=,"%,15A(G"501@Aa++.0,BAIH
?IG".$"+517H
Please refer to the localization information on page 76 for more information.
How to Enable or Disable the Usage of the GUI for a Specific Device
J2ME Polish's GUI is deactivated by default for some older devices like the first version of Nokia
Series 40 models.
You can override this behavior by setting the “supportsPolishGui”-attribute of the device in
question in the “devices.xml” file, which is located in installation folder of J2ME Polish. When
the file is missing, re-run the installation and choose to install the “external device database” as
189
Cooking Tips and How-Tos
well.
Open devices.xml and search the device in question. Now set the “supportsPolishGui”-attribute
: It needs to be true, when the device should support J2ME Polish's GUI.
?#1G$,1
70!!/.37S/5$7B`0$@A2"571A(H
?$#1%3$2$1.HJ/-$"IN1.$17hK?I$#1%3$2$1.H
?f44("%#(7/(/%(44H
?I#1G$,1H

You can also override the settings in the device-database by setting the “usePolishGui”-attribute of
the <build>-element in the build.xml file to “always”. In that case the GUI will be used for all
devices, regardless of the settings in the device database.
Trouble Shooting
Using Subfolders for Resources
Subfolders for resources are not supported for two simple reasons:
1. They are unnecessary and waste space in the application JAR.
2. The automatic resource assembling of J2ME Polish is based on using subfolders.
Find more information about the assembling of resources on page 67.
Compile Error
If you have a compile error within the J2ME Polish package or a compile error which seems to be
erroneous, please try a clean build: remove the “build” folder or call the “ant clean” before building
again.
Preverify Error
If you have a preverify error, please try a clean build: remove the “build” folder or call the “ant
clean” before building again.
190
Appendix
Appendix
Introduction to Ant
“Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's
wrinkles.”
J2ME Polish uses Ant as its foundation for the build-process, therefore it is useful to get to know
Ant a little bit to make the most out of J2ME Polish.
The file “build.xml” is an XML based document which controls and configures Ant. The basic
syntax consists of the the <project>-root-element and several <target>-elements. Each <target>-
element is normally used to accomplish one or several specific tasks:
?!./b1,3(%":1@A1%/0&B4!/5$7B41L":!51A(H
?3".&13(%":1@A,51"%AH
?#15131(#$.@A+0$5#A(IH
?#15131(#$.@A#$73A(IH
?I3".&13H
?I!./b1,3H
In the above example we have one target called “clean” defined which uses two <delete>-tasks for –
who would have thought that – deleting two folders.
Assuming that Ant has been set up correctly (compare page 21) and that you are in the directory
containing the “build.xml” file, you can call each of the defined targets by calling “ant [target-
name]” on the command line. In the above example only one target is available, so you can only call
“ant clean”.
Usually there are several targets defined in the “build.xml” file. In that case it us useful to define a
default-target, which is executed whenever no target has been specified:
?!./b1,3(%":1@A1%/0&B4!/5$7B41L":!51A(
(((#12"053@AB155/A
H
?3".&13(%":1@AB155/AH
?1,B/(:177"&1@A[155/(d/.5#fA(IH
?I3".&13H
?3".&13(%":1@A,51"%AH
?#15131(#$.@A+0$5#A(IH
?#15131(#$.@A#$73A(IH
?I3".&13H
?I!./b1,3H
Now the “hello” target will be executed, when just “ant” is called from the command line.
Another powerful feature of Ant are properties, which are like variables with the difference that they
can only set once: after a property is set, it can not be changed anymore. This can be combined with
dependencies of targets to create complex behavior:
191
Appendix
?!./b1,3(%":1@A1%/0&B4!/5$7B41L":!51A(
(((#12"053@AB155/A
H
?3".&13(%":1@A#1!5/8AH
?!./!1.38(%":1@A#1!5/840.5A(
G"501@AB33!'IICCC=,/:!"%8=,/:I#/C%5/"#AIH
?I3".&13H
?3".&13(%":1@A$%$3AH
?!./!1.38(%":1@A#1!5/840.5A(G"501@AB33!'II5/,"5B/73AIH
?I3".&13H
?3".&13(%":1@AB155/A(#1!1%#7@A$%$3AH
?1,B/(:177"&1@AYB1(#1!5/840.5($7(ij#1!5/840.5;A(IH
?I3".&13H
?3".&13(%":1@A,51"%AH
?#15131(#$.@A+0$5#A(IH
?#15131(#$.@A#$73A(IH
?I3".&13H
?I!./b1,3H
In the above example the property “deploy-url” is defined in two targets – either in “init” or in
“deploy”. When we call “ant hello” or just “ant” the property will be “http://localhost”, because the
“hello” target depends on the execution of the “init”-target:
> ant
Buildfile: build.xml
init:
hello:
[echo] The deploy-url is http://localhost
BUILD SUCCESSFUL
Total time: 1 second
But when we call “ant deploy hello” the property will contain the value
“http://www.company.com/download” instead, since the “deploy”-target will be called first, then the
“init”-target (since the “hello”-target depends on the “init”-target) and last but not least the
“hello”-target:
> ant deploy hello
Buildfile: build.xml
deploy:
init:
hello:
[echo] The deploy-url is http://www.company.com/download
BUILD SUCCESSFUL
Total time: 1 second
How to Use Quotation-Marks in Attributes
Sometimes quotation-marks are needed within attribute-values. Such special characters needs to be
192
Appendix
specified xml-encoded, a quotation-mark is encoded with “&quot;”.
How to Specify Properties on the Command Line
You can specify Ant-properties on the command-line with the “-D[name]=[value]” option, e.g.
> ant -Dpassword=1234
Such properties can be use like any other properties within the “build.xml” script.
This closes the short introduction to Ant. We recommend either one of the many good books about
Ant or to consult the official Ant manual at http://ant.apache.org/manual/ for further
information.
193
Appendix
Licenses
J2ME Polish is licensed under the GNU General Public License (GPL) as well as several
commercial licenses.
GNU GPL
You can use the GPL license for projects, which are licensed under the GNU General Public License
without limitations.
More information about the GPL is available at these sites:
" http://www.gnu.org/licenses/gpl.html
" http://www.gnu.org/licenses/gpl-faq.html
Commercial Licenses
If the source code of your mobile applications should not be published under the GNU GPL license,
you can use one of the following commercial licenses:
! Single License
The single license can be used for the creation and distribution of one mobile application.
! Runtime License
The runtime license can be used for the creation of any number of mobile applications. The
drawback is that all applications together can be installed/sold only a 100 hundred times.
! Enterprise License
The enterprise license allows to create and sell any number of applications.
The pricing and license terms can be obtained at http://www.j2mepolish.org/licenses.html.
194
Contact
Contact
ENOUGH SOFTWARE
Robert Virkus
Vor dem Steintor 218
28203 Bremen
Germany
Telephone +49 ÷ (0)421 ÷ 98 89 131
Fax +49 ÷ (0)421 ÷ 98 89 132
Mobile +49 ÷ (0)160 ÷ 77 88 203
E-Mail j2mepolish@enough.de
Web www.enough.de
195

Table of Contents
Preamble.............................................................................................................................9 Introduction to J2ME Polish............................................................................................11 Installation......................................................................................................................11 An Example Application..................................................................................................11 Building the Application..................................................................................................11 Designing the Application with CSS...............................................................................12 Debugging and Logging.................................................................................................14 Easy Device-Optimizations with Preprocessing and the Device-Database....................15 Fun Fun Fun: The Game-Engine....................................................................................16 Extending J2ME Polish..................................................................................................17 Installation........................................................................................................................18 Requirements.................................................................................................................18 Installation of J2ME Polish.............................................................................................18 Updating J2ME Polish....................................................................................................18 Integrating J2ME Polish into Eclipse..............................................................................18 Integrating J2ME Polish into Borland's JBuilder.............................................................19 Integrating J2ME Polish into NetBeans..........................................................................20
NetBeans 3.6..........................................................................................................................20 NetBeans 4.x..........................................................................................................................20 NetBeans 5.x...........................................................................................................................21

Setup and Configuration of Ant......................................................................................21 Integrating J2ME Polish with an Existing Project...........................................................22 The Device Database.......................................................................................................23 vendors.xml....................................................................................................................23 groups.xml......................................................................................................................23 devices.xml.....................................................................................................................24 apis.xml..........................................................................................................................25 Extending the Devic Database.......................................................................................26 Device Capabilities.........................................................................................................26 The Build Process............................................................................................................28 Introduction....................................................................................................................28 Definition of the J2ME Polish-task.................................................................................28 Example.........................................................................................................................28 The <info>-Section.........................................................................................................31 The <deviceRequirements>-Section..............................................................................33 The <build>-Section.......................................................................................................36
Attributes of the build-Section.................................................................................................36 Elements of the build-Section.................................................................................................39 <sources>..........................................................................................................................39 <midlet> and <midlets>......................................................................................................40

2

<iappli>...............................................................................................................................40 <resources>.......................................................................................................................41
The <filter> Subelement..............................................................................................................................42 The <fileset> Subelement............................................................................................................................42 The <localization> Subelement...................................................................................................................43 The <copier> Subelement............................................................................................................................43 The antcall Resource Copier..................................................................................................................44 The renamer Resource Copier................................................................................................................44 The svgconverter Resource Copier........................................................................................................45

<compiler>.........................................................................................................................45
The <compilerargs> Subelement.................................................................................................................47

<obfuscator>......................................................................................................................48
The <keep> Subelement..............................................................................................................................49 The <parameter> Subelement......................................................................................................................49 Combining Several Obfuscators..................................................................................................................50 Specific Obfuscator Settings........................................................................................................................50 ProGuard................................................................................................................................................50 yGuard....................................................................................................................................................50 RetroGuard.............................................................................................................................................51 Zelix KlassMaster...................................................................................................................................51 DashO Pro..............................................................................................................................................51 JODE......................................................................................................................................................52

<variables> and <variable>................................................................................................52 <debug>.............................................................................................................................54 <jad>..................................................................................................................................55
Sorting and Filtering JAD attributes............................................................................................................56

<manifestFilter>.................................................................................................................57 <preprocessor>..................................................................................................................58 <java>................................................................................................................................59 <packager>........................................................................................................................60

The <emulator>-Section.................................................................................................61
Attributes of the <emulator>-Section......................................................................................62 The <parameter> Subelement................................................................................................63 Emulator-Settings in the Device Database and in the build.xml.............................................63 WTK Emulators..................................................................................................................63 Nokia Emulators.................................................................................................................64 Siemens Emulators............................................................................................................64 Motorola Emulators............................................................................................................64 Launching any Emulator with the GenericEmulator-Implementation.................................64 Automatic Resolving of Stack Traces and Exceptions............................................................65

Resource Assembling......................................................................................................67 Concepts........................................................................................................................67 Often Used Groups........................................................................................................67 Fine Tuning the Resource Assembling..........................................................................69 Localization.......................................................................................................................70 Concepts........................................................................................................................70 The <localization>-Element and Localized Resource Assembling.................................71 Managing Translations...................................................................................................71
The Locale Class....................................................................................................................71

3

...................Dynamic Translations.....88 Handling Several Values in Variables with #foreach ............76 The World of Preprocessing........................................................................................................................................................97 Using Dynamic and Predefined Styles..........................................................................................................89 Useful Symbols...................................................................................................................................................................................88 Analyzing the Preprocessing-Phase with #message and #todo.................................................................90 Useful Variables....................................................... #elif and #endif..............................................................87 Inserting Code Fragments with #include.......................................86 Exclude or Include Complete Files with #condition............. #else...................................................................................................................................87 Defining Temporary Symbols or Variables with #define and #undefine...........................................84 Variable-Functions.........................................................................................................................................................................................................................................................................................................................................................................................92 Configuring the J2ME Polish GUI..........................................74 Using Localized Attributes................................................95 The J2ME Polish GUI for Programmers..................................................................................................99 The J2ME Polish GUI for Designers...................................................................................................................................... #elifndef and #endif......................75 Using Quotation Marks and Other Special Characters in Translations.............75 Localizing the J2ME Polish GUI.........................98 Porting MIDP/2............................................................................. #elifdef.......................................................................................................................................93 Configuring Commands....................................................................................... #ifndef........................................................................................................... #else............................................................................................................................79 Using Variable-Functions for Comparing Values..............................74 Common Traps.........92 Overview...............................90 J2ME Polish Symbols....................................90 File Operations......................................................................................................................75 Invalid Locale Calls..........................................99 Programming Specific Items and Screens...............................................78 Checking a Single Symbol with #ifdef........72 Defining Translations...........84 Using Variables with #=.................................................................................................93 Using the GUI in Full-Screen-Mode........ Labels and Programming of the GUI........................................................................85 Setting CSS Styles with #style....................................................................................................102 A Quick Glance.0 Applications to MIDP/1.....................82 Debug Levels.........................................................................................................................92 Activation of the GUI................................................................................78 Checking Several Symbols and Variables with #if....................81 Hiding Code...................................75 Adjusting the JAR-name....82 Debugging with #debug........................................................................73 Setting and Using Localized Variables.................0 Platforms......................................................96 Setting Styles.....................................................................99 Programming the TabbedForm....................................... #mdebug and #enddebug..........................................................................................................................................................................................................................90 APIs and MIDP-Version.....................................................................91 The J2ME Polish GUI.........................................................................................................................................102 4 ............83 The Debug Utility Class.........................................................................74 Coping with Dates and Currencies..............................................

....................................................................................................................................110 Referring to Other Styles................................................................................................................................................................................................................................................................115 Alpha Blending...................................................................................118 Backgrounds and Borders............................124 Opening-Round-Rect Background...................................................................................................................................................103 The Hierarchy of the “resources” Folder...............................................................................117 Using Bitmap-Fonts Directly .........................................................................................................................................................................................................................................................................................................................................111 Structure of a Style Definition.................................123 Pulsating Circles Background....................................................116 Bitmap-Fonts.......................................................................................................................128 5 ........................................114 The colors Section............................104 API.......................................................................................106 Dynamic Styles................................124 Opening Background..................................................................................................112 The Layout Attribute.....................................126 Tiger-Stripes Background.............120 Backgrounds...............................................................................................................................................................................................110 Comments..................................................................................................................103 Groups....................................................................................................css............................114 Predefined Colors..............................................................................................................................................................................................................................................109 Structure of a CSS Declaration......................................................................................................................................................................................................................................................................126 Smooth-Color Background......................................107 Extending Styles..................................................................113 Colors.............................................................................................................................................................................................................117 Using Bitmap-Fonts in the J2ME Polish GUI................................................123 Pulsating Circle Background......................109 CSS Syntax..........................................................................118 Labels.121 Circle Background........................ Static and Predefined Styles...............................................................................................................................105 Static Styles.............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................104 BitsPerPixel-Groups.................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................115 How to Define Colors.................................................................................................................................................111 The CSS Box Model: Margins and Paddings..............120 Image Background.........................................................................................................................................................109 Naming...............................................................119 Before and After Attributes............................................................................................................................................111 Structure of polish......................................................................................................................................110 Grouping of Attributes.......117 Creating Bitmap-Fonts................122 Pulsating Background...........................and Java-Platform-Groups..............................................................................106 Predefined Styles....................120 Round-Rect Background...............125 Round-Tab Background..................................................................................................................127 Borders....................................119 Specific Design Attributes..............................................................................................................120 Simple Background....................127 Ball-Games Background..........................................116 Fonts....................................................Designing for Specific Devices or Device-Groups..............................110 Common Design Attributes.............................................................................................104 Dynamic.......................................................................................................

...................................................................................................................... Forms and TextBoxes...................................................................................................................................................................................................................................................................................................................................149 Limitations...........................................................................................133 Example.............149 Optimizations.............................................. Hyperlink or Button..........................................................133 TextBox....................................0...................................................................0 Game to MIDP/1.........................................................................145 The Extended Menu Bar....................................................................................................................................................................................130 Screens: List......................................................................................................................133 Commands....................................................................................................137 MIDP/2..........................................136 Shuffle View.....................................................................................................................................................................131 Additional Attributes for Screens..................................................................................................................133 Form................................154 Porting the Game to MIDP/1.................................128 Round-Rect Border.................................................................................................................................129 Shadow Border........................................................................................................................................................... Bottom............................................131 Predefined Styles for Lists...150 Backbuffer Optimization for the TiledLayer.........................................................................................................................0-Compatible Game-Engine.....151 Porting a MIDP/2................................................................................................................134 View Types.......148 The MIDP/2...................................................................................................................................................................................136 Dropping View.........139 The Gauge...........................................................................................................133 List...............................154 Working Around the Limitations of the Game-Engine...............................................................................137 The StringItem: Text....................................................................................................................................................................................................................................................................................................................................................................................151 Defining the Grid Type of a TiledLayer......................................................................................154 Necessary Source Code Changes................................151 Using the Game-Engine for MIDP/2.............Simple Border..............................................149 How It Works....................................137 The IconItem......................................................... Left and Right Border............................................................................................................................................................................................................150 Splitting an Image into Single Tiles......................................................................................................................................................................................... Form and TextBox.................................153 Building the Game..........................................144 The Ticker...........................................................................................................................................................................................................................................................................................................................................................................................140 The TextField.........................................................................131 Dynamic Styles for Screens.145 The Menu Bar..146 The TabbedForm......................................................................................................................152 Managing the Resources...........................................................................................................141 TextField-Commands.......xml......................................................................................................................................................................0 Platforms........................................................................152 Adjusting the build............129 Top.........................................................................................................................149 Using a Fullscreen-GameCanvas ..........................138 The ChoiceGroup........................................138 The ChoiceItem..............................................152 Building the Existing Application.......0 View..........................................154 6 ...............................................130 Circle Border...............................................................................................0 Devices.......................................................................................................................................142 The DateField.142 Direct Input Mode........................................................................................................................154 Pixel-Level Collision Detection.............................................................................................................

.................................................................................................................................................................................................................................................................176 Developing for Palm Devices.......176 Library.............................161 Using Custom Items...............................................................................................................................................................................................................................................................................................................................................................................................................................................................175 Using the J2ME Polish GUI on BlackBerry Devices.....................................................................173 Non-MIDP Platforms......................................158 Creating and Using Custom Preprocessing Directives...........157 Integrating a Custom Obfuscator...........................................................................................168 Creating the Client-Side Border-Class..........177 7 ..........................171 Standalone Tools..................................................................................Sprite Transformations....................................................154 Using Preprocessing for Device Specific Adjustments................................160 Configuring the Preprocessor with Parameters.........................................................................................................................175 Developing for BlackBerry Devices................................................170 Contributing Your Extensions................164 Creating the Server-Side Background-Class.........................................176 Developing Native BlackBerry Applications..............................................................................169 Integrating the Custom Border....................176 Troubleshooting..................................................................................................................................................................................................................................................................................................................................................................158 Configuring the Obfuscator with Parameters..............................................................................................163 Backgrounds and Borders...175 Preparations............................................................................................................................................................160 Integrating the Preprocessor into the build..........................................................................................................................................175 Converting JARs into CODs..........161 Extending the J2ME Polish GUI......164 Adding a Custom Background..168 Creating the Server-Side Border-Class............................................................................................................................................................................................xml...........167 Adding a Custom Border....161 Using CSS for Designing the CustomItem...................................................................................................................................................................................................................................................................................................................................................172 The Font Editor..............................................................156 Extending J2ME Polish................175 Signing COD Files..............................................................................................................................................................................................xml......................................................157 Integrating the Obfuscator into the build.........................................................................................................................................................176 Deactivate Obfuscation.........162 Registering Custom CSS Attributes...........................................................................................................159 Using the processClass()-Method..................................159 Preparations.....................................................................................................................................................................................................................................................164 Creating the Client-Side Background-Class.........157 Creating the Obfuscator Class.....................................................................................................................................................................................................................161 Initialisation.........................159 Using the registerDirective()-Method...........................................................................................................................161 Interaction Modes..............................................166 Integrating the Custom Background....157 Preparations.........159 Creating the Preprocessor Class..................172 The Binary Data Editor.........................................................161 Traversal...................................................................................

..............................................................193 Licenses..............................................179 Developing DoJa Applications under Linux and Mac OS X.......................................skipArgumentCheck and polish................189 Trouble Shooting............................................................................................190 Using Subfolders for Resources...........187 How to Apply the J2ME Polish GUI for Existing Applications......................184 Use Preprocessing......................................183 Image Load Strategy.......................................................................................194 Commercial Licenses..................................................................................................................................................................................................................191 How to Use Quotation-Marks in Attributes........................................................190 Preverify Error...............................................................................................................................................186 How to Sign MIDlets with J2ME Polish............................................................................................190 Appendix............................................................................................................181 How to Integrate a Source Code Third Party API ..........................................................................................................................................................187 How to Apply Different Designs to One Application.........................................................................192 How to Specify Properties on the Command Line..........................194 Contact............................................178 J2ME Polish Setup..............177 Converting JARs into PRCs....................181 How to Integrate Third Party APIs.................................................................................................................181 How to Integrate a Binary Third Party API ...............189 How to Enable or Disable the Usage of the GUI for a Specific Device.........183 polish..........................................................................................................................................................................................................................................................................191 Introduction to Ant.....................................................179 Developing for MIDP and DoJa at the Same Time.........................................................................................................................177 Starting the Palm Simulator............................................................................................................................................................................................................................190 Compile Error....................182 How to Use Several Obfuscators Combined......................178 Developing DoJa Applications with J2ME Polish...............Preparations................................180 Cooking Tips and How-Tos........................183 Optimizing the "polish......................................................................................................................................................css" File....182 How to Integrate a Device API ................178 Optional JAM Attributes...............................................................181 Building How-Tos.......................184 Remove Debug Code....................................................181 How to Use Several Source Folders........188 How to Change the Labels of Standard-Commands and Menu-Labels....................................................................................................................187 How to Use Tables....................186 General Optimization Tips...............................................................................................................................................................................................................................................................................................................................................................................................................................................................178 Preparations..................debugVerbose..................................................................................................................................................................................183 Using Optimal Resources..........................................................186 GUI How-Tos..........................195 8 .....................................................................................................................................................................................................................................................183 How to Minimize the Memory Footprint..............................................................................................................................194 GNU GPL..................................................................................................................................................................

for example. Localization: It's easy to create localized applications – just provide the translations and – if you like – other locale specific resources and J2ME Polish will embed them into the application.0 API for MIDP/1./0(&120!%34)%056”.0 widgets in your program and design them with simple CSS-directives like “!"#$%&'()*+. e.g. so that MIDIsoundfiles are only included when the target-device does not support MP3 but supports the MIDI format..1 for managing font-based texts can be used for solving day-to-day problems.0 standard – or they choose to support only a few handsets. J2ME Polish takes care for the porting! You can also adjust the API. by specifying that a backbuffer-optimization should be used for >. Logging Framework: The logging framework can be used to enable or disable logging levels for classes or complete packages just by modifying some settings in the central build.89 or the >. Automatic Resource Assembling: All resources like images and soundfiles are assembled automatically for you. J2ME Polish can also invoke any emulators for you. compilation. Device Database: An XML-based device database provides a convenient and portable way for adjusting your application to different devices. 9 ! ! ! ! ! ! ! .0 phones! Utilities: Some often used components like the fast . With J2ME Polish you can use the standard MIDP/1. preverifying and packaging the applications to a sophisticated optional GUI which can be designed with simple CSS text-files. This saves runtime as well as memory.*="<.xml. localization. The tools range from standard build tools for compiling. Following tools are included: ! Build-Tools / J2ME Polish Task: preprocessing. You can use specific resources for vendors like Nokia or for devices which support a specific format easily. so that no traces are left in the application. Web-designers can now design the application independently of programmers and designs can be adjusted easily for different handsets. GUI: The standard J2ME widgets cannot be designed at all. resource assembling. You can even include resources on conditions. The open source tool J2ME Polish promises a solution to this problem – and more. J2ME Polish is actually a whole collection of different tools for wireless Java programmers.println() can be shown on real devices as well! Of course you can disable all logging completely. Messages which are given out with System.0 devices as well. preverification.0 widgets like the 7(89'-:9.0 as well as MIDP/2. obfucation and packaging of J2ME applications.Preamble Preamble J2ME developers face a serious problem: either they use only the lowest-common-denominator of J2ME devices – the MIDP/1. In contrast to all other solutions. You can even use MIDP/2.?9@9.1.out. You can optimize your application for multiple devices and languages/locales at the same time.&&"<=.-"%.& etc. for which they optimize their applications with a lot of energy.on MIDP/1. Together with the powerful preprocessing capabilities you can use this database directly in your application. since the translations are actually integrated on the source-code level. localized applications do not have an overhead compared with non-localized applications. Game-Engine: With the highly-optimized game-engine you can use the MIDP/2.

Migrating to J2ME Polish is easy. Another tool is the bitmap font editor. add your own preprocessor. since it is based on Ant. which are easy to manage with the binary data editor. Obviously you can also extend and use the more advanced features of the J2ME Polish framework. You can invoke J2ME Polish either from within your IDE of choice or from the command line. You can use your own widgets. I hope you find J2ME Polish useful and have fun with it! Bremen/Germany. Ant is the standard for building Java applications and is supported by all IDEs. which can be used for creating bitmap fonts out of any True Type fonts.Preamble ! Stand-alone Tools: The binary data editor can be used for editing any structured binary data files much more comfortable than a hex-editor. An often needed feature are level-data files. or integrate your own obfuscator with ease. November 2005 Robert Virkus / Enough Software 10 .

49.EL0.)0F0.)*2EN(.)*2E='"*0%"-. An additional “Developer Seat” license needs to be obtained for every developer (99.1. optional.9B. compiling.Introduction to J2ME Polish Introduction to J2ME Polish This chapter introduces you to some of the possibilities of J2ME Polish.)(A. we need to right-click the build.-€ valid for any number of applications).)%0*.. J2ME Polish now preprocesses.%-..)*2ED9"&90%"-. A:B1.xml” which controls the build process.*1.)3"44.)%0A. 2)*3)45%6.).)9.%#/47#)8(/39:."$$56 .&2+0%(56 0D<89.org Building the Application To build the application with J2ME Polish we need to create a file called “build."1. To build the sample application.j2mepolish.+0%(3-. compiles... Operating Systems: Windows. The build process can also be started from the command-line: enter the installation directory and type the “ant” command.)(D#&.)*2EM. Mac OS X Prerequisites: Java Wireless Toolkit.-3'(934&. please refer to the following chapters. e.)(D#&. The resulting application bundles can be found in the “dist” 11 .3E56 O !/2+)&+)-032%-089"&9. Runtime License (199.9E56 . the main parts of it are shown in listing 2.)(D#&.-€ valid for one J2ME application).)(D#&."$$56 . localization.*1.*1. www. so most IDEs support the editing of this file with syntax highlighting. deviceoptimization."$$56 .g.9250C .)(A.89.I?#.+0%(3-. The application just shows a simple menu which is typical for many J2ME applications (listing 1). This is a standard Ant file. An Example Application For this introduction we use a simple application as an example.. signing of MIDlets. !"#$%&0&$'((0A.8KEL0 =. The build. If you want to know specific details.7K")%.841"<3E56 0B.)91)2E89"&9. auto completion etc. Ant Build-Process: preprocessing.)6 !"#$%&0A.)3"44.)/1 Editions: GPL (for Open Source products).("!)/256 0D<89.jar” from the command line. “Run Ant./0.)(A.)(D#&. Enterprise License (2990.892EGHAI0J'1.)920 +0%(3-.841"<3%.9EL0.-3'(934&.jar”..)91)2E8.EL0. device-database.-3'(934&..+0%(3-.)(D#&.99.” or “make” depending on the IDE.-€ valid for an arbitrary number of applications which can only be installed a 100 times).')0*').€ ). 100% compatible to the MIDP standard. obfuscating.90C =.97(&&.97'--")*=.')0C 0D<89. preverifies obfuscates and packages the code automatically for a number of devices.+0%(3-..8"9.90)*+). Don't worry if you have never worked with Ant before – although it can look quite scary at the beginning it is easy to master after a while. creation of jar and jad files GUI: Design via CSS..)3"44..xml file is also included in the J2ME Polish distribution. Linux.893:AJ=:7:>56 .44250+0/21(. This is the sample application which is included into the J2ME Polish distribution.+0%(3-.)(D#&.0 devices..)10=.xml within the IDE and select “Execute”. Installation J2ME Polish contains a graphical installer which can be started by double-clicking the downloaded jar-File or by calling “java -jar j2mepolish-[VERSION].+0%(3-.)056 O P333Q !"#$%&'()*+.)3"44. resource assembling.841"<2+0%(538.9D9"9..890-.-(0A:B1.)38..)(D#&. preverifying. “java -jar j2mepolish-1. Single License (199.)91)2E.14EL0."$$56 .0 game-API for MIDP/1. Game-Engine: MIDP/2.

we can use the J2ME Polish GUI by setting the “usePolishGui”-attribute of the <build>-element to true (listing 2).3. The “title”-style is used for designing the screen-titles.)90)"-.&.O+ .)98T 0U!(. 2)*3)45%".E0ZT 0UZ*.FE9&(. Designing the Application with CSS Even though the application just uses plain MIDP code. All settings specified in the “list”-style are used for designing screens of the type “list”.)*'&O+]C4'1.&.css” in the folder “resources” needs to be created or changed (listing 3).-4'&9Z4&'%("&*3S"& EZT U9"&%. As you might have guessed._(.8#&.8K3)"-. we need to have a closer look at the build._(. The Ant-property “wtk. J2ME Polish then “weaves” the necessary code and APIs into the application automatically..style are used for items which are embedded in a list.#. “<deviceRequirements>” and “<build>”. the file “polish.8K`(."+(.FEI?"-41. First we define the used colors in the “colors” section.FE7/XV9$H3YET U9"8$*. Here you can also define additional variables and symbols which can be used in the preprocessing step.90#1"88FEA.&.FE.^. we need to use “dynamic” style-selectors like “list” and “listitem” for designing the application.FED.3S"&E0 000S"&@&1FE]C4'1.8KE 0#1"88)"-.?"-41. and so on.Introduction to J2ME Polish folder after J2ME Polish finished the build.')FEY3[3[E 000*.1* 000R(118#&.8K3S"&\"-.09.)R' 000)"-. The “polish.FESH-.8904&'S. To understand and control the build process.#9E 000S"&\"-.8KET USH-.R0)"-.)(E 000(8.8KT 46+'/7)+8 46!/25)&+8 You can also use the additional section “<emulator>” for launching any WTK-based emulators from within J2ME Polish. As we have not used any #style preprocessing directives in the code.OE 0UZ.A. By doing so we can later change the colors of the complete application in one place.1*3S"&/.&8.90)"-. The “focused”.)'(%K+SH-. what MIDlets are used.EZT 0UZ!(.4'1.R"(19FESH-.E 000000000000000W"1(.FEV9$3K'-.)"-. of a form or a list.49. 12 .8K3W.-.W.FE*. which obfuscators should be used.8KET U4&'4.FEG"W"J"#$"%.-41._(.)(E 000W. This element controls whether the J2ME Polish GUI should be used.xml (listing 2): At first the J2ME Polish Ant-task needs to be defined with the <taskdef> construct.E0W"1(.-4'&9Z.4'1.1*T UZSH-.)(A. The J2ME Polish task has the three mainsections “<info>”. The <info>-element specifies some general information about the project like the name and the version.^.FE)'$.)'(%K34'1.FE]C4'1.8KT 0U.style is used for designing the currently focused item.4'1.')FE.8K>"8$E 0#1"884"9KFE.FESH-.%<7)(89=>( 4!/25)&+. For specifying or changing the design.-.E0*. And all settings specified in the “listitem”.&9<0)"-.*1.#.)FE-.g.J'1.4'1.E 00U-.*1.?"-41.8K3")93J'1.home” points to the installation directory of the Wireless Toolkit. The <build>-element is the central controller of the actual build process.-.4'1.css” file contains the style definitions for all items and screens of the application.-4'&9ZS*'-3S"&/.W.)98T 00U&.4'1.9E0)"-. this file is included in the J2ME Polish distribution as well.)R'T 0U*. e. The <deviceRequirements>-element is used to select the devices for which the application should be builded.8K+ !(.

&+V. This directive can be placed before any constructor of a screen or an item (and some more places like the List-append()-methods) within the code.-&.)96 00.893:AJ=:7:>56 0669(+:$).)9.#"1+ #.=2.892EGHAI0J'1.)%/0h6 0!"#$%&'()*0C 009<4.-"%./08-"116 0O 01"<'(9/0. font.%K9e%7'1'&/00&%!2HafLHbYLHHc56 0!&.-3'(934&..%K9g')97'1'&/0&%!2HafLHbYLHHc56 0R')97'1'&/0&%!20a[L0fhL0fd056 O 9.'.. Designs and resources like images and so on can be adjusted to different devices by placing them into the appropriate subfolder of the “resources” folder."$$56 0669(+:$).)10=. !"#$%&0A.)%/0H6-"&%.)3"44.-"%.+0%(3-.&0j0.)%+ 0&.i.%K9e%7'1'&60!'&*.)9.("!)/256 0D<89./0(&120.)91)2E89"&9.60!'&*.669(+:$).&0j0W.6 01"<'(9/0#. In contrast to dynamic styles.890C 04"**.?4")*0j0#.'%.#')k:\BIlk34)%056 0.91.)*2ED9"&90%"-.-0C to use “static” styles.*0C 04"**. 0-"&%.9E56 .+"1.89.#')+.+0%(3-.#')+.60R')9+89<1.EL0.&6 0#'1(-)8/0H6 O When an application has more than one screen and the screens should have different designs. the #style-preprocessingdirective is used./0&'()*+&./5/. one need 1./0!'1*60R')9+#'1'&/ 0!&.8KEL0=. layout.'%.&6 efficient.)(A. The resource-assembling does work independently of the usage of the J2ME Polish GUI by the way..')"160R')9+8. The same is true for other resources like images or soundfiles.)9. .)9.'.)(A. etc.%)/09'46 application-code: For using a static style. background and border as well as the special attributes before and after.i.?4")*6 O R'#(8. Most items do also support specific attributes.&/0)')./ 01"&%. need changes in the 0./0!'1*60#'1'&/0R')97'1'&6 008.%K9g')97'1'&6 0!"#$%&'()*/0)').)%+1../0%#' static styles are added during the compilation phase (%/%1*(2/%34. faster and more memory01"<'(9/0#.&+#'1'&/ 00R')97'1'&60!'&*. 13 .-"%.9250C .=2. and for using a special design for the Nokia/6600 phone you can add the file “resources/Nokia/6600”.'%. The “list”-style in the example utilizes the specific attribute “columns” for specifying that a table with two columns should be used for the list (figure 1).%@'()*+9A** #'1'&80C 0!%7'1'&/00&%!2YaHLYbaLcd56 0!&.&6 O 1.*1.. however./0(&120!%34)%056 0O 01"<'(9/0.*(2/%34 (73851'(+/5#*(2/%347$91'(7:"55* and are..R9/0Yh604"**. 1: The designed sample Nokia/polish.)0F0.)9.*9K/0H6 0O 0R')90C 0089<1. For using a different design for Nokia phones you can add the file “resources/ Fig.'(2/%36/5/.*1.<&/)).?4")*0j0#.)(D#&..%K9/0Yh6 0!"#$%&'()*0C 00#'1'&/09&")84"&.css” application. 2)*3)45%?.)+!'99'-/0h60 0R')9+R"#.0C 04"**..#960"&#/0f60#'1'&/ 00!&./04&'4'&9.)%0A. Static styles.)/0H60!"##$%&'()*(+".)(D#&.Introduction to J2ME Polish All styles support the common attributes margin.&9.)%/0h604"**.9.. padding.- . therefore.

they need to start with a dot in the polish.)(D#&. User-defined levels can be used.=2.). info.'%.css file: 3-". Logging-messages can be viewed on real devices as well.3E56 O Instead of using the “list” and the “listitem”-styles in the polish.8"9.. error etc.'.)91)2E. ! ! The logging is controlled with the <debug> -element in the “build./0%#' (<===> .)(D#&. no resources at all.)9...)3"44. On one hand logging messages need memory as well as computing time and on the other hand there are no logging frameworks like Fig.)(D#&...'%. This design is also included in the J2ME Polish distribution and can be used when the “resDir”-Attribute is set to “resources2” in the build.'. 2: The same application with log4j available for J2ME. This mechanism can be used to create different designs of one application.out.=2..+0%(3-..css.EL0. will not be compiled and use.)7'--")*0C 0-"&%.&2+0%(56 0D<89.97'--")*=.. Simple System.println()-calls are used for logging. The complete logging can be deactivated.=2.'.+0%(3-. can be defined for single classes or packages.R9/0Yh604"**.)0C 04"**.)3"44.)*2EN(.. Figure 2 shows the sample application with a different design. you now need to use the styles “mainCommand” and “mainScreen”.+0%(3-..)%+ 0P333Q O 3-".')0*')..)/0H60!"##$%&'()*(+". With using the #style-preprocessing directive the code still remains 100% compatible to the MIDP standard.."1.9EL0.xml” file : 14 .)38. too. Debugging and Logging Logging and debugging is complex and difficult task under J2ME.+0%(3-. therefore.xml.)*2EM."$$56 0669(+:$). This is why J2ME Polish includes such a another design.)D#&.."$$56 0669(+:$)."$$56 0669(+:$). Since these are static styles.)*2E='"*0%"-.-3'(934&.89. The background is actually animated: it starts white framework with these features: ! Logging-levels like debug. ! ! ! Logging-messages which are not active.)%/0h604"**.)%+1. and dithers to the shown pink. You can specify in the build.xml file what “resources” folder should be used.14EL0.)(D#&. warn.-&..)3"44.Introduction to J2ME Polish . so one use the native/standard GUI for very old devices while using the J2ME Polish GUI for modern devices at the same time.'%.

)R'E0ZT 0000UR..50C 00ZZn*.9K'*0R".0560ZZ0VK.3A<71"88E01. O0000000000000000000000000000000000000000000000000000ZZ09K. There are however./.1109&.0A'!.W.&04"99. The J2ME APIs of J2ME Polish will also specify details of errors whenever they throw an exception.&)FE#'-3#'-4")<34"#$"%.out. 000ZZ09K. “#if” and “#=” are used for optimizations: When an API is required for a specific functionality. The “showLogOnError”-attribute can be used for showing the log automatically.-3'(934&.[api-name]” symbol.')0.)R' 00D<89.18.W.&)FE#'-3#'-4")<34"#$"%.. e.*."0. whenever an error has been logged.80*. when the “verbose”-attribute is true.R 15 . With the help of the preprocessing capabilities and device database of J2ME Polish.808(44'&90*'. though.?A.*.-3'(934&.)08K'V='%p)I&&'&0. This only works when the GUI of J2ME Polish is used.9K'*256 00ZZn*.R04'1./. “error” and so on will also be logged. Often the preprocessing directives “#ifdef”. after each logging message the current time and the sourcecode file as well line of the message will be added. 000P333Q ZZn.0A.)*. The “level“-attribute controls the general logging-level which is used when no specific level has been assigned for a class.J: 000P333Q ZZn. other situations in which device optimizations are useful.)91)20E#'-41. When no level is specified the “debug” level is assumed.01A(G1.&&'& 00D<89.3mE01.1FE*. An error can be logged just by appending the error object to a System.9K'*08(##. which can specify the logging-level. but no “debug” messages.println()-call: 9&<0C 00#"117'-41.80V.08(44'&9809K.!(%0.@A3. The UI of J2ME Polish adapts automatically to devices and can – thanks to the resource assembling – be easily adjusted to different devices and device-groups.80)'908(44'&909K.&04"99. these optimizations are done easy and without risking the portability of the application. messages with a level of “warn”.%%.0--"4.&09K. Easy Device-Optimizations with Preprocessing and the Device-Database Device optimizations are mostly needed for the user interface of an application.49.809&(. which is defined for each supported API: ZZn. 000ZZ09K..#.19.1.!(%0. The logging-levels are hierarchically ordered: debug < info < warn < error < fatal < user-definiert When a class has the logging-level “info” assigned.*3E056 O0#"9#K02A<I?#.*E0o0. In the source code logging messages will be introduced with the #debug-preprocessing-directive.1FE.01A(7B/CD/&E%F.Introduction to J2ME Polish ?#1+0&(1%"+51@A3. just use the “polish.W. This eases the location of errors especially when obfuscation is used.3--"4.+/71@A2"571A(51G15@A1.!(%E0ZT ?I#1+0&H The “enable”-attribute defines whether logging should be activated at all.g.?0-.AH 0000UR. “//#debug info”.01'% When the “verbose”-attribute is true.)91)20E#'-41.1.19.api.8K3"4.?0-.

3--"4.)*'&0FF0\'$.R"(19+W"1(. TiledLayer.)'(%K3*. GameCanvas.8K3e.8K3-.).9.13 ZZn.W.')0V"80R'()*L0(8.R.R04'1.80.08(44'&980"901.+(&10OE6 ZZn.?.#0R.#089"9.)"10D9&.+(&1/*.)"10D9&.80"901.R Variables can be defined as well and be used within the source code.midp2” symbol: ZZn.8T 000UW"&.W.8K3-. The complete API can be used: Sprite. ZZn. since the necessary API is weaved into the application automatically for MIDP/1.+(&1E0W"1(.#0A'!.0A:BJZY3[089")*"&* 000P333Q ZZn.&04.midp1” and the “polish.)*.R"(193#'-Z(4*"9.80"0\'$.xml like this: UW"&.9804.&J.R0(4*"9.)%0@JB. 000ZZ0)'0W"&.808(44'&909K.)*.10TF0YH 000ZZ09K.0)"-."0."890YH0!.80*.R.E6 ZZn.R*.)*.)*.).0*.*4H 000ZZ09K.E0ZT UZW"&.0” and “polish.0!"8.R04'1.0 devices as well.)*.1.R Fun Fun Fun: The Game-Engine The game-engine of J2ME Polish lets you use the Game-API of the MIDP/2.18.Introduction to J2ME Polish One can differentiate between MIDP-versions with the “polish.80*.R04'1.)%0@JB.#." 000ZZ09K.8T The defined variable can be used in the source code with the “#=”-directive: ZZn."8909K. 000ZZ09K."!1.0"0*. No changes in the source-code are necessary.8K3#1*#Y3Y 000R1'"90R0F0Y3HR6 000P333Q ZZn.R04'1.#.R ZZn.W.0 devices.808(44'&90*'. LayerManager and Layer.0 and the CLDC/1.R One can compare variables as well: ZZn.* 000ZZnF04(!1.1 standard.?.#089"9.FEK994/ZZVVV3. the “polish."0*.8K3"4.80*.>Ir@^=0F0E]C0(4*"9.0A."!1.R04'1.08(44'&980A:BJZH3[089")*"&* 000P333Q ZZn.8K3q.1” symbols can be used: ZZn."!1. The 16 .#.)*.0(8.Z(4*"9.cldc1.*4H 000ZZ09K. An URL could be defined in the build. too: ZZn.0jj04'1.J: 000P333Q ZZn.*.R Several requirements can be combined.cldc1.>Ir@^=0F0EK994/ZZ*.98J.#0R.FE(4*"9./ 0004(!1.R To distinguish between the CLDC/1.#.0 standard for MIDP/1.18."!1.W.

Extending J2ME Polish J2ME Polish can be extended in several ways: Build-Tools: ! ! ! Obfuscator: integrate your own (or a third party) obfuscator Preprocessing: add your own preprocessing directives You can also use the <java>-element to extend J2ME Polish Backgrounds and Borders: custom borders or backgrounds enhance the possibilities Items: extend and use standard CustomItems – and design them using CSS GUI: ! ! How these extensions are implemented is described in the “Extending J2ME Polish Chapter” on page 157. The <java>-element is described on page 59. The game-engine can be optimized for several usage scenarios.Introduction to J2ME Polish current limitations are that no pixel-level collision-detections and no sprite-transformations for nonNokia devices are supported (for Nokia devices sprite transformations are supported). for example. you can specify that the backbufferoptimization should be used for the TiledLayer implementation. 17 .

48.ZY3b3HZ.jar. so it is recommended to have such an emulator installed.Installation Installation Requirements To use J2ME Polish.jar. You should find the sample application now in the Package-Explorer (package de.0. for example the “menu” application. This application is optimized for Nokia Series 60 devices. following components need to be installed: ! ! Java 2 Standard Edition SDK 1.jar” and “enough-j2mepolish-client.home}/import” folder to your classpath: import/midp2. import/wmapi.jar.)*..*4+'8?Z0for Mac OS X Favorite IDE.9Z-.)*.V9''1$. if not already integrated in the IDE. Integrating J2ME Polish into Eclipse To integrate J2ME Polish into Eclipse the easiest way is to copy one of the sample applications (from the “samples” folder of your J2ME Polish installation) in your workspace. K994/ZZS"W"38()3#'-ZSH8. import/nokia-ui.polish. for example Eclipse 3. For saving bandwidth you can download just the update-package. The installer of J2ME Polish contains a sample MIDlet application with two different designs. you do not need to re-install the whole package. Actually only the first two 18 .example). K994/ZZ")93"4"#K. import/enough-j2mepolishclient.3'&% ! ! Installation of J2ME Polish For installing J2ME Polish download the latest release and start the installation either by doubleclicking the file or by calling "java -jar j2mepolish-$VERSION.jar. import/mmapi.9Z.jar” which need to be copied into the "import"-folder of your installation directory.#1.&83). To build the sample application.enough.com.5 or higher.jar" from the command-line (where $VERSION denotes the current version of J2ME Polish).4 or higher. please include the following jar-files from the “${polish.. set the source-directory of the project to the “src” directory: Select “Project” -> “Properties. K994/ZZS"W"38()3#'-Z4&'*(#98ZSH-. This package contains the two JAR-files “enough-j2mepolish-build. If the sources have not been integrated automatically.?3K9-1L0 or0K994/ZZ-4'V.xml” from your favorite Java IDE or call "ant" from the command-line. When the classpath was not set correctly. The Nokia emulator can be retrieved from http://forum. Call "ant test j2mepolish" to skip the obfuscation and to include debug-information of the sample application.” -> “Java Build Path” -> “Source” and add the source-folder “src” there.nokia. Eclipse then automatically integrates all source-files and sets the classpath. run the included “sample/build.?3S84 Java Wireless Toolkit.jar. Then start Eclipse and create a new project called "application".3'&%0 Ant 1. K994/ZZVVV3. Also the default emulator is launched with the application. after you have switched to the “sample” directory. Updating J2ME Polish When you want to update an existing installation.

You can now create the JAR and JAD files by right-clicking the “build. Should not be shared in CVS and similar systems. future enhancements are easier to accomplish.jar” and “nokia-ui. “mmapi.jar”. select the “build. you will find following structure in your project (assuming that your project is called “sample” and your workspace “workspace”): Folder / File workspace/ sample workspace/sample/build.. but if you later want to explore the full possibilities of J2ME Polish you already have all important libraries included.. Should not be shared in CVS and similar systems. You will find the JAR and JAD files then in the "dist" folder of the project. Then start JBuilder and create a new project called "sample".. “wmapi. you need to integrate the provided “build. Description Integrating J2ME Polish into Borland's JBuilder To integrate J2ME Polish into JBuilder it is best to copy the sample application (the “sample” folder of your J2ME Polish installation) in your workspace.xml” is shown in the project-view.xml” file. Important: you need to deactivate the Borland-compiler 19 . Enter “MIDPDevelopment” or similar as the name of the library and add the files “enough-j2mepolish-client.xml” file. Switch to the “Required Libraries” tab and select “Add. Note: only the first two files are actually needed by the sample application..home}/import” folder to the library path.xml” in the project-root. will be created automatically.” command is not shown. The example is optimized to Nokia Series 60 devices.xml” file: Select “Wizard” -> “Ant” -> “Add. In the project-dialog select the appropriate path and confirm the “src” folder as the main sourcefolder.xml" (which is located in the root of the sample project).css workspace/sample/build workspace/sample/dist The applications project The controller of the build process Folder for all resources and design descriptions of the project Basic design description Temporary build folder. It will be created automatically. selecting "Run Ant" and running Ant in the next dialog. After the project has been created.xml workspace/sample/resources workspace/sample/resources/polish. After you have integrated the sample application into Eclipse.”.jar”.” and then “New. you might need to refresh your project: Right-click the project and select "Refresh"... then open the Menu “Run” and select “External Tools” -> “Run as” -> “Ant Build”. Now the “build. Optionally you can change the build-settings by modifying the file "build. If you want to access them from within Eclipse..” and select the file “build.jar”. Folder for the ready-to-deploy applications.Installation libraries are needed for the sample application.. but when the others are included.jar” from the “${polish. “midp2. For example you can change the deviceRequirements if you want to. Now create the new project. If the “Run Ant.

xml” file.x For integrating J2ME Polish with NetBeans 4..” and deselect the “Use Borland Java compiler” check box. right-click your new project in the "Projects" view and select "Refresh Folders". Mounting the Libraries: Open the mounted file-system. Executing J2ME Polish: Open the mounted file-system (switch to the file-system-window by pressing "Control-2"). if you want to. Copy the sample project: Navigate to the "${polish. Overwrite any existing files. Just select the J2ME Polish directory and click "Finish". Select "Add Jar/Zip" and add the "${polish.. Open the Sample Application: You can now change the sample application.home}/import/enough-j2mepolish20 ! ! ! .6 For integrating J2ME Polish with NetBeans 3. locate the file "sample/build. select “Properties. You can find it in the "sample/src" directory (in the package "de.6 mount the installation directory of your J2ME Polish installation. Select the "resources". right-click it and select "Execute". Integrating J2ME Polish into NetBeans NetBeans 3..polish. ! Create a new project: Go to "File" -> "New Project" and select "Mobile" -> "Mobile Application" as your project type. Windows Explorer on Windows or Finder on Mac OS X).0 create a new project and copy the sample project from ${polish. De-select the "Create Hello MIDlet"-option and select "Finish" to create the project..example" package..xml". right-click the "sample/build.xml" file and copy all into the folder of your NetBeans project.home}/sample" directory with your filemanager (e.. Go to "Build" and select "Libraries and Resources". You can now view the sample application in the "de.xml” file and selecting “Make”.home}/sample into your new project with a file-manager." and call the new project "j2mepolish". "nokia-ui" and "wmapi". You will find the created J2ME application files in the “dist” folder of your project. Mounting the Filesystem: Select "File" -> "Mount Filesystem.g. ! ! ! ! NetBeans 4.xml" file and choose "Execute". Note: Don't navigate into the directory." -> "Local Directory" and select the folder into which you have installed J2ME Polish. open the "import" directory and rightclick the "enough-j2mepolish-client" jar and select "Mount JAR".enough. "mmapi". Return to NetBeans.polish. You can now build the sample application by right-clicking the “build. Right-click your project again and select "Properties". After the execution you will find the created applications in the "dist" folder. Do the same with the libraries "midp2".enough. ! Create a New Project: Go to "Project" -> "Project Manager" and select "New. Right-click the build.Installation for building the actual applications: Right-click the “build. "resources2" and "src" folders as well as the "build.example"). after you have switched to the “File Browser” view. Give the project any name and choose any folder as the project's home.xml and choose "Run Target" > "j2mepolish" for running the example.

After you have downloaded and installed Ant (http://ant.xml. e. You can now just open any of the provided sample applications.xml" file. so that the “ant”-command can be found. just copy one of the sample build.x J2ME Polish provides NetBeans specific build scripts from J2ME Polish 1. ! Now switch to the "Files" view and right-click the "build. If you have installed Ant into “C:\tools\ant” then enter following command on your Windows-command-line (or your shellscript): DI>0J.rMpAIF7/XSH8*$Y3b3H Under Unix/Linux/Mac OS X please use the “export” command instead of the “SET” command.” (or similar). From now on you can build. Setup and Configuration of Ant Ant only needs to be configured when it should be called from the command-line. Windows Explorer). you need to set your PATHenvironment variable.xml. Just select a folder like the menu folder and select Open..g. Now switch to the Files window by selecting Window > Files. do it directly from the file system (e.>MFkJ.apache.home}/samples. Now you need set the JAVA_HOME variable as well. Now you should be able to issue following calls from the command-line (make sure that you are in 21 .g. so that the "test" target is executed first.Installation client. In this window delete or rename the build. F5 for debugging). j2mepolish" in the following dialog. Integrating a sample application in NetBeans: ! Select File > Open Project.q..g.xml script and rename it to build. delete the default build. NetBeans 5.xml script to build. Now right-click the build-netbeans. debug and compile with the normal NetBeans commands (e. followed by the "j2mepolish" target.>Mk67/X9''18X")9X!. When the renaming does not work. and select any sample application in ${polish.xml script and rename the build-netbeans.org).: DI>0G.jar" file to your project.xml scripts to your project's folder.. J2ME Polish now executes and starts the WTK emulator.) You can change the PATH variable permanently in the System-Settings of Windows (Control Center -> System -> Advanced -> Environment variables). Since Ant is integrated in every modern Java-IDE..xml”-file in your IDE and choose “Run Ant. J2ME Polish is then used for building etc. build and compile facilities of NetBeans. Select "Run Target" > "Advanced".3 Beta 3 onwards. Write "test. You can from then on use the normal debugging. you just need to right-click the “build. ! ! ! ! When you start a new project in NetBeans.xml script which is in the base folder of the project. Then adjust the settings according to your needs. run.

?"-41.890SH-. do you have set the JAVA_HOME environment variable? Call “ant” within your project root to build your application. currently applications are build for 4 device-groups: 1) Nokia Series 60 ("Nokia/Series60").L08'09K.&/ ")909. you need to make changes to the "resources/polish. If you want to use the J2ME Polish GUI.0!(./ ")9 .1*0.0 ("Nokia/Series60Midp2"). sound-files etc into the “resources” folder of your project. Here are the required steps: ! ! Copy the "sample/build. 2) Nokia Series 60 with MIDP/2.8K Integrating J2ME Polish with an Existing Project You can use J2ME Polish for any existing project by copying the file "sample/build.09K.9K09K.xml" file: you need to specify your MIDlet class in the <midlet> element.09.Installation the “sample” folder of your J2ME Polish installation): . Ensure that your Ant-setup is correct.4'1.0 phone ("Generic/midp2"). You then need to adjust the "build.1*0")*0'!R(8#"9. Remember that you cannot use subfolders for resources.xml" and the "resources/polish. 4) Any MIDP/2. Have a look at the how-to explaining the first steps for using the J2ME Polish GUI on page 187.xml" and the "sample/resources" folder to your project-root.909'09&(.)%0")909'0!(. ! ! ! ! ! 22 .css" file. Move your resources like images.#K'0G(890#"11. 3) Any MIDP/1. disable it by setting the "usePolishGui"-attribute of the <build>-element to "false".80R"89.0. Tip: use dynamic styles like "form" and "list" for a start.#K'0\'V0#"11. If you do not want to use the J2ME Polish GUI.&9<08.css" files. You might also want to adjust the <deviceRequirements> element.)%0")90V.xml" as well as the "sample/resources" folder to the root-folder of the project.0 phone("Generic/midp1"). Adjust the "build.89+4&'4. since subfolders are used for the automatic resource assembling of J2ME Polish (see page 67).

?&. which is defined in the file “vendors.H ?%":1HJ/-$"?I%":1H ?21"30.jar”.1%3HJ/-$"4OP?I!".:A( G"501@AUPMSIV=KA(IH ?I&. extract them from the jar file into the root folder of the project.7H In this code 2 vendors are defined – Nokia and Siemens."!"+$5$38(%":1@AR"G"S". page 78).xml The device groups are defined in the file groups. This allows you to use your own vendors without needing to merge the vendors./0!7H ?&. Features are just a comma separated list. whereas capabilities always have a name and a value.xml”. You can define your own vendors in the custom-vendors. Vendors can possess features and capabilities.xml./0!H ?I&..xml”. which are defined in the file “groups./0!H ?%":1HJ/-$"4OP?I%":1H ?21"30.xml. An example definition is: ?G1%#/. which are inherited by all devices of that vendor.07A(G"501@AKL))))MMA(IH ?IG1%#/./5/./0!H ?%":1HN1. A device can be a member in any number of groups. These abilities can be used during the preprocessing (compare chapter “The world of preprocessing”.17H?I21"30./:=%/-$"=:$#=0$=Q0556"%G"7A(IH ?.H ?IG1%#/.17H ?. The custom-vendors. groups.xml”.7H ?G1%#/.xml file is loaded from the current project folder and – if that file doesn't exist – from the J2ME Polish installation folder."!"+$5$38(%":1@AR"G"S5"32/.xml”./0!7H 23 .xml The vendors of J2ME devices are defined in vendors. Every device can belong to an arbitrary number of groups.H ?G1%#/.5"7717=20557. All these files are contained in the file “enough-j2mepolish-build.$17TK?I%":1H ?!".H ?%":1HN$1:1%7?I%":1H ?IG1%#/. Every device has a vendor.11%A( G"501@A./0!H ?&.-"&1A(G"501@A%/-$"40$A(IH ?I&.xml file with each update of J2ME Polish.1%3H ?."!"+$5$38(%":1@A.17H ?. so when you do not find them. Libraries can be managed using the file “apis.7=2/.The Device Database The Device Database All J2ME devices are defined in the file “devices."!"+$5$38(%":1@A.xml file. vendors.17H?I21"30.

17H In the example the Motorola Ident 730 and the Nokia 6600 are defined. ?#1G$..The Device Database The group “Nokia-UI” is used for devices which support the UI API of Nokia.-"&1A G"501@AC:"!$^(::"!$^(:/3/.xml file is loaded from the current project folder and – if that file doesn't exist – from the J2ME Polish installation folder.17H Groups can be defined explicitly with the <groups>-element.1S5"32/.17HB"76":1.:=R"G"S.xml file with each update of J2ME Polish.1S5"32/.xml file. Capabilities can be grouped into hardware. thus one cannot use the same name for a SoftwarePlatform and a HardwarePlatform capability."!"+$5$38(%":1@AN/23C"."?I21"30.4"&1%3HJ/-$"TTKK?I071."!"+$5$38(%":1@A["."!"+$5$38(%":1@AN/23C".#C".1S5"32/.#C".1S5"32/."!"+$5$38(%":1@AN/23C".1S5"32/."!"+$5$38(%":1@A[".H ?071.:=N.xml all J2ME devices are defined.H ?071.:=U"LR".1H ?#1G$. The group “Series60” extends this group. All group-names to which the device 24 .$"5A(IH ?.and software-capabilities.:=[1"!N$91A G"501@AV=V)(U\A(IH ?.$17TK?I&. The structure is “[vendor]/[device-name]”./5A G"501@AOMS^(Y6S^(NND^([YYS^([YYSN^(N1.:=6":1.#C". The custom-groups..N$91A G"501@A)KK(-+A(IH ?I#1G$. This grouping is optional and will not be distinguished in the preprocessing step. This allows you to use your own groups without needing to merge the groups.1H ?$#1%3$2$1."!"+$5$38(%":1@A[". Any capabilities or features defined in the groups can be overridden or completed by the device definitions."!"+$5$38(%":1@AN/23C". The identifier consists of the vendor and device-name. devices.11%N$91A G"501@AVXKLVXKA(IH ?.17H ?."3$/%4"!$A(IH ?.FG1%37^(B"7S/$%31.1S5"32/.11%N$91A(G"501@AVWTLZK_AIH ?."]17/503$/%A G"501@AXKKLZKKA(IH ?.1S5"32/. You can define your own groups in the custom-groups.:A(G"501@AUPMSIZ=KA(IH ?I#1G$.17HB"7S/$%31./0!7H ?21"30.HU/3/.:A G"501@AUPMSIZ=KA(IH ?./5"I$WXK?I$#1%3$2$1. The <features>-element defines preprocessing symbols.:=\$37S1.1H ?I#1G$.xml In devices./5"45C3^(5/.FG1%37?I21"30./0!7HN1."!"+$5$38(%":1@AR"G"S5"32/."!"+$5$38(%":1@A\$37S1.4"&1%3HUEY$WXK?I071.:=R"G"S5"32/."!"+$5$38(%":1@AN.4"&1%3H ?."!"+$5$38(%":1@AR"G"S".S$L15A(G"501@AVTAIH ?./3/.17H ?#1G$. These can be checked in the source code for example with “//#ifdef [symbol-name]“.S$L15A G"501@AVTA(IH ?.:=R"G"S"."!"+$5$38(%":1@AN/23C". Several features need to be separated by comma: ?21"30.HJ/-$"ITTKK?I$#1%3$2$1.1S5"32/.-"&1A(G"501@A::"!$^(+3"!$^(C:"!$A(IH ?.1H ?$#1%3$2$1.4"&1%3H ?&.

The <files> element defines the names of the library on the filesystem.xml defines some common libraries.$!3$/%H ?%":17H%/-$"40$^%/-$"0$^(%/-$"0$"!$?I%":17H ?2$517H%/-$"40$=b".xml file with each update of J2ME Polish. ?"!$7H ?"!$H ?%":1HJ/-$"(O71.(#"3"(1L.37S/5$7B`0$@A3.1(aSP?I%":1H ?#17. You do not need to add every API you or your device supports.(P%31./0!7HN1./0!7H(defines 2 groups for the device.1(aSP(!.1#(#./G$#17 7/:1("#G"%..3$/%"5$3$17= ?I#17. The <name> element describes the default name of a library..xml The file apis.$!3$/%HYB1(\5013//3B(aSP(!. You can define your own devices in the custom-devices. The custom-devices.(P%31.2".xml file with each update of J2ME Polish.The Device Database belongs are in a comma separated list: ?&. J2ME Polish tries to find the API with the help of the file-names defined in the <files> element.xml file.3IbZ:14+3"!$=b".?I!"3BH ?I"!$H ?"!$H ?%":1H\5013//3B(aSP?I%":1(H ?#17. 25 . The “supportsPolishGui”-attribute overrides this calculation. The <device>-Element supports the single attribute “supportsPolishGui”: ?#1G$.(+5013//3B( #1G$./G$#17 20%. The customapis.^(%/-$"0$=9$!?I2$517H ?!"3BH$:!/.. apis.17= ?I#17.?I!"3BH ?I"!$H ?I"!$7H In the above example two libraries are defined. This allows you to use your own libraries without needing to merge the apis.^(+5013//3B=9$!?I2$517H ?!"3BH$:!/.3$/%"5$3$17(2/. but if a API is known under several names.2". the device supports the GUI."C$%&(20%.3I%/-$"40$=b". whereas the <names> element defines other possible names of the library.xml file. Groups can also be defined indirectly by the capabilities of the device.xml. When that path is not found./0!?I&.$!3$/%H ?%":17H+3"!$^+34"!$^(+5013//3B^(+5013//3B4"!$?I%":17H ?2$517HbZ:14+3"!$=b". it is advised to add that API to apis.$!3$/%HYB1(J/-$"(O71.$17TK^(N/:1`.xml file is loaded from the current project folder and – if that file doesn't exist – from the J2ME Polish installation folder.01AH=== Normally it is calculated whether a device supports the J2ME Polish GUI: when it has a color depth of at least 8 bits per pixel and a heap size of 500 kb or more. The <path> element just defines the default path..B"%&1(C$3B(/3B1. This allows you to use your own devices without needing to merge the devices.xml file is loaded from the current project folder and – if that file doesn't exist – from the J2ME Polish installation folder. You can define your own libraries in the custom-apis.1(70!!/.

8 = 256 colors.ScreenSize. polish.0 or MIDP/2.midp1 or polish.ScreenWidth.BitsPerPixel.CameraResolution..CameraWidth. The disadvantage is that you need to backup these files when you upgrade your J2ME Polish installation. Symbols: polish.320x 200 polish. You can store these files either in the root directory of your project (the same place where the build.777.xml file lives) or in the ]C4'1. Variable: polish. polish.The Device Database Extending the Devic Database You can extend the device database by either modifying the custom-devices.ScreenHeight.1 or polish.4.200 - CameraResolution Resolution of the camera. customvendors.xml and custom-apis.xml. 16 = 65. JavaPlatform The supported Java platform. polish.)'(%K3*.g.216 colors Width times height of the screen resolution in pixels. The advantage of storing the files in the installation directory of J2ME Polish is that you always have the very same device definitions.BitsPerPixel. but following categories are predefined: Capability BitsPerPixel Explanation Color depth: 1 is monochrome. Please consider to submit your changes to the J2ME Polish community by sending them to SH-.BitsPerPixel. 24 = 16. “176 x 208” Preprocessing-Access Variable: polish.BitsPerPixel.CameraWidth.176x208 polish. polish.CameraResolution.ScreenWidth.xml.8K3K'-.4'1.8Ks.JavaPlatform Symbols: polish.ScreenSize.0.16 etc Variables: polish.176 polish. You can use capabilities with any name.320 polish.g.536 colors. Device Capabilities The device database of J2ME Polish supports a number of capabilities. Variables: polish.ScreenHeight Symbols (example): polish.xml. Currently either MIDP/1. 4 are 16 colors. which are useful for preprocessing and the assembling of resources. ScreenSize. custom-groups.Odirectory.CameraHeight Symbols (example): polish.4+ and BitsPerPixel.8 Respectively the screensize of the target device. polish.Like ScreenSize Canvas.208 Groups At 8 bits per pixel for example: BitsPerPixel. e.176x208 or ScreenSize.128x128 ScreenSize CanvasSize Width times height of an MIDP. e.midp2 midp1 or midp2 26 .CameraHeight.

All MIDP/2.JavaProtocol. mmapi - Groups cldc1.g.HeapSize Variable: polish.midi polish.3gpp polish.cldc1.midi polish. All MIDP/1. “3GPP. JavaPackage Supported APIs.g.video. Example: 3gpp mpeg-4 The supported video formats of Variable: the device.0 or CLDC/1. “Symbian OS 6.api. “midi. e.1 Respectively the name of the supported API.VideoFormat 4” Symbols (examples): polish. nokia-ui or mmapi (one group for each supported API).VideoFormat.SoundFormat.api.polish.SoundFormat. MPEG.The Device Database Capability Explanation Preprocessing-Access Variable: polish.audio.JavaProtocol Symbols (example): polish. e. “nokia-ui. Variables: polish. e.JavaPackage Symbols (example): polish.mmapi JavaProtocol Supported data exchange protocols. Currently either CLDC/1.g.3gpp polish.mpeg-4 polish.JavaProtocol.0 or polish. The maximum heap size.g. e. “500 kb” or “1.1.VideoFormat.SoundFormat Symbols (examples): polish.1” Variable: polish.g. “100 kb” or “2 MB” The operating system of the device.audio. wav” Variable: polish.JavaConfigiration Symbols: polish.0 or cldc1.video. Example: midi wav 27 .OS HeapSize MaxJarSize - OS VideoFormat One group for each supported video format.g. e.g.api.https Variable: polish.0 devices support additionally the HTTPS protocol. Example: nokia-ui. e.mpeg-4 The sound formats which are supported by the device.wav polish.1 JavaConfiguration The supported Java configuration. e.serial polish.2 MB” The maximum size of the MIDlet-JAR-bundle.wav SoundFormat One group for each supported audio format.nokia-ui polish.0 devices support the HTTP protocol.MaxJarSize Variable: polish.cldc1. mmapi” polish.

xml file: ?f44(YB$7(2$51(. “deviceRequirements” and “build”."55(A"%3(3173(bZ:1!/5$7BA(3/(7-$!(3B1(/+207. The process is controlled by the build.3I1%/0&B4bZ:1!/5$7B4 +0$5#=b"./&0"./..'$:!/.5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A( ./%3.home”-property.15177(Y//5-$3($%73"551#(((44H ?f44(8/0(%11#(3/(#12$%1(3B1(A!. optimized application-bundles from the source code./:(3B1(.&13^((((((44H ?f44(CB$.1"31#("%#(7/(/%=((((((((((((((((((((((((((((((((((((44H ?f44((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44H ?f44(P:!/.3"%3(3".(CB"3(#1G$./57(2/. The J2ME Polish-task is separated into the sections “info”."%(((((((((44H ?f44(.177=((((((((((((((((((((44H ?f44(YB1(:/73($:!/./!1.1G1. which is situated at the root of the project. Example The following example shows a complete build.3I!.17(3B1("!!5$.3"%3'(CB1%(8/0(B"G1(%/(d$. You can find a short introduction to Ant in the appendix on page 191.5"77!"3B@A$:!/."3$/%(7B/05#(((44H ?f44(+1(.B(.#=b".xml file.$+031(((((((((((((44H ?f44(/2(3B1(?+0$5#H4151:1%3(/2(3B1(RZUF(S/5$7B(3"7-=((((((((((44H ?f44((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44H ?f44(dB1%(8/0(./%3."3$/%(((((((44H 28 .AIH Now you can use the 2ME Polish-Task under the name “j2mepolish”. You need also define where to find the Wireless Toolkit by defining the Ant-property “wtk. During the build following steps are accomplished: " " " " " " " Selection of the supported devices Assembling of the resources Compilation of the application Obfuscation and shrinking of the compiled code Preverification Creation of the JAR and JAD files Preprocessing of the source code.'$:!/.3Ib#/:=b".The Build Process The Build Process Introduction The build process creates “ready to deploy”. This file is a standard Ant file which is used to control the J2ME Polish-task.xml file: ?3"7-#12(%":1@AbZ:1!/5$7BA(. optimizing for the device } for each selected device Definition of the J2ME Polish-task You need to define the J2ME Polish-task in the build.&13($7(3B1(bZ:1!/5$7B43".home”: ?!.38(%":1@AC3-=B/:1A(G"501@A6'cdYeZ=VA(IH On a system without the Wireless Toolkit (like Mac OS X) you can still use J2ME Polish by defining the preverify-attribute of the <build>-element instead of using the “wkt./57(3B1(+0$5#(!./::"%#45$%1^(8/0(.$28A4"33."55(a%3(2.

&13(+0$5#7("%#(/+207.(B"%#7137=(((((((((((((44H ?f44(YB1(#12"053(3".(2/.13.AIH ?f44(+0$5#(3".O.8((((((44H ?f44(.17(44H 29 .J":1@AF%/0&B(N/23C"./551./&0".&13(%":1@A$%$3AH (( ?!."55$%&(3B1(#12"05343".3I!.( (((((.A( (b".38(%":1@A3173A(G"501@A3.1A ($%2/O.3$/%7'(((((((((((((((((((((((((((((((((((((((44H ?f44((((V=(YB1($%2/471./b1.$!3$/%@Aa(7":!51(!.&13(3B1(RZUF(S/5$7B(3"7-($7(071#=(((((((((((((44H ?f44(P3(B"7(X(71./%3."5(7133$%&7(44H ?$%2/ (5$.(b073(A"%3A(2/.1=(a55(.(3B1(RZUF(+0$5#(!./%3./%@A$.B//717(3B1(#1G$.&13(./&0".$&B37(.3$/%(#12$%17(7/:1(&1%1.30"5(+0$5#((((((((44H ?f44(((((((!.$&B3@A6/!8.'$:!/."551#(G$"(A"%3(<%":1>A^( (((((1=&=(A"%3(.&13H ?3".&13(44H ?3".J":1./.1.'$:!/.15177(Y//5-$3=(((((((((((((((((((((((((44H ?!.5@AB33!'IICCC=bZ:1!/5$7B=/.5"77!"3B@A$:!/.(CB$.$!3$/%@AYB$7($7(3B1(./!1.:"3$/%((44H ?f44((((Z=(YB1(#1G$.3( %":1@A1%/0&B4bZ:1!/5$7B41L":!51A( #12"053@AbZ:1!/5$7BAH ?f44(YB1(C3-=B/:1(!.3$/%(.1"558(C"%3(3/(-$55(:1kA( IH ?f44(7151.01A(IH ?I3"./!1./%3"$%$%&(3B1(d$.41L":!51=b"../.'$:!/.&A ($./%=!%&A (b"./!1.177=(((((((((((((((((((((((((((((((((((((((((((44H ?3"."317(3B1(1L":!51=((((44H ?f44((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44H ?f44(YB1(2055(#/.(21C1."%(+1(."%(+1(2/0%#("3(((((((((((((((((((44H ?f44(B33!'IICCC=bZ:1!/5$7B=/.17(44H ?f44(((((((2/.3Ib#/:=b".51"%A^(A"%3(%/3173(bZ:1!/5$7BA(/.&137^(1"./57(3B1(".#=b".5@Aij!/5$7B=b"..$&B3(ZKKh(F%/0&B(N/23C".B(3B1("!!5$.38(7B/05#(!/$%3(3/(3B1(#$.1:1%37471.177=A( H ?bZ:1!/5$7BH ((((?f44(&1%1.G1#=A (#151316/%2$.3A (G1%#/./!8./!1.The Build Process ?f44("%#(3/(+0$5#(3B1(1L":!51(2/.&13H ( ?f44(P%(3B$7(3".&13(%":1@AbZ:1!/5$7BA( #1!1%#7@A$%$3A #17.31#(#1G$.A (.1]1g0$.3$/%(/2(70!!/.5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A( .&((((((((((((((((((((((((((((((((44H ?f44((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44H ?f44(["G1(20%f((((((((((((((((((((((((((((((((((((((((((((((((44H ?!./b1.J":1@Aij!/5$7B=G1%#/.38(%":1@A3173A(G"501@A2"571A(IH ?I3".4ij!/5$7B=%":1.#=b".171.38(%":1@AC3-=B/:1A(G"501@A6'cdYeZ=VA(IH ?f44(M12$%$3$/%(/2(3B1(RZUF(S/5$7B(3"7-'((((((((((((((((((((((44H ?3"7-#12(%":1@AbZ:1!/5$7BA(."5($%2/.7$/%@AV=X=hA (#17.3$/%(."3$/%($7(/!3$:$91#=((((((((((((44H ?f44((((X=(YB1(+0$5#471.3/.0:1%3"3$/%(.1%71@A`SDA (%":1@ARZUF(S/5$7BA (G1.3I.B(3".3I1%/0&B4bZ:1!/5$7B4 +0$5#=b".&13(%":1@A3173A(H ?!..:@AM/(8/0(.

"31(CB1%(3B1(31734!.01(44H ((?#1+0&($2@A3173A(7B/CD/&E%F.(!"331.%A(IH ((?I#1+0&H ((?f44(071.01A( 51G15@A1.1:1%37(C$55(+1(071#($%731"#=(44H ?#1G$.01A(G1.$.01(44 H ( ((?/+207.$"+517H ((?f44(/+207.11%@A:1%0A (071S/5$7B`0$@A3.1g0$.."3/.1]1g0$.%@A#1=1%/0&B=!/5$7B=1L":!51=nA(51G15@A#1+0&A(IH ?2$531.1:1%37H ((((?f44(+0$5#(7133$%&7(44H ?+0$5# (78:+/57@AFL":!51N8:+/5^(a%/3B1.I:$#!Z^(`1%1.A(G"501@AJ/-$"IXT)K^(J/-$"ITTKKA( IH ?I#1G$.%@A#1=1%/0&B=!/5$7B=0$=nA(51G15@AC".(.$.$17TK^( J/-$"IN1.8A(G"501@A`":1A( $2@A!/5$7B=&./`0".1]1g0$.1:1%37(0%5177@A3173AH ?./."55(<"%3(.$17hKA(IH ((?Ib"#H ?I+0$5#H ?IbZ:1!/5$7BH ?I3".17/0.17M$."31&8@A2/.1g0$.H ?"%#H ?.(0%5177@A3173A(%":1@AS.(#1G$.H (44H ?I#1G$.(!.( 30 .I:$#!VA(IH ?f44(/%(.1:1%3(%":1@AR"G"S".$"+517H ( ?G".@A3.$+0317(.@A./.1g0$./!1.1&.50#1(#1+0&(7133$%&(CB1%(3B1(31734 (!.(!"331.-"&1A(G"501@A%/-$"40$A( IH ?.+/71@A3./05#(071(/3B1.1:1%3(%":1@AP#1%3$2$1.177$%&((44H ((?G".01A (.$17TKU$#!Z^(`1%1.1:1%3(%":1@A\$37S1.A(G"501@AJ/-$"IN1.&13(%":1@A.The Build Process ?f44(P%(3B1(3173(:/#1(3B1("!!5$..1"5(+0$5#7^(1=&=(' ?/.51"%A( (( ((#17.1!..1:1%3(%":1@AP#1%3$2$1.1:1%37H ?#1G$.$!3$/%@A"55/C7("(.38($7(3.(3B1((44H ?f44(J/-$"IXT)K("%#(3B1(TTKK(!B/%17^(/3B1.$"+517(4(071#(2/.&13H ?3"."3$/%($7(+0$5#(/%58(2/.FL":!51A ($:"&1D/"#N3.S$L15A(G"501@AVTlA(IH ?I"%#H ?I/.$+031(%":1@AJ/-$"4UPM51346"31&/.5A( G"501@AB33!'IICCC=1%/0&B=#1I0!#"31A(IH ?G".#A(IH ((?f44(#1+0&(7133$%&7'(/%58($%./.38($7(3./0!=N1.$"+51(%":1@A3$351A(G"501@ARZUF(S/5$7BA(IH ((?IG".17(2/./!1..1g0$.AH ?2$531.1]1g0$.51"%(+0$5#=(o/0(7B/05#(.17A (H ((?f44(:$#5137(#12$%$3$/%(44H ((?:$#513(.34C$#1(G".(#12$%1#(RaM("33.C$71((44H ?f44(3B1(71.1]1g0$."3/..5"77@A#1=1%/0&B=!/5$7B=1L":!51=U1%0U$#513A(%":1@AFL":!51A( IH ((?f44(!.$"+51(%":1@A0!#"3140.51"%>(CB1%1G1./0%#A (20557./b1./%#(#1G$.1]1g0$.1:1%37($2@A3173AH ?.'(#/%m3(/+207."%("57/(+1(071#'(44H ((?b"#H ?"33.

or the commercial license key.G1#=A ((((#151316/%2$.[minor]. This allows controlling the build-script without changing it.O.17=L:5^(G1%#/.. If you call Ant without any arguments.[build].1A (((($%2/O.and MANIFEST-attributes.The Build Process 8/0(:"#1(.$&B3@A6/!8.J":1@AF%/0&B(N/23C".4ij!/5$7B=%":1. the Ant-property “test” will be set to false in the “init” target."51. The variable “MIDlet-Version” overrides this setting.A ((((. you can always use the <jad>-element./%@A$. the variable “MIDlet-Name” overrides this setting.171. Either “GPL” when the source code of the application is published under the GNU General Public License. In the example the obfuscation step is skipped when the test-property is true./!8. name version Yes Yes 31 .8A (((($.. which is a subelement of the <build>-section. The name of the project. This can be necessary after you made changes in the device database or in rare cases when there is a compile error in the J2ME Polish packages.J":1@Aij!/5$7B=G1%#/. The version of the project in the format [major]. “init”./b1. “j2mepolish” and “clean”.3H In the first section the J2ME Polish-task and the location of the wireless-toolkit are defined. If you need to set attribute which are not supported by the <info>-section.$!3$/%@Aa(3173(!.3A ((((G1%#/. followed by the build-targets “test”.$&B3(ZKKh(F%/0&B(N/23C".1%71@A`SDA ((((%":1@AN$:!51U1%0A ((((G1./%=!%&A ((((b".7$/%@AV=X=hA ((((#17.J":1. the test-property will be set to true.5@AB33!'IICCC=1%/0&B=#1I#$.A( ((((b". Also the debug messages are only included when test is true. You can force a complete rebuild by calling “ant clean”.7=L:5(/.org. which can be obtained at www.&13H ?I!.$&B37(.1=(a55(. The <info>-Section In the <info>-section general information about the project is defined.5@Aij!/5$7B=b"./0!7=L:5AH ?#15131(#$. This variable can be used to localize the application.j2mepolish.41L":!51=b". The targets “test” and “init” are responsible for entering the test mode.3$/%". ?$%2/ ((((5$. If you call Ant with the arguments “test j2mepolish”.B"%&17(3/(#1G$.4ij!/5$7B=5/.7$/%@pZ=V=VKp.(&./b1.:@AM/(8/0(. Example: G1.@A#$73A(IH ?I3".@A+0$5#A(IH ?#15131(#$.1"558(C"%3(3/(-$55(:1kA( ((((IH The information giving here is used for setting the JAD. The <info> element supports following attributes: <info> Attribute license Required Yes Explanation The license for this project.

8K3S"&\"-.8K31'#"1.8K3W. Apart from the usual J2ME Polish variables. jarUrl No The URL from which the jar file can be downloaded.O: The current locale.Ft`"-. The text which is presented to the user when he tries to delete the application. which should be called after the successful installation of the application..)*'& OZ]C4'1. or just the name of the jar-file. e.)'(%K3*.jar” for an application which has been optimized for the Nokia/6600 and uses the English locale.Z]C4'1. you can use the name of the jar-file as defined above: S"&@&1FtK994/ZZVVV3. The variable “MIDlet-Info-URL” overrides this setting. this van be used to localize the application. e.R.O: The name of the device ]C4'1. this van be used to localize the application.8K3W. The name of the vendor of this application.8K3#'()9&<O: The two letter ISO country-code. e.O: The two letter ISO language-code.8K3W.8K3W. ]C4'1. The variable “MIDlet-Delete-Confirm” overrides this setting. This can be empty when no country is defined in the current locale.g.Z-. When no jarUrl is defined. ]C4'1. “en” or “de”. this van be used to localize the application. This can be useful for tracking how many 32 copyright No deleteConfirm No installNotify No .)*'&O: The vendor of the device.8K3)"-.')O: The version of the project as defined above.g.)*'&O+]C4'1.&8. Example: S"&\"-.8K3)"-.g.98Z`"-.8K3. This is either the HTTP address.Ot0 infoUrl No The URL containing more information about the application.. “Nokia/6600” ]C4'1.8K3)"-.8K31'#"1. the jarName defined above is used.*1.)9.The Build Process <info> Attribute description Required No Explanation The description of the project. A HTTP-URL. “en” or “de_DE”. e. The variable “MIDletVendor” overrides this setting.*. when it is loaded locally. A brief explanation about what this application does should be given here.g. Copyright notice. Apart from the variables available for the jarName-attribute. Samsung or vendorName jarName Yes Yes Motorola ]C4'1. ]C4'1.8K31")%("%.&O: Vendor and device name.O+ ]C4'1.O3S"&t results into “Game-Nokia-6600-en.OZ]C4'1. e. The variable “MIDletDescription” overrides the value given here. “US” or “DE”.+]C4'1.g. the following variables are especially useful: ]C4'1. The name of the jar-files which will be created.

S$L15A(G"501@AhlA(IH ?I#1G$.*.g.1:1%37($2@A3173AH ?.-"&1A(G"501@A%/-$"40$A(IH ?.1]1g0$.1:1%37(0%5177@A3173AH ?. The user can prevent the installnotify.FtYH[$!t. This is useful only in cases. See the explanation of installNotify.')3.1g0$.#&'.1:1%3(%":1@AP#1%3$2$1.1g0$. deleteNotify No A HTTP-URL. The permissions which are useful for this application to work. Normally J2ME Polish is using the JavaConfiguration capability of the current target device for determining the correct "MicroEditionConfiguration" setting. which should be called after the application has been deleted from the device.#9'&3K994t.9.1:1%3(%":1@A\$37S1.'37')). for example. The variable “MIDlet-Data-Size” overrides this setting. *"9"D. dataSize No permissions No optionalPermi No ssions profile No configuration No The <deviceRequirements>-Section The optional <deviceRequirements>-section is responsible for selecting the devices which are supported by the application. The variable “MIDlet-Permissions-Opt” overrides this setting. You can override this by hardcoding the profile for all target devices.1]1g0$.The Build Process <info> Attribute Required Explanation applications are installed.i. When this section is omitted. The variable “MIDlet-Install-Notify” overrides this setting. This is useful only in cases.1]1g0$. uS"W"?3-. when you determine device capabilities during the runtime of the application and want to deliver one application bundle for all target devices. The variable “MIDlet-Delete-Notify” overrides this setting. The variable “MIDletPermissions” overrides this setting. Normally J2ME Polish is using the JavaPlatform capability of the current target device for determining the correct "MicroEdition-Profile" setting. You can override this by hardcoding the configuration for all target devices.1g0$. The minimum space which is needed on the device.1:1%37H In this example two alternative device-selections are defined – when the test-property is set to true 33 . e.1:1%3(%":1@AR"G"S". the application will be optimized for all known devices.1:1%37H ?#1G$. One can use the same variables as for the jarUrlattribute. e. Any device capabilities or features can be used for the device selection: ?#1G$.A(G"501@AJ/-$"ITTKKA(IH ?I#1G$. though.g. when you determine device capabilities during the runtime of the application and want to deliver one application bundle for all target devices.1]1g0$. The permissions which are needed by this application.

<and>. Series of requirements. The class which controls this requirement. of which all need to be fulfilled. or one of the base types “Size”. There are <or>. of which at least one needs to be fulfilled. Series of requirements. Either a class which extends the #1=1%/0&B=!/5$7B="%3=. only the upper <deviceRequirements>-element is used and the second <deviceRequirements>-element is ignored. of which none must be fulfilled. <not> and <xor> elements can be nested in any manner: ?#1G$. <and>. which can be used to define the requirements very flexible.-"&1A(G"501@A%/-$"40$^(::"!$A(IH 34 . of which one needs to be fulfilled.01A(IH). “4+” for a color depth or at least 4 bits per pixel. e.1:1%37H ?. <not> and <xor> elements.H ?. Example: ?. all listed requirements need to be fulfilled by the device to be selected.g.1g0$. The name of the Ant-property which needs to be “false” or “no” to use this <deviceRequirements>.1:1%3(%":1@AU"LR". “String”. deviceRequirements Required -Element requirement and or xor not Yes No No No No The actual work is done by the <requirement> element: requirementAttribute name value type Required Yes Yes No Explanation The name of the needed capability.1:1%3(%":1@AR"G"S".1]1g0$.1:1%3(%":1@A\$37S1.The Build Process (by defining it with ?!.1g0$./!1. deviceRequirements Required -Attribute if unless No No Explanation The name of the Ant-property which needs to be “true” or “yes” to use this <deviceRequirements>.g. e.38(%":1@A3173A(G"501@A3. “BitsPerPixel”.S$L15A(G"501@AhlA(IH ?/. “Int”. Without any clarification. The needed value of the capability. Explanation The requirement which needs to be fulfilled by the device Series of requirements.N$91A(G"501@AVKKl(-+A( 38!1@AU1:/.1g0$. Series of requirements. The actual requirements are defined with the sub-elements <requirement>. “Version” or “Memory”.1g0$.8A(IH The <or>.1:1%37=]1g0$.1:1%3(class.

g. 4 are 16 colors.1:1%3(%":1@AR"G"S".g.1:1%37H In this example each supported device must have a color depth of at least 4 bits per pixel. or the Mobile Media-API and the MIDP/2..0” or “MIDP/2.216 colors.0 platform. e.(q!/5$7B="!$=::"!$("%#(!/5$7B=:$#!ZrrA(IH ?I#1G$."3$/%@A(G"501@A6DM6IV=VlA(IH Needed APIs.S$L15(H@(hr("%#(qq!/5$7B="!$=%/-$"40$("%#( !/5$7B="!$=::"!$r(/.g.1:1%3(%":1@AR"G"6/%2$&0.1g0$.1g0$. ?.. “CLDC/1.1]1g0$.1]1g0$.S$L15A(G"501@AhlA(IH ScreenSize Required width and height of the display.-"&1A(G"501@A%/-$"40$^(::"!$A(IH 35 .1g0$. The following example includes the very same requirements like the above one – but only one "Term" requirement is used: ?#1G$. “100+” for at least 100 pixels. ?.1:1%3(%":1@AY1.1:1%3(%":1@AR"G"S5"32/.g.:A( G"501@Aq!/5$7B=\$37S1. Some devices do not allow the usage of the complete screen.11%N$91A(G"501@AVZKl(L(VKKlA(IH ScreenWidth The needed horizontal resolution of the display .1+”. ?.. ?.11%d$#3BA(G"501@AVZKlA(IH ScreenHeight The needed vertical resolution of the display.1:1%3(%":1@AN.1:1%37H ?.11%[1$&B3A(G"501@AVKKlA(IH CanvasSize Required width and height of the MIDP-Canvas.1g0$.1:1%3(%":1@AR"G"S".-"&1A(G"501@A::"!$A(IH ?.g. you can also use the "Term" requirement that allows you to select devices with the same power like the #if preprocessing directive. ?.536 colors.777. 24 = 16.1:1%37H J2ME Polish provides several requirements that can be used "out of the box": requirement-name BitsPerPixel Explanation Needed color depth of the device: 1 is monochrome. “120+ x 100+” for a resolution of at least 120 pixels horizontally and 100 pixels vertically. ?. Instead of using such nested requirements. e. “nokia-ui.1g0$.1g0$. Example: “4+” for at least 4 bits per pixel or “16” for precisely 16 bits per pixel.g.The Build Process ?"%#H ?. mmapi”: ?.1:1%3(%":1@A\$37S1.1g0$.1:1%3(%":1@AN.1]1g0$. 16 = 65. e. e.0+”.1:1%3(%":1@AR"G"S5"32/. “120+” for at least 120 pixels.1:1%3(%":1@A6"%G"7N$91A(G"501@AVZKl(L(VKKlA(IH JavaPlatform JavaConfiguration JavaPackage The needed platform.H ?I#1G$. e. Additionally the device needs to support either the Nokia-UI-API and the Mobile Media-API (mmapi).:A(G"501@AUPMSIZ=KlA(IH The needed configuration. “MIDP/1. 8 = 256 colors.1g0$.1:1%3(%":1@AN.1g0$. ?.:A(G"501@AUPMSIZ=KlA(IH ?I"%#H ?I/. e.1g0$.1g0$.

"3/. “200+ kb” or “1./.1g0$. ?.1g0$.(f@( J/-$"rA(IH The <build>-Section With the <build>-section the actual build process is controlled: ?+0$5# 78:+/57@A7B/CN!5"7B^(a%/3B1.177$%&((44H ?G".AH ?2$531.(!. ?.1!.1:1%3(%":1@A[1"!N$91A(G"501@AZKKl-+A(IH The vendor of the device.30"5(uu(q!/5$7B=s1%#/.77/%IStKKA(IH A feature which needs to be supported by the device. “Nokia/6600”.$"+51(%":1@A0!#"3140.1:1%3(%":1@AY1.34C$#1(G".-13A(IH The needed heap size of the device.(7133$%&7'(#/(%/3(/+207."3/."31(CB1%(3173($7(3.1:1%3(%":1@AP#1%3$2$1.1g0$.$"5^7/. You can use this flexible requirement just like the //#if-preprocessing directive in your source code./.1g0$.01(44H ?/+207./3/.%@A#1=1%/0&B=!/5$7B=0$=nA(51G15@AC". socket”: ?.g.$"+517(4(071#(2/.$.1A(G"501@AB"7S/$%31...%@A#1=1%/0&B=!/5$7B=#$.5A( ((((G"501@AB33!'IICCC=1%/0&B=#1I0!#"31A(IH ?IG".(%":1@AS.g. e.-"&1@A3.1:1%3(%":1@As1%#/.01A(0%5177@A3173A(IH ?f44(#1+0&(7133$%&7'(/%58(#1+0&(CB1%(3173($7(3.01A(51G15@A1.1g0$./5A(G"501@A71.11%@A:1%0A 071S/5$7B`0$@A3.1g0$.The Build Process requirement-name JavaProtocol HeapSize Vendor Identifier Feature Term Explanation Needed data exchange protocols.$. ?.g.A(G"501@AJ/-$"ITTKK^( N/%8F.$"+517H ?f44(/+207.01(44H ?#1+0&($2@A3173A( (G$70"5@A2"571A(G1.$"+517H ?G".77/%A(IH The identifier of the device. “serial.FL":!51N8:+/5A 20557.A(G"501@AJ/-$"^(N/%8F.1:1%3(%":1@AR"G"S.(!"331.:A( G"501@A!/5$7B=::"!$(uu(f!/5$7B=$7s$.1+ MB” ?.g.%A(IH ?I#1+0&H ?I+0$5#H Attributes of the build-Section The build-section has following attributes: 36 .1:1%3(%":1@AQ1"30.3=nA(51G15@A#1+0&A(IH ?2$531.+/71@A3. “Nokia” or “Siemens”.(!"331.5"77@AU1%0U$#513A(%":1@AFL":!51A(IH ?f44(!./`0". e. ?. e.FG1%37A(IH A preprocessing term that needs to be fulfilled by the device.01A H ?f44(:$#5137(#12$%$3$/%(44H ?:$#513(./b1.#A(071M12"053S". e.

Refer to the GUI chapter on page 93 for more details.'.OZ"4. which support the NokiaUI API.g. since variables can have conditions. Several libraries can be separated by colons ':' or by semicolons '. the GUI will be used for all devices.g. With “yes” the complete screen is used but no commands are supported. Possible values are either “no”. Remember that you need to target a specific device that has known Softkeys for this option. Possible values are either “foreground” or “background”. the libraries will be searched within the “import” folder by default. Defines whether the J2ME Polish GUI should be used at all. Otherwise always the default (“unpolishable”) commands menu is used. Currently these includes all MIDP/2. Either the name of the directory which contains binary-only libraries or the name(s) of the libraries. Defines whether the complete screen should be used for devices which support a full screen mode. Several symbols need to be separated by comma.0 devices as well as devices.FullScreen” can be set. The “background” strategy loads the images in a background-thread. “false”/”no” or “always”. “yes” and “menu”. When no path is defined. e.The Build Process build-Attribute sourceDir Required No Explanation The path to the source directory. which are not available on the phone itself. With “menu” commands can be used as well. Please compare the howto about including APIs on page 181.': [path1]:[path2]. Project specific symbols. When “always” is given. This allows a finer grained control. This mechanism can only be used for third party APIs. The “foreground” strategy loads images directly when they are requested. Alternatively the preprocessing-variable “polish. With the 37 binaryLibraries or binaryLibrary No symbols No usePolishGui No fullscreen No . “source” or “src”. after they have been defined in the ]CSH-.8K3K'-. The default path is either “source/src”.4'1. When “true” is given the GUI will be used only for devices which have the recommended capabilities (e. Device-APIs are automatically included. Default setting is “no”. You can define several paths by separating them with a colon ':' or a semicolon '. “showSplash” which can be checked with “//#ifdef showSplash” in the source code.83?-1 file. Possible values are “true”/”yes”. You can also include source-directories based on conditions when the nested <sources>-element is used instead (see below). imageLoadStrategy No The strategy for loading pictures. Default value is “true”. a color depth of at least 8 bits).

The program is usually within the “bin” folder of the Wireless Toolkit.xml-file. movies etc.0 API. Path to the devices. Defaults to “import/midp2.-&. but not all pictures might be shown right away when the user enters a screen.xml in the current folder or in enough-j2mepolish-build. Default strategy is “foreground”.1” is used.1. When the “foreground” strategy is used.jar. The path to the preverify executable of the Wireless Toolkit. in which case the target “1.xml in the current folder or in enough-j2mepolish-build. The folder which contains all design definitions and other resources like images. Defaults to “dist”. The folder into which the “ready-to-deploy” application bundles should be stored.The Build Process build-Attribute Required Explanation background strategy the felt performance of an application can be increased.3D/"#” will be defined. Path to the vendors. Defaults to apis. The definition of the imageLoadStrategy makes only sense when the J2ME Polish GUI is used (usePolishGui=”true”). The temporary build folder. Path to the apis. Path to the MIDP/2. the preprocessing symbol “!/5$7B=$:"&17=#$. By setting a different folder.xml in the current folder or in enough-j2mepolish-build.xml in the current folder or in enough-j2mepolish-build. The directory containing the sources of J2ME Polish. Defaults to groups. The folder in which the APIs are stored. unless a WTK 1.jar. defaults to “import”. javacTarget No The target for the java-compiler. Default folder is “resources”.jar”. When using the “background” strategy. This can be used for defining a preverfying program different from the standard WTK program. Defaults to devices. Defaults to vendors.xml-file.0 API. Defaults to “build”. By default the “1./0%#D/"#” is defined. Defaults to “import/midp1. Path to the MIDP/1. Path to the groups. You can also use the <resources>-subelement which allows to fine-tune the resource-assembling process as well.jar”.xml-file.jar. preverify No polishDir devices groups vendors apis midp1Path midp2Path workDir destDir apiDir resDir No No No No No No No No No No No 38 . the symbol “!/5$7B=$:"&17=+". This is used by developers of the J2ME Polish GUI itself.xml-file.x or Mac OS X is used. completely different designs can be demonstrated.2” target is used.jar.

The Build Process build-Attribute obfuscate Required No Explanation Either “true” or “false”. Defines whether the applications should be obfuscated. Defaults to “false”. Alternatively the nested element “obfuscator” can be used (see below). The name of the obfuscator. Defaults to “ProGuard”. Possible values are “ProGuard”, “KlassMaster”, “Dasho”, “YGuard” or “RetroGuard”. Alternatively the nested element “obfuscator” can be used (see below). When the compiler-mode is activated, J2ME Polish will not package the application and only process one device. This mode is useful for IDEs which support indirect compilation like NetBeans for example. You can select “Run” in NetBeans and NetBeans uses J2ME Polish as compiler, packages the application and starts the emulator - this saves valuable time during the development phase. Possible values are “true” or “false”. The compiler mode is deactivated (“false”) by default. The “compilerDestDir”-attribute defines where the compiled (and obfuscated) classes should be stored. The default target directory is “bin/classes”. Defines whether J2ME Polish should preverify the compiled classes as well. This is needed for using J2ME Polish as a compiler for the EclipseME plugin. Possible values are “true” or “false”. The preverifying is deactivated (“false”) by default. The encoding for the generated JAD and MANIFEST files, this defaults to "UTF8" like the standard mandates.

obfuscator

No

compilerMode

No

compilerDestDir

No

compilerModePrever No ify

encoding

No

Elements of the build-Section The build section supports several nested elements: <sources>, <midlet>, <midlets>, <resources>, <obfuscator>, <variables>, <debug>, <jad>, <manifestFilter> , <preprocessor> and <java>.
<sources>

The <sources>-element can be used for a finer grained control of the source-directories. This can be useful to include test classes, for example:
?7/0.,17H ?7/0.,1(#$.@A7/0.,1I7.,A(IH ?7/0.,1(#$.@A7/0.,1I3173A($2@A3173A(IH ?I7/0.,17H

sources-Attribute if

Required No

Explanation The Ant-property which needs to be “true” for the nested source directories to be used. 39

The Build Process sources-Attribute unless Required No Explanation The Ant-property which needs to be “false” for the nested source directories to be used. Explanation The directory containing Java source files. The Ant-property which needs to be “true” for this source directory to be used. The Ant-property which needs to be “false” for this source directory to be used.

source-Attribute dir if unless

Required Yes No No

<midlet> and <midlets>

The <midlet>-element defines the actual MIDlet class:
?:$#513(,5"77@A#1=1%/0&B=!/5$7B=1L":!51=FL":!51U$#513A(IH

midlet-Attribute class name

Required Yes No

Explanation The complete package and class-name of the MIDlet. The name of the MIDlet. Default is the class-name without the package: The MIDlet “com.company.SomeMidlet” is named “SomeMidlet” by default. The icon of this MIDlet. When none is defined, the icon defined in the <info>-section will be used. The number of this MIDlet. This is interesting only for MIDletsuites in which several MIDlets are contained. The Ant-property or preprocessing directive which needs to be “true” for this MIDlet to be included.

icon number if unless

No No No No

The Ant-property or preprocessing directive which needs to be “false” for this MIDlet to be included. The optional <midlets>-element is used as a container for several <midlet>-elements:
?:$#5137H ?:$#513(,5"77@A#1=1%/0&B=!/5$7B=1L":!51=FL":!51U$#513A(IH ?:$#513(%":1@ARZUF(S/5$7B(M1:/A(%0:+1.@AZA($,/%@A%/Z=!%&A ((,5"77@A#1=1%/0&B=!/5$7B=1L":!51=`0$M1:/U$#513A(IH ?I:$#5137H

<iappli>

The <iappli> or <doja> element defines the IApplication class of your DoJa release. This is only applicable when you are targeting this platform (see page 178). iappliAttribute Require d Explanation

40

The Build Process class if unless Yes No No The complete package and class-name of the main IApplication. The Ant-property or preprocessing directive that needs to be/result "true" for this iappli to be used. The Ant-property or preprocessing directive that needs to be/result "false" for this iappli to be used.

<resources>
?.17/0.,17 #$.@A.17/0.,17A 1L,50#17@An=3L3A H ?2$51713( #$.@A.17/0.,17I:053$:1#$"A( $%,50#17@An=:!XA( $2@A!/5$7B="0#$/=:!XA( IH ?2$51713( #$.@A.17/0.,17I:053$:1#$"A( $%,50#17@An=:$#A( $2@A!/5$7B="0#$/=:$#$("%#(%/3(!/5$7B="0#$/=:!XA( IH ?2$51713( #$.@A.17/0.,17I:053$:1#$"I$:"&17Iij!/5$7B=5"%&0"&1;A( $%,50#17@An=!%&A( IH ?5/,"5$9"3$/%(5/,"517@A#1^(1%A(0%5177@A3173A(IH ?5/,"5$9"3$/%(5/,"517@A1%A($2@A3173A(IH ?I.17/0.,17H

The <resources>-element can be used to fine tune the resources assembling as well as the localization of the application. When it is used, the “resDir”-attribute of the <build>-section should not be used. The <resources>-element supports following attributes: resources-Attribute Required dir defaultexcludes No No Explanation The directory containing all resources, defaults to the “resources” folder. Either “yes”/”true” or “no”/”false”. Defines whether typical files should not be copied in the application-jar-bundle during packaging. The files “polish.css”, “Thumbs.db”, any backupfiles (*.bak and *~) and the messages-files used in the localization are excluded by default. Additional files which should not be included in the JAR-files can be defined using the “excludes”-attribute. Several files need to be separated by comma. The star can be used to select several files at once, e.g. “*.txt, readme*”.

excludes

No

41

filterZeroLengthFiles No The <resources> elements accepts the nested elements <filter>. You can also use regular expressions in this attribute.amr" /> filter-Attribute excludes if unless Required Yes No No Explanation Defines which files should be excluded.g.1. ]C4'1. Imagine the situation where you have a image file in the resources directory. “en” for English and “fr_CA” for Canadian French.8K3#'()9&<O0 42 .O.audio. The Ant-property which needs to be “true” or the preprocessing term which needs result true for this filter to be used. “*.midi and polish. <localization> and <copier>: The <filter> Subelement Sometimes it is easier to exclude resources for specific devices rather than to include it for the other devices. <fileset>. but it offers the additional “if” and “unless”-attributes for allowing a fine grained control. You can use any number of <filter> elements for this purpose.8FER"18. ]C4'1.8K3)"-.&\(11g. The Ant-property which needs to be “false” or the preprocessing term which needs result false for this filter to be used.The Build Process resources-Attribute Required locales No Explanation The locales which should be supported in a comma-separated list. You can use this mechanism for removing files for specific devices or device groups.19.mid”. You can now remove that file for that specific devices by placing a file with the same name but with a length of 0 bytes into resources/Vendor/DeviceName. The most important attributes are: fileset-Attribute dir Required Yes Explanation The base directory of this fileset.O.)*'&O.audio.8K3W. The following element removes all *. The <fileset> Subelement The <fileset> behaves like any Ant fileset.>. unless you activate this by setting R. Defines whether files with a length of 0 should also be filtered.mid files when the target device supports both MIDI as well as AMR files: <filter excludes="*. This is true by default. This directory needs to exist unless you use variables in it like ]C4'1.8K31")%("%. e.mid" if="polish. You want to use that image on all devices except the Vendor/DeviceName one. ]C4'1. The standard Java locale-abbreviations are used.g. “de” for German. Alternatively the nested <localization>-element can be used. so any files with a length of 0 bytes will not be copied. e.

It supports following attributes: localizationAttribute locales Required Yes Explanation The locales which should be supported in a comma-separated list. This defaults to "false". includes if unless Yes No No Defines which files should be included. e. e. unless Explanation The name of the resource copier. Dynamic translations can be changed during runtime but require additional resources.txt”. You can chain several copiers together just by defining several <copier> elements. e.The Build Process fileset-Attribute Required Explanation and so on.g. You can register your own resource copier in 43 . copier-Attribute name Required Yes. The Ant-property which needs to be “true” or the preprocessing term which needs result true for this fileset to be included. “antcall”.g. messages dynamic No No default if unless No No No More information about localization can be found in the localization chapter on page 70. Defines whether dynamic translations should be enabled. This defaults to “messages. The Ant-property which needs to be “false” or the preprocessing term which needs result false for this fileset to be included.mid”. The default localization – this makes only sense when dynamic translations are enabled. “en” for English and “fr_CA” for Canadian French. The Ant-property which needs to be “false” or the preprocessing term which needs result false for this localization to be used. The standard Java locale-abbreviations are used. You can use any J2ME Polish preprocessing variable or Ant property in the *. “de” for German. The Ant-property which needs to be “true” or the preprocessing term which needs result true for this localization to be used. The <copier> Subelement Use the <copier>-element to transform the resources before they are packaged in the final JAR file. The file which contains the translations. “renamer” or “svgconverter”. The <localization> Subelement With the <localization>-element the internationalization of the application can be controlled.g. “*.& attribute.

@)(2"/&).xml script that should be called when using the “antcall” copier.-.99. The following renamer removes all characters that are surrounded by curly braces.&0)"-. The classpath that is used.)"-.'.R.41"#.resources..8ET U4"&"-.0#K")%.&)E0W"1(.target}: contains the target directory.=2!%)/ The “antcall” resource copier executes another target in your build. You can use this for giving your resources meaningful names while using short names in the JAR file.)% 00000000000)"-.8'(&#..*/0 ++T U4"&"-. This saves some precious space.O38.&0)"-. The target in your build.. U#'4. ! ! You can also specify your own properties by using nested <parameter> elements.9.R.%(1"&0.png.FEA<D. The file i0{ start game icon }.ResourceCopier class. The Ant property which needs to be “false” or the preprocessing term which needs result false for this copier to be used.'./).&T 44 .polish.9.88.9FE#'4<&.)/.08."&#KJ"99.FE&. for example.FEE0ZT UZ#'4.FEXC3mXOE0ZT Uv++0*.+&'$$./0++T U4"&"-.FE]C4'1.8K3)"-. ?0).)90R'&09K.&0)"-. The Ant property which needs to be “true” or the preprocessing term which needs result true for this copier to be used.0"0&.filePaths}: includes a semicolon (Windows) or colon (Unix) separated list of the files that should be copied.@)(2"/&).png will be renamed to i0.)%8E0ZT UZ#'4.home}/custom-extensions with the type “resourcecopier”.&0)"-..)9E0W"1(.xml script for copying the resources.?4&.&. The class that extends the de.resources.).99. to which the resources need to be copied ${polish.-.files}: includes a comma separated list of the files that should be copied ${polish.9.The Build Process copier-Attribute Required class is set class classpath target if unless No No No No No Explanation ${polish.enough.resources. U#'4.09K.)%8E0W"1(.41"#."&#KJ"99. You can use all (lowercase) J2ME Polish variables and properties of the current target device as well as following specific properties: ! ${polish.resources.FE&.&)0K.FE")9#"11E09"&%.).=2!%)/ Use the “renamer” resource copier for modifying the file-names of the resources before they are packaged in the final JAR.&T ?0).&0)"-.FE8.&ET Uv++0(8.04"&9809K"908K'(1*0!.0&.')0R'&0*.

or space-separated list of files (may be specified using wildcard patterns) that must be excluded. When the target device does not specify these sizes the default size for icons is 15x15 and for backgrounds 128x160 pixels.@)(2"/&).. The name of a file that contains a list of files to exclude (may be specified using wildcard patterns).i. It scales the SVG image to the appropriate size of the current target device and converts it into a PNG image.(37&2. J2ME Polish normally calls the Java compiler normally with the appropriate classpath as well as bootclasspath for the current target device.&0)"-. This defaults to the temporary build directory into which class files are written before they are obfuscated. The sourcepath to use. and :#')D. Comma.FE8W%#')W. the <compiler>-element also supports the "if" and "unless" attributes for selecting to appropriate compiler setting: compiler-Attribute srcdir destdir Required No No Explanation Location of the java files. defaults to the value of the srcdir attribute.i.java files are included when omitted.svg”). The svgconverter then uses the defined D#&. which defaults to the temporary directory to which the preprocessed files are written.. In some cases you might want to adjust the compiler settings.&E0ZT <compiler> The optional <compiler>-element can be used for specifying any compiler-arguments. of the target device for scaling such images.=2!%)/ Use the “svgconverter” for modifying SVG images of the resources before they are packaged in the final JAR. To suppress the sourcepath switch.or space-separated list of files (may be specified using wildcard patterns) that must be included. Comma. The name of a file that contains a list of files to include (may be specified using wildcard patterns). includes No includesfile excludes No No excludesfile classpath classpathref sourcepath No No No No 45 . however. J2ME Polish includes all supported libraries of the current target device by default. U#'4. The classpath to use. The svgconverter allows you to provide only one icon or background image for a variety of phones. Along to all attributes of the standard <javac>-task. all . Location to store the class files. For an background image you have to start naming your image “bg”(“bg”+whatever+”. use sourcepath="".&9.)D. for an icon start with “icon”. no files (except default excludes) are excluded when omitted.The Build Process ?0). given as a reference to a path defined elsewhere. so you can use the nested <compiler>-element.3)/+)/. The classpath to use.

J2ME Polish only enables the debugging when the <debug>-element is active for the current target device. Keyword list to be appended to the -g command-line switch. 1. defaults to false.1 or 1. If debuglevel is not specified. Indicates whether source should be compiled with deprecation information. by default.The Build Process compiler-Attribute sourcepathref bootclasspath Required No No Explanation The sourcepath to use. Asks the compiler for verbose output. defaults to off. Indicates whether source should be compiled with debug information.2). If set to off. If set to true.jar or midp2-cldc11. the value of the debuglevel attribute determines the command line argument. midp1.) Indicates whether the -nowarn switch should be passed to the compiler. defaults to off. Location of bootstrap class files. defaults to off. nothing will be appended to -g. Indicates whether source should be compiled with optimization.jar. J2ME Polish uses 1. no command line argument will be used). Generate class files for specific VM version (e. If debug is not turned on. and source. 46 bootclasspathref extdirs encoding nowarn debug No No No No No debuglevel No optimize deprecation target No No No verbose depend includeAntRuntime No No No .2). Location of bootstrap class files. given as a reference to a path defined elsewhere. defaults to off.2 by default when the WTK 2. This will be ignored by all implementations except modern and classic(ver >= 1. The target can also be set with the "javacTarget"-attribute of the <build>-element. (Note: gcj doesn't support this option yet. Legal values are none or a comma-separated list of the following keywords: lines. Whether to include the Ant run-time libraries in the classpath.g.. vars. defaults to no.g. e. Encoding of source files. J2ME Polish uses either the platform specific library files for the bootclasspath. Enables dependency-tracking for compilers that support this (jikes and classic). -g:none will be passed on the command line for compilers that support it (for other compilers. Location of installed extensions. given as a reference to a path defined elsewhere.x is used. this attribute will be ignored.

gcj or sj. Since Ant 1. ignored otherwise. will be used. If this attribute is not set.3. defaults to no.The Build Process compiler-Attribute Required Explanation Whether to include the default run-time libraries from the executing VM in the classpath. Value of the -source command-line switch. Defaults to the compiler of the Java version that is currently running Ant. defaults to true.3 VM) and jikes.3" source switch will be used. Indicates whether the source files to be compiled will be listed. 81920k.4 and 1. jvc. Ignored if fork="no". if javac is run externally. The Ant-property which needs to be “true” or the preprocessing term which needs result true for this compiler-setting to be used. you must make sure that your version of jikes supports the -source switch. includeJavaRuntime No fork executable No No memoryInitialSize No memoryMaximumSi No ze failonerror source No No compiler No listfiles tempdir if unless No No No No The <compilerargs> Subelement You can specify additional command line arguments for the compiler with nested <compilerarg> 47 . ignored otherwise. if set. Complete path to the javac executable to use in case of fork="yes". (Examples: 83886080. 1. if javac is run externally. will be ignored by all implementations prior to javac1. The initial size of the memory for the underlying VM. 81920k. defaults to no. the value of the build. (Examples: 83886080.compiler property. the "1. Where Ant should place temporary files. Whether to execute javac using the JDK compiler externally. The Ant-property which needs to be “false” or the preprocessing term which needs result false for this compiler-setting to be used. If you use this attribute together with jikes.4 (or modern when Ant is not running in a 1.5 – by default. defaults to no. or 80m) Indicates whether the build will continue even if there are compilation errors. Defaults to the standard VM memory setting. This is only used if the task is forked and the command line args length exceeds 4k. Defaults to the standard VM memory setting. Otherwise. Legal values are 1.6 this attribute can also be used to specify the path to the executable when using jikes. the default compiler for the current VM will be used. The compiler implementation to use. or 80m) The maximum size of the memory for the underlying VM.

J2ME Polish can move all classes to the default package for you. Defaults to “ProGuard”. “Dasho”. A single command-line argument. You do not need to adjust your <midlet>-settings. "useDefaultPackage" defaults to “false”. The name of a file as a single command-line argument.useDefaultPackage" is defined. or : as path separators and Ant will convert it to the platform's local conventions. The name of the Ant-property. No Only pass the specified argument if the chosen compiler implementation matches the value of this attribute. can contain space file or path characters. Either value. which needs to be “true” or “yes”. A string that will be treated as a path-like string as a file or path single command-line argument. this is done automatically by J2ME Polish. line. when this <obfuscator> element should be used. This includes the MIDlet-classes as well and can result in a smaller jar-size. which needs to be “false” or “no”. A single command-line argument. When the default package is used. The name of the Ant-property. adjust any <keep>-settings you have./`0". “YGuard” or “RetroGuard”. cannot contain space file or path characters. 48 useDefaultPackage No if unless No No . Please note that you are responsible for preventing name-clashes of classes.01A(0%5177@A3173A(IH obfuscator-Attribute Required name No Explanation The name of the obfuscator which should be used. line. Either value. ?/+207. “KlassMaster”. line. however. file or path will be replaced with the absolute filename of the file."3/. line.#A(071M12"053S". You need. compiler <obfuscator> The optional <obfuscator>-element controls the obfuscating of the application bundle.-"&1@A3. Possible values are “ProGuard”. Either value.The Build Process elements. the preprocessing symbol "polish. you can use . compilerargsAttribute value line file path Required Explanation Either value.(%":1@AS. which decreases the jar-size and makes it difficult to reverse engineer the application. These elements are specified like Command-line Arguments but have an additional attribute that can be used to enable arguments only if a given compiler implementation will be used. You can use this to adjust the loading of dynamic classes.

With this mechanism third party obfuscators can be integrated easily (compare page 157). 49 . The <parameter> Subelement The <parameter>-element is used to specify parameters for the obfuscator.. The class which controls the obfuscator.5"77@A."3/.=N/:1M8%":$.(0%5177@A3173A(1%"+51@A3. The classpath for this obfuscator. since they are saved from obfuscation automatically./`0".forName(."3/."3/.":131.$!3Q$51A(G"501@A==I7..M8%":$.. This can be useful for integrating third party obfuscators which require additional settings (see page 157): ?/+207. The used MIDlet classes do not need to be set with the <keep> element.=N/:1M8%":$../:=."3/./:!"%8=#8%":$. This is useful for integrating a third party obfuscator. with Class.65"77A(IH ?-11!(.5"77@A.(can be used.65"77A(IH ?-11!(.65"77A(IH ?!"./:!"%8=#8%":$. All active obfuscators are combined by J2ME Polish.The Build Process obfuscator-Attribute Required class No Explanation when this <obfuscator> element should be used.5"77@A.01A(%":1@AS.(%":1@A7./:!"%8=#8%":$.=a%/3B1.) ) and should not be obfuscated: ?/+207."3/./:=."31=7./:=.M8%":$.H parameter-Attribute Required name value Yes Yes Explanation The name of the parameter. The value of the parameter./`0".H keep-Attribute class Required Yes Explanation The full name of the class which should not get obfuscated.#A(H ?-11!(.=a%/3B1./:=.g.$!37I/+207. The <obfuscator> supports the subelements <keep> and <parameter>.(0%5177@A3173A(1%"+51@A3. The <keep> Subelement The <keep> element is used to define classes which are loaded dynamically (e./:!"%8=#8%":$.. Each class which extends #1=1%/0&B=!/5$7B=/+207. classPath No Any number of <obfuscator>-elements can be used in a project.65"77A(IH ?I/+207.#A(H ?-11!(.5"77@A.01A(%":1@AS.$!3A(IH ?I/+207."31=E+207.

01A(%":1@Ao`0".#.3Ib#/:=b".$012.jar or the original yguard.(0%5177@A3173A(1%"+51@A3.01A(%":1@AS.":131.xml): ?3"7-#12(%":1@AbZ:1!/5$7BA( .5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A( .3I1%/0&B4bZ:1!/5$7B4 +0$5#=b".jar-file is listed in the classpath of the J2ME Polish task-definition (build. If you want to use ProGuard as an obfuscator."3/.'ij!/5$7B=B/:1. J2ME Polish will then use the obfuscated output of one obfuscator as input for the following obfuscator. Specific Obfuscator Settings A/2B"'/- ProGuard is an excellent obfuscator.3)42.3Ib#/:=b".(%":1@A/!3$:$91A(G"501@A3. ProGuard 3.QZP1'#"1.QZ'!R(8#"9.5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A( . The optimization can be enabled by setting the “optimize”-parameter to “true”: ?/+207. it only needs to be specified on of the <obfuscator> elements.#A(IH 50 .I$:!/.I$:!/. This file is useful if you get exceptions in the obfuscated application.'!"#$%&'()($*+. please make sure that the proguard.The Build Process Combining Several Obfuscators Several obfuscators can be combined just by specifying several <obfuscator> elements.5"77!"3B@Aij!/5$7B=B/:1.1*ZPW.x offers an additional optimization of the bytecode.01A(IH ?I/+207.-&*#$.AIH The yGuard obfuscator can be used by setting the name-attribute of the <obfuscator>-element to “YGuard”: ?/+207.36%&7)42."3/."3/.'ij!/5$7B=B/:1. When the <keep> subelement is used.W./-#.H A text-file which lists all renaming operations is written to !(.5"77!"3B@Aij!/5$7B=B/:1.3I1%/0&B4bZ:1!/5$7B4 +0$5#=b"..R'&%.jar is listed in the classpath of the J2ME Polish task-definition (build.)*'&QZP*./-5012./`0".(0%5177@A3173A(1%"+51@A3.I$:!/. If you want to use yGuard as an obfuscator. please make sure that either the yguard-lib.-&*#$. which are licensed under the GNU Lesser General Public License.'!"#$%&'()($*+.')+-"439?9. The full obfuscator is freely available from K994/ZZVVV3<V'&$83*. It is freely availabe under the GNU General Public License and can be downloaded from K994/ZZ4&'%("&*38'(&#. shrinker and optimizer by Eric Lafortune. which is disabled by default. :B"'/- The yGuard obfuscator by the yWorks GmbH is another interesting obfuscator and code-shrinker.I$:!/.xml): ?3"7-#12(%":1@AbZ:1!/5$7BA( .9.AIH You can use ProGuard by setting the name-attribute of the <obfuscator>-element to “ProGuard”. J2ME Polish includes the library-classes.3).#A(H ?!".

jar”.D$'((E'(+)/ KlassMaster is a commercial obfuscator available from Zelix Pty Ltd.H F'(0G. A free evaluation version can be requested at K994/ZZVVV3i."3/.'ij!/5$7B=B/:1.(0%5177@A3173A(1%"+51@A3.01A(%":1@A]13. q. It can be activated by setting the .)"!1.1”.9&'1'%.1. When the DashO Pro obfuscator is used..')-parameter.3Ib#/:=b".4 needs to be on the classpath: ?3"7-#12(%":1@AbZ:1!/5$7BA( .g1'Vp!R(8#"9. but the application-size as well. A free evaluation version can be requested at K994/ZZVVV34&.!"</=)($* +. " p!R(8#"9.The Build Process @)+/2B"'/- RetroGuard is the basis of both yGuard and ProGuard and was developed by Retrologic Systems/Mark Welsh. It is deactivated by default.#A(IH C)$%*.. therefore.g1'Vp!R(8#"9.3#'-.g1'Vp!R(8#"9. .(0%5177@A3173A(1%"+51@A3."3/. therefore both the wxA3S"& as well as the $.)"!1.49g. The current default version is “3.01A(%":1@Ae5"77U"731. You can use RetroGuard just by setting the “name”-attribute to “RetroGuard”: ?/+207.1. This is deactivated by default. “none” or “aggressive”."3/. It can be downloaded from K994/ZZVVV3&.-</=%&7-=+>?)@&#AIH The KlassMaster-integration allows several parameters to be set: " . The DashO Pro obfuscator supports following parameters: " " " B"8K'M'-.-&*#$.I$:!/.g.(%":1@AE+207. The following example shows a possible invocation of KlassMaster: ?/+207./`0".A(H ?!".&8. This parameter takes precedent above the .3I1%/0&B4bZ:1!/5$7B4 +0$5#=b". either the Ant property “dasho.'): the flow-obfuscation increases the security of the application."31Q5/CD1G15A(G"501@A%/%1A(IH ?I/+207.#3#'-./-89:)42.: The file containing the full script can also be set. e. The KlassMaster integration is based on the WTK-mechanism for calling obfuscators.)"!1.5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A( . DashO will obfuscate the application flow as well.g1'Vp!R(8#"9.home” or the parameter “DashoHome” needs to be given.'): needs to correspond to the used version of DashO.'): when “true” is given.A/2 DashO Pro is a commercial obfuscator by Preemptive Solutions.5"77!"3B@Aij!/5$7B=B/:1.W. It is licensed under the GNU Lesser General Public License and is included in J2ME Polish by default.?3#'-.'!"#$%&'()($*+.":131.)W3i. In that case please note that the " source-jar-file is always the “build/source.g1'V=.')-parameter to “true”. D#&.-49.W.I$:!/.jar” and the target-file is the “build/dest. The classpath does not need to be modified.1: The obfuscation-flow level can also be set directly.: needs to point to the installation directory of the DashO Pro obfuscator.)"!1. 51 .

1. several problems ranging from preverification/linking-errors to NullPointerExceptions in the JODE-API can occur.I$:!/. It is licensed under the GNU General Public License and is available at K994/ZZS'*. J2ME Polish will create a default script.AIH JODE supports the “ScriptFile”-parameter which can be used to specify the obfuscator-script. all possible classes will be renamed.-. " .'): when “true” is given.: The file containing the full script can also be set.jar”.jar”: ?/+207./-A$3+6B)B)C6 #."3/.i"9.7$/%A(G"501@AX=VA(IH ?I/+207.R'&%.-&*#$.49g.3Ib#/:=b".(%":1@As1.5"77!"3B@Aij!/5$7B=B/:1.^.49. Maybe someone with more experience with JODE can provide help here – please get in touch with j2mepolish@enough.)%: when “true” is given.jar” and the target-file is the “build/dest. Depending on the application and environment. " D#&.1*ZPW.H HGFI JODE is quite a powerful optimizer.QZP1'#"1.+B)42. please make sure that the jode-jar-file is on the classpath: ?3"7-#12(%":1@AbZ:1!/5$7BA( .)"!1.W.)"-.":131. Since this decreases the performance.'ij!/5$7B=B/:1.)"!1.jar” and the target-file is the “build/dest.(0%5177@A3173A(1%"+51@A3. If you want to use JODE.'!"#$%&'()($*+. In that case please note that the source-jar-file is always the “build/source.'): when “true” is given.":131.(0%5177@A3173A(1%"+51@A3. Strings will be obfuscated by DashO as well.9 free of charge. <variables> and <variable> The optional <variables>-element contains several variable definitions. it is deactivated by default.3). " .01A(%":1@AR/#1A(H ?!". This is activated by default.":131.3I1%/0&B4bZ:1!/5$7B4 +0$5#=b"."3/.p49. This file is useful for resolving stacktraces in the obfuscated application.')+-"439?9. This is only visible when a decompiler is used.)*'&QZP*.5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A( .$!3Q$51A(G"501@A/+207."31=b/7A(IH ?I/+207.(%":1@AN.38'(&#. " 7')89")9J''1>"%: a tag which will be added to all processed classes. shrinker and obfuscator by Jochen Hoenicke.D9&.H When no script-file-parameter is present."3/. A report about the renamed clases as well as methods will be written to !(.IM"7BES. This example shows the integration of DashO Pro: ?/+207. which can be used for the 52 .The Build Process " . the byte-code will be optimized by DashO.I$:!/.01A(%":1@AM"7B/A(H ?!". Please note that the source-jar-file is always the “build/source./vX=VA(IH ?!".(%":1@AM"7B/[/:1A(G"501@AIB/:1I071.)"!1. This feature is activated by default.de.)%I)#&..#."3/.QZ'!R(8#"9.

50#1a%3S.=7!5$3P:"&1A ((((G"501@A3. This mechanism can be used for example to define configuration values: ?G".$%&(0. if unless No No Variables which have been defined in this way can be included into the source code with the “ZZnF” preprocessing directive and can be checked with the “PW"&. In the file the variable-names and -values are separated by equals-signs (=). includeAntProperties No The <variables>-element contains an arbitrary number of <variable>-elements.3$17@A3./!1. When “true” all Ant-properties will be included and can be used in the preprocessing.R. Empty lines and lines starting with a hash-mark (#) are ignored. The Ant-property which needs to be “true” or the preprocessing term which needs result true for this variable to be included.(@@(J/-$"A(IH ?IG".+)"-.$"+517H variables-Attribute Required Explanation Either “true” or “false”./:I0!#"31A* IIw1%#$2 Variables can also be compared.R-directive on page 79 for more information."!1. please refer to the description of the n. Defaults to “false”. Explanation value The value of the variable. which define the actual variables.5(.$"+51(%":1@A0!#"3140.5(@(AB33!'IICCC=#12"053=.$"+51(%":1@A!/5$7B=Y$51#D"81. file The file which contains several variable-definitions. Each variable needs the attributes name and value: variable-Attribute name Required Yes unless file is used Yes unless file is used No The name of the variable.The Build Process preprocessing.).5A(G"501@AB33!'IICCC=1%/0&B=#1I0!#"31A(IH ?G". 53 .*” symbol: IIw$2#12(0!#"3140. The Ant-property which needs to be “false” or the preprocessing term which needs result false for this variable to be included.$"+517($%.5'#12$%1# IIw@(N3.$%&(0.Q/*.01AH ?G".A* IIw1571 N3.5(@(Aij(0!#"3140.01A( (((($2@A!/5$7B=s1%#/.

. An exception is logged by printing out a message which is followed by a plus and the exception variable: IIw#1+0&(1. When the verbose mode is enabled.% N8731:=/03=!./:!"%8=!". class-name and line-number will be included in each debugging message. Either “true” or “false”. when the J2ME Polish GUI is used./. “fatal” or a user-defined level. N8731:=/03=!. so the performance will not be decreased.01A(G1./:=./05#(%/3(5/"#(7/:13B$%&===Ar* or IIw#1+0&(1.-"&1=U865"77A(51G15@A#1+0&A(IH ?I#1+0&H In the source code any debug messages must be accompanied by a //#debug-directive: IIw#1+0& N8731:=/03=!./.&!'8.A($2@A3173A(H ?2$531.%@A.. When “true” the log containing all logging-messages will be shown when an exception is logged.!(%q. Defaults to “false”./.8K3*..(!"331.. the preprocessing symbol “4'1./05#(%/3(5/"#(7/:13B$%&'(A(l(1r* In the chapter “The world of preprocessing” on page 82 you will find more about the debugging possibilities.$%35%qA. N8731:=/03=!. so all debugging messages will be included. debug-Attribute level Required No Explanation The general debug level which is needed for debug messages.(!"331. “error”. The debugging messages will be activated or deactivated in the source code.$%35%qA.$%35%qA$%$3$"5$9"3$/%(#/%1=Ar* or IIw#1+0&(C".The Build Process <debug> The optional <debug>-element controls the inclusion of debugging messages for specific classes or packages. When “true” the time.” will be defined.+/71@A2"571A(51G15@A1.%@A. Default level is “debug”. Possible values are “debug”. Also the key-handling and animation-handling will be monitored and error messages will be given out. ?#1+0&(7B/CD/&E%F./:!"%8=!". showLogOnError No Either “true” or “false”.-"&1=nA(51G15@A$%2/A(IH ?2$531./05#(%/3(5/"#(7/:13B$%&'(A(l( 1r* verbose No The log can only be shown automatically./:=. “warn”. “info”.$%35%qA. when the debugging is deactivated. 54 .@A3. In the verbose mode exceptions thrown by J2ME Polish will contain useful information./.

/:=70%=1L":!51=N":!516B"3^(nA( $2@A!/5$7B=:$#!ZA( IH ?Ib"#H attribute-Attribute name Required Yes unless file is used Yes Explanation The name of the attribute.$17hKA( IH (?"33. “warn”. which defines the debug-level for specific classes or packages. level Yes <jad> With the <jad>-element user-defined attributes can be added to the JAD1-file as well as the MANIFEST-file which is contained in the created JAR-file. “fatal” or a user-defined level. The name of the Ant-property.debugEnabled” will be defined. e. which needs to be “true” or “yes”.-13'II'Wt^(. “error”. “Nokia-MIDlet-Category” value The value of the attribute. The <jad> element contains a number of <attribute>-sub-elements which define the actual attributes: ?b"#H (?"33.g.$+031( %":1@AUPM5134S07B4VA( G"501@A7/.8A( G"501@A`":1A( $2@A!/5$7B=&. all classes of that package will be included.3m” The debugging level for all classes with the specified pattern. e. When the pattern ends with a star. “info”. the <debug>-element allows the sub-element <filter>. Possible values are “debug”. “#'-3#'-4")<3-<4"#$"%. filter-Attribute pattern Required Yes Explanation The name of the class or of the package. When the <debug> element is activated. when this <debug> element should be used. which needs to be “false” or “no”. 1 Java Application Descriptor 55 . when this <debug> element should be used.g./0!=N1.$+031( %":1@AJ/-$"4UPM51346"31&/.The Build Process debug-Attribute if Required No Explanation The name of the Ant-property. unless No For a finer control of the debugging process. the preprocessing symbol “polish.

by default. In the file the attribute-names and -values are separated by colons (:). “manifest” or “jad. Explanation target No if unless No No Attributes which are defined in this way can be loaded in the application with the MIDlet. Empty lines and lines starting with a hash-mark (#) are ignored.$+031( %":1@AJ/-$"4UPM51346"31&/.4O]D^(UPM5134R". You can use different filters by using the "if" or "unless" attributes: jadFilter-Attribute if Required No Explanation The Ant-property which needs to be “true” or the preprocessing 56 .^(UPM5134R"./%k^(UPM5134P%2/4O]Dk^ UPM5134M"3"4N$91k^(UPM5134n^(n (?Ib"#Q$531.. The specification says user-defined attributes should only be added to the JAD file. An user-defined attribute is added to both.The Build Process attribute-Attribute Required unless file is used file No The file which contains several attribute-definitions. the MANIFEST as well as the JAD.. much faster than the getAppProperty(. The Ant-property which needs to be “true” or the preprocessing term which needs result true for this attribute to be included.H UPM5134J":1^(UPM5134s1.H ?Ib"#H The <jadfilter> element contains all allowed attribute names in the desired order and separated by commas. Sorting and Filtering JAD attributes The JAD-attributes can filtered and sorted using the <jadFilter> subelement: ?b"#H (?"33. which needs the name of the attribute as an argument and returns the value of that argument.$!3$/%k^(UPM5134P. but there are some devices out there which expect these attributes in the MANIFEST as well. Either “jad”. The Ant-property which needs to be “false” or the preprocessing term which needs result false for this attribute to be included. therefore.8A( G"501@A`":1A( $2@A!/5$7B=&.)-mechanism../0!=N1.getAppProperty( String name ) method.4N$91^( UPM5134M17.$17hKA( IH (?b"#Q$531. Often it is advisable to use the variablemechanism of J2ME Polish instead.7$/%^( UPM5134s1%#/. manifest”. since such values are actually hard-coded into the application and are.

Please note that the first included attribute should always be the “Manifest-Version”-attribute./%k^(UPM5134P%2/4O]Dk^ UPM5134M"3"4N$91k ?I:"%$2173Q$531. Otherwise the application will most likely not work: ?:"%$2173Q$531./2$51^(U$. The Ant-property which needs to be “false” or the preprocessing term which needs result false so that this filter is used.7$/%^(UPM5134s1%#/. A star can only positioned at the end of a filter."3$/%^ UPM5134M17. name followed by UPM5134P. All remaining attributes will be included at this position.0/user_html/Ap_Attributes. 57 ./F#$3$/%46/%2$&0.. The complete name of an optional attribute./F#$3$/%4S.com/j2me/docs/wtk2..The Build Process jadFilter-Attribute unless Required No Explanation term which needs result true so that this filter is used.H U"%$21734s1./%k a questionmark UPM5134n beginning of a name followed by a star star n An overview about allowed attributes can be found at http://java.H The <manifestFilter> element contains all allowed attribute names in the desired order and separated by commas.^ UPM5134V^(UPM5134Zk^(UPM5134Xk^(UPM5134hk^(UPM5134)k^( U$. Inside of the <jadfilter> element you can specify all allowed JAD-attributes in the desired order and separated by commas.sun. Following syntax is used: jadFilter-Text name Example UPM5134J":1 Explanation The complete name of a required attribute. <manifestFilter> The manifest filter element can be used to sort and filter manifest attributes.html.7$/%^(UPM5134J":1^(UPM5134s1. You can use different filters by using the "if" or "unless" attributes: manifestFilterAttribute if Required No Explanation The Ant-property which needs to be “true” or the preprocessing term which needs result true so that this filter is used. All remaining attributes which names start with the given sequence will be included at this position.$!3$/%k^(UPM5134P..

/:!"%8=!. Inside of the <manifestFilter > element you can specify all allowed MANIFEST-attributes in the desired order and separated by commas.The Build Process manifestFilterAttribute unless Required No Explanation The Ant-property which needs to be “false” or the preprocessing term which needs result false so that this filter is used./. name followed by UPM5134Zk a questionmark UPM5134n beginning of a name followed by a star star n An overview about allowed attributes can be found at http://java.1!.$!37I!.$!3A( IH ?I!. The complete name of an optional attribute. The classpath for the preprocessor. The name of the Ant-property.1!.177/.1!.":131.A( H (?!". <preprocessor> The <preprocessor> element can be used to integrate own or third party preprocessors./.$!3Q$51A( G"501@A==I7.3I!././. Following syntax is used: ManifestFilterText name Example UPM5134J":1 Explanation The complete name of a required attribute. which needs to be “false” or “no”. .sun. which needs to be “true” or “yes”.1!.177$%&=b"..1!. This can be used for allowing new preprocessing directives for example (compare page 159)..177/. All remaining attributes which names start with the given sequence will be included at this position.html.0/user_html/Ap_Attributes. All remaining attributes will be included at this position. A star can only positioned at the end of a filter.H preprocessorAttribute class classPath if unless Required Yes No No No Explanation The class of the preprocessor././:=.com/j2me/docs/wtk2. 58 .177/./.( %":1@A7. ?!.177=U8S..A( . when this <preprocessor> element should be used.5"77S"3B@A$:!/.1!. The name of the Ant-property.5"77@A.177=7.

OEZT U"&%01.8K3S"*\"-.FE+S"&R.).name polish.FE+$.jar of the Wireless Toolkit for signing a JAD file: US"W"0S"&FE]CV9$3K'-.OEZT U"&%01. The identifier of the current device.<89'&. The following example calls the JadUtil.89Z]C4'1. The preprocessor can be configured using a number <parameter> subelements.9EZT U"&%01. The version of the application as defined in the info-section. The name of the current device.FE+$.0R'&0*.OZ!.).identifier polish. e.8K3-.%EZT U"&%01.88FE9.)9.vendor polish.).0-.RFE4'1.).*.89Z]C4'1. “unless” and “message”.983$8EZT U"&%01. “Siemens/SX1”.1').). “Siemens” or “Nokia”.#. The name of the jar-file as defined in the info-section.E0 000000 R". The name of the jad-file as defined in the info-section.%)"9(&.).*4HE0 ()1. e.89E -.version polish.FE.88"%.)4(9S"*0*.**.FE+'(94(9S"*0*.0*..OEZT UZS"W"T Following variables can be used in the <arg>-element and the “message”-attribute: variable polish.8K3S"*\"-. Each defined <java>-element is called after the successful creation of an application-bundle.8K3.R.g. J2ME Polish variables can be used in the nested <arg>-elements.html) as well as the additional attribute “if”.0]C4'1.g.)%08.FE+.FE+"1.E0 0000 .89Z]C4'1.&&'&FE9&(.apache. Each <parameter> subelement needs to define the attributes “name” and “value”. “N-Gage”."80D. which is described in the signinghow-to on page 186.W.jadName Explanation The vendor of the current device. A possible use of the <java>-element is the signing of MIDlets.FE+"**S"&8.The Build Process preprocessorAttribute Required Explanation when this <preprocessor > element should be used.)ZG"*>''13S"&E0 000000 R'&$FE9&(.org/manual/CoreTasks/java. It accepts all attributes and nested elements like the Ant-<java>-element (compare http://ant.8K3S"&\"-.&OE T U"&%01. so that the call can be adjusted for the current device.<4"880]C4"88V'&*OEZT U"&%01. <java> The <java>-element can be used to extend J2ME Polish with any Java utility.1. 59 .g. e.%)A:B1.*1.jarName polish.).

The Ant-property which needs to be “false” or the preprocessing term which needs result false when this <java>element should be executed.**=A IH A much simpler but equally valid call is this: ?!".A ".. The Ant-property which needs to be “true” or the preprocessing term which needs result true when this <java>-element should be executed. 1L1. such as ${ polish.-"&1M$.-"&1. Fork must be set to true if this option is or jar selected. A message which will be printed out on the standard output when this <java>-element is executed.**46**ij!/5$7B=!".S"3B.A(IH A possible alternative might be the Open Source tool “7-Zip”.-"&1. which can create smaller files 60 .apache.(%":1@Ab".The Build Process The most important attributes of the <java>-element are: java-Attribute classname Required Explanation either The name of the class which should be executed.html for more information about the <java>-element. classname or jar either The location of the jar file to execute (must have a Main-Class classname entry in the manifest). For using a different packaging-program. The message can contain J2ME Polish variables.G2U**ij!/5$7B=b".identifier }. the <packager>-element can be used: ?!". No No If enabled triggers the class execution in another VM (disabled by default).org/manual/CoreTasks/java.&0:1%37@A. jar fork message if No unless No The most important nested element is the <arg>-element: arg-Attribute line Required No Explanation A space-delimited list of command-line arguments. Please refer to the Ant-documentation at http://ant.03"+51@Ab". <packager> Usually the efficient internal J2ME Polish packager is used for creating the final application bundles.

).)'(%K34'1. unless executable or class is defined No No No Explanation The name of the packager. “jar” or “7za. “7zip” or “kzip”. This might result in problems on the actual device.3.=!.-U/%$3/. Often needed variables are: ]C4'1.1%.The Build Process compared to the standard ZIP mechanism. The 7-Zip tool can be obtained free of charge at http://www. class No The name of the class which extends the *.@A3.01A 1%"+51U1:/.B.7-zip. though.8U/%$3/.01A $2@A3173A H ?!".& class.$38M/:"$%@A3.@A3. The Ant target that should be used for the packaging step.@A3.exe”.17@A:81:05"3/.121.&O: the directory which contains the classes and the resources which should be “jared”. In that case further parameters can be set using nested <parameter>-elements./!1.8K3S"&J"9KO: the full path to the jar-file which should target executable arguments be created.3$17A 71.xml by using the “packager” type."5B/73'_K_KIij!/5$7B=b"#J":1.g.". “antcall”./2$51.5"77A !.0731#A 1%"+51S."%7$1%3@B33!'II5/.8K34"#$"%. The <packager>-element supports following attributes: packager-Attribute name Required Yes. e.8K3S"&3J"#$"%.1@A.home}/custom-extensions.01A 1%"+51J13C/. Any Ant-properties as well as J2ME Polish variables can be used. “jar”. so use with care. You can register your own packager in ${polish. ]C4'1.(%":1@A4xb":A( G"501@A3. C"$3@A3. Only relevant when the “antcall” packager is used.":131. Several arguments can be separated by using double-semicolons (. The <emulator>-Section The <emulator>-element is responsible for launching any emulators after the application has been build. The name of the program. e.A(IH 61 .0.01A 3. ?1:05"3/..g. The arguments for the packager when you have defined the “executable” attribute. This mechanism can be used for extending the packaging capabilities of J2ME Polish.org/.

gc”. In “trusted” and “maximum” mode all security sensitive activities are allowed.0 security-domain of the application: either "trusted".The Build Process ?I1:05"3/. Determines whether a decompiled stack-trace should be shown. Defines whether the J2ME Polish task should wait until the emulator is finished. When such a file is used. Please consult the documentation of the Wireless Toolkit for detailed information about the preferences file. Several values can be given when they are separated by comma. in the “untrusted” mode the user will be questioned before each security sensitive activity and in the “minimum” mode any security sensitive activity will not be allowed. Possible values are “class” for showing the loading of classes. when the “test”-property is “true”. therefore wait defaults to “yes”. Either “yes”/”true” or “no”/”false”. Defines if any virtual machine activities should be shown on the output. The results will be shown when the emulator itself is closed.H In the above example the emulator is only started. even when the sourcecode position of an exception could be be located. “gc” for activities of the garbage collection and “all” for a very extensive output. The MIDP/2. The file which contains the emulator-preferences. "minimum" or "maximum". When activated the performance will be profiled during the execution of the application. Either “yes”/”true” or “no”/”false”.g “class. e. When activated the memory usage of the application will be shown. This is needed when any output should be shown on the Ant-output. The automatic resolving of stack traces is discussed below. The Ant-property which needs to be “true” when the 62 trace No securityDomain No enableProfiler No enableMemoryMonit No or enableNetworkMonit No or preferences No showDecompiledSta No ckTrace if No . When any network activities are done. Attributes of the <emulator>-Section The <emulator>-element supports following attributes: emulator-Attribute wait Required No Explanation Either “yes”/”true” or “no”/”false”. a monitor will show details of the sent and received data. the profiler and monitor settings are ignored. "untrusted". Either “yes”/”true” or “no”/”false”. Either “yes”/”true” or “no”/”false”.

*1.O: The name of the JAR-file ]C4'1.8K3S"&\"-.9. This is the name which can be found in the 63 .8K3#1"88.83-.9+HO: The second MIDlet class.)%E0W"1(. e.&0)"-.9K. just define an empty value.9+)O: The nth MIDlet class. WTK Emulators For emulators which are integrated in the Wireless Toolkit the “I-(1"9'&3D$. The Ant-property which needs to be “false” when the <emulator>-element should be executed.8K3S"*\"-.9+YO: The main MIDlet class ]C4'1.xml J2ME Polish uses the device-database to determine the correct emulator. if any ]C4'1.FE+l8'-.O: The name of the JAD-file ]C4'1.*1.)”-capability is used for determining the correct emulator.83-.8K3#1"88. Emulator-Settings in the Device Database and in the build.8K3#1"88.*1. The value of the parameter. The Ant-property which needs to be “false” or the preprocessing term which needs result false when this parameter should be used. if any When only a command-line switch should be defined. U4"&"-. If an emulator cannot be started.The Build Process emulator-Attribute unless Required No Explanation <emulator>-element should be executed. you can tell J2ME Polish how to launch it by modifying these settings. the following variables are especially useful: ]C4'1.g.FEE0ZT if unless No The Ant-property which needs to be “true” or the preprocessing term which needs result true when this parameter should be used. the value can use any J2ME Polish or user-defined variable.8K3S"*J"9KO: The absolute path of the JAD-file ]C4'1.83-. The <parameter> Subelement The <emulator>-element supports the nested subelement <parameter> for defining additional command line parameters: parameter-Attribute Required name value Yes Yes Explanation The name of the parameter.8K3S"&J"9KO: The absolute path of the JAR-file ]C4'1.

”-property in the !(.?. When a Siemens-emulator should be used.)”-capability has been set in the “${polish. the emulators are started by the “GenericEmulator”.g.-(S"W"3. Some non-standard-emulators make it necessary the use the “GenericEmulator”-class instead.The Build Process “${wtk. See below for more details. The “I-(1"9'&371"88”-capability then needs to be “NokiaEmulator” and the “I-(1"9'&3D$. The “I-(1"9'&3I?. please check if the “I-(1"9'&3D$. This property needs to point to the installation directory of the Motorola SDK.#(9"!1.home}/SMTK/emulators”-directory.”.1*3?-1. “C:\program files\Motorola\SDK v.. If that capability is missing.1*3?-1. Nokia Emulators For launching Siemens-emulators it might be necessary to define the “)'$.)”-capability is found. When no “I-(1"9'&3D$.3YZ!.home}/devices.”-capability needs to define the program which should be started.-. When the wrong emulator is started. The invocation of such emulators is explained below. The “Emulator. This property needs to point to the installation directory of the “Siemens Mobile Toolkit” (SMTK) and defaults to “C:\siemens”. Launching any Emulator with the GenericEmulator-Implementation You can start any kind of emulator with the GenericEmulator class. so that the device database can be improved. for example. This property needs to point to the installation directory of the Nokia emulators and defaults to “C:\Nokia” on Windows machines and to “${user. the corresponding device-definition in the “${polish. e.)3H”.Skin”-capability needs to specify the name of the emulator. which can be found in the “${siemens. You should set the “I-(1"9'&371"88”-capability of the corresponding device-definition in the “${polish.home}/wtklib/devices” folder.)”-capabilities of the device in the “${polish.)Z. Motorola Emulators For launching Motorola-emulators it is necessary to define the “-'9'&'1"3K'-. “I-(1"9'&3D$.)”-capability needs to correspond with the name of the emulator which can be found in the “${nokia.xml” file needs to set the “I-(1"9'&371"88”-capability to “SiemensEmulator” (this is the default for all Siemens-phones).4.)83K'-.home}/devices. when several versions of an emulator do exist."3K'-. e.g.g.”-property in the !(. Since Motorola-emulators do not support the “Unified Emulator Interface”.home}/Nokia” on Unix machines.xml” file. This program is responsible for starting the emulator.4'1.)3a” and so forth. For many emulators it is sufficient to set the “I-(1"9'&371"88” and “I-(1"9'&3D$.”-property in the !(. “java” or “]C-'9'&'1"3K'-.3 for J2ME”. e.OZI-(1"9'&.)'(%K3*.1*3?-1.home}/Devices”-directory. You can also set several skins. 64 . Additional skins are defined by the capabilities “I-(1"9'&3D$.xml” file. the current default emulator will be started instead. J2ME Polish will then choose the the first emulator it finds.home}/devices.8Ks.home}/devices.xml” file to “GenericEmulator”. please report it also to SH-. Siemens Emulators For launching Siemens-emulators it might be necessary to define the “8. “SonyEricsson_P900” etc.

-.)%2oH[[5” automatically.)89&(#9.${polish.')0"90 #'-3#'-4")<3A<71"883*'D'-.W.${polish. If you execute J2ME Polish from within an IDE.-classpath. Thanks! Automatic Resolving of Stack Traces and Exceptions J2ME Polish can resolve stack traces like “I?#. so that it includes the installation directory of jad or install the jadexcecutable (jad. “-Xdescriptor. Often used is the “polish..21')%5T In the first line the actual directive is given and in the following lines the binary equivalent compiled java code is listed.jarPath”-variable. e.9K'*2oYyc5).1*00000000nYa00Ug.1*3?-1 file.exe or jad) to the “${polish.-. which does the same for the JAR-file..A.8K3#1"88.56 0000ZZ000fy00Ydc/"1'"*r[000000000 0000ZZ000ff00Yy[/%. “8&#Z#'-Z#'-4")<ZA<71"883S"W"/cy/0.9R.#0000nYy00UA. When jad is installed correctly.)W'$. Command-line arguments are separated by two semicolons in a row. 4"#$"%. These properties can then be defined within the corresponding !(. J2ME Polish will resolve stack traces automatically. In cases when J2ME Polish is not able to locate the position in the source code.xml is called first: 65 . you can click on such a message and then edit the faulty code directly.9K'*2o. Just send an email to SH-..95.)9>.*0z'&1*3").&9("1000nHa00UA.-"9.jarPath}”.g. when the free “jad” decompiler is installed. The following fragment gives an example of a decompiled class code: 000000000000V'&1*3").home}/bin” folder.-3#(&&.9+Y variable that contains the name of the first MIDlet class. When the “showDecompiledStackTrace”-attribute of the <emulator>-element is set to “true” or “yes”. when the debugging-mode is activated. even when the sourcecode position could be located.49.11..11. Please inform the J2ME Polish community about any emulators you have integrated.9K'*0W'.')'RR8.8Ks. which contains the absolute path to the JAD-file and the “polish.home” or “nokia.2D<89.&%(-. The second number from the left is the number which is given in the original error message (e. You should try to minimize the dependency on a specific system setup by using properties like “motorola.)9>.jadPath}. This extract will help you to identify the source of the error. As you can see in the example..The Build Process You need also to define the command-line arguments for the emulator with the “I-(1"9'&3.825T 0000ZZ000c[00Yyd/11'"*00000000000b 0000ZZ000cY00Yyf/18(!000000000000 0000ZZ000cH00Yyc/. In the default-setup this is done when the “test”-target of the build.jadPath”-variable.A.-3#(&&.)'(%K3*.4'1.g. any J2ME Polish-variables as well as Ant-properties can be used within the emulatorarguments. e.3#1"883-.home” in your settings. This is done by setting the “enable”-attribute of the <debug>-element to “true”. Please note that the source-code position can only be located.89"9. Also useful is the 4'1. an additional message giving the source-location as well as the faulty source code is printed out.*1. This decompiler can be downloaded at K994/ZZVVV3$4*(83#'-ZS"*3K9-1.)W'$.-.8250+01"897<#1. a decompiled code fragment will be given out for each stack-trace.1*0z'&1*0V'&1*T 0000ZZ000fc00Yya/. Instead of seeing only the rather obscure stack trace 4"#$"%..)98”-capability. an extract of the decompiled class-code will be shown instead.8(190F0-"?0Z0[6”.)90&.3#1"883-.9K.g.83-.9K'*01')%0D<89.-"9. so that other users can also benefit from your settings.>. Please adjust the PATH environment variable.

The Build Process “")909.4'1.8K”.890SH-. 66 .

png” will be used for the application which is build for the Nokia/6600 phone. the HTML-documentation also lists all groups for each device contained in the device database.W.:-"%.16+” folder. All resources will be copied to the root of the application and more specific resources will overwrite the common resources: If you have a picture named “hello.13-"4E560ZZ09K. No subfolders can be used within an application."-2EZ1. Resources for a specific device can be placed into the “resources/[vendor-name]/[device-name]” folder.18Z1. no matter from where the resource was copied from.. the folder “resources/Nokia/3650” for Nokia/3650 devices."-0. High-color images can be be put into the “resources/BitsPerPixel.8D9&.W.*/ :)4(9D9&. Here a couple of examples: 67 .. the version in the “resources” folder will be used for all non-Nokia devices.971"88253%.8'(&#. The groups can be used very efficiently to include only those resources which are actually relevant for a specific device. For more general resources the groups can be used to which a device belongs to.8D9&."9. Resources for all devices will be placed into the “resources” folder (when no other directory has been specified in the <resources>-element or with the “resDir”-attribute of the <build>-element in the “build.3#&. A device can belong to many different groups.80'$ Subfolders are merely used to differentiate between different devices and device groups.g.80. for example. e. Instead of ZZ09K. but the image “resources/Nokia/6600/hello.80. Often Used Groups For a complete list of groups please refer to the section “Device Capabilities” on page 26.xml” file)."-2EZ1. e.11'34)%E05. so it is not possible to load resources from a subfolder within the application.8'(&#.13-"4E560 the following code needs to be used: :)4(9D9&.80F0%."-0. In the application code you can load this image from the root: :-"%.9^. this is why the usage of subfolders is not allowed. which are defined either implicitly by the capabilities of that device (compare the section “Device Capabilities” on page 26) or explicitly by setting the <groups>-element of a device in the device-database.80F0%.W. are assembled automatically for each device.9^. the version contained in the “resources/Nokia” folder will be used for all Nokia devices. sound files etc. Resources for devices of specific vendors can be placed into the “resources/[vendor-name]” folder.png” in the “resources” folder as well as in the “resources/Nokia” and in the “resources/Nokia/6600” folder.g.20EZK. Subfolders do add overhead to an application.971"88253%.Resource Assembling Resource Assembling Concepts During the build process resources like images. the “resources/Nokia” folder for Nokia devices.80)'90"11'V.

g. For devices supporting the MIDP/2. FullCanvasSi FullCan resources/FullCanvasSi Folder for devices with canvasses that are as ze.176x208 of the target devices.170+x200+ large or larger than the specified canvas size in fullscreen-mode. resources for this device can be placed into the “resources/midp1” folder.1 configuration. e.0 platform.0 configuration.Resource Assembling Group Type Default Folder Explanation ScreenSize. e. resources/ScreenSize.176x208 vas ze. resources/CanvasSize. In the example the canvas needs to be at least 170 pixels wide and 200 pixel high in fullscreen-mode so that resources from that folder are included.128x128 and so on.1 ration api resources/mmapi . FullCanvasSize.0 ration Configu resources/cldc1. CanvasSize.17 Canvas 6x208 CanvasSize.g. resources/CanvasSize. When a device supports the Mobile Media API.176x208 or CanvasSize. When a device supports the MIDP/1.1 Folder for different screen sizes of the target 76x208 devices. Folder for Symbian Series 40 devices.1 Folder for devices with canvasses that are as 70+x200+ large or larger than the specified canvas size.128x128 and so on. 68 midp2 cldc1. For devices supporting the CLDC/1. e. In the example the screen needs to be at least 170 pixels wide and 200 pixel high so that resources from that folder are included. resources which need this API can be placed into the “resources/mmapi” folder. For devices supporting the CLDC/1.1 Folder for devices with screens that are as large 70+x200+ or larger than the specified screen size.1 mmapi Platform resources/midp2 Configu resources/cldc1.176x208 or FullCanvasSize. ScreenSize.0 platform.g. Series60 Series40 midp1 Platform resources/Series60 Platform resources/Series40 Platform resources/midp1 Folder for Symbian Series 60 devices. CanvasSize.170+x200+ vas ze.0 cldc1.176x208 or ScreenSize.17 Screen 6x208 ScreenSize.17 Screen 0+x200+ resources/ScreenSize.1 Folder for different canvas sizes of the target 76x208 devices.1 Canvas 70+x200+ FullCanvasSi FullCan resources/FullCanvasSi Folder for different fullscreen-mode-canvas sizes ze.128x128 and so on. In the example the canvas needs to be at least 170 pixels wide and 200 pixel high so that resources from that folder are included.

8K3"(*.R04'1.*. For devices with a color depth of at least 12 bits 12+ per color. For devices which support the WAV sound format.08'()*0.R04'1.1 colors 6 resources/BitsPerPixel. the application will contain the MIDI files as well. even though only the MP3 files 69 . For devices which support the MP3 sound format. BitsPerPixel.'3-.263 video format.R*.audio. For devices with a color depth of exactly 16 bits 16 per color. Obviously you can put all MP3files into the “resources/mp3” folder and all MIDI-files into the “resources/midi”-folder.Resource Assembling Group Type Default Folder Explanation motorola-lwt api nokia-ui wav mp3 amr midi mpeg-4 h. For devices which support the MIDI sound format. though. Imagine the situation where you have an application which uses MP3 soundfiles when the device supports MP3.263 3gpp api audio audio audio audio video video video resources/motorola-lwt For devices which support Motorola's Lightweight Windowing Toolkit-API. resources/nokia-ui resources/wav resources/mp3 resources/amr resources/midi resources/mpeg-4 resources/h. resources/BitsPerPixel.263 resources/3gpp For devices which support Nokia's User Interface API.*."* ZZn.R*. In the source code you can use the preprocessing symbols “polish.'3-4a ZZ0'$"<041"<09K.mp3” and “polish. For devices which support the 3GPP video format. For devices which support the h.R The situation is different in the resource assembling step.1 colors 2+ BitsPerPixel.)89.8K3"(*. But for devices which support both MP3 as well as MIDI sound.audio.0-4a08'()* ZZn. and MIDI soundfiles when the device supports MIDI. ZZ041"<0-. so that these resources are available when they are needed.)*. For devices which support the AMR sound format.1. For devices which support the MPEG-4 video format.midi” to distinguish between these cases: ZZn. Fine Tuning the Resource Assembling Sometimes it is necessary to adjust the resource assembling.

The <resources>-element is a subelement of the <build>-section. since this will yield unpredictable results.17 #$. so in most cases a localized application has absolutely no overhead at all compared to a non-localized application – both in size 70 .Resource Assembling are actually needed.@A.50#17@A.1*3?-1 which will be included when specific conditions are fulfilled: ?.17/0. On a final note please remember not to use the “resDir”-attribute of the <build>-element when you use the <resources>-element. Traditionally localization involved loading the localized messages from a file during runtime and retrieving these messages with Hashtable-keys.17H In the above example MIDI files are only included when two conditions are met: 1) The device supports MIDI sound 2) The device does not support MP3 sound.17/0.17/0.. Even enhanced features like locale-aware date-formatting is no problem with J2ME Polish. An often used attribute is the “exclude”-attribute which specifies any files which should not be included into the application bundle. but in several ones. The process of adjusting an application to a specific region is called localization.1"#:1nA( H ?2$51713( #$.@A.50#17@An=:$#A( $2@A!/5$7B="0#$/=:$#$("%#(%/3(!/5$7B="0#$/=:!XA( IH ?I. In the above example all files starting with “readme” are excluded from the final application JAR file.17I:053$:1#$"A( $%.17/0. A unique feature of J2ME Polish is that the translations are actually directly embedded into the source-code.50#17@An=:!XA( $2@A!/5$7B="0#$/=:!XA( IH ?2$51713( #$. You can have readme-files for example with background information for designers. which is discussed in the following chapter.17A 1L. Localization Concepts Often applications should not only be marketed in one country or region. J2ME Polish offers a very powerful framework for not only managing the obvious needed translations. but also for adjusting any kind of resources like images or sounds to specific regions.17I:053$:1#$"A( $%. For such cases you can define file-sets in the !(.. This significantly slows down a localized application and also enlarges the application size. The <resources>-element is also responsible for the localization of the application. look at page 41 for detailed information about the supported attributes as well as the nested elements..17/0..@A..

9. “resources/en” for general English resources and “resources/fr_CA” for resources for the French speaking Canadians.v6aA(0%5177@A3173A(IH ?5/.)%PQ04"&"-.ics.17/0. in which case the application is only build for the English locale.17 #$. e.3. “FR” for France and so on).L0D9&.6 2 ISO-639.3. so a more specific resource in “resources/Nokia/en” will override a resource with the same name in “resources/Nokia” when the English locale is used.50#17@An=3L3A H ?5/.05.13='#"1.fu-berlin."5$9"3$/%(5/.@A.8K3(9. Possible combinations separate the language and the region with an underline.920D9&."517@A1%A($2@A3173A(IH ?I.txt 3 ISO-3166. In the above example the locales “de” (German) and “en” (English) are used.8K3(9.&805.."517@A#1^(1%^(2."5$9"3$/%(5/.html 71 .)%04"&"-. and 89"9.)%0)"-. so that you can for example provide one Nokia specific resource for each supported locale. The following code illustrates the usage of these methods: . which is a subelement of the <resources>-element (compare pages 67 and 41).&05. In each used resources-folder you can create a subfolder for a specific locale. The <localization>-Element and Localized Resource Assembling ?.13='#"1. In that case any String-keys are converted into simple integer-keys during the preprocessing phase so that translations can be retrieved as fast as possible. “de” for German. compare http://www. class is used for the retrieval of translations.)%0%.17A 1L..)%0%.de/diverse/doc/ISO_3166. unless the test-mode is active. You can localize your application for French speaking Canadians by supporting the locale “fr_CA” for example.)%0)"-.#0D9&.uci. The usual specification rules also apply here. 89"9. It offers three distinct translation methods: ! ! ! 89"9.)%0)"-.17/0.edu/pub/ietf/http/related/iso639. “DE” for Germany. Managing Translations The Locale Class The *. “fr” for French and so on) and two optional uppercase letters for the country3 (“US” for USA. compare http://www. The localization framework extends the concepts of the resource assembling.L0D9&. Locales are defined using the ISO standard of two lowercase letters for the language2 (“en” for English. The localization is controlled by the <localization>-element.)%0%.9.920D9&.Localization as well as in performance.17/0.17H The <localization>-element is responsible for defining which locales should be supported.g.)'(%K34'1. You can also enable dynamic translations that can be changed during the runtime of the application.#0D9&.-4'&90*.chemie.#0D9&.)'(%K34'1..920D9&.

88"%.91.FD9"&90>.& -.&\"-.&\"-.6 P333Q ZZ0%.)*20ED9"&90>.05L0)(1156 ZZ0%.9K08.&/ 9K.9.)9&'0R'&0"0).0.)%PHQ6 4"&"-.)(D#&..')0V.&+)"-.0'R09K.&8P[Q0F0(8.9.&805056 You need to put the ]C4'1.1*38.0{0V.920E-.0C[Ov n09K.).0g. In the “&.9K0').8K3K'-.)890CYO0.0E0o0(8. you will find following code: .9K0').9.99.&"104"&"-.')EL04"&"-.8Z-. Only for the third method a call to the Locale class is actually made.&8P[Q0F0(8.3A".0o0EvEL0)(1156 ZZ0%.?9g.Localization P333Q ZZ0%.0'R09K.)38.9D9&.?9g.V0D9&.-'9.-<\"-.#$1.6 9K.20='#"1.&8/ D9&.%K9EL0)(1156 ZZ0%.-41.3%.9.&8PYQ0F0..W.9.8K+#1. but in that call the former String key “messages.-41.8K3(9.)%0"09&")81"9. the first parameter is C[O.)%0"09&")81"9.)93S"& on the classpath of your project to use the Locale-class in your IDE."9.9D9&.0"809K.)%333 As you can see in the above example you can use parameters in the translations.1#'-.&/ 9K.)%20='#"1.%K9 n09K.).9>.9.91.99.6 4"&"-.04"&"-.839?9” the above localizations need to be defined: -.)%PHQ6 4"&"-.9K09K.& n0CYO/09K.. You can also use any Java specific characters.9.)%PQ04"&"-..')0V.3%.)38..)%0"09&")81"9.)(D#&.20Ez.)%PQ04"&"-.3%. the second CYO and so on.83-.04"&"-.&8PYQ0F0.83:)9&'*(#9.3%.0)"-.)3"44.91.99.)%20='#"1.92[L04"&"-.9K08.)%0"08. so there is no performance or size impact compared to a non-localized application at all for these kinds of translations.)809'09.W.839..)%0"09&")81"9.)(3D9"&9`"-.9.0g.-<\"-.83-.9.&8/ D9&.)(D#&.88"%.09&")81"9.0&.041"<.')0V.1#'-.&\"-.9. “X9” for a tab or “XE” for using a quotation mark.9>.91.92E-.6 9K.0-".&80F0).')FCYO09K&.83-.)(D#&.V0D9&.0')1<04"&"-.OZ..9.)+8#&.')/ 9K.1*38.)'(%K34'1.)3"44.99.99.0<'(vX)C[O0"%".83:)9&'*(#9. thus saving valuable bytes as well as ensuring a fast retrieval of the resource in question.9.)%04"&"-.801'"*.&041"<.g.839.&"104"&"-.&805056 The translations for the first two Locale-methods are directly embedded into the source-code.)*20='#"1.Introduction” is transformed to a simple integer. You have to activate dynamic translations by setting the "dynamic"-attribute of the <localization>72 .3. Dynamic Translations You can also use dynamic translations that can be changed during the runtime of your application. e.0(8.0)"-. if you have a look at the preprocessed code.#$1.91.88"%.')0V..&/ 9.8'(&#.09.6 4"&"-.&\"-.-4'&9Z.09&")81"9.99.)(3D9"&9`"-.#$1.&80F0). The translations are embedded in the actual code during the preprocessing phase.&8/ n0C[O/09K.3A".)%0"08.0'R09K.')/ 9K.0'&0#'-4(9.9.9.)'(%K+4'1.-4'&90*.E5L0)(1156 ZZ0%.V0%"-.920E9.83-.13='#"1.)EL0(8.)Fz.)0V.9K0R'11'V.

88"%.g. these can be defined in the “&.01A #12"053@A1%A 5/. The translations can be adjusted by the usual hierarchy of the resource assembling.txt 3.17/0.88"%. You can switch to the German translation by calling ='#"1.17A 1L. “&.839?9”.17/0. "de.39?9” if you prefer to have all translations in one folder. You can also use the files “&. the only difference to using static translations is that the translations are not embedded into your source-code but rather retrieved dynamically from the Locale class.+)"-. J2ME Polish tries to find a translation in following places: 1."Z-.loc".17H You can now use the Locale class normally."517@A#1^(1%^(2.8Z-.txt 8. e.Q31'# file. resources/Nokia/de/messages. resources/[group-name]/messages_de.8'(&#.8'(&#.Z-. All default messages are defined in “&.txt.17 #$.g.txt When the translation is still not found the same hierarchy is searched again.17/0.31'#E05. resources/Nokia/6600/messages_de.txt 7.loc" or "fr_CA.txt 2. resources/Series60/messages_de. e.8'(&#. "en.8Z-.39?9” and “&.')820D9&.')820 EZ*.8'(&#.txt 6.loc". . all German messages in “&..31'"*>&")81"9. For each supported locale J2ME Polish generates a P1'#"1.839?9”. For allowing a fast performance J2ME Polish converts all String-based keys into simple integer-values. Defining Translations All translations are by default defined in the -.88"%. for example.8'(&#.8'(&#.88"%. so if you have Nokia-specific translations. Don't forget the slash character '/' at the start of the URL. resources/[group-name]/de/messages.839?9”.txt 4. resources/de/messages.88"%.31'"*>&")81"9.8r*. The name of the messages-files can be adjusted with the “messages”-attribute of the <localization>-element by the way. resources/Series60/de/messages.839?9” and all French Canadian resources in “&. e. You can change the translations by calling ='#"1.88"%.Localization element to "true": ?.)%0(&105. resources/Nokia/6600/de/messages.88"%.@A. When an application is localized for the Nokia/6600 phone and the German (“de”) language. resources/Nokia/messages_de.50#17@An=3L3A H ?5/.8Z*. resources/messages_de.839?9” etc..g.v6aA( IH ?I.@A3."5$9"3$/%( #8%":$.txt.txt 5.. but this time the default 73 . so that only a minimal overhead is present.8ZR&r7.Z-.88"%.8Z\'$.8Z-.8rR&r7.8Z-.8'(&#.839?9 file.

3.& n0CYO/09K.0'R09K.0)"-.98L0C[O084.9K0R'11'V."Zdd[[ZR&Z-.#$1. class offers some help for dealing with localized content: ! 89"9.13='#"1.0%"-.49.FD9"&90>.).8K3(9. {1}.9.&9("17(&&.%K9 n09K.&041"<.)890CYO0.88"%.V0%"-.839?9”.F>.91. In the actual translation files you can insert comments by starting the line with a hash-mark (#).8'(&#.)(3D9"&9`"-. from “&.')FCYO09K&.839?9”.9+B.#0D9&.)%0W.09.0)"-. 89"9.83:)9&'*(#9.. e.)+8#&.Z-.88"%.g.91.')F.0)(%%.+g. Variabledefinitions need to start with either “W"&/” or “W"&.g./”: W"&/q.1#'-.8Z\'$.8Z\'$.&0K"80V')08'-.)*"&05 formats a date specific to the current locale.`I is a field holding the ISO language code.)'(%K34'1.& -.g. ! 74 .3A".0<'(&0.&/ 9.*09'09. and 1')%.-. {2} and so on: -.)%0R'&-"9B"9..0'&0#'-4(9.%K9 Please compare the documentation of the <info>-section on page 31 for learning the names of the MIDlet-attributes.)%0=.)*'&O+]Cq.0. If the translation cannot be found.-'9.0<'(vX)C[O0"%".&9("17(&&.g.)809'09. Coping with Dates and Currencies The *.)#<Ov Naturally the variables can be used during the usual preprocessing in the Java source code as well: ZZnF0D9&.041"<.)#<OE6 Using Localized Attributes Some JAR.9+\"-.0(8.#. e.801'"*.809K. this method is also available for B"9. J2ME Polish will report the error and stop the build.txt file is used."!1. When also a region is specified (e.0'R09K.8v A:B1.0-".0<'(0).)#<F\(%%.&+)"-.&9("17(&&.&9("17(&&.&0'R0V')0)(%%..)%04"&"-.0')1<04"&"-.207"1.)0V.#0D9&.9. “fr_CA” for French Canadian). which are denoted by {0}. Like in normal Java internationalization you can use parameters within the translations. This can be done by defining such MIDlet-attributes in the appropriate messages-file: A:B1.8'(&#.)Fz..)%333 Setting and Using Localized Variables You can set localized variables just by defining them in the appropriate messages-file. “&. J2ME Polish will first try to get a specific “fr_CA” message. the description of the application.83|'(M"W.Localization messages.0C[Ov n09K.98 Such variables can also be used within the translations (of course normal variables can also be used): n0>K.&8/ n0C[O/09K.0V')0C[O0]C4'1.8#&. e.0"809K.\`@.)#<0F0E]Cq.z')F7')%&"98v0|'(0K"W."9.98/ -.0)(-!. secondly the translation will be searched for the language.0'R09K.R.041"<.0&.or MANIFEST-attributes need to be localized as well.0VK.)*"&0#"1.0{0V.88"%."Zdd[[ZR&r7.9K09K.8K3q.#$1.0g.88"%.&. before the translation is retrieved from the default messages-file.#$1.#$1.)9&'0R'&0"0).

J":1@Aij!/5$7B=G1%#/.g. Common Traps Adjusting the JAR-name You need to remember to adjust the JAR-name of the application in the <info>-section of the !(. ! 89"9.<0F0E-. “$” or “€”. You can use the variables ${polish.E6 9K.83-.)*20='#"1.)%0B:DJ=.. ! 89"9.language} e. otherwise only the last localized application is actually written to the “dist” folder.#0D9&. so that the locale is included.4ij!/5$7B=%":1. This is null when no country is used in the current locale.#0D9&.)(D#&.920$.)%0B:DJ=..g.|r=.)3"44. “fr_CA”. and ${polish.)%07@^^I\7|rD|Aep= is a field holding the symbol of the used currency. Invalid Locale Calls Please ensure that the key of the translation is always given directly instead of using a variable.1*3?-1. e. usually with a backslash-character “\” at the start. This is null when no country is used in the current locale.`I is a field holding the localized language name.3%. “Deutsch” for German. e. This is null when no country is used in the current locale.locale} e.Localization ! 89"9."51. “CA” in the jarName-attribute.<05L0)(1156 Instead use the key directly in the call as in this example: 75 . ! 89"9.\`@.)%07@^^I\7|r7pBI is a field holding the three-letter code of the used currency. “Deutschland” for Germany. “fr”. This is null when no country is used in the current locale.g.g. In the translations all standard Java escape sequences are supported.g.#0D9&. e.#0D9&. otherwise J2ME Polish will not be able to embed the translation correctly and you end up with compile errors.8/ D9&. ${polish.#0D9&. An example jarName-attribute is the following: ?$%2/(<===> b". “USD” or “EUR”.A( Using Quotation Marks and Other Special Characters in Translations You can use quotation marks as well as any special character if you escape them directly.4ij!/5$7B=5/.&0*'09K. e.)(3D9"&9`"-. The following example must not be used: ZZ0). ! 89"9.41L":!51=b".)%07p@\>^| is a field holding the ISO country code.g.|r7p@\>^| is a field holding the localized country name.country} e.: ! ! ! ! Quotation marks: XE Tab: X9 Backslash: XX and so on.g.g.)%0$.W. e.

command. The label for the Cancel-menu-item.command.V0D9&.3%.unmark Unmark polish.)(3D9"&9`"-.839?9 file: W"&/4'1. This title is only used.command. which is used by TextFields.0O056 Instead define the parameters before the actual call: ZZ09K.88"%.&\"-.1F. The label for the Mark-menu-item of a multiple List or ChoiceGroup.cancel polish.)%PQC0(8. The label for the Delete-menu-item.!!&(#K 76 .)(D#&.3%. The label for the Clear-menu-item.80.0O6 9K.E05L0)(1156 When you have several parameters.&0*'09K. which is used by TextFields.920E-.W... The title of the native TextBox which is used for the actual input of text.83-.3D9"&9A.input Delete Clear Input The following example shows the definition of some of these variables within a -. the parameters need to be given in a variable.9.). The label for the Select-menu-item.-<)"-. When the TextField has a label.E05L04"&"-.)%PQ04"&"-. The following variables can be set either in the !(.)(D#&. which is used Screenmenus when the “menu”-fullscreen-mode is used.&\"-.920E%"-.&80F0).83-..80. The label for the menu when several menu-items are available.L0 .9.)%PQC0(8. otherwise J2ME Polish is again unable to process the call correctly: ZZ0).)3"44.mark Default OK Cancel Select Mark Explanation The label for the OK-menu-item.).)*20='#"1.88"%.)*20='#"1.command.)3"44.V0D9&.&8056 Localizing the J2ME Polish GUI The J2ME Polish GUI uses several texts.delete polish.Localization ZZ09K.-<)"-.)(D#&. which can be localized using variables.options Options polish.)*20='#"1.88"%.8/ 9K.839?9 file: Variable polish./ D9&.).ok polish.3%.8K3#'--")*3#")#.920E%"-. which is used by an implicit or exclusive List or ChoiceGroup.command. polish.select polish.command.command. The label for the Unmark-menu-item of a multiple List or ChoiceGroup. that label is used as a title instead./ 9K.83-.3D9"&9A.88"%.80S(890R.80S(890R.command.clear polish.L0. when the corresponding TextField-item has no label.E05L0).1*3?-1 or within the -.title.).)3"44.

F=}8#K.)E0ZT UW"&.0)"-.0)"-.8K3#'--")*3#")#."!1. This approach is useful when no complete localization/internationalization should be done: UW"&.0)"-.8K3#'--")*3*.9.FE!/5$7B=3$351=$%!03E0W"1(.) G".FE4'1.'!/5$7B=3$351=$%!03@F$%&"+1 This example shows the definition of some of these variables within the !(.Localization W"&/4'1.FE."!1.FE=}8#K.E0W"1(.1*3?-1 file.1E0W"1(.FEF$%&"+1E0ZT 77 .!!&(#KE0ZT UW"&.9."!1.8K3#'--")*3*.FE4'1.1.1.

%(%055* IIw1%#$2 Each #ifdef and #ifndef directive needs to be closed by the #endif directive. the transformation will be: IIw$2#12(!/5$7B=$:"&17=#$. So if you migrate from antenna.%($:"&1* IIw1571 IIw(7.130.xml: symbols are defined by the <features>-element. #else.images. #elifndef and #endif Single symbols can be checked easily with the #ifdef directive: IIw$2#12(!/5$7B=$:"&17=#$. which can be used or compared during the preprocessing.xml. An example is the inclusion of the J2ME Polish GUI. which can be included without any intervention of the developer.1. Most preprocessing is triggered by directives.directLoad” is not defined.3D/"# P:"&1($:"&1(@(P:"&1=.%($:"&1* IIw1571 7.images. see the section “Capabilities” on page 26..The World of Preprocessing The World of Preprocessing Preprocessing changes the source code before it is compiled. J2ME Polish supports all directives of the antenna preprocessor (antenna.130. whereas variables are defined by the capabilities. #elifdef. however.130. Symbols and variables are defined in several files: " build.%(%055* IIw1%#$2 If.xml..1.1. #ifndef. devices.130. A variable.130. the code will be transformed to the following: IIw$2#12(!/5$7B=$:"&17=#$. " Preprocessing directives always start with a “//#” and often have one or more arguments.3D/"# P:"&1($:"&1(@(P:"&1=.3D/"# IIw(P:"&1($:"&1(@(P:"&1=.sourceforge. always contains a value. 78 . you can keep your preprocessing directives.directLoad” is defined.B1#051P:"&1q(%":1(r* IIw(.%(%055* IIw1%#$2 When the symbol “polish. the symbol “polish.1"31P:"&1q(%":1(r* IIw(. A symbol is like a boolean value – either it is defined or the symbol is not defined.1"31P:"&1q(%":1(r* .1"31P:"&1q(%":1(r* IIw(.net).B1#051P:"&1q(%":1(r* . Most capabilities also define symbols. Checking a Single Symbol with #ifdef. With this mechanism any device optimization can be done easily.%($:"&1* IIw1571 7. by the way. which use either symbols or variables. All directives must not span several rows.130.B1#051P:"&1q(%":1(r* . groups. however.xml: with the “symbols”-attribute of the <build>-element and with the <variables>element vendors..

The World of Preprocessing If a variable is defined, it can be checked via ZZn,R*.R0PW"&,"!1.Q/*.R,).* :
IIw$2#12(!/5$7B=N,.11%N$91'#12$%1#

Directive //#ifdef [symbol]

Meaning if [symbol] is defined

Explanation The symbol named [symbol] needs to be defined, when the next section should be compiled. The symbol named [symbol] must not be defined, when the next section should be compiled. When the previous section was false, the following section will be compiled (and the other way round). The symbol named [symbol] needs to be defined and the previous section needs to be false, when the next section should be compiled.

//#ifndef [symbol]

if [symbol] is not defined

//#else

else

//#elifdef [symbol]

else if [symbol] is defined

//#elifndef [symbol]

else if [symbol] is not defined The symbol named [symbol] must not be defined and the previous section needs to be false, when the next section should be compiled. end of the if-block End of every ifdef and ifndef block.

//#endif

The #ifdef directives can be nested, of course. Other preprocessing directives can be included into the sub-sections as well:
IIw$2#12(:8N8:+/5 IIw$2%#12(:8E3B1.N8:+/5 IIw#1+0& N8731:=/03=!.$%35%qA/%58(:8N8:+/5($7(#12$%1#=Ar* #/N/:13B$%&qr* IIw1571 IIw#1+0& N8731:=/03=!.$%35%qA:8N8:+/5("%#(:8E3B1.N8:+/5(".1(#12$%1#=Ar* #/N/:13B$%&F571qr* IIw1%#$2 IIw1%#$2

The #ifdef directive and its related directives are faster to process than the more complex #if directives. Checking Several Symbols and Variables with #if, #else, #elif and #endif With each #ifdef directive only a single symbol can be checked. With the #if and #elif directives, however, complex terms containing several symbols and variables can be evaluated:
IIw$2(071F%B"%,1#P%!03(uu(q!/5$7B=B"7S/$%31.FG1%37(yy(!/5$7B=:/071N0!!/.31#r

79

The World of Preprocessing
#/N/:13B$%&qr* IIw1%#$2

#if directives can also be nested and contain other preprocessing directives like the #ifdef directives. #if and #ifdef directives can also be mixed:
IIw$2(f+"7$,P%!03(uu(q!/5$7B=B"7S/$%31.FG1%37(yy(!/5$7B=:/071N0!!/.31#r #/N/:13B$%&qr* IIw$2(!/5$7B=\$37S1.S$L15(H@(_ #/N/:13B$%&6/5/.205qr* IIw1571 #/N/:13B$%&M055qr* IIw1%#$2 IIw15$2#12(#/d$5#N3022 #/d$5#N3022qr* IIw1%#$2

Directive //#if [term] //#else

Meaning if [term] is true else

Explanation The specified term must be true, when the next section should be compiled. When the previous section was false, the following section will be compiled (and the other way round). The specified term needs to be true and the previous section needs to be false, when the next section should be compiled. End of every if block.

//#elif [term]

else if [term] is true

//#endif

end of the if-block

In the terms the boolean operators &&, ||, ^ and ! can be used. Complex terms can be separated using normal parenthesizes “(“ and “)”. The term arguments for boolean operators are symbols, which are true when they are defined and false otherwise. Variables can be checked with the comparator FF, >, <, <= and >=. Arguments for the comparators are variables or constants. A term can include comparators and boolean operators, when the sections are separated by parenthesizes. Boolean Operator Meaning && or “and” || or “or” ^ or “xor” and or Explanation Both arguments/symbols need to be defined:
9&(.0~~09&(.0F09&(. 9&(.0~~0R"18.0F0R"18.0~~09&(.0F0R"18.0~~0R"18.0F0R"18.

At least one argument/symbol must be defined:
9&(.0jj09&(.0F09&(.0jj0R"18.0F0R"18.0jj09&(.0F09&(. R"18.0jj0R"18.0F0R"18.

exclusive Only and at least one argument/symbol must be defined: or (xor) 9&(.0•0R"18.0F0R"18.0•09&(.0F09&(.
9&(.0•09&(.0F0R"18.0•0R"18.0F0R"18.

80

The World of Preprocessing Boolean Operator Meaning ! or “not” not
v0R"18.0F09&(. v09&(.0F0R"18.

Explanation The argument/symbol must not be defined:

Comparator FF

Meaning equals

Explanation The left and the right argument must be equal, integers and strings can be compared:
f0FF0f0F09&(. \'$,"0FF0\'$,"0F09&(. IIw$2(!/5$7B=\$37S1.S$L15(@@(_ IIw$2(!/5$7B=G1%#/.(@@(J/-$"

vF

not equals The left and the right argument must not be equal, integers and strings can be compared:
f0vF0f0F0R"18. \'$,"0vF0D')<+I&,#88')0F09&(. IIw$2(!/5$7B=\$37S1.S$L15(f@(_ IIw$2(!/5$7B=G1%#/.(f@(J/-$"

>

greater

The left argument must be greater than the right one. Only integers can be compared:
f0T0f0F0R"18. Yd0T0f0F09&(.0 IIw$2(!/5$7B=\$37S1.S$L15(H(_

<

smaller

The left argument must be smaller than the right one. Only integers can be compared:
f0U0f0F0R"18. f0U0Yd0F09&(.0 IIw$2(!/5$7B=\$37S1.S$L15(?(_

>=

greater or equals

The left argument must be greater than - or equals - the right one. Only integers can be compared:
f0TF0f0F09&(. Yd0TF0f0F09&(.0 IIw$2(!/5$7B=\$37S1.S$L15(H@(_

<=

smaller or The left argument must be smaller than - or equals - the right one. equals Only integers can be compared:
f0UF0f0F09&(. f0UF0Yd0F0R"18.0 IIw$2(!/5$7B=\$37S1.S$L15(?@(_

Using Variable-Functions for Comparing Values Some variables have not only different values but also store them in different ways. An example are memory values like the HeapSize which is sometimes defined in kilobytes and sometimes in megabytes. In such situation functions can be used:
IIw$2(ij(+8317q(!/5$7B=[1"!N$91(r(;(H(VKZhKK

In the above example the heapsize is compared using the !<9.8-function. When a function should be used, a dollar-sign and curly parenthesizes needs to embrace the call. The !<9.8-function will 81

It must be finished with the #enddebug directive: IIw:#1+0&(1.1qr* N8731:=/03=!.(3B$7(..B1#051P:"&1q(%":1(r* . A typical problem are several return statements: IIw$2#12(!/5$7B=$:"&17=#$. 1=!.5"77=Ar* You can define what debugging level is used by adding the debugging-level to the #debug directive.130. the corresponding code will be made visible again.3D/"# P:"&1($:"&1(@(P:"&1=.The World of Preprocessing return -1 when the given memory-value is “dynamic”. Debugging with #debug. #mdebug and #enddebug To include debugging information in a J2ME application is not without problems.$%35%qA#1+0&&$%&($7(1%"+51#(2/. so it might be necessary to test for both values: IIw$2(q(ij(+8317q(!/5$7B=[1"!N$91(r(.". With J2ME Polish debugging statements can be included into the applications without having the above disadvantages.%($:"&1* IIw1571 7.130. Hiding Code Code sections can be temporarily commented out./. to avoid problems in the IDE. The #debug directive is used to include a single line of debugging information: IIw#1+0& N8731:=/03=!.(q!/5$7B=[1"!N$91(@@(#8%":$. You will find more information about using functions at the “Using Variables” section on page 85.$%3N3". When no level is specified the “debug” level is assumed. When the first #ifdef directive is true.%(%055* IIw1%#$2 In this example the first return statement is hidden with a “//# “ directive. IIw#1+0&($%2/ N8731:=/03=!.(H(VKZhKK(r(/.1.r Functions can also be used for fixed values: IIw$2(ij(+8317q(!/5$7B=[1"!N$91(r(.$%35%qA3B1($%2/(#1+0&&$%&(51G15($7(1%"+51#(2/.(3B$7(.$%35%qA0%"+51(3/(5/"#(7/:13B$%&'(A(l(1(r* IIw1%##1+0& The above example actually results in the same code as: 82 .1"31P:"&1q(%":1(r* IIw(. The space after the # sign is important for the correct handling of such comments.. Another problem is that nobody wants the debugging information in an application which should be deployed “in the wild”.(H(ij(+8317q(VKK(-+(r(.5"77=Ar* The #mdebug (multi-line debug) directive can be used to use multiple lines of debugging information.-Y. The main problem is that any debugging slows down an application unnecessarily.

80)(11vt56 00O ZZn. //#if Debug Levels Following debug levels are predefined: “debug”. “polish.B:". The specific level for a class can be defined with the <debug> element of the J2ME Polish-task: ?#1+0&(7B/CD/&E%F.-3'(934&.R02"&%(-.debug”. “fatal” and with a user-defined level will also be compiled.info”./:!"%8=!".)90FF0)(1150C 00000D<89.B:".!(%3. When no level is specified. “polish.%@A.The World of Preprocessing IIw#1+0&(1.debug."556/:!51LU13B/#qr* IIw#1+0&(+1%.@A3. all debugging information with the level “warn”.debug. “polish. User specific debugging levels can be useful for accomplishing specific tasks. the “debug” level is assumed.$%35%qA0%"+51(3/(5/"#(7/:13B$%&'(A(l(1(r* Directive //#debug [level] Explanation The next line is only compiled when the debugging setting for the class in which the debugging information is enabled for the specified level. “error”.)90./:=.%@A. “error” and “fatal”. “warn”.(!"331.)91)2u"&%(-.+/71@A2"571A(51G15@A1.. The levels are weighted.1%3Y$:1U$5$7qr* .)R' 00..5/%&(73". Marks the end of the #mdebug section.01A(G1. When no level is specified../. the “debug” level is assumed. The preprocessing symbols “polish.info”.debug”. “info”./:=.0. For example a level “benchmark” could be defined to allow the measurement of the performance: IIw#1+0&(+1%.. meaning that the debug level is lower than the info level.)*.-"&1=U865"77A(51G15@A#1+0&A(IH ?I#1+0&H Please see the section <debug> in the chapter “The Build Process” for further information.warn” etc can be used with the #ifdef directive.-"&1=nA(51G15@A$%2/A(IH ?2$531. “polish.debug.R04'1.A($2@A3173A(H ?2$531.8K3*.(!"331.3Y$:1(@(N8731:=.debug.R //#mdebug [level] //#enddebug //#ifdef./:!"%8=!". N8731:=/03=!. Instead the preprocessing symbols “polish./.debug.- 83 ./. The next lines up to the #enddebug directive will be compiled only when the debugging setting for the class in which the debugging information is enabled for the specified level.warn” etc can be used instead of the #mdebug directive: ZZn.debug. which is in turn lower than the error level and so forth: debug < info < warn < error < fatal < user-defined Thus when the info level is activated for a class.

3Y$:1r(l(A>(:7=Ar* The Debug Utility Class The utility class de./:=.util././(#1=1%/0&B=!/5$7B=03$5=M1+0&* #17%&DED%2''E:5:FG%+/E+H/+>3'E:FG%+/E" IIw$2#12(!/5$7B=#1+0&F%"+51# #. Especially its showLog()-method can be useful in some circumstances when the “showLogOnError”-attribute is not sufficient.debugEnabled” will be defined. that you have added the “import/enough-j2mepolish-client./:!51L(:13B/#(3//-(<A(l(qN8731:=.%@A.%@A. When this is the case.:#(@@(/(&'=5/&6:#r(j M1+0&=7B/CD/&q(/(&'=#$7!5"8(r* . When another message is added while the log is shown.0..showLog( Display display ) Shows the log containing all messages.11%* #.11%="##6/::"%#q(/(&'=5/&6:#(r* IIw1%#$2 . the log will be updated. The user can then select the “show log” command to see view all logging messages.-"&1=U865"77A(51G15@A#1+0&A(IH ?I#1+0&H You can make the debug information available in your MIDlet class with the following code: &*#$.@A3.. When the user selects the “return” command from the log-screen.A($2@A3173A(H ?2$531.1%3Y$:1U$5$7qr(4( 73"./:=. the preprocessing symbol “polish.+/71@A2"571A(51G15@A1. ?#1+0&(7B/CD/&E%F.polish.&?2/+(6/::"%#(5/&6:#(@(>+<(6/::"%#q(A7B/C(5/&A^(6/::"%#=N6]FFJ^(VK(r* IIw1%#$2 #.:#^(M$7!5"8"+51(7.01A(G1.jar” to the classpath of your project.11%(:"$%N..11%(r(j <===> IIw$2#12(!/5$7B=#1+0&F%"+51# &I(q.&?2/+(N.11%(#$7!5"8* <===> #17%&D(U8UPM513qr(j <===> IIw$2#12(!/5$7B=#1+0&F%"+51# /(&'=:"$%N. #17%&D(?$&3(.$%35%qA.. Using Variables with #= You can add the contents of variables with the #= directive: 84 . when using the Debug-class. Please make sure. he will return to the screen which has been shown before.Debug can also be used directly for debugging..(!"331.. Debug-Method Explanation Debug..-"&1=nA(51G15@A$%2/A(IH ?2$531.&?2/+(N. IIw1%#$2 ./:!"%8=!"./:!"%8=!"./::"%#a.3$/%q6/::"%#(.enough.(!"331./. In the above example the MIDlet “MyMIDlet” adds a command to its main screen when the debugging mode is enabled..The World of Preprocessing N8731:=/03=!.

Calculates the (double) number of megabytes of the given memory value. Following functions can be used: Function uppercase lowercase bytes kilobytes Explanation Translates the given value into uppercase.5'#12$%1# IIw@(!. The name of the variable needs to be surrounded by a Dollar-Sign followed by curly parenthesizes (]CW"&. which is set for every known variable: IIw$2#12(73". which can change easily.xml. Variable-Functions You can use functions like “uppercase” to change the values.. “abc” becomes “ABC” for example. just like referring to Ant-properties in the build. Calculates the (double) number of kilobytes of the given memory value.340.O).&?2/+EN3. The value will contain a point and decimal places."71q73". “512 bytes” becomes “0.xml by the capabilities of the devices. “1 kb” becomes 1024 for example.340. vendors. You can use the “[variable]:defined” symbol.$%&(0.5(.A* When the variable is not defined. “ABC” becomes “abc” for example. A function is used within the curly parenthesizes and surrounds the variable-name by normal parenthesizes: IIw$2#12(73".5(.xml. vendors and groups.5(@(AB33!'IIVtZ=VT_=VKV=VKVA* IIw1%#$2 When using function you do not necessarily need a variable – you can also use a direct value. Calculates the (double) number of gigabytes of the given memory value. “1024 bytes” becomes “1” and so on.$%&(0. 85 megabytes gigabytes . Translates the given value into lowercase. Other variables are defined in the devices.340."!1. the above example would throw an exception during the preprocessing step of the build process.340.5(@(Aij(5/C1.5'#12$%1# IIw@(!.xml and groups. Variables can be defined in the <variables>-element in the build.$G"31(N3.5” for example.The World of Preprocessing IIw@(!.5(@(Aij(73".(H(ij(+8317qVKK(-+r(.340.$G"31(N3.$%&(0. The memory-value “dynamic” results in -1.$%&(0.5r(.xml.A* IIw1571 #.$%&(0.5(@(AB33!'IIVtZ=VT_=VKV=VKVA* IIw1%#$2 This is especially useful for setting configuration values.+)"-. This can be handy when handling with memory values for example: IIw$2(ij(+8317q(!/5$7B=[1"!N$91(r(. like Web-URLs and so on. These files are located in the installation directory of J2ME Polish.A* IIw1571 #.5(@(Aij(73". Calculates the number of bytes of the given memory value.&?2/+EN3.$G"31(N3.

5(@(%1C(N3. even when the designer does not define it explicitly. List. The style “frosty” is only used when the style “cool” is not defined.frosty” or “default”."%. since dynamic styles need some processing time. The #style directive can be placed before adding a list element.//5k N3. “frosty” or “default” is used for the new item. IIw73851(/!1%D$%Item.//5^(2. that this method is only available in J2ME Polish.$%&P31:(0.1U/#1q( setAppearanceMode P31:=[oSF]DPJe(r* () The #style directive can be placed before calling the setAppearanceMode-method of an Item.//5 P:"&1P31:($:&(@(%1C(P:"&1P31:q( %055^($. Styles can be set for all items-constructors and for many methods: Insertion Point Item constructors Example IIw73851(. The developer can control which styles are used for specific Items by using the #style directive: IIw73851(.$%&P31:(0. since it is always defined. The “default” style is a predefined style and its name must not.$%&P31:q( %055^(AB33!'IIVtZ=VT_=VKV=VKVA(r* IIw73851(.1 5$73="!!1%#q(AN3".The World of Preprocessing Setting CSS Styles with #style CSS styles are used for the design of the application. This can be triggered with the “usePolishGui” attribute of the <build> element in the build. Dynamic styles design items by their position in screens.cool”.$%&P31:q(%055^(AB33!'IIVtZ=VT_=VKV=VKVA(r* In the above example one of the styles “cool”. The styles are defined in the file polish. The #style directive needs at least one style name as argument. In that case it will only be used when it is defined: IIw73851(.5(@(%1C(N3. therefore. Please note.$%&P31:q(%055^(AB33!'IIVtZ=VT_=VKV=VKVA(r* The styles mentioned here can be defined in the “resources/polish. Using #style directive improves the performance of the application. 0.css” file./738^(#12"053 N3.5=713a!!1"./%P:"&1^( P:"&1P31:=DaoEOYvMFQaODY^(%055(r* Explanation The #style directive can be placed before any item constructor.3A^(%055((r* 86 . In that file the names of custom styles need to start with a dot. see section “Dynamic Styles” on page 107.append() IIw73851(.5(@(%1C(N3. The style is deemed optional when the style ends with a question mark.xml. The style “default” is only used.B/$.//5^(2. Styles are only used. The style “default” is special. when the J2ME Polish GUI is used.css in the resources folder of the project. start with a dot.$%&P31:(0. “. In the above example you can define the styles “./738^(#12"053 N3. when neither the style “cool” nor the style “frosty” is defined.

B/$.1(VA^(%055((r* d() placed before adding an element to a ChoiceGroup..3A^(%055((r* Explanation The #style directive can be placed before inserting a list element.3q(Z^(AN3"./%#$3$/%(!/5$7B=071S/5$7B`0$ When in the above example the J2ME Polish GUI is not used (and thus the symbol polish.:(@(%1C(Q/./0!="!!1%#q(A6B/$. ChoiceGroup.B/$. Form constructor IIw73851(:"$%N..set() IIw73851(.:q(AU1%0A(r* II($%(70+.insert( IIw73851(.1(XA^(%055( ) placed before inserting an r* element to a ChoiceGroup.11% 70!1.. List.1 5$73=$%71. the file will not be included into the application bundle for the current device.B/$.insert() Example IIw73851(.1 The #style directive can be &.appen IIw73851(.1 &.1(XA^(%055((r* The #style directive can be placed before setting an element of a ChoiceGroup./0!=$%71.1 5$73=713q(Z^(AN3".set() IIw73851(. when a condition is not met: IIw. Use the #style directive before a List-constructor or before calling super() in subclassconstructors.11% Q/.5"7717(/2(D$73' IIw73851(:"$%N.q(AU1%0A(r* List constructor IIw73851(:"$%N.. ChoiceGroup.B/$.11% D$73(5$73(@(%1C(D$73q(AU1%0A^( D$73=PUSDP6PY(r* II($%(70+.1 The #style directive can be &./0!=713q(Z^(A6B/$.usePolishGui is not defined).B/$. Use the #style directive before a Form-constructor or before calling super() in subclassconstructors.3A^(%055((r* ChoiceGroup. Defining Temporary Symbols or Variables with #define and #undefine You can temporarily define and undefine symbols with the #define directive.:(2/.11% 70!1. Conditions can use the same operators and comparators like the #if directive. The #style directive can be placed before setting a list element.5"7717(/2(Q/. This can be used to evaluate a complex if-term only once and then referring a simple symbol instead of using the complex term again: 87 .The World of Preprocessing Insertion Point List.3q(Z^(A6B/$.q(AU1%0A(^(D$73=PUSDP6PY(r* Exclude or Include Complete Files with #condition The #condition directive can be used to prevent the usage of complete files.:' IIw73851(:"$%N.

”. Removes the specified symbol from the pool of defined symbols.p* Directive //#define [name]=[value] //#undefine [name] Explanation Defines the specified variable with the given value.The World of Preprocessing IIw$2(f+"7$. and the right part as the variable value: IIw$2(f:177"&1'#12$%1# IIw#12$%1(:177"&1(@([155/(C/. please bear in mind. that the base directory is the root of your project (or to be more precise: the directory which contains the build./:!51LP%!03 #/N/:13B$%&6/:!51Lqr* IIw1%#$2 Directive //#define [symbol] //#undefine [symbol] Explanation Defines the specified symbol.FG1%37(yy(!/5$7B=:/071N0!!/.P%!03(uu(q!/5$7B=B"7S/$%31.1.31#r IIw#12$%1(3:!=.. When the expression after the #define directive contains the equals-sign.xml file)./:!51LP%!03 IIw1%#$2 You can later just check the temporary defined symbol: IIw$2#12(3:!=.50#1(ij!/5$7B=7/0.source”. which points the base directory of the file. I you use only relative names. You can temporarily define and undefine variables with the #define as well. You can never undefine the symbol “true”.I$%. the left part will be taken as the variable name.50#17I:8$%.50#1=b"G" Within the file-name you can use all defined variables.5# IIw1%#$2 You can later just use the defined variable normally: IIw@(N3.$%&(:177"&1(@(zij(:177"&1(. Inserting Code Fragments with #include You can insert complete code fragments with the #include directive: IIw$%. You can never define the symbol “false”. A useful variable is especially “polish. Removes the specified variable. which is currently preprocessed. Please note that you should rely on a defined or undefined symbol only in the same source-file where you defined or undefined that symbol. It is advised that you start the names of defined symbols with “tmp. so that you always know that this is a temporary symbol. The #message directive can help to 88 . Analyzing the Preprocessing-Phase with #message and #todo Sometimes the preprocessing itself is rather complex.

When this variable is not defined.The World of Preprocessing understand the process by printing out messages during the build-process: IIw$2(f+"7$. The #foreach directive defines a temporary loop-variable and ends with the “#next [loop-var-name]” directive: ZZnR'&. for example.:"3(r(. Handling Several Values in Variables with #foreach The #foreach directive can be used for processing a variable which has several values separated by comma. the message “MESSAGE: using the update-url ${update-url}."#K0P1''4+W"&+)"-.company.com”. This copying process has two implications: 1. So you can even use nested #foreach loops.:"3* IIw2/. In the above example it would be copied three times.Q 333P")<0*./:!51L($%!03($7(1%"+51# IIw1571 IIw:177"&1(.31#(+8(3B$7( #1G$.$%&(2/."71q(2/. since in the example three formats are supported.:"3(@(Aij(5/C1. “-.1=A(r* IIw%1L3(2/. The code-fragment within the #foreach-loop will be copied into the preprocessed source-code as many time as there are values.FG1%37(yy(!/5$7B=:/071N0!!/. but it adds the name of the source-code and the line in which the #todo-directive is embedded before the actual message (e./:!51L($%!03($7(#$7"+51# IIw1%#$2 Within each message any variables can be used.A* N8731:=/03=!.W.$%35%q(AYB1("0#$/42/.+)"-./:!51LP%!03 IIw:177"&1(.:"3(l(A($7(70!!/. “TODO: MyMidlet line 12: Implement pauseApp()”).5(ij0!#"3140.= The above example results in the message “MESSAGE: using the update-url http://update.Q The following example illustrates this: N3. Any variables should be defined outside of the loop (but they can be set and used within the loop..?90P1''4+W"&+)"-.” being given out.31#r IIw#12$%1(3:!=.&.:"3 You can use any number and any kind of code and preprocessing directives within the #foreach-loop itself. when the variable “update-url” has the value “http://update.g.5.:"3($%(!/5$7B=N/0%#Q/.:"3(A(l(2/.#9.*.B(2/. of course).Q333 ZZn). If a variable is not defined.1". and 89 .)0PW"&.80")*0#'*.P%!03(uu(q!/5$7B=B"7S/$%31. An example is the “4'1.L0"-&L0-4a”.Q0. the variable-definition will be included in the message.:"3 2/. IIw:177"&1(07$%&(3B1(0!#"3140. The #todo directive works very similar like the #message directive."!1.” will be printed out instead.8K3D'()*g'&-"9”-variable which lists all supported audioformats of a device.g.company. e.com.

Following example illustrates the usage: #17%&D(27'/. When the application is debugged or compiled.FullCanvas”.#$0can be defined in the symbols-attribute of the <build>-element within the “build. page 36. For each API the device supports a corresponding symbol “polish.*4Y”.0is defined when the GUI of J2ME Polish is used for the current device.!(%q.)97K.0 platform. ! ! 4'1.0 standard is supported. When this symbol is defined. Please compare the “The Build Section”.8K3#1*#Y3Y” is defined instead.8K3"). but you can change this value within the <variables> element of the <build>-section. This defaults to 100 ms. When the verbose mode is enabled.8K3-.8K3*.11%'#12$%1# 90 .8K3(8.The World of Preprocessing 2.. If you keep these implications in mind you have another powerful directive at your hand. or 4'1. the symbol “4'1. J2ME Polish Symbols Depending on the settings in the build. 4'1. thrown exceptions should contain a detailed message.0 standard..&%(-.) defines the name of the fullscreen-class. otherwise the symbol “4'1.xml” file. breakpoints or errors can point to the wrong source-code lines.*4H” is defined.8K3"4. ! 4'1. when the device supports such a class.8K3#1*#Y3[” is defined. all GUI classes of J2ME Polish will not check the input variables. When the CLDC/1.0when the device supports the Nokia UI API.8K3"4.11%(uu(!/5$7B=.3)'$.!(%I)"!1.api. Useful Symbols APIs and MIDP-Version Please refer to the section “Capabilities” in the chapter “The Device Database” for standard preprocessing symbols.ui.8K3-.0when the Mobile Media API is supported. This is useful for minimizing the memory footprint when an application is stable.5"7717=20557.0is defined when the debug-mode is enabled and is set to “verbose”.8K3#1"88..J'1."+(.4. the symbol “4'1.&W"1 defines the interval in milliseconds for animations. ! 4'1.8K38$. Other variables include: ! 4'1. ! 4'1.83R(118#&. Useful Variables Please refer to the section “Capabilities” on page 26 for standard preprocessing variables. the symbol “4'1.3--"4. For devices which support the Nokia UI API this variable contains “com.*0is defined when the logging of messages and the debug-mode is enabled.8K`(. When the device supports the MIDP/2.mid.8K3*.&!'8.-"9.2D/(D%2''(U86"%G"7( IIw$2(!/5$7B=071Q055N. When a device supports the CLDC/1.nokia.[name]” is defined: 4'1.xml different symbols will be defined.'):)9.

11% IIw@(1L31%#7(ij!/5$7B=.9+) defines the nth MIDlet of the current suite.83-. 91 .. points the current source directory.g.9+Y defines the first MIDlet of the current suite. if there is any..*1.& defines the identifier of the current device. ! ! ! ! File Operations The variable 4'1.g. 4'1. “Siemens” or “Nokia”: IIw$2(!/5$7B=s1%#/. 4'1. e.R. 4'1.(@@(J/-$" 4'1.5"7717=20557. IIw1571 +H/+>3'(6"%G"7 IIw1%#$2 ! 4'1.8K3q. if there is any.8K3:*.*1.83-.9+H defines the second MIDlet of the current suite.8K3#1"88.83-.8K3#1"88. e.11%.*1.The World of Preprocessing IIw#12$%1(3:!=2055N. “Nokia/6600”.)9.8K38'(&#. This is useful for //#include directives..)*'& defines the vendor of the current device.8K3#1"88.

The J2ME Polish GUI The J2ME Polish GUI Overview The J2ME Polish GUI4 provides a very powerful and efficient way to design the user interface of wireless Java applications. which reside outside of the actual application source code. Activation of the GUI The GUI can be activated by the setting the “(8. The background is actually animated: it starts white and dithers to the shown pink.J'1.0 GUI are supported – even on MIDP/1.”-attribute of the <build>-element in the 4 GUI stands for Graphical User Interface 5 CSS: Cascading Style Sheets 92 . Fig. so the programmer does not need to learn a new API. while the programmers can concentrate on the business logic. 4: The same application with another design. so the additional size is most often no problem. So MIDP/2. Fig. depending on what GUI-elements and what designs are used. device-groups or even locales. which only accepted applications with a size of up to 64 kb. For such devices the GUI is usually not used even when the GUI is activated.`&'(4 or a 7(89'-:9. The web-standard CSS5 is used for the design. Also the design can be changed at any time without changing the source code. ! ! ! ! The drawback of the J2ME Polish GUI is the increased size of the application package. The necessary code is weaved into the application automatically by J2ME Polish.0 specific items like a JpJ@J07K'. vendors. All elements of the MIDP/2. so that no specific import-statements need to be used and that even existing applications can use the GUI without any modifications. 3: An example design of a normal List-Screen. The GUI is designed using simple text-files. Siemens and many other vendors) support application-sizes up to several megabytes.0 phones as well.. All designs can be adjusted easily to different devices. Modern devices like Symbian based devices (Nokia. different on some older devices like Nokia's old “Series 40”-models. so that web-designers can now work on the design of J2ME applications without the help of programmers. unless the usage is forced. You should calculate up to 30 kb additional space for the GUI. however.#. The situation is.0 devices.8K`(. It has several unique features which ease the usage significantly: ! The J2ME Polish GUI is compatible with the standard MIDP GUI.can be used on MIDP/1.

)”-attribute of the <build>-element: ?+0$5# 071S/5$7B`0$@A3...01A 20557. the GUI will be used. When the attribute is set to “always”..17((44H ?G".$"+517H <===> ?I+0$5#H Configuring the J2ME Polish GUI The GUI can be configured quite extensively by modifying the build.$"+51( %":1@A!/5$7B=071S/5$7B`0$A( (((( G"501@A3. “no”/”false” or “menu”.$17TKA(IH ?IG".1*3?-1 file.11%@A:1%0A 071S/5$7B`0$@A2"571A H ?f44(". a maximum JAR size above 100kb and at least a color-depth of 8 bits per color). Siemensdevices do accept commands even in the normal fullscreen-mode. “no”/”false” and “always”. The following example activates the GUI for most devices: ?+0$5# 071S/5$7B`0$@A3.g.01A( $2@A!/5$7B=&. The full-screen mode can be activated with the “R(118#&. In that case the menu-bar will be rendered by J2ME Polish and the menu can be designed with CSS (e. Using the GUI in Full-Screen-Mode The J2ME Polish GUI can use the complete screen on MIDP/2. This is useful if the GUI should be activated for selected devices only. which accepts the same values as the the “R(118#&. so there is no need to use the 93 .11%@A:1%0A <===> The attribute can have the values “yes”/”true”.)(!"&+#'1'&attribute or using the “menu” style). This can be used for a fine grained control.FL":!51N8:+/5A 20557. by setting the -.xml file. unless a target-device has not the recommended capabilities (i.8K3g(11D#&. J2ME Polish will then weave the necessary code automatically into the application. even when they do not have the recommended capabilities. The following example activated the GUI only for Nokia/Series 60 devices: ?+0$5# 78:+/57@A7B/CN!5"7B^(a%/3B1.)”-attribute. The attribute accepts the values “yes”/”true”. the “menu”-mode needs to be used.01A <===> Alternatively you can enable the J2ME Polish GUI by defining the preprocessing variable “polish. Alternatively the “4'1./0!=N1.e.$17(#1G$.$"+517H ?G".usePolishGui”. the GUI will be used for all target-devices.)”-preprocessing variable can be set. When “true” or “yes” is given.3$G"31(3B1(`OP(2/.The J2ME Polish GUI !(. When commands are used by the application. For such devices the normal MIDP-GUI is then used.0 devices as well as on MIDP/1.(J/-$"IN1...0 devices which provide proprietary methods for using a fullscreen-mode.

W.9<0)"-.+(46J)'+"/)(8 00U#"4"!.88.)9.<3=.11%@A:1%0A H ((?G".1..0 “menu” mode.T 94 .<J&..R9D'R9x.#.8K`(.)9.<3^.9<0)"-..)8Z7ldhUZ.$"+51( %":1@A!/5$7B=Q055N.)D.FE$.R9D'R9x.FE+bE0ZT UZ*.<” can be set to define the key-codes for the soft-keys (these are the values.FE+YE0ZT 00U#"4"!.(@@(N$1:1%7A (((((IH ((?G".R.11%A( G"501@A817A $2@A!/5$7B=G1%#/.. 008(44'&98J'1.FEYaH?YydEZT 00U#"4"!. since they do not forward key-events when a soft-key is pressed.E0W"1(.<3^.#.The J2ME Polish GUI menu-mode for such devices: ?+0$5# 071S/5$7B`0$@A3.1.i.&T 004J)'+"/)(80'(=2. U*.01A 20557..<E0W"1(.<E0W"1(.$"+517H (((((?G".W.9<0)"-.<IW.*.*.*”-method of a 7")W"8).<3=.FE$.%K9D'R9x.'. which are reported to the “$.<” and “$.0 devices do not support the “menu” mode.R. and the value “-7” for the right soft key.1.FED#&..-..)98”-feature is set. When no keys are defined. J2ME Polish determines whether a device supports the “menu” mode by evaluating the device database.FE9&(. the value “-6” is assumed for the left soft key. Additionally the capabilities “$.-D):I3).%K9D'R9x. When the “K"87'--")*x.ET 00U. the device supports the pure MIDP/2.$"+517H ((<===> Fig. 1: The "menu" and the normal fullscreen-mode on the Siemens CX65 Some MIDP/2.&TD.

') method. This defaults to 100 ms. A TextField and TextBox do contain the “Delete” as well as the “Clear”-commands by default.49. method arguments will not be checked.9.ImageLoader” variable.skipArgumentCheck When this symbol is defined. which is responsible for polish.ChoiceGroup. which is used Screen-menus when the “menu”-fullscreen-mode is used.')31#*(. the “polish.ChoiceGroup.ChoiceGroup. This works fine for most situations.suppres false sSelectCommand polish. The label for the OK-menu-item. The label for the Select-menu-item. The label for the Cancel-menu-item.ImageLoader - retrieving the image. compare page 76. The given class (or static field of a class) needs to implement the S"W"?3-.)%0(&105 9K&'V80 :pI?#. This improves the runtime performance and the size of the application a bit.suppressCo false mmands polish.classes.3:-"%.animationInterval 100 Default Explanation Defines the interval in milliseconds for animations.20D9&. The names of the commands can be changed easily.suppres false sMarkCommands A multiple List or ChoiceGroup adds the commands “Mark” and “Unmark” by default to the menu."9. polish.command.*.)%0 (&1050method. but sometimes images should be retrieved from the RMS or the internet. In such cases you can define the “polish. which is used 95 polish. An implicit or popup ChoiceGroup or List do usually have a “Select”-command which also can be deactivated. Usually J2ME Polish loads all images from the JAR file using the :-"%.command.20D9&.3#&. Labels and Programming of the GUI Preprocessing variables and symbols can be used for changing the appearance or logic of the J2ME Polish GUI.ok OK polish. Preprocessing Symbol Explanation polish.The J2ME Polish GUI Configuring Commands.select Cancel Select .TextField.command.classes.cancel polish.0 1'"*:-"%.:-"%. Preprocessing Variable polish.suppressMarkCommands”variable has to be set to “true”.#&'. If you want to suppress the commands completely.

/::"%#7(2/.-A H ((?G".":131.-(.clear polish.FullScreen - The following example demonstrates some configuration options: ?f44(78:+/5'(#/%m3(.command. When the TextField has a label. polish..(. The title of the native TextBox which is used for the actual input of text.(Y1L3\/L17("%#(Y1L3Q$15#7'((44H (((((?G".-6/::"%#7A( G"501@A3.$"+51( %":1@A!/5$7B=Y1L3Q$15#=70!!.command. Can be used for selectively activating the FullScreen mode.(6B/$.$"+517H ((<===> The J2ME Polish GUI for Programmers Using the J2ME Polish GUI is quite simple actually.-(:13B/#4!".5"7717=P:"&1D/"#1. The label for the menu when several menu-items are available.A(IH ((?G".options polish.The J2ME Polish GUI Preprocessing Variable polish.mark polish.title.01A(IH ?f44(071(/C%($:"&1(5/"#1. Since the J2ME Polish GUI is compatible with 96 .7'((44H ?+0$5# 071S/5$7B`0$@A3.usePolishGui polish.command.B1./0!7("%#(D$737'((44H (((((?G". Possible values are “true”.command.unmark polish. The label for the Mark-menu-item of a multiple List or ChoiceGroup. which is used by TextFields. “false” or “menu”.177(U". The label for the Delete-menu-item.$"+51( %":1@A!/5$7B=.&0:1%36B1.command.-IO%:".$"+51( %":1@A!/5$7B=6B/$./::"%#7(2/.177(M15131I651". when the corresponding TextField-item has no label. that label is used as a title instead./:=./0!=70!!. which is used by TextFields./:!"%8=bZ:1=P:"&1D/"#1.A( G"501@A.01A(IH ?f44(70!!.1776/::"%#7A( G"501@A3.1`.01A 20557. The label for the Clear-menu-item.$"+517H ?f44(70!!.($:!51:1%3"3$/%'((44H (((((?G". Can be used for activating the Polish GUI only for selected devices.1`.delete polish.177U".input Default Mark Unmark Options Delete Clear Input Explanation by an implicit or exclusive List or ChoiceGroup. The label for the Unmark-menu-item of a multiple List or ChoiceGroup. This title is only used.11%@A:1%0A 78:+/57@A!/5$7B=7-$!a.

$%&P31:(0.11% Q/.5"7717(/2(Q/.5=713a!!1"..q(AU1%0A(r* 97 .appen IIw73851(. List.$%&P31:q( %055^(AB33!'IIVtZ=VT_=VKV=VKVA(r* IIw73851(.1 The #style directive can be &.B/$./0!=713q(Z^(A6B/$.1 5$73=713q(Z^(AN3".append() IIw73851(./0!="!!1%#q(A6B/$. The #style directive can be placed before inserting a list element.1 &. 0.11% 70!1.//5^(2. Use the #style directive before a Form-constructor or before calling super() in subclassconstructors. This directive can be used in front of any Item-constructor and before some other methods: Insertion Point Item constructors Example IIw73851(. that this method is only available in J2ME Polish.1 5$73="!!1%#q(AN3"./%P:"&1^( P:"&1P31:=DaoEOYvMFQaODY^(%055(r* Explanation The #style directive can be placed before any item constructor.3A^(%055((r* List.//5 P:"&1P31:($:&(@(%1C(P:"&1P31:q( %055^($./738^(#12"053 N3.:' IIw73851(:"$%N.-preprocessing-directive for applying the desired design-styles. Setting Styles You should use the n89<1. The #style directive can be placed before adding a list element.B/$.1(XA^(%055( ) placed before inserting an r* element to a ChoiceGroup.1 5$73=$%71.B/$. Form constructor IIw73851(:"$%N. IIw73851(/!1%D$%Item.set() IIw73851(.B/$.:q(AU1%0A(r* II($%(70+.3q(Z^(A6B/$.insert() IIw73851(.3A^(%055((r* List."%.1(VA^(%055((r* d() placed before adding an element to a ChoiceGroup.5(@(%1C(N3.set() IIw73851(. ChoiceGroup.:(2/./0!=$%71.B/$.1 The #style directive can be &. The #style directive can be placed before setting a list element. ChoiceGroup. neither import-statements nor the actual code needs to be changed.insert( IIw73851(.3q(Z^(AN3".1U/#1q( setAppearanceMode P31:=[oSF]DPJe(r* () The #style directive can be placed before calling the setAppearanceMode-method of an Item.B/$.The J2ME Polish GUI the MIDP-standard.:(@(%1C(Q/..1(XA^(%055((r* The #style directive can be placed before setting an element of a ChoiceGroup. Please note.3A^(%055((r* ChoiceGroup.

)( 8(4.)(20D9&.#&'. but this requires additional memory and runtime.)A.)A. use normal “static” styles for the final application.*.-4'&90S"W"?3-.5"7717(/2(D$73' IIw73851(:"$%N.-directives.91. All g'&-s are designed with the “form”-style for example.0-". dynamic and 98 .)A.)(0. The following example uses the “.9. the build will report this error and abort the processing.?9.3g'&-6 4(!1. So is the “title”-style responsible for the appearance of D#&.) 8(4. Please refer to the documentation on page 105 for more information on static..#0#1"880A". You should.)(L08#&.)A.?9.The J2ME Polish GUI Insertion Point List constructor Example IIw73851(:"$%N.')31#*(.#0A".050C ZZn89<1.-4'&90S"W"?3-. In this case the first found directive is used: . In this case the designs do depend on the classes. e.11% 70!1.)A.&209.#&'.91.)-titles for example. Using Dynamic and Predefined Styles When dynamic styles are used.)*80g'&-0C 4(!1.css”-file.-directive.)%09.)%09.91. Predefined styles are used by default for some elements. therefore./0(&120!%34)%056 #'1(-)8/0H6 O You can also use several style-names in a n89<1.g.056 333 O O When none of the provided style-definitions is found.)(20D9&.mainMenu”-style for the design of the form: .3g'&-6 4(!1.91.056 333 O O The “.#0A".-"%.: 3-". you do not even have to set the n89<1.')31#*(.050C ZZn89<1..9.0-"..)(0.#0#1"880A".)*80g'&-0C 4(!1.q(AU1%0A(^(D$73=PUSDP6PY(r* Explanation Use the #style directive before a List-constructor or before calling super() in subclassconstructors.)A. Using dynamic styles can be a fast way to check out the GUI for existing applications.11% D$73(5$73(@(%1C(D$73q(AU1%0A^( D$73=PUSDP6PY(r* II($%(70+.*.)A.mainMenu”-style then needs to be defined within the “resources/polish..&209.)(0C !"#$%&'()*+.

^(%055(r* Creates a new TabbedForm. B.83*.The J2ME Polish GUI predefined styles. Programming the TabbedForm The TabbedForm is a form that separates the included GUI elements on several tabs."+(. is enabled when the GUI of J2ME Polish is used.8K3"4.841"<3R1"8Ke"#$1.: ZZn.0only features are used.g. Image[] tabImages ) IIw73851(:8Y"++1#Q/.0 Applications to MIDP/1.3)'$.0 standard.8K3-. e.%K92. 2/. ! 4'1.0 call Display.%K920Y[[[056 ZZn.(3"+A. The MIDP/2.*4Y0Z0 4'1.)*. You can use any Form methods like setItemStateListener( .. The implementation offers some additional methods for configuring its tabs: directive can be used in front of any Item-constructor and before some other methods: Method Example Explanation TabbedForm( String title..$%&<>(jAQ$. ) in the TabbedForm.8K3#1*#Y3[0Z0 4'1.0 as well as MIDP/1.8K3(8. Sets the item to the specified set( int tabIndex. is defined when the Mobile Media API is supported by the current device.: Y"++1#Q/.0 widgets like a JpJ@J07K'.0 devices. When a specific call is not supported by a target-device.:=713q(Z^(V^(:8N3. is defined when the Nokia UI API is supported by the current device.3--"4.:="!!1%#q(Z^(:8N3. Usually that error then needs to be surrounded by an appropriate n.Rpreprocessing directive. There are.R Useful Preprocessing Symbols ! 4'1.#.$%&P31:(r* append( int tabIndex.8K3#1*#Y3Y indicates the current configuration.0 UI standard.8K3"4. ! 4'1.8K3-.841"<3R1"8Ke"#$1. which are outside of the scope of the J2ME Polish GUI. String[] tabNames.R*.:q( A[155/A^(%1C(N3.R04'1.8K`(. Programming Specific Items and Screens In general the J2ME Polish GUI is fully compatible to the MIDP/2.)95.*4H indicates the current MIDP platform. Source code adjustments are only necessary when MIDP/2. The first tab has got the index 0. int 2/.0 Platforms When you use the J2ME Polish GUI you can use MIDP/2.`&'(4 or a 7(89'-:9.*4H 9K. e.73( Y"+A^(A"%/3B1. Item item ) Adds the item to the specified tab.$%&P31:(r* 99 .:(@(%1C(Y"++1#Q/. 4'1. ! ! Please have a look at the chapter “Using Custom Items” on page 161 for more information on custom items. 4'1.8K3-.on MIDP/1.J'1.0 devices as well without any restrictions.g. however some enhancement that are not available in the MIDP/2. Porting MIDP/2.:(2/. the build-process will be aborted with a compile error.setCurrentItem( Item ) is supported by the J2ME Polish GUI for both MIDP/2.

-4'&90*.#.>I056 R'&-3"44.8K3(.=r7.-01"!. 2/.#&'.')31#*(.841"<0*.3"44.89EL0ED.')31#*(.$.#&'.&0C 4&...#&'.). Deletes the given item from the specified tab.&6 .).3>.#.#.01"!.*1.*.=.*.&9K*"9.V07K'.9(&)7-*050C D9&.V0B"9.-4'&90S"W"?3-.0F0).10F0).01"!.3.80F0).01"!.-4'&90S"W"?3-.-4'&90S"W"?3-.?9g.) >"!!.)'(%K34'1.-.-4'&90S"W"?3-.*.#.?9g.\|0j0 >.-2)(11L0EzK"90$.-'EL09"!\"-.#&'.V0D9&.3:9.9.9L0B.-6 .1*0)"-.1*56 ZZn89<1.-D9"9.3B"9.')31#*(.V0>.')EL0 E>.&9K*"</E056 R'&-3"44.0*.V0D9&.37'--")*6 .g..&9EL0a[L0>.9.*B.*.89.-6 .3:9.0#K'.)%8EL0E:)9.9.)*2E*'%8EL0)(1156 Example Explanation index on the given tab.1 1"!.9.9.)*20YL01"!.#.9.:9.g.#.90-. 7K'.841"<6 .8L0)(11056 ZZn89<1.9.*D#&.#&'.g.-41.EL0E7')).1*6 4(!1.1*0!.9.V0D9&.-'200B.*.#9.83)"-.)*2[L09K.9E0O6 ZZn89<1.#&'..')31#*(.')31#*(.g.1 1"!.6 .')31#*(.-"180*'0<'(01.0F0).V0D9&. Item item ) delete( int tabIndex.1*6 .0-(19.)4(9 9K.?9g..')31#*(.*1.)*20[L01"!.3A@=>:J=I056 ZZn89<1.37K'.0.g.99.')31#*(.#..=.1056 ZZn89<1.)980:9.1*3.&9K*"9.#0>"!!.*g'&-6 4(!1..09"!!.W"9.-4'&90S"W"?3-.g./E056 R'&-3"44.)%PQ09"!\"-.V0>"!!.*g'&-0R'&-0F0).37K'.1*3:\:>:.83)"-.g.JDrzp^B056 R'&-3"44..7K'.-'A..)'(%K34'1.`&'(40#K'.1*3B.?9g.#&'.-4'&90S"W"?3-.1 D9&.)%:9..#&'.:=#15131q(Z^(:8N3.1*20)(11L0B"9.1056 ZZn89<1. 100 .*.10F0).10F0).)%:9.)*20[L01"!..-4'&90S"W"?3-.#.)*0'R0")..41.3D9&.0.-'0.?9g.1*20)(11L0E^'!.*.`&'(46 .9.*.#.1056 ZZn89<1.#0#1"880>"!!.#.3>"!!.841"<L07'--")*0 &.&)./E56 R'&-3"44.`&'(420)(11L07K'.-4'&90S"W"?3-.)%:9.056 ZZn89<1..-4'&90S"W"?3-.-'6 .)*20[L0!.-20)(11L0E!.)4(9 B"9.1*6 .0>.*g'&-2E>"!!.8K3*.#K'.#&'.89.-D9"9.*g'&-B.')31#*(.$%&P31:(r* Item item ) The following listing demonstrates the usage of the TabbedForm: 4"#$"%.3B.)%:9.*g'&-B.)%:9.*.)%PQC0E:)4(9EL0E7K'.-20)(11L0E)"-.The J2ME Polish GUI Method itemIndex.1*0F0).3.

V07K'.#.0C D<89.9:9.#.3"44.-20#K'.#K'.`&'(420)(11L07K'.0#K'.-D9"9.-0.)89")#.)*2YL0#K'.#K'..?9g.8056 *.0F0).)%25056 O0.EL0)(1156 R'&-3"44.#.9.0#K'.*2:9.956 R'&-38.#0W'.3"44.).-056 O O O 101 ..)*2E!.V0D9&.:9.=.9D9&.)9:9.')/E56 R'&-3"44.)%:9.#.-2)(11L0E7')).-3'(934&.#9.9.056 4(!1.9.7K")%.#.)91)2E:9.-0D9"9.:9.*1.1 1"!.9.0#K'.1*50C >.01"!.&2-.#.0-(19.1*3%.The J2ME Polish GUI ZZn89<1.1*0F02>.1*50.)*20HL01"!.1056 ZZn89<1.7K'.0#K'.)*2EBD=EL0)(1156 ZZn89<1.89.07K")%.#K'.9.841"<38..97(&&.-3'(934&.56 O R'&-3"**7'--")*2&.#K'.&209K.89.'R0>..#.0#K'.-0.&*8EL0)(1156 R'&-3"44. #K'.:9.10F0).56 ZZn89<1.#.-6 D<89.-D9"9.3"44.?9g.*/0E0o0 R.97'--")*=.*0.#.#.-50C .*/0E0o0.)*2E#"98EL0)(1156 ZZn89<1.)*2E:DB\EL0)(1156 ZZn89<1.?9g.1*0R.3"44.#.)*2HL0#K'.18.:9.07K")%.3"44.).-0D9"9.9(&)7-*56 R'&-38.#.)91)2E:9.#.:9.#.41.#K'.R02..3A@=>:J=I056 ZZn89<1.#.#.)*2E7"!1.#.

So every web-designer can now design mobile applications thanks to J2ME Polish! This chapter will explain all details of the design possibilities.The J2ME Polish GUI The J2ME Polish GUI for Designers J2ME Polish includes an optional Graphical User Interface. Alternatively you can use the dynamic names of the GUI items. A style can be assigned to any GUI item like a title. The GUI will be incorporated by the preprocessing mechanism automatically. unless another directory has been specified. “a” for hyperlinks or “form p” for all text-items which are embedded in a form. therefore no changes need to be made in the source code of the application. This is described in more detail in the “Designing Specific Devices and Device-Groups” section.com/css/ for an excellent tutorial of CSS for web pages. Sub-folders are used for styles and content for specific devices and groups./0!'1*6 R')9+8. You can put all resources for Nokia devices into the “Nokia” folder and resources for Samsung's E700 into the “Samsung/E700” folder. The design definitions are grouped in “styles”. “p” for text-items.ui-classes. Any style contains a selector as well as a number of attributes and its values: 03-<D9<1.MySTYle” is the same as “.g. which can be designed using the webstandard Cascading Style Sheets (CSS). 102 .w3schools.8K3#88 file.myStyle”. unless the “usePolishGui”-attribute of the <build> element is set to false in the build./04&'4'&9. no prior knowledge about CSS is required./01"&%.xml file.9.i.')"16 !"#$%&'()*+#'1'&/0!1"#$6 O In this example the style called “myStyle” defines some font values and the color of the background. You can specify styles directly for GUI items with the #style preprocessing directive in the source code. The style declaration needs to be finished by a closing curved parenthesis.8K3#88 in that directory. Within a style several attributes and its values are defined: 3-<D9<1.7 The most important file is 4'1. so “.microedition. Apart from the 4'1. 7 You can specify the directory with the “resDir” attribute of the <build> element in the build. The possible combinations as well as the predefined style-names are discussed in the section “Dynamic. Static and Predefined 6 Refer to http://www.6 R')9+R"#.00 0C0R')9+#'1'&/00VK.xml file. you can put images and other contents into the resources-folder.6 The GUI is compatible with the javax. a paragraph or an input field. e. This can be used to create completely different designs for one application.6 O selector/name attribute value Fig.6 R')9+89<1. 2: Structure of a style Each attribute-value pair needs to be finished with a semicolon.9. All design definitions can be found here. A Quick Glance All design settings and files are stored in the “resources” directory of the project.0C R')9+#'1'&/0VK. The selector or name of style is case-insensitive.

the border and font-settings. “. You need to specify the more specific setting only.The J2ME Polish GUI Styles”.myStyle extends baseStyle {}”. 2. paddings and content. No other attributes or styles need to be defined. implicit groups are defined by the supported APIs of a device and the BitsPerPixel capability of devices. “resources/mmapi”. This process is described in the section “Extending Styles”. You can add a small movie for all devices which support the Mobile Media API (mmapi) by putting that movie into the “resources/mmapi” folder.g. “Nokia”. An explicit group is for example the “Series60” group.16”. “Samsung” or “Motorola”) you put all resources and design definitions for devices of that vendor. The resources will copied into the root folder of the application. Thirdly the group-specific resources will be used. “resources/Nokia/6600” or “resources/Samsung/E700”.g. The Hierarchy of the “resources” Folder In the resources folder itself you put all resources and design definitions which should be valid for all devices. “resources/Series60”. Last but not least you can use device specific resources and design definitions by putting them into the “resources/[vendor]/[device]” folder. group or device.8+” or “resources/BitsPerPixe.g.g. These common settings are described in the section “Common Design Attributes”. In the folder named like the explicit and implicit groups of a device you add the resources and design definitions for these device-groups. “resources/Nokia”. Other common design settings include the background. Designing for Specific Devices or Device-Groups Sometimes the design needs to be adapted to a specific device or a group of devices. When you want to change the color of a font. J2ME Polish supports the CSS box model with margins.css file for a specific vendor. Attributes for specific GUI items as well as the details of the different background and border types are discussed in the section “Specific Design Attributes”. You can easily use specific pictures. Any existing resources will be overwritten by more specific resources: 1. you just need to specify the “font-color” attribute of that style. e. Or you can add colored images for all devices which have at least a color depth of 8 bits per pixel by putting these images into the “resources/BitsPerPixel8+” folder. 3. 4. “resources/BitsPerPixel. you do not need to repeat all styles and attributes from the more basic settings. Styles can extend other styles with the extends-keyword. When you add the polish. e. e. In the folder named like the vendor of a device (e. This is the cascading 103 .g. Secondly the vendor-specific resources will be used. e. styles etcetera by using the appropriate sub folders of the “resources” folder. The resources and settings in the device specific folder will overwrite all other resources and settings. The device specific folder is for example the folder “resources/Nokia/6600” for the Nokia/6600 phone or the folder “resources/Samsung/E700” for Samsung's E700. At first the basic resources and definitions found in the “resources” folder will be used.

BitsPerPixel-Groups Every device display has a specific color depth which is specified by the BitsPerPixel-capability of that device in the devices. API.6 R')9+89<1.xml can either be found in the root folder of the project or in the import/enough-j2mepolish-build.css: In “resources/polish. Explicit groups are stated by the <groups> element of the device in the file devices.*.')"16 !"#$%&'()*+#'1'&/0!1"#$6 O You can change the font-color of that style for all Nokia devices with the following declaration in “resources/Nokia/polish.(-6 O Groups Every device can have explicit and implicit groups.css” you define the style “myStyle”: 3-<D9<1.The J2ME Polish GUI character of the Cascading Style Sheets of J2ME Polish. The supported platform of a device can be specified in the devices. it belongs to the “nokia-ui” group.0C R')9+#'1'&/0VK. it belongs to the “mmapi”-group. So you can specify the layout of MIDP/1. Implicit groups are defined by the capabilities of the device: Each supported API results in an implicit group and the BitsPerPixel capability results in several groups. And you can use specific images or other resources for MIDP/2.6 R')9+R"#.0C R')9+#'1'&/0%&"<6 O You can specify another font-size and font-color for the Nokia 6600 phone with these settings in “resources/Nokia/6600/polish. otherwise it belongs to the “midp2”-group. it belongs to the “midp1”-group.0 devices in “resources/midp1/polish.*6 R')9+8. 104 .css”: 3-<D9<1.and Java-Platform-Groups A device can support different APIs and Java-platforms.css”. This example illustrates the cascading character of polish.0 devices in the folder “resources/midp2”. the device 8 devices.0 standard. When the device supports the Nokia-UI API. Alternatively this setting can be specified in the file groups.jar file.xml for specific groups.9.css”: 3-<D9<1.xml8.xml. The name of the implicit group is defined by the <symbol> element of the API in the file apis. When the device supports the Mobile Media API (mmapi).i. When the device supports the MIDP/1./0!'1*6 R')9+8.0C R')9+#'1'&/0&. For each supported API an implicit group is created.xml file with the <JavaPlatform> element./0-./04&'4'&9.i. Depending on how many bits per pixel are supported./01"&%.xml file.

096 16 216 = 65.18+ BitsPerPixel.24 BitsPerPixel.16+ BitsPerPixel.4 BitsPerPixel.16 BitsPerPixel.777.16+ BitsPerPixel.css”.16+ BitsPerPixel.12+ BitsPerPixel.4+ BitsPerPixel. Static and Predefined Styles J2ME Polish distinguishes between dynamic.536 18 218 = 262.18 BitsPerPixel.24/polish. static and predefined styles: ! ! Predefined styles are used by the GUI for several items like screen-titles.4+ BitsPerPixel.8+ BitsPerPixel.4+ BitsPerPixel.12 BitsPerPixel.12+ BitsPerPixel.4+” folder.8+ BitsPerPixel. Static styles are defined in the source code of the application with the #style preprocessing directive.4+ BitsPerPixel.18+ BitsPerPixel. Dynamic.8+ BitsPerPixel.8+ BitsPerPixel.144 24 224 = 16.216 So you can put images for phones with at least 16 colors into the “resources/BitsPerPixel.8 BitsPerPixel.4+ 12 212 = 4.8+ BitsPerPixel. 105 .4+ BitsPerPixel.The J2ME Polish GUI belongs to different groups: Bits per Pixel 1 4 8 Colors 2 1 = 2 (b/w) 24 = 16 28 = 256 Groups BitsPerPixel.12+ BitsPerPixel. And you can specify settings for true color devices in the file “resources/BitsPerPixel.1 BitsPerPixel.12+ BitsPerPixel.24+ BitsPerPixel.

”. which refers to another style.xml (with fullScreenMode=”menu”). This style is used for the menu the label of any item. unless the preprocessing variable “polish.css file.The J2ME Polish GUI ! Dynamic styles are used for items according to their position on the screen.g. For MIDP/2.J'1.FE4'1. Static Styles The easiest styles are the static ones. In contrast to the normal “user-defined” static styles their names do not start with a dot. This style is used in Lists. “title” instead of “. e. Currently this is only used for showing the current input mode when the “direct input mode” of a TextField or a TextBox is enabled.8K>. e.myStyle”. The style used for the menu items (the commands) of a screen. The style that is used for displaying additional information in a screen. “focused-style: menuFocused.title”.E0 ()1. The full screen mode can be triggered by the “fullScreenMode” attribute of the <build> element in the build. the “menu” style is used instead. Forms and for Containers like the ChoiceGroup. Static styles are faster than dynamic styles.FE9&(.E0W"1(."!1. It is therefore recommended to use static styles whenever possible.g. Compare menu menuItem label info 106 . The programmer just needs to tell the designer the style names and what they are used for (that is for what kind of items or screens) and the designer defines them in the appropriate polish. Static styles always start with a dot. When menuItem is not defined. Following predefined styles are used: Style title Description The style of screen-titles.usePolishTitle” is defined with “true”: UW"&.g. This style is used for designing the menu bar in the full screen mode.8K3q. e.8K3(8.menuFocused” as well. In this case you need to define the static style “. You can also use custom styles for specific Screens or ChoiceGroups by using the “focusedstyle”-attribute (compare page 131).91.0)"-. Predefined Styles Predefined styles are static styles which are used by the J2ME Polish GUI. “. One can specify another label-style by defining the CSS-attribute “label-style” in the appropriate style."E0ZT You can also use custom styles for specific Screens or ChoiceGroups by using the “title-style”-attribute (compare page 131).)*'&0FF0\'$. In the menu style you can also define which style is used for the currently focused command with the “focusedstyle”-attribute.0 devices the native implementation is used by default.88FE4'1. focused The style of a currently focused item.

“button” or “icon”.i. therefore. 40C R')9+#'1'&/0!1"#$6 R')9+8. even when it is not explicitly defined in the polish. “list” or “textbox”. This style designs the tab-bar of a TabbedForm. tabbar activetab Inactivetab The names of predefined styles must not be used for static styles.6 O R'&-0C -"&%./0-. “form”./0-./0-. Obviously. You can also check out the power and possibilities of the J2ME Polish API without changing the source code of an existing application at all. e.*.i.(-6 O Static styles and dynamic styles can be used together. Screens use the name of the screen.&/0)').*.9.(-6 !"#$%&'()*/0)'). Dynamic Styles Dynamic styles can be used to apply styles to items without using #style directives in the source code.title” etc.*. Designs all tabs but the currently selected one of a TabbedForm. Dynamic styles do not start with a dot and use the selectors of the items they want to design: Texts use either “p”.css file. “a”. to use static styles instead for finished applications.)/0h6 !"#$%&'()*+#'1'&/0%&"<6 !'&*. The default style is always defined. so you must not use a static style with the name “. With dynamic styles the designer can work completely independent of the programmer and try out new designs for GUI items which have not yet an associated static style. you can design all hyperlinks9 in the screen 9 StringItems which have the appearance mode Item.(-6 O You can also design only items which are contained in other items or screens: The style “form p” designs all text-items (of the class StringItem) which are contained in a form: R'&-040C R')9+#'1'&/0VK.i.g. Designs the currently active tab of a TabbedForm.6 R')9+8.The J2ME Polish GUI Style default Description page 142 for more information. It is recommended.6 R')9+8.HYPERLINK 107 . The style which is used by the J2ME Polish GUI when the desired predefined style is not defined. dynamic styles need a bit more memory and processing time than static styles.

Shows an image together with text. since the spaces can be set for all items with the margin and padding attributes.#6 O Items and screens have specific selectors for dynamic styles: Item-Class StringItem p a button ImageItem Gauge Spacer img gauge spacer Selector Explanation StringItem shows text. The selector “checkbox” is used when the list or choice group has the type “multiple”. when this item is contained in an implicit list. Allows textual input from the user.startScreen” for example with the following style declaration: 389"&9D#&. IconItem TextField DateField ChoiceGroup ChoiceItem icon textfield datefield choicegroup listitem radiobox checkbox popup Screen-Class List Form TextBox list Selector form textbox 108 .. Explanation Shows several choice items. The selector “listitem” is used. when the item has the appearance mode PLAIN. Allows the input of dates or times from the user./0. The “a” selector is used. Shows a single choice. The usage of the Spacer item is discouraged. The selector “radiobox” is used when the list or choice group has the type “exclusive”./0-.*. Contains several choice items. The “button” selector is used.The J2ME Polish GUI with the style “. Contains a single textfield. Contains different GUI items.i.6 R')9+8.9"1. The selector “popup” is used when the choice group has the type “popup”. The “p” selector is used.(-6 R')9+89<1. Shows a progress indicator. Shows an image. when the item has the appearance mode BUTTON. when the item has the appearance mode HYPERLINK. Is used for showing an empty space.)0"0C R')9+#'1'&/0!1(.

80.)0C R')9+#'1'&/0VK.6 !"#$%&'()*+#'1'&/0!1"#$6 O The above example would be valid.)0.)0C00Zm09K.80.)/0h6 R')9+#'1'&/0VK. a number of attribute-value pairs and a closing curved parenthesis./0-.%K8#'&. 3: Structure of a style Every style starts with the selector followed by an opening curved parenthesis. but “font-color” and “background-color” are specified differently.9.?9.)0.9.?9.9.D#&.i.)*80.%K8#'&.)D#&.)D#&.6 !"#$%&'()*+#'1'&/0!1"#$6 O In the above example the style “highscoreScreen” inherits all attributes of the “mainScreen” style.6 O 3-".)*80-"...?9.)0. when the style “baseScreen” would not extend the “highscoreScreen”-style. The selector can consist of several item-names and contain an “extends” clause.)D#&.*./0.#6 !"#$%&'()*+#'1'&/0%&"<6 O 3K.6 O selector/name attribute value Fig.The J2ME Polish GUI Extending Styles A style can extend another style.?9. Circle inheritance is not allowed. 109 . so the following example results in a build error: 3!"8.9. With this mechanism a lot of writing work can be saved: 3-".i.)*80!"8.)0C -"&%.9"1.)0C R')9+#'1'&/0VK.*v0mZ -"&%...D#&..9"1.)/0Y[6 R')9+#'1'&/0!1"#$6 R')9+8.*./0.?9.D#&..)0. It inherits all the attributes of the extended style.)*80K../0-.D#&.)*80-".)0C -"&%. CSS Syntax Following rules do apply for CSS styles: Structure of a CSS Declaration 03-<D9<1.(-6 R')9+89<1..)D#&.)W"1.%K8#'&.(-6 R')9+89<1.)/0Y[6 R')9+#'1'&/0!1"#$6 R')9+8.#6 !"#$%&'()*+#'1'&/0%&"<6 O 3K.D#&..00 0C0R')9+#'1'&/00VK.

/08<89./0mZ R')9+8.)08#&.)0C R')9+#'1'&/0!1"#$6 R')9+8. Naming Styles can use any names.i.(-6 89<1. Referring to Other Styles When another style is referred.)D#&. Everything between these boundaries is ignored: Zm09K./0.(-6 Zm089<1.-L04&'4'&9./08<89./08<89.)%09K.0-".0#")0. Styles can be referred in attributes or after the extends keyword in the selector of a style.0#'1'&0'R0"0R')9/0mZ R')9+#'1'&/0!1"#$6 Zm08.0R"#. Names are not case-sensitive./0.*.*. All Java keywords like “class”.#6 R"#.)D#&.i.(-0")*01"&%.9"1.-6 O 110 ..#6 R')9+R"#.#0'&0()*.08<89../0-.8.%)809K. the dots of static styles do not need to be written.(-6 R')9+89<1./0mZ R')9+R"#.-6 O O The grouping makes the declarations better readable for humans.041".9"1.80"&. Grouping of Attributes Attributes can be grouped for easier handling: 3-".R.i.8089<1. Static styles need to start with a dot.')"10'&0-')'84"#.#6 Zm09K./0-.9"1.)/0mZ 3-". “int” or “boolean” etcetera are not allowed as style names.)0C R')90C #'1'&/0!1"#$6 8.. Static styles must not use the names of dynamic or predefined styles.0*.*/0mZ R')9+89<1./0.&0!.. as long as they consist of alphanumeric and underline (_) characters only.9"1./0-.08-"11L0-.)D#&.-6 O The above code is equivalent with the following: 3-". Comments Comments can be inserted at any place and start with “/*” and stop with “*/”.The J2ME Polish GUI Each attribute-value pair needs to be finished by a semicolon.9K.*.80"&.i.).*.&1.).)0C Zm0*..)L0!'1*L0.

&/0)').1.)%8/0mZ -"&%. The defined colors.)%/0Y6 4"**.*0C Zm0-"&%.6 8.*/0mZ 1"<'(9/0#.8089<1.R9/0h6 -"&%. background: The definition of the item's background border: The definition of the item's border before and after: Elements which should be inserted before or after the items. This makes changes very easy. An example of such a complete style definition is the following: Zm09K.9#/0mZ R'#(8.)9.&.0#(&&.)+1.-.The J2ME Polish GUI Common Design Attributes Structure of polish./08<89. specific attributes: All attributes for specific GUI items. fonts: The fonts-section contains font definitions.#"1/0H6 Zm0R')90mZ R')90C #'1'&/0!1(.)%+W.)+&.-6 O Zm01"<'(90.&/0Zm !'&*.89L0R'&-0.&6 Zm0!"#$%&'()*/0mZ !"#$%&'()*+#'1'&/0%&"<6 Zm0)'0!'&*.&9. since you need to change the value only in one position.)80")*04"**.css The polish. fonts. rest: The rest of polish.*.*0./0-.%)809K.6 111 .css file can contain different sections: " " " " " colors: The colors-section contains the definition of colors.)91<0R'#(8. borders: The borders-section contains definition of borders.css contains the actual style definitions.0*.)0"01.(-6 R"#.i.)/0H6 -"&%. backgrounds: The backgrounds-section contains background definitions. Structure of a Style Definition Each style can contain different “sections”: " " " " " " " " margin: The gap between items padding: The gap between the border and the content of an item font: The used content-font and its colors layout: The layout of the items.80#. backgrounds and borders can be referenced in the actual style definitions.)9.8.)90.%K9/0Y[6 4"**.

*0. top and bottom elements. The padding describes the gap between the border of the item and the actual content of that item.)+1.?"-41.80"&. The gap between the label of an item and the actual content is defined by the horizontal padding.#0"99&.&/0"**0")'9K.and padding-attributes define the default gaps for the left.R9. Next to the left.The J2ME Polish GUI Zm0!.&&'V34)%056 Zm0)'084./0mZ "R9.)/0h6 -"&%.#.R'&. either the vertical or the horizontal padding fills the space between the icon-image and the icon-text. which consists of an image and a text. Depending on the align of the image. top and bottom padding. right and horizontal attributes relate to the width of the display: 112 .R9/0Y[6 R')9+#'1'&/0!1"#$6 O Percentage values can also be used. whereas the left margin is 10 pixels: 3-<D9<1. Percentage values for left./0mZ !.0C -"&%. Percentage values for top. J2ME Polish also knows the vertical and the horizontal paddings. bottom and vertical attributes relate to the height of the display.0(8. Since this is a more bizarre and seldom used feature. the top.80. The margin./0(&120"&&'V34)%056 Zm0"R9.R'&. right. whereas any padding defaults to 1 pixel. right. right./0"**0")0.&0. Another example is the icon.)09K.R. In the following example. not much harm is done. right and bottom margin is 5 pixels. These define the gaps between different content sections.mZ O The CSS Box Model: Margins and Paddings All GUI items support the standard CSS box model: margin-top border padding-top padding-right padding-left content margin-right margin-left padding-bottom The margin describes the gap to other GUI items.!(9.&/0(&1201.-"%.-"%. top and bottom) can be set with J2ME Polish. Any margin has the default value of 0 pixels. So far no different border-widths (for left.

%K9/0Hk6 4"**.e.0C 4"**. should fill the complete row). Items following an item with a newline-after layout should be placed on the next line.08 pixels or effectively 2 pixels. right or center. The affected items should use the minimum height possible.R9/0Hk6 4"**. The affected items should be right-aligned. Possible layout values are for example left.)%+&.#"1/0Yk6 R')9+#'1'&/0!1"#$6 O When the device has a width of 176 pixels. No specific layout should be used. The affected items should be centered vertically. hcenter horizontal-expand. The affected items should be centered horizontally. The affected items should always start on a new line (when there are any items in front of it). The Layout Attribute The layout attribute defines how the affected item should be aligned and laid out.52 pixels. The affected items should use the minimum width possible. All layout values of the MIDP/2.)%+1. since every item will be placed on a new line. Such a layout does 113 newline-before - plain default. The affected items should be top-aligned.e. The affected items should use the whole available width (i. meaning effectively a padding of 3 pixels. none . Please note that the capability “ScreenSize” of the device needs to be defined when you use percentage values. hshrink vertical-center vertical-expand vertical-shrink Alternative Names Explanation The affected items should be left-aligned. The affected items should be bottom-aligned. a padding of 2% results into 3. The affected items should use the whole available height (i. instead the default behavior should be used. hexpand horizontal-shrink. Currently the newline settings will be ignored. since every item will be placed on a new line.The J2ME Polish GUI 3-<D9<1.)%+W.&9. At a display height of 208 pixels a vertical padding of 1% results into a padding of 2.0 standard can be used: Layout left right center expand shrink top bottom vcenter vexpand vshrink newline-after horizontal-center. should fill the complete column). Currently the newline settings will be ignored.

?4")*6 O This is equivalent with: 3-<D9<1.0C 1"<'(9/0#. but it can be useful to overwrite a basic setting. using either the “||”. “|”.&0j0.0C 1"<'(9/0K#. All operators result in the same combination.i')9"1+#.0C 1"<'(9/0#. “border-color” etc.0C 1"<'(9/0#.&0'&0.&0j0K'&.?4")*6 O And equivalent with: 3-<D9<1.The J2ME Polish GUI Layout Alternative Names Explanation not need to be defined explicitly.&0jj0.&0")*0.)9.)9.?4")*6 O Colors Colors can be defined in the colors section and in each attribute which ends on “-color”.?4")*6 O And equivalent with: 3-<D9<1.)9.?4")*6 O And equivalent with: 3-<D9<1.)9.&0j0K. Layout values can also be combined.)9.?4")*6 O And equivalent with: 3-<D9<1. An item can be centered and using the whole available width with following example: 3-<D9<1. e.i')9"1+. Predefined Colors The 16 standard windows colors are predefined: Color white black Hex-Value ngggggg n[[[[[[ Example Color yellow maroon Hex-Value ngggg[[ nf[[[[[ Example 114 . “or“ or “and“ operators.0C 1"<'(9/0#. “fontcolor”.)9.0C 1"<'(9/0K'&.g.

which results in an transparent area.0V.)(+#'1'&/0nygf[ggf[60 Zm0")0"14K"+&%!0K.0'R09K. color: nyggg[[[[6 defines a half transparent red. which can be referenced in the styles. “transparent” is only supported by some GUI elements like the menu-bar of a full-screen menu.0#'1'&0mZ !'&*. The colors Section The colors section of the polish.0C R')9+#'1'&/0VK.?+W"1(.?0W"1(.1+#'1'&/0"&%!20YHfL0HhhL0h[L0YHf0560Zm0"0"""L0&&&L0%%%L0!!!0W"1(.0mZ 89"&9+#'1'&/0ng[[60 Zm0"08K'&90&%!+K.?0W"1(.80.)9"%.0mZ 1"!.css file can contain colors.%K9/0nh[BcBc6 %&"</0nygygyg6 O How to Define Colors A color can be defined in many different ways: 3-<D9<1.0mZ !"#$%&'()*+#'1'&/0&%!20HhhL0h[L0YHf05600Zm0"0&&&L%%%L!!!0W"1(. #'1'&/0ngg[[[6 defines red. 115 . fonts.9K04.0)"-.9.0+09K.0mZ R.60 Zm09K.0mZ O Color names refer to one of the predefined colors or a color which has been defined in the colorssection: #'1'&/0!1"#$6 or #'1'&/0*"&$e"#$%&'()*7'1'&6 The hex-value defines a color with two hexadecimal digits for each color (RRGGBB). You can even overwrite the predefined colors to confuse other designers! #'1'&80C !%7'1'&/0nh[7y7y6 !%7'1'&=.The J2ME Polish GUI Color red lime blue green silver gray Hex-Value ngg[[[[ n[[gg[[ n[[[[gg n[[f[[[ n7[7[7[ nf[f[f[ Example Color purple fuchsia olive navy teal aqua Hex-Value nf[[[f[ ngg[[gg nf[f[[[ n[[[[f[ n[[f[f[ n[[gggg Example Another predefined color is “transparent”. Additionally the alpha blending-component can be added (AARRGGBB). The shortened hex-value defines a color by a RGB-value in hexadecimal. Every digit will be doubled to retrieve the full hex-value: #'1'&/0ng[[6 is equivalent with #'1'&/0ngg[[[[6 #'1'&/0n[BH6 is equivalent with #'1'&/0n[[BBHH6 and so on.&+#'1'&/0nf[ggf[60 Zm0"0&%!0K.&#.*0mZ -.80&.11+#'1'&/0&%!20Y[[kL0a[kL0h[k0560 0000Zm0"0&%!+W"1(. border and background sections.

The J2ME Polish GUI A rgb-value starts with “rgb(“ and then lists the decimal value of each color from 0 up to 255: #'1'&/0&%!20HhhL0[L0[056 defines red. With the “bitmap”-attribute a bitmapfont can be used instead of the system. which results in transparent colors. Alternatively percentage values can be used for rgb-colors: #'1'&/0&%!20Y[[kL0[kL0[k056 defines red as well as #'1'&/0&%!20Y[[3[[kL0[3[[kL0[3[[k05 6. which can be designed with the font-attributes: Attribute color Possible Values Explanation Reference to a color or direct declaration Depending on the number of colors the of the color. The smallest possible font. Please note that bitmap-fonts cannot be changed in neither size. The name of the bitmap font. Compare the following section for a detailed discussion of bitmap-fonts. normal) proportional monospace size small medium (default. A font-face in which each character has the same width. #'1'&/0&!%20[L0[L0Hhh56 defines blue and so on. The extension “. proportional and monospace fonts. device supports. whereas the value FF (or 255 or 100%) results in fully opaque pixels. color or style. The default font-face which is used when the font-face or label-face attribute is not set. Some devices support values between 0 and FF. For the argb-construct percentage values can be used as well. The default size for texts. Alpha-RGB colors can be defined with the argb()-construct: #'1'&/0"&%!20YHfL0HhhL0[L0[056 defines a half transparent red. normal) large (big) . This is on some devices actually the same font-face as the system-font. An alpha value of 0 results in fully transparent pixels. Colors with a specified alpha channel can only be used by specific GUI items. Fonts Many GUI-Items have text elements. 116 bitmap face system (default. Please refer to the documentation of the specific design attributes. Alpha Blending Colors with alpha blending can be defined with hexadecimal or argb-definitions (see above). The largest possible font size. A proportional face.bmf” is not needed. colors can look differently on the actual device.

/0!'1*6 O The same specification can also be written as follows: 3-<D9<1. A bold thick style.bmf” extension does not need to be given.9./0*.9'&. StringItems.The J2ME Polish GUI Attribute style bold italic (cursive) underlined Possible Values plain (default. They can be integrated using the “font-bitmap”-attribute.9-"4/0#K.6 89<1./0*.9'& executable.8K3K'-.OZ!./0!'1*6 O O In the font-definition the above face and size attributes can be skipped.R"(1960Zm08"-. The created bitmap-fonts-files (*.9.bmf) can also be fine-tuned using the binary data editor ]C4'1.)"6 !"#$%&'()*+#'1'&/0<.)"&<*"9".OZ!.)Z!. Using Bitmap-Fonts in the J2ME Polish GUI The created bitmap-fonts can be used for any text-based items in the J2ME Polish GUI.i.(-0'&0)'&-"10mZ0 R')9+89<1. Not really a style. The created bitmap-font needs to be copied into the “resources” folder of the project.*0C R')9+!. Just select the File -> “open in binary editor”-command.0C R')9+#'1'&/0VK. just an underlined text. The “.bmf” font is used for the currently focused item: R'#(8.*.ttf) using the ]C4'1.R"(1960Zm08"-.0"808<89. In some cases it might be beneficial to optimize the created PNG image manually for decreasing the size of the image and making manual adjustments.0"80-. A cursive style. Bitmap-Fonts Bitmap-Fonts can be used instead of the usual predefined fonts for any text elements like titles.11'V6 117 . An example font specification: 3-<D9<1.-0'&0)'&-"10mZ R')9+8.*.6 R')9+R"#.)ZR')9. In the following example the “china. etc. since they only define the default behavior anyhow.0C R')90C #'1'&/0VK. Creating Bitmap-Fonts Bitmap-Fonts can be created out of any True Type Fonts (*.*.8K3K'-. normal) Explanation The default style.

.#%+E'!O2.+0%(K#%+E'!O2.P.+)*+V%)1)/M 4(!1.0C R')9+89<1.)920`&"4K.#0A<D#&.)6 !"#$%&'()*+#'1'&/0<.1D9<1.1+89<1.9A"4g')9 class.N%+E'!O2..(+'.?9.)6 !"#$%&'()*/0)').6 O 3-<="!.1D9<1. When you want to have a line-break after each label.N%+E'!O2.JT.)90?0F0H[6 . in which all labels are placed on the left side and all input-fields etc on the right side.)*807")W"80C !/%3'+).)90<0F0h[6 +0%(K3%)1)/K!'%. compare the Screens-description on page 131.)'(%K34'1.)2509K&'V80:pI?#.P.')0C +0%(K+)*+V%)1)/.9.+R. which is designed using the pre-defined style “label”.*Z.S6&0%.3. One can specify another-style by using the “label-style”-attribute: 3-<D9<1.UM O O Labels All GUI-Items can have a label.N%+E'!O2.:Z.+.)0. just add the “newline-after”-value to the layout: 1"!.X2/$-YT.6 89<1.*04".!2/+.+.+K7)+V%)1)/R.)9.+V%)1)/.7./0!'1*6 R')9+#'1'&/0%&.-)K)./0!'1*6 O 1"!.#80%050C ./0-<="!./0!'1*6 R')9+#'1'&/0%&.49.&0j0.13e.8K3(9.2"70K!2$%(0K"+%$KLM 4(!1.The J2ME Polish GUI O 1"<'(9/0#.#0W'.&)R. Please compare the JavaDoc documentation for more information.+K7)+Q. In that way you can get a clean design by using a table.11'V6 O It is often advisable to use separate items for labels and contents..0C R')90C #'1'&/0VK.UM !/%3'+).6 118 .?4")*6 Using Bitmap-Fonts Directly The bitmap-fonts can also be used directly in the program-code with the help of the *.SW)$$2. This example uses a bitmap-font for displaying a text: %.10C R')9+89<1.'K#.. Tables are defined by using the “#'1(-)8”-attribute of the corresponding screen.#0#1"880A<D#&.UM 333 O 333 4(!1.

)*+#'1'&/04. The “focused” style is a predefined style which is used for lists.&6 Backgrounds and Borders Each style can define a specific background and border.R90j0). which colors change all the time: The available background.and border-types are explained in detail in the section “Specific Design Attributes”. There are many different types of backgrounds and borders available.6 .V1.&+#'1'&/0%&"<6 !'&*.*9K/0H6 O This example creates a white rectangular background with a gray border.48/0a[6 O O The above example creates a background which color is constantly changing between white and pink. R'#(8.).6 !'&*.+"R9. When no background or border should be used. 30 color shades are used for the animation.6 O If more complex types should be used. the “none” value can be set: 3-<D9<1. The following example adds a heart picture after the actual GUI items.or border-type needs to be specified explicitly. forms. of which some are even animated.)%60 89"&9+#'1'&/0VK. 3-<D9<1. The following example illustrates this for an background.*0C 119 .9. A specification of a simple background and border is the following example: 3-<D9<1.0C !"#$%&'()*0C 9<4. Before and After Attributes The before and after attributes can be used to insert content before or after GUI items which have the specified style.&/0)').The J2ME Polish GUI O 1"<'(9/01./04(18"9.0C !"#$%&'()*/0)').9.&+V.0C !"#$%&'()*+#'1'&/0VK.)$6 89. the background. which is 2 pixel wide.6 !'&*. and so on.

either the name of the color or a direct definition. unless the “background-image” attribute is set.&D9<1. When no background type is specified. It supports following attributes: Attribute type Required Yes Explanation The type needs to be “round-rect” or “roundrect”.6 !'&*.&+#'1'&/0<.The J2ME Polish GUI "R9.R90j0.&+9<4.0C !"#$%&'()*+#'1'&/0&%!20HhhL0HhhL0[056 O Round-Rect Background The round-rect background paints a rectangular background with round edges.&+V. When no background at all should be used. There are many different background-types which make use of specific CSS attributes. The following styles use a yellow background: 3-<D9<1. The simple background supports the color attribute: Attribute color Required Yes Explanation The color of the background."&934)%056 !"#$%&'()*/0)').#96 !'&*. Backgrounds Fig. 120 .11'V6 !'&*./0&'()*+&.&+"&#/0d6 !'&*. Specific Design Attributes Many GUI items support specific CSS attributes.0C !"#$%&'()*+#'1'&/0<. In the later case the image background will be used. When another background than the default simple background or the image background should be used.*9K/0H6 1"<'(9/01.?4")*6 R')9+#'1'&/0!1"#$6 O Currently only images can be included. 4: The after attribute in action. the background-type attribute needs to be declared. the !"#$%&'()*/0)').&/0(&120K.6 declaration can be used. the simple background is used by default.11'V6 O 3-<p9K. Simple Background The simple background just fills the background with one color.

e. "bottom" and "left". "right". when none is specified. “repeat-x”/“repeat-horizontal” or “repeat- image anchor Yes No repeat No 121 . "top | left". This background type is used by default when no type is set and the “background-image” attribute is set. The vertical diameter of the arc at the four corners. The default color is white. “no-repeat”. a direct definition or “transparent”.#96 #'1'&/04(&41./0&'()*+&. Either “repeat”. The diameter of the arc at the four corners.The J2ME Polish GUI Attribute color arc arc-width arc-height Required No No No No Explanation The color of the background.g. Defaults to the arcvalue. The default color is white. when none is specified. The color of the background.6 "&#/0d6 O O The following example uses a different horizontal arc diameter: 3-<D9<1.0C !"#$%&'()*0C 9<4. E.g. either the name of the color or a direct definition. either the name of the color.#96 !"#$%&'()*+#'1'&/04(&41. You can use a combination of "top".png )” The anchor of the image – when not specified the image will be centered ("horizontal-center | vertical-center"). The URL of the image. "vertical-center" (="vcenter"). “url( background.*9K/0Y[6 O Image Background The image background uses an image for painting the background. The horizontal diameter of the arc at the four corners. This example creates a purple background with an arc diameter of 6 pixels: 3-<D9<1. when none is specified.0C !"#$%&'()*+9<4. Defaults to the arcvalue./0&'()*+&.6 !"#$%&'()*+"&#/0d6 !"#$%&'()*+"&#+V. Defaults to 10 pixels. "horizontalcenter" (= "hcenter" = "center"). This color can only be seen when the image is not big enough. The background supports following attributes: Attribute type color Required No No Explanation When used needs to be “image”.

Either “true”/“yes” or “no”/“false”. can be negative for overlapping the tiles. Default is no repeat. The vertical gap between tiles."96 O Circle Background The circle background paints a circular or elliptical background.)9. Determines whether the background should be repeated.6 !"#$%&'()*+#'1'&/0%&. Is only applicable when the repeat mode is activated.-"%.0C !"#$%&'()*+9<4. With the “diameter” attribute it can be ensured that always a circle and never an ellipse is painted.9. The following style uses the image “gradient. Is only applicable when the repeat mode is activated. Explanation The following example uses a green circle background with a diameter of 20 pixels: 3-<D9<1. Defaults to “white”. repeated horizontally or repeated vertically."&934)%056 !"#$%&'()*+&. Is only applicable when the repeat mode is activated..&/0H[6 O 122 . paddinghorizontal paddingvertical overlap No No No The horizontal gap between tiles.)6 !"#$%&'()*+*. Defaults to 0.4. Defaults to 0.&6 !"#$%&'()*+#'1'&/0&%!20dcL0fYL0yy056 O This style uses the image “heart.."9/0&.0C !"#$%&'()*+. Defaults to false. The color of the background.4. It supports following attributes: Attribute type color diameter Required Yes No No The type needs to be “circle”.)934)%056 !"#$%&'()*+")#K'&/09'40j0#. Defines whether the tiles should overlap over the actual background-area when they don't fit exactly into the actual background-area. The diameter then defines the diameter of the circle.png” as a repeated background: 3-<D9<1.The J2ME Polish GUI Attribute Required Explanation y”/“repeat-vertical”./0(&120K.&#1./0#.png” as a background: 3-<D9<1."-./0(&120%&"*. either the name of the color or a direct definition. can be negative for overlapping the tiles.-"%.0C !"#$%&'()*+.

The color is changing from a startcolor to an end-color. The color of the background at the end of the animation sequence.The J2ME Polish GUI Pulsating Background The pulsating background animates the color of the background. Either “yes”/”true” or “no”/”false”.)*+#'1'&/0<. The following style starts with a white background and stops with a yellow background: 3-<D9<1. either the name of the color or a direct definition.6 !"#$+")*+R'&9K/0R"18. Determines whether the animation should be repeated.11'V6 89. Defaults to “yes”.6 O O Pulsating Circle Background The pulsating circle background paints a circular or background which size constantly increases and decreases.)%6 89"&9+#'1'&/0VK.0C !"#$%&'()*0C 9<4. the animation will jump from the end-color directly to the start-color (when repeat is enabled). Defaults to “white”.6 .48/0Yh6 &. The maximum diameter of the circle. Either “yes”/”true” or “no”/”false. Defaults to “yes”. The color of the background.and the end-color should be used. The color of the background at the beginning of the animation sequence./04(18"9. 123 .4. after it reaches the end-color."9/0R"18. It supports following attributes: Attribute type start-color end-color steps repeat back-andforth Required Yes Yes Yes Yes No No Explanation The type needs to be “pulsating”.9. It supports following attributes: Attribute type color mindiameter maxdiameter Required Yes No Yes Yes Explanation The type needs to be “pulsating-circle”. Defines how many color-shades between the start. The minimum diameter of the circle. Determines whether the animation sequence should be running backwards to the start-color again. When “no” is selected.

&#1.. It supports following attributes: 124 .517* 2$.0C +". either the name of the color or a direct definition. The following example uses the pulsating circles background with a dark and with a bright color: 3-<D9<1.'(+.* 71./04(18"9.* :$%4#$":131.The J2ME Polish GUI The following example uses a green pulsating circle background with a minimum diameter of 20 pixels and a maximum diameter of 40 pixels: 3-<D9<1. It supports following attributes: Attribute type first-color secondcolor mindiameter maxdiameter circlesnumber step Required Yes Yes Yes Yes Yes Yes No Explanation The type needs to be “pulsating-circles”. The maximum diameter of the circle."-. Float-values like “1. The second circle-color.0C !"#$%&'()*+9<4.$. The number of circles which should be painted.$&B3\&6/5/./0%#(j 38!1'(!057"3$%&4.734.5” are also allowed.)+*.'(_* 731!'(Z=)* .'(XKK* .)%+#..'(K* :"L4#$":131./5/.'(+&6/5/. O Opening Background The opening background paints an animated background which height starts small and then increases whenever it changes the position. This defaults to “1” pixel. Its primary use is for the “focused”-style.$.5174%0:+1. The minimum diameter of the circle. The first circle-color. The number of pixels each circle should grow in each animation phase.)6 !"#$%&'()*+-.-&./5/./%#4."-.&/0H[6 !"#$%&'()*+-"?+*.6 !"#$%&'()*+#'1'&/0%&.&/0b[6 O Pulsating Circles Background The pulsating circles background paints an animated background of ever-growing circles..9.9. either the name of the color or a direct definition.

* 73". It supports following attributes: Attribute type color start-height steps Required Yes Yes No No Explanation The type needs to be “opening-round-rect”. This defaults to 1 pixel. Defaults to 10 pixels. The background color. This defaults to 1 pixel. O Opening-Round-Rect Background The opening round rectangle background paints an animated background which height starts small and then increases whenever it changes the position. Its primary use is for the “focused”-style. The vertical diameter of the arc at the four corners. The height of the background immediately after it has changed its position. Defaults to the arcvalue.34B1$&B3'(Z* 731!7'(h* . defaults to black. when none is specified. This defaults to 4 pixels. The width of the border. when none is specified.0C +". The color of the border. The number of pixels by which the height should be increased in each animation step. The diameter of the arc at the four corners. either the name of the color or a direct definition.'(+&6/5/. When the height is as big as the normal background-height.The J2ME Polish GUI Attribute type color start-height steps Required Yes Yes No No Explanation The type needs to be “opening”. This defaults to 4 pixels. The following example uses the opening background: 3-<D9<1. The number of pixels by which the height should be increased in each animation step./0%#(j 38!1'(/!1%$%&* .-&. The background color. Defaults to the arcvalue. When the height is as big as the normal background-height. The horizontal diameter of the arc at the four corners./5/. borderwidth arc arc-width arc-height No border-color No No No No 125 . The height of the background immediately after it has changed its position. the animation is stopped. the animation is stopped. when none is specified. defaults to 0 (no border). either the name of the color or a direct definition.

The default color is white.34B1$&B3'(Z* 731!7'(h* +/.'(+&6/5/. The vertical diameter of the arc at the four corners./0&'()*+9"!6 #'1'&/04(&41.1.-\&6/5/.3* . Defaults to the arcvalue.4C$#3B'(Z* +/./5/./5/. Defaults to the arcvalue. Defaults to 10 pixels. either the name of the color or a direct definition.#1. The horizontal diameter of the arc at the four corners. It supports following attributes: Attribute type color arc arc-width arc-height Required Yes No No No No Explanation The type needs to be “round-tab” The color of the background. The diameter of the arc at the four corners. It supports following attributes: Attribute Required Explanation 126 .* ./0%#4. O Round-Tab Background The round-tab background paints a rectangular background where the top edges are rounded.'(#".6 "&#/0d6 O O The following example uses a different horizontal arc diameter: 3-<D9<1.6 !"#$%&'()*+"&#/0d6 !"#$%&'()*+"&#+V. This example creates a purple background with an arc diameter of 6 pixels: 3-<D9<1.#1. when none is specified.-&./0%#(j 38!1'(/!1%$%&4.The J2ME Polish GUI The following example uses the opening-round-rect background: 3-<D9<1.4.* 73".0C !"#$%&'()*+9<4. when none is specified.0C !"#$%&'()*0C 9<4./0&'()*+9"!6 !"#$%&'()*+#'1'&/04(&41.*9K/0Y[6 O Smooth-Color Background The smooth-color background paints an gradient background. when none is specified.0C +".

%. stroke No The default value is 0.&+89&.11'V6 0000000000000000 00000000O O Tiger-Stripes Background The tiger-stripes background paints an background with randomized numbers of Stripes. This example creates a red background with an maximum of 25 black stripes: 3-<D9<1. This example creates a red background with an gradient to yellow: 3-<D9<1.4. either the name of the color or a direct definition. It supports following attributes: Attribute color stripescolor Required Yes Yes Explanation The color of the background. either the name of the color or a direct definition.860000 0000000000000000#'1'&/0&. It supports following attributes: 127 .0C 00000000!"#$%&'()*0C 00000000000000009<4. number Yes The posible number of stripes that can be displayed.The J2ME Polish GUI color gradientcolor Yes Yes The color of the background. The color for the gradient.)9+#'1'&/0<. either the name of the color or a direct definition.&/0Hh6 00000000O O Ball-Games Background The ball-games background paints an animated background with an number of sprites which moving through the background./09.0C 00000000!"#$%&'()*0C 00000000000000009<4..+#'1'&/0!1"#$6 0000000000000000)(-!. either the name of the color or a direct definition. The color for the stripes.*6 000000000000000089&.For effects set stroke 1./08-''9K+#'1'&6 0000000000000000#'1'&/0&.4.*6 0000000000000000%&"*.

&+#'1'&/0%&.*9K/0Yh6 0000000000000000. The width of the border in pixels.-"%.0C 00000000!"#$%&'()*0C 00000000000000009<4. border-color Yes imageYes The height for the sprite..+K. either the name of the color or a direct definition.The J2ME Polish GUI Attribute color number image imagewidth Required Yes Yes Yes Yes Explanation The color of the background./0!"11+%"-.)6 0000000000000000 00000000O O Borders There are many different border-types which make use of specific CSS attributes. the border-type attribute needs to be declared./0(&12041"<.&/0)'). When no border at all should be used. Simple Border The simple border paints a rectangle border in one color.-"%.The sprites include the given image(player. The width for the sprite.%K9/0Yh6 0000000000000000#'1'&/0!1(. 128 . The number of sprites that were displayed.&34)%0560000000 0000000000000000. height This example creates blue background with 5 sprites.86 0000000000000000. When another border than the default simple border should be used. either the name of the color or a direct definition. The type attribute does not need to be set for the simple border.png): 3-<D9<1..-"%. Defaults to 1. The only supported attributes are the color and the width of the border: Attribute color width Required Yes No Explanation The color of the border. The image for the sprite. since this is the default border.+V. The border color from the background.&/0h6 0000000000000000!'&*. the !'&*.6 declaration can be used.6 0000000000000000)(-!.

&+"&#+V.0C !'&*.6 V. Defaults to 1. when none is specified. The color of the border.*9K/0H6 "&#/0d6 O O The following example uses a different horizontal arc diameter: 3-<D9<1. This example creates a 2 pixels wide purple border with an arc diameter of 6 pixels: 3-<D9<1.&+V. when none is specified.*9K/0H6 !'&*./0&'()*+&. The vertical diameter of the arc at the four corners. Following attributes are supported: 129 . The diameter of the arc at the four corners. Defaults to 10 pixels. when none is specified.&+#'1'&/0!1"#$6 !'&*. Defaults to the arcvalue./0&'()*+&. The horizontal diameter of the arc at the four corners.0C !'&*. The width of the border in pixels. It supports following attributes: Attribute type color width arc arc-width arc-height Required Yes Yes No No No No Explanation The type needs to be “round-rect” or “roundrect”.*9K/0Y[6 O Shadow Border The shadow border paints a shadowy border.&+V.&+"&#/0d6 !'&*.6 !'&*.*9K/0H6 O Round-Rect Border The round-rect border paints a rectangular border with round edges.#96 !'&*.The J2ME Polish GUI The following style uses a black border which is 2 pixels wide: 3-<D9<1. either the name of the color or a direct definition.&0C 9<4.&+#'1'&/04(&41.&+9<4.0C !'&*. Defaults to the arcvalue.#96 #'1'&/04(&41.

.91. either the name of the color or a direct definition.0C !'&*. either the name of the color or a direct definition.&+#'1'&/0%&. Following attributes are supported: Attribute type color width Required Yes Yes No Explanation The type needs to be “top”. Left and Right Border These border paints a simple border on one side the corresponding item./08K"*'V6 !'&*. The following example uses a green shadow border: 3-<D9<1.&+9<4. The color of the border. The width of the border in pixels. The following example uses a green border on the bottom of the title: 9.&+#'1'&/0%&.The J2ME Polish GUI Attribute type color width offset Required Yes Yes No No Explanation The type needs to be “shadow”.&+V. “bottom”. The width of the border in pixels.*9K/0H6 O Circle Border The circle border paints a round or elliptical border and supports following attributes: Attribute type Required Yes The type needs to be “circle”. when none is specified.*9K/0H6 !'&*. Defaults to 1 pixel. Explanation 130 ./0!'99'-6 !'&*. so the border is painted below the item and right of the item. “left” or “right”. “bottom-right-shadow” or “rightbottom-shadow”. Bottom.9/0H6 O Top. Defaults to 1.)6 !'&*. Currently only a “bottom-right-shadow” is supported.&+9<4. The offset between the corner and the start of the shadow.&+V. Defaults to 1. The color of the border.&+'RR8..0C !'&*.)6 !'&*.

Screens can also have a designable menu. Default color is “black”.&#1.)6 !'&*. When not defined. Defaults to “black”. Defaults to 1. “Cancel”).The J2ME Polish GUI Attribute color width Required No No Explanation The color of the border. The background color of the menu-bar.xml file.0C !'&*. Either the name or the definition of a color or “transparent”. Defines the painting style of the border. Explanation label-color.&+V./0#. Defaults to “white”. label-size. label. Attributes The title of a screen.The font of the menu-commands (like “Select” or face.6 !'&*. when the application uses a full-screenmode10. Please refer to page 145 for more information about designing the menu bar. the menu-style will be used./0*'99.. The style of the full-screen menu. Style-Name title focused menu focused-style menubar-color Add. stroke-style No The following example uses a green circle border with a two pixel wide dotted line: 3-<D9<1. default font is the label-style system font in a bold style and medium size.*9K/0H6 !'&*.&+9<4. Either “solid” or “dotted”. In a Form or List one item is usually focused.&+#'1'&/0%&. menuItem The style for the commands in the menu.+89<1. Defaults to “solid”.*6 O Screens: List. The width of the border in pixels. The style of the currently focused item in the screen. Some of the used styles can also use additional attributes. Form and TextBox Predefined Styles for Lists. 131 . The name of the style for the currently focused menu item. Additional Attributes for Screens Each screen itself can have some additional attributes: 10 The fullscreen-mode can be activated by setting the <build> attribute “fullscreen” to either “menu” or “yes” in the build.&+89&'$. either the name of the color or a direct definition. Forms and TextBoxes All screens have a title and one or several embedded GUI items.

This can be used to layout the items in a table. Defaults to the predefined “focused” style. which can be either “true” or “false”. The “equal” width leads to columns which have all the same width. The name of the custom style for the title of the screen. columns columns-width No No scrollindicator-color show-text-in-title No No foreground-image foreground-x foreground-y No No No 132 . An example is the “dropping” view-type in which the contained items seem to fall from the top to their positions. Either “normal”. “#'1(-)8+V. The x-position of the foreground image in pixels from the the left border. Defaults to “normal”.g. Defaults to 1 column. “equal” or the width for each column in a comma separated list (e.xml” file. The number of columns. when the “menu” fullscreen setting is activated in the “build. An attribute for Lists only. This defaults to the predefined “title” style. "url( mascot. e. The view-type can be used for defining very different and even animated views of the items in a screen. only the image-elements of the List will be shown and the text-elements will be used as titles. The title will be updated with each new selection. This attribute is only used. The default color is “black”. Please note that not all viewtypes support the “columns” and “columns-width”-attributes.g.The J2ME Polish GUI Attribute focused-style title-style view-type Required No No No Explanation The name of the style for the currently focused item. The explicit list of column-widths results in the usage of those widths. The URL of a image that should be painted at the very front of the screen. The y-position of the foreground image in pixels from the the top border.png )". meaning that each column uses as much space as the widest item of that column needs. menubar-color No The color of the menu-bar.*9K/0d[Ld[LY[[6”). This overrides the settings in the predefined style “menu”. The color of the element which is shown when the screen can be scrolled. When “true” is given.

0u1.89g'#(8D9<1./0!'1*6 O defines the font style for the items in an implicit list. 1.)$6 O defines the background color for screens of the type “List”.).890C !"#$%&'()*+#'1'&/04. a multiple list contains a “checkbox” and an exclusive list contains a “radiobox”.R. Dynamic Styles for Screens Fig.0).89. The selector of these items depends on the type of the list.89.9.8901.. ?)*+N2* A TextBox uses the dynamic selector “textbox” and contains a single “textfield” item.*80 9'0!. [%(+ A list uses the dynamic selector “list” and always contains choice-items.)$6 O defines the background color for screens of the type “Form”.60Zm09K.The J2ME Polish GUI The following example uses some of these additional attributes: 1.-"%.*+89<1.9. R'&-040C R')9+89<1. A form uses the dynamic selector “form” and can contain different GUI items. 133 . Commands A multiple List or ChoiceGroup adds the commands “Mark” and “Unmark” by default to the menu._("16 R'#(8. 5: Using columns instead of a normal list.0*.-t0mZ R')9+89<1./0(&120!%34)%056 #'1(-)8/0H6 #'1(-)8+V. 1.*L09''0mZ O TextBoxes also support a direct input mode and all CSS-attributes of the text-field./0!'1*6 O defines the font style for normal text items in a “Form”.8089<1./031. please compare the discussion on page 142 for more information.890C !"#$%&'()*+. R'&-0C !"#$%&'()*+#'1'&/04.*9K/0.-0C0Zm0<'(0#'(1*0"18'0(8. Dynamic styles can be used when no styles are explicitly set in the application code (compare page 107). O2/. An implicit list contains a “listitem”.

)$/00&%!2YfhLHdLYaf56 O -.88A"&$7'--")*8E0W"1(.R9/0H6 4"**.EZT A TextBox or TextField adds the “Clear”.-0C -"&%.8K3>.. compare page 76.88D.ChoiceGroup.8K37K'.)(!"&+#'1'&/09&")84"&.FE4'1.)%/0H6 !"#$%&'()*0C 9<4."&934)%56 O 9.?9. which is implemented using a List.&+#'1'&/0<.FE9&(.)%/0H6 4"**.&/0(&12K.R96 O 3-.?9g.)+1.91. compare page 76.9.11'V6 O R'#(8.)96 -./0-.9.i')9"1+.9. If you want to suppress the commands completely.)(R')9+#'1'&/0VK.FE9&(.0)"-.`&'(438(44&.#96 #'1'&/0VK.)$/00&%!2HbfLacLYfd56 *"&$4.suppressMarkCommands”-variable has to be set: UW"&.*9K/0H6 !'&*.)(g'#(8.FE4'1.EZT The same holds true for the “Select” command in implicit and popup Lists and ChoiceGroups: UW"&.*.#.)(:9.*+89<1.i.)%+1.0)"-.6 !'&*.R9/0h6 R')90C #'1'&/0!1"#$6 8.and “Delete”-commands to the menu by default.-0C !"#$%&'()*+#'1'&/0!1"#$6 R')9+#'1'&/0VK.0)"-.*6 -.*0.FE9&(.)*803-.(-6 89<1. the “polish. If you want to suppress the commands completely./03-."!1.)(:9.)(g'#(8.)(0C -"&%. the “polish."!1.R90j0K'&."!1.EZT Example The following example designs the main menu of an application.#97'--")*E0W"1(.)+9'4/0H6 4"**./0&'()*+&.suppressCommands”-variable has to be set: UW"&.The J2ME Polish GUI The names of the commands can be changed easily.6 1"<'(9/01.`&'(438(44&.1*38(44&.FE4'1.&+V.887'--")*8E0W"1(.8K37K'.#.6 O -.?4")*6 "R9.0C 134 . #'1'&80C 4./0!'1*6 O 1"<'(9/01.TextField. The names of these commands can be changed easily.1.

/0&'()*+&.89.%K9/0a6 4"**.)+1.0!'&*.0mZ 4"**./0!'1*6 R')9+#'1'&/0VK.)%+1.i')9"1+#.)+9'4/0[6 -"&%.&9.6 R')9+89<1.)%/0H6 4"**.#96 !"#$%&'()*+"&#/0f6 !"#$%&'()*+#'1'&/04./08-"116 O 1"<'(9/0.R9/0[6 -"&%./04&'4'&9.)%+!'99'-/0Y[6 !"#$%&'()*+9<4.)/0H60Zm0R'&09K.#"1+#.6 1"<'(9/0K'&.)%+W.-0C -"&%.#"1/0Y[6 4"**.-"%./0(&120K.?4")*0j0K'&.)9.*0C 4"**.)$6 !'&*.&0'R09K.R9/0a6 135 .)%+K'&./01"&%.6 !"#$%&'()*0C #'1'&/0*"&$4.&0j0K'&.890C 4"**.&9.&6 O 1.%K9/0[6 R')9+R"#.)%+W."&934)%056 O #'1(-)8/0H6 #'1(-)8+V.)%+1.i.R9/0a6 4"**.&0C 9<4.)%+1.)+&.&6 O 1.i')9"1+#.)%+&./0!'1*6 #'1'&/0!1"#$6 8.%K9/0h6 4"**.*089<1.)%/0H6 4"**.&9.&9./0&'()*+&.*9K/0.)9.)9.*9K/0H6 O R')90C 89<1.&/0)').)+!'99'-/0h6 -"&%.)%+&.&0j0W.i')9"1+.)$6 O !'&*.R9/0h6 4"**.i.#"1/0a6 4"**.#96 "&#/0f6 #'1'&/0<.9._("16 1"<'(9/0K'&.)$6 .')"16 R')9+8.?4")*0j0#.#"1/0a6 4"**.)%+W.)%+9'4/0Y[6 4"**.i')9"1/0Y[6 !"#$%&'()*0C #'1'&/04.)9.The J2ME Polish GUI 4"**.)%/0H6 -"&%.?4")*6 O R'#(8.11'V6 V.i')9"1+.0R'#(8.9.

e.7M O You can use either a (predefined) name of the view-type or the fully qualified class-name of that type.73%)1\-'.)%+1.)D#&. which are usually defined in a screen-style. Possible values are “true” and “false”. droppingview-repeat.6 R')9+89<1. Dropping View The dropping view shows an animation of dropping and bouncing items./08-"116 1"<'(9/0#.)0C 4"**.&q.3.).^_M -/2!!%.`M O 136 ._M -/2!!%. This defaults to 5.&6 .%K9/0h6 3%)1\+:!)].No animation droppingviewmaximum droppingviewdamping droppingviewmaxperiode No No No 3-".The J2ME Polish GUI 4"**./0!'1*6 R')9+8.7M -/2!!%.V class.)%+&.-/2!!%. Defines whether the animation should be repeated each time the screen is shown.8K3(.73%)1\.#')+.R9/0h6 4"**.%K9/0a6 4"**.g.)%+&.)9.6 R')9+#'1'&/0VK.#')+.)D#&.R9/0h6 4"**.)0C 4"**. The default speed is 10. By having a damping.'*!)/%2-)].9.%K9/0h6 3%)1\+:!)]. The default damping is 10.: 3-". There are several view-types available.37')9".#')34)%056 . The maximum bouncing-height in pixels.+"1.%)/09'46 O View Types View-types can be used for animating Forms.i.73%)1\(!))-]. Lists. which needs to extend the *. ChoiceGroups or even menus.7]./0(&120k:\BIlk.)%+9'4/0Y[6 4"**.-"%.)%+1. This defaults to 30.)%+&. the top items seem to bounce higher than lower ones.. The value by which the maximum is decreased for each following item. The maximum allowed number of bounces. This defaults to “false”..)%+!'99'-/0Y[6 !"#$%&'()*/0)').-"%.)'(%K34'1.-/2!!%.. It is activated by specifying the “dropping” view-type and supports following additional attributes: Attribute droppingview-speed Required No Explanation The speed in pixels per animation-step.!%.

the “a” or the “button” selector is used for dynamic styles: Dynamic Selector p a Explanation The “p” selector is used for normal texts. 11 The appearance mode can be set in the application code with Item.)D#&.)%+1.%K9/0h6 3%)1\+:!)]. The “a” selector is used for hyperlinks.. either the “p”.)%+&.setAppearanceMode( int ).0 standard encourages it: the items are all lined up into one row until there is not enough space anymore or until an item with a "newlineafter" or "newline-before" layout is inserted.)D#&. 3-". but the padding-vertical attribute has a special meaning: Attribute padding-vertical Required No Explanation The space between the lines when there the text contains linebreaks. It is activated by specifying the “midp2” view-type and supports no additional attributes. This defaults to “false”.)0C 4"**. The default speed is 10.%K9/0h6 3%)1\+:!)]. 3-". Hyperlink or Button Texts have no specific attributes. 137 .0 view arranges the items just like the MIDP/2.%-!`M O The StringItem: Text. It is activated by specifying the “shuffle” view-type and supports following additional attributes: Attribute shuffleview-speed shuffleview-repeatanimation Required No No Explanation The speed in pixels per animation-step.R9/0h6 4"**.The J2ME Polish GUI Shuffle View The shuffle view animates the items by moving them from the left and right side into their final target-position.)%+&. Possible values are “true” and “false”.)%+1..(0"JJ$)M (0"JJ$)3%)1\(!))-].^_M O MIDP/2. Depending on the appearance mode11 of the text. Defines whether the animation should be repeated each time the screen is shown.)0C 4"**.0 View The MIDP/2..R9/0h6 4"**.

“bottom”. Defaults to “left”.png” and so on.6 R')9+89<1. e. the image will be drawn directly at the right border of the item (with a gap specified by the padding-right attribute).png”.g. The IconItem Icons can only be used directly. The keyword %INDEX% can be used for adding the position of the icon to the name. The position of the image relative to the text.#')+.%)/09'46 O When the icon-item has a “right” image align and the layout is set to “horizontal-expand”.The J2ME Polish GUI Dynamic Selector button Explanation The “button” selector is used for buttons.#')34)%056 . See the general explanation of dynamic styles on page 107 for more details. “bottom”. The image used for the first item will be “icon0./0(&12./0(&12. the second item will use the image “icon1.#')34)%56”.-"%. e.#')k:\BIlk34)%56”. Defaults to “left”./0(&12. Defaults to “none”. e. Icons support following additional attributes: Attribute icon-image Required No Explanation The URL of the image. Otherwise the image will be drawn right of the text with the specified horizontal padding. The position of the image relative to the text. The ChoiceItem The ChoiceItem is used in lists and in choice groups. “left” or “right”. the second icon will use the image “icon1.#')0C !"#$%&'()*/0)').png”. meaning that the image will be drawn left of the text. “. It supports following additional attributes: Attribute icon-image Required No Explanation The URL of the image./0(&120k:\BIlk.#')34)%56”.-"%. meaning that the 138 icon-image-align No .png” and so on. The image used for the first icon will be “icon0.-"%.g.-"%. Either “top”.#')k:\BIlk34)%56”. “. Either “top”.#')+./0!'1*6 . The keyword %INDEX% can be used for adding the position of the item to the name.#')+.g. “left” or “right”.#')+.-"%./0(&12.#')+.#')+. icon-image-align No This example uses the attributes for designing all icons: . “.9.-"%.g.6 R')9+#'1'&/0VK. e. “.+"1.

*9K/0d[Ld[LY[[6”). This will be used only when the type of the list or of the choice group is either exclusive or multiple. The URL of the image for a selected item. The URL of the image for a not-selected item. The number of columns. Only the image for selected items will be drawn in that case. The “equal” width leads to columns which have all the same width. meaning that each column uses as much space as the widest item of that column needs. 139 . Default is a simple image drawn in the defined choice-color. When “none” is given. Default is a simple image drawn in the defined choice-color. no image will be drawn for not-selected items. Defaults to 1 column. Defaults to black. checkbox-plain radiobox-plain No Depending on the type of the corresponding list or choice group. different dynamic selectors are used by a choice item: Type of List or ChoiceGroup implicit exclusive multiple popup Selector listitem radiobox checkbox popup The ChoiceGroup A choice group contains several choice items. Either “normal”. “#'1(-)8+V. It supports the “focused-style” attribute: Attribute focused-style columns columns-width Required No No No Explanation The name of the style for the currently focused item. Defaults to “normal”. “equal” or the width for each column in a comma separated list (e. This will be used only when the type of the list or of the choice group is either exclusive or multiple. The color in which the check. This can be used to layout the items in a table.g.or radio-box will be painted.The J2ME Polish GUI Attribute choice-color checkbox-selected radiobox-selected Required No No Explanation image will be drawn left of the text.

compare page 76.8K37K'. view-type popup-image No No The view-type used for this choice group.`&'(438(44&./0 (&124&'%&. When an image is provided.FE4'1.8834)%56”. If you want to suppress the commands completely.-"%. Defaults to 10.88A"&$7'--")*8E0W"1(.FE9&(.EZT The Gauge A Gauge shows a progress indicator.The J2ME Polish GUI Attribute Required Explanation The explicit list of column-widths results in the usage of those widths. either the available width or the width of the provided image will be used. Please compare the discussion of view-types on page 136. the width of this image will be used instead.#. the “polish. The height of the gauge element in pixels.8K37K'. When no gauge-width is defined. The URL to the image which should be shown in the closed popup-group. Per default a simple dropdown image will be used.ChoiceGroup.88D.0)"-. “%"(%. the height of the image will be used. The color for the background in the dropdown-image of a closed popup-group. The color of the progress bar. The width of the gauge element in pixels. Default value is “chunked”. The color for the arrow in the dropdown-image of a closed popup-group. It supports following additional attributes: Attribute gauge-image Required No Explanation The URL of the image. e.suppressMarkCommands”-variable has to be set: UW"&.`&'(438(44&. Defaults to white.0)"-.#97'--")*E0W"1(. When no width is defined. whereas the chunked mode intersects the indicator in chunks. popup-color popup-backgroundcolor No No An multiple ChoiceGroup adds the commands “Mark” and “Unmark” by default to the menu. In the continuous mode only the gauge-color will be used.1. The names of the commands can be changed easily.+.g. The setting is ignored when an image is provided.FE4'1. Either “chunked” or “continuous”."!1.EZT The same holds true for the “Select” command: UW"&. Defaults to black. Defaults to blue. gauge-color gauge-width No No gauge-height No gauge-mode No 140 .FE9&(."!1.#.

The TextField supports following additional attributes: 141 .*9K/0Y[6 mZ O When the Gauge item is used with an indefinite range. Defaults to 3.The J2ME Polish GUI Attribute gauge-gap-color Required No Explanation The color of gaps between single chunks.D9<1. Only used in the “chunked” gauge-mode or when a gauge with an indefinite range is used.#"9'&34)%0560 %"(%.+%"4+#'1'&/0&%!20afL0chL0Yhf056 Zm09K. When the native mode is activated. Determines whether the current value should be shown.+K. Defaults to “left”. the image will “fly” from the left to the right of the indicator.9.99. You can choose whether the native input methods or a direct input mode should be used.)*. Please compare the following subsection “Direct Input Mode” for more information.*./0#K()$. no extra screen will be shown and J2ME Polish accepts the entered character directly.&+#'1'&/0VK.8.0. Default gap-color is white.. the gauge-gap-color will be used to indicate the idle state.*6 %"(%.-"%.0. that is left of the actual gauge item.*L08. The width of the single chunks in the “chunked” gauge-mode.+%"4+V.)#.%K9/0f60 %"(%./0(&120.6 %"(%.*/ %"(%.+#K()$+V.*9K/0d[6 %"(%. Only used in the “chunked” gauge-mode.+V.+#'1'&/0&%!20fdL0YdhL0Hhh056 %"(%. a new input screen will pop up for the user and special input modes like T9 or handwriting recognition can be used.*9K/0h6 %"(%.)%/0H6 !'&*. When the direct input mode is used instead.%)'&.+-'*. This defaults to true for all definite gauge items. Either “true” or “false”.08.+. Either “left” or “right”. gauge-gap-width gauge-chunk-width gauge-show-value No No No gauge-value-align No The following example shows the use of the gauge attributes: 3%"(%. The width of gaps in pixels between single chunks.0")0.)%0"&.0C 4"**.-"%. In the latter case the provided color will be used to indicate the idle state. Defines where the current value of the gauge should be displayed. The TextField A TextField is used to get user input.804&'W. When the “continuous running” state is entered and an image has been specified.

EZT You can also deactivate the "Clear" command singly: UW"&.FE4'1.6 9."&7'--")*E0W"1(.*9K/0b[6 9.The J2ME Polish GUI Attribute textfield-width textfield-height Required No No Explanation The minimum width of the textfield-element in pixels..)4(9D9<1.suppressCommands”-variable has to be set: UW"&.0)"-.&+#'1'&/0!1"#$6 9..?9R. This defaults to “|”.1*3?-1 file: 142 .#9+.1."!1.0C 4"**."!1. the “polish.6 O TextField-Commands A TextField adds the “Clear”..1*+*.?9R.8871. Defaults to the height of the used font. compare page 76.9. The minimum height of the textfield-element in pixels.FE9&(.)%9K/09&(.887'--")*8E0W"1(. By default the direct input mode is deactivated (“false”).8K3>. Possible values are either “false” or “true”..?9R.?9R.0)"-.1*38(44&..9+#K"&/0T6 9.TextField.9.1*38(44&."!1. Determines whether the length of the entered text should be shown during the editing of this field.1*+#"&..FE9&(.1*+V.useDirectInput” in the !(.FE4'1.*6 9.0)"-. The names of these commands can be changed easily.8K3>.. This defaults to the color of the used font.?9R. The character which indicates the editing position.FE9&(..?9R.88B.%K9/0Yh60 9.EZT Direct Input Mode The direct input mode can be activated for TextFields as well as for TextBoxes using the CSSattribute “textfield-direct-input” or by defining the preprocessing-variable “polish.?9g.1*38(44&.?9g.1*+#"&.1*+K.TextField.1*+8K'V+1. Defines whether the direct input mode should be activated. The color of the caret which indicates the editing position..&.)%/0H6 !"#$%&'()*+#'1'&/0VK.and “Delete”-commands to the menu by default. textfield-direct-input No textfield-caret-color textfield-caret-char No No textfield-show-length No The following example shows the use of the TextField attributes: 3.7'--")*E0W"1(.EZT Last but not least it is also possible to deactivate the "Delete" command singly: UW"&. If you want to suppress the commands completely.9+#'1'&/0&.8K3>. This has an effect only when the direct input mode is used.)4(9/09&(..6 !'&*.?9g.FE4'1.

TextField.InputT “1000” imeout polish.E0 .g.FE4'1..E0ZT Next to using the CSS-attributes “textfield-caret-color”. uppercase (“ABC”).8K3>.FE4'1."!1.)R'0C 4"**..)9.?9g.?9g.showI “true” nputInfo polish.8K3>. since T9 and similar input helpers cannot be used in this mode.1*38K'V:)4(9:)R'E0W"1(./08-"1160 R')9+#'1'&/0R')97'1'&60Zm0"0#'1'&0*.showInputInfo”-variable to “false”: UW"&. The key which is used for changing the input mode between lowercase (“abc”).%K96 O The info-item can be deactivated globally by setting the “polish.R. This can be ensured by setting the preprocessing variable only for devices which have no pointer-events: UW"&.e. When the TextField is used within a Form. no extra screen will be used for editing the text and all designing possibilities of J2ME Polish can be used.showInputInfo” variable to “false”.i. The user can change the input mode from lowercase (“abc”) to initial-letter uppercase (“Abc”) to uppercase (“ABC”) and to numeric (“123”).*0.8K3K"8J'. “textfield-caret-char” and “textfield-showlength” the behavior of the direct input mode can be adjusted using several preprocessing variables. TextBoxes).&+#'1'&/0!1"#$6 R')9+89<1.B. Following variables can be set: Variable Default Explanation The timeout in milliseconds after which a chosen character is inserted into the text automatically.)%+&./041".6 !'&*.key.FE9&(.0u#'1'&8t08.?9g.&IW.')0mZ 1"<'(9/0&.)98EZT The direct input should not be used for editing longs texts (i.0)"-. “123”.The J2ME Polish GUI UW"&.FE4'1."!1."!1. Defines whether the box showing the current input mode (e.0)"-.#9:)4(9E0W"1(.&. this mode should not be used since these devices often rely on native input methods like handwriting recognition.FER"18.0)"-. This item can be designed using the predefined CSS-style “info”: . which can be necessary for localizing the direct input. The current input mode is shown below the title in an extra StringItem.%K9/0Y[6 !"#$%&'()*/0)').#9:)4(9E0W"1(.EZT When the direct input mode is used.&.TextField.FE9&(. “Abc”. Especially the available character can be changed. initial143 polish. “abc”.)60 R')9+R"#.)09K. “ABC”) should be shown at all.1*3(8.ChangeInput Varying ModeKey .TextField./04&'4'&9.B.')"160 R')9+8..1*3(8.#9.). On stylus-based devices. the associated ItemStateListener will be notified after each change of the text.RFEv4'1.8K3>. You can deactivate the box globally by setting the “polish.TextField.

TextField.charac “ghi4” tersKey3 polish. The characters which are available when the key “9” is pressed.TextField.charac “mno6” tersKey6 polish.!?:/@_-+” The characters which are available when the key “*” is tersKeyStar pressed. polish.TextField.charac “. The DateField supports following additional attributes: 144 .TextField. on Motorola devices Canvas.TextField. The characters which are available when the key “5” is pressed. The characters which are available when the key “0” is pressed. The characters which are available when the key “6” is pressed. so that special input modes can be used (like T9 or handwriting recognition). polish.TextField.TextField.KEY_POUND (35) is used.TextField..TextField.charac “jkl5” tersKey5 polish.KEY_STAR (42).TextField. It might be useful to add local specific umlauts here.charac “wxyz9” tersKey9 polish.TextField.KEY_NUM0 (48) and on all other devices Canvas. The DateField A DateField is used to enter date or time information.charac (none) tersKeyPound The characters which are available when the key “#” is pressed.!?:/@_tersKey1 +1” polish. Currently the input is done with the use of the native functions.charac “pqrs7” tersKey7 polish. The characters which are available when the key “4” is pressed.charac “def3” tersKey3 polish.TextField. The characters which are available when the key “7” is pressed.charac “ 0” tersKey0 The characters which are available when the key “1” is pressed. polish. The characters which are available when the key “8” is pressed. On SonyEricsson devices Canvas. On Sony-Ericsson devices this key is used for entering spaces (“ ”). On Motorola devices this key is used for entering spaces (“ ”).charac “. The characters which are available when the key “3” is pressed.The J2ME Polish GUI Variable Default Explanation letter uppercase (“Abc”) and numeric (“123”).. On Motorola devices this key is used for switching the input mode.charac “abc2” tersKey2 polish. The characters which are available when the key “2” is pressed.charac “tuv8” tersKey8 polish.

FEZEZT UW"&. Defaults to the height of the used font.g. When this attribute is also defined in a screen-style.-#.FE4'1. e.g'&-"9D.#90B"9. “mdy” (month-day-year) or “ymd” (year-month-day).0)"-.DateFormat”.FE4'1.8K3B"9.8K3B"9.” defines the color of the menu-bar.DateFormatSeparator-variable and the polish.4"&"9'&E0W"1(. and the CSS attrbute “:1%0+".12./5/. Along with the polish.0)"-.g.6 !"#$%&#'&()*+#.0)"-.FE4'1.MM.FE*.E0ZT: The German standard of DD. " UW"&.The J2ME Polish GUI Attribute datefield-width datefield-height Required No No Explanation The minimum width of the datefield-element in pixels.g.8K3B"9.FE4'1.YYYY is used. " All other settings: The ISO 8601 standard of YYYY-MM-DD is used. The font-settings in this style are used to render the actual commands.0)"-.)(0C 4"**. Defaults to 2 pixels.g'&-"9I-49<>. which is useful when the background of the corresponding screen should be shown. which can be defined in the <variables> section of the J2ME Polish task: " UW"&.FED.g'&-"9E0W"1(. e.g'&-"9E0W"1(. it will override the setting in the “-.2004”./5/."!1."!1."!1. " UW"&. The color can have any setting including “transparent”.%&#/.?9E0W"1(.EZT The Ticker A Ticker scrolls a text over the current screen.FE4'1.FE(8E0ZT: The US standard of MM-DD- YYYY is used. e."!1.)(” style. The DateFormat also supports the generic values “dmy” (day-month-year). This bar can be designed using the predefined “-.DateFormatEmptyText-variable one can use any custom date format: UW"&. Following attribute is supported: Attribute ticker-step Required No Explanation The number of pixels by which the ticker is shifted at each update."!1.)%/0h6 !"#$%&'()*/0)').FE<-*EZT UW"&.FER&E0ZT: The French standard of DD/MM/YYYY is used. e.%&#0&+234156#"! 145 .1.0)"-.FE4'1.” defaults to white by the way.8K3B"9. “24.0)"-. The Menu Bar In the menu bar the commands reside that have been added to a screen.)(” style for the corresponding screen. In J2ME Polish the ticker is situated right above the menu-bar on the bottom of a screen.g'&-"9E0W"1(. “12-24-2004”."!1.4. Let me demonstrate: -.8K3B"9.001+'(#)+#. The appearance of the datefield can also be adjusted using the preprocessing variable “polish.8K3B"9.g.g'&-"9E0W"1(. The minimum height of the datefield-element in pixels. The “:1%0+".4. “24/12/2004”. “2004-12-24”.

7&< #########(. In contrast to the normal menu bar.-"%. The items in the opened menu are designed using the predefined “-.-#.%&#4*=9+*#)01*&#)(#(%.)(./08-"1160 R')9+#'1'&/0&.)D9<1. you need to set the "polish. 6: Using images <variables>-section of the build.:+#)+#.%&#0&+2415#41/8*5. Designs the right command ("Cancel" and user-defined BACK or 146 ."!1.I?9. the extended menu bar is a full blown item and can.*6 !"#$%&#/.8K3A.')"160 R')9+8.FE9&(. "Select" and user-defined commands).#.)(!"&+#'1'&/09&")84"&.5#. which opens the real menu when pressed (like shown in the following figures)..%#./0!'1*60 R')9+R"#.E0 ZT UZW"&.xml file: UW"&.2+'6##"! -. The background and the border of the opened menu is designed using the “-..8T UW"&.0C !"#$%&'()*+.%&#0&+2415#1(#:&776#"! -.)*./04&'4'&9. therefore. "leftcommand" and "rightcommand": Style menubar leftcommand rightcommand Description This design of the menu-bar itself. an “Options” menu will be shown automatically. Accepts all attributes of the IconItem.)(” style.FE4'1. be designed just like any other item.%1.)(e"&E0 W"1(.)(e"&3(8. You can change the names of the “Options”. Designs the left command ("Options"."!1.7. The Extended Menu Bar You can use the extended menu bar in cases when the design possibilities of the normal menu bar are not sufficient for you. The price for using the extended menu bar is to have an additional 2 kb class file in your JAR.9./0(&120!%34)%056 !"#2(&#1#."!1.-” style.#0&+2415#-.51+(915&+.The J2ME Polish GUI R')9+89<1.i.%)(#(.)(!"&+#'1'&/0!1"#$6 O 3-<D#&.useExtendedMenuBar" preprocessing variable to "true" in the Fig.*A.0 )"-. “Select” and “Cancel” commands by the way. this is explained in the localization chapter on page 76. For using the extended menu-bar instead of the normal one.#.5#(/5&&+(#:).8T in the extended menu bar. The menu bar can be designed using the predefined styles "menubar".MenuBar.)96 O When there is more than one item available in the menu.

)+!'99'-/0[6 -"&%.%K9/0H6 4"**.?9/09&(. 147 .i')9"1/0b6 4"**.-"%./0(&120#")#.-"%.6 ./0!'1*6 !"#$%&'()*/0)').)%+K'&.6 O &.)+9'4/0[6 -"&%. The menubar-style offers following additional attributes: Attribute menubar-optionsimage menubar-selectimage menubar-cancelimage menubar-showimage-and-text Required No No No No Explanation Defines the image-URL for the options-image of the extended menubar.)(!"&+'49.R9/0H6 -"&%. when an image has been defined for the corresponding action.+")*+9./0(&120#K.#$.)%+!'99'-/0[6 R')9+#'1'&/0R')97'1'&6 R')9+89<1. Defines the image-URL for the cancel-image of the extended menubar.*34)%056 -.6 mZ O 1./0(&120'49.-"%. Defines the image-URL for the select-image of the extended menubar.%K9#'--")*0C 4"**. Accepts all attributes of the IconItem.)%/0[6 !"#$%&'()*/0)').')834)%056 Zm -. Defaults to "false".)(!"&0C -"&%.#9+.1+.6 -.i')9"1/0b6 4"**.The J2ME Polish GUI Style Description CANCEL commands).)(!"&+8.1.)+&. The following example demonstrates the design of the extended menu-bar: -.-"%.)(!"&+8K'V+.)+1.)%+!'99'-/0[6 R')9+#'1'&/0R')97'1'&6 R')9+89<1.)%+K'&.R9#'--")*0C 4"**.')8+./0!'1*6 !"#$%&'()*/0)').)(!"&+#")#. Determines whether the text should be shown as well in the menubar.134)%056 -.

%K9/0f6 O . Style tabbar activetab inactivetab Description This style designs the tab-bar of a TabbedForm.#"9'&+#'1'&/0!1"#$6 O "#9.)%+. Designs all tabs but the currently selected one of a TabbedForm.1W.W.R9/0Y[6 4"**.R9/0d6 4"**.9"!0C !"#$%&'()*+9<4.9.1W.)%+1./0&'()*+9"!6 !"#$%&'()*+#'1'&/08.)%+&.)%+&.W.6 1"<'(9/0.The J2ME Polish GUI The TabbedForm The tabbed form can be designed like any Form and accepts the very same CSS-attributes. Additionally the predefined styles "tabbar".R9/0H6 -"&%.&6 !"#$%&'()*+"&#/0f6 R')9+#'1'&/0VK.&6 O 148 .)*.)+&.)+1.6 4"**.)%+!'99'-/0[6 9"!!"&+8#&'11.9"!0C 4"**.)"#9.)%+1. Designs the currently active tab of a TabbedForm.?4")*6 4"**.9. "activetab" and "inactivetab" can be used to design the additional elements of a tabbed form./0&'()*+9"!6 !"#$%&'()*+#'1'&/0%&"<6 !"#$%&'()*+"&#/0f6 R')9+#'1'&/08.%K9/0H6 !"#$%&'()*+9<4. You can set the color of the scrolling indicator within the tabbar-style with the tabbar-scrollingindicator-color attribute: 9"!!"&0C !"#$%&'()*+#'1'&/0VK.%K9/0b6 -"&%.

0 as well as MIDP/1. when one of the methods keyPressed(int).The MIDP/2.*.0 devices. A TiledLayer is a visual element composed of a grid of cells that can be filled with a set of tile images.0 game API and “weaves” the necessary wrapper classes into the code.0-Compatible Game-Engine The MIDP/2. J2ME Polish offers a nifty solution for those developers who want to support both platforms with the advanced MIDP/2.0 technology. Limitations For technical reasons the collision detection works only with collision rectangles.')31#*(. the market is crowded with MIDP/1. The obfuscation step then removes all unnecessary functionality to ensure that only the needed parts are actually included into the application. All classes of the S"W"?3-. which can be triggered by defining specific variables in the “build. The J2ME Polish game-engine only needs about 5 to 6 kb extra space in the resulting JAR package. it should call the super-implementations.0 devices without changing anything within the source code! How It Works The J2ME Polish build-tool identifies the usage of the MIDP/2. otherwise the transformations will be ignored.9. Optimizations The TiledLayer and the GameCanvas implementations have several optional optimizations. keyReleased(int) or keyRepeated(int) is overridden. TiledLayer With this game-engine it is possible to program a game with one source code for MIDP/2. which should be set tightly for Sprites therefore.3%"-. different frames can be shown to animate the Sprite.xml” file (compare the variables section on page 52). When a class extends the GameCanvas class. A pixel-level collision detection is not supported.0 is the future. A Layer is an abstract class representing a visual element of a game. when all classes are used.-package can be used normally: Class GameCanvas Layer LayerManager Sprite Explanation The GameCanvas class provides the basis for a game user interface.0-Compatible Game-Engine Even though MIDP/2.#&'. The LayerManager manages a series of Layers. 149 . The transformation of Sprites is currently only supported for Nokia devices. A Sprite is a basic visual element that can be rendered with one of several frames stored in an Image.

This behavior can be overridden with defining the “polish.R. overrides the reen “fullscreen”-attribute of the <build>-element.83R(118#&.R04'1.0-Compatible Game-Engine Using a Fullscreen-GameCanvas The GameCanvas normally uses the “fullscreen”-attribute of the <build>-element to determine whether it should use a fullscreen-canvas (compare page 36). Please note that the “menu” mode (which should be used when commands are added to the GameCanvas) is only supported when the J2ME Polish GUI is used.Transparent The color which is used for tiles which should transparent.$"+51(%":1@A!/5$7B=`":16"%G"7=071Q055N.04".#0W'.#0#1"880A<`"-.-.useFullSc Defines whether the fullscreen mode is used.#80%5 ZZn. The drawback of the backbuffer optimization is that it uses more memory and that no transparent tiles can be used.)9D#&.11%A(G"501@A817A(IH This example shows how to override the paint()-method. even though the J2ME Polish GUI and the “menu” fullscreen mode is used: 4(!1. This can result in a significant higher frames per second throughput.TiledLayer. since the complete layer needs to be painted only seldomly.0~~04'1.18.)90-.GameCanvas.)*80`"-.9K'* 000333 O O Backbuffer Optimization for the TiledLayer The backbuffer optimization uses a buffer..). Allowed value are “yes”.The MIDP/2.* ZZn04(!1.-41. it is recommended not to use the backbuffer optimization.GameCanvas. Possible values are “yes”.7")W"80.)20`&"4K.?9.8K`(.useFullScreen” variable. er needs to be ”true” to enable the optimization.R C 000ZZ0.*04". “no” or “menu”. Variable Explanation polish.#0W'.#80%5 ZZn. So when memory is an issue or when the tiled layer is not used as the background. polish.8K3#1"88.)*.)/*.8K3(8. “no” and “menu”. Another limitation of the “menu” mode is that the paint()-method of the GameCanvas cannot be overridden. Variable Explanation polish. This 150 .useBackBuff Defines whether the backbuffer optimization should be used.. The following example enables the fullscreen mode for the GameCanvas: ?G"..)909K. to which the tiles are only painted when they have changed. 4(!1.TiledLayer.)920`&"4K.7")W"80C 00333 ZZn.J'1.*04".

1%3Y$516/5/.$"+51(%":1@A!/5$7B=Y$51#D"81. you need to define the preprocessing variable “polish. This optimization needs a bit more memory compared to a basic tiled layer. This defaults to “byte”. The following example uses a short-grid.01A(IH Defining the Grid Type of a TiledLayer The J2ME Polish implementation uses a byte-grid. “short” or “byte”. which allows the usage of 32767 different tiles instead of 128 different tiles: ?G". The following example enables the single tiles optimization: ?G".$"+51(%":1@A!/5$7B=Y$51#D"81.=7!5$3P:"&1A(G"501@A3.01A(IH Splitting an Image into Single Tiles A tiled layer can be drawn significantly faster when the base image is split into single tiles.TiledLayer.0 devices as well. but which also limits the number of different tiles to 128. Variable polish.-\0221.$#Y8!1A(G"501@A7B/. “short” or “byte”.usePolishGameApi”: 151 .GridType Explanation Defines the type of the used grid in TiledLayer.=Y.$"+51(%":1@A!/5$7B=Y$51#D"81."%7!".A(G"501@AKLMKMKKKA(IH ?G". Explanation The following example enables the backbuffer optimization: ?G".3A(IH Using the Game-Engine for MIDP/2. Also the transparency of tiles is lost when the device does not support the Nokia UI API (all Nokia devices do support this API). When the gameengine should be used for MIDP/2.0 Devices You can use the J2ME Polish implementation for MIDP/2. Needs to be “true” to enable this optimization.0-Compatible Game-Engine Variable TileColor defaults to black.=`.0 devices as well.=071Y$51\".$"+51(%":1@A!/5$7B=Y$51#D"81. For cases where more different tiles are used.A(G"501@A3. which significantly decrease the memory footprint. Variable polish. Possible values are “int”.The MIDP/2.TiledLayer.splitImage Explanation Defines whether the base image of a TiledLayer should be split into single tiles. This can make sense because some vendor implementations are buggy or have sluggish performance. one can define the type to either “int”.

Many IDEs support syntax highlighting and autocompletion for this file.0 device first. The J2ME Polish task is divided in 3 subsections: U. the target-devices. The U.W.O.)98T and U!(.8K3)"-. U*.The MIDP/2.0 Platforms Building the Existing Application In the first step we use J2ME Polish for building the game.1*3?-1 file from the provided sample-application of J2ME Polish and we might need to adjust the handling of resources.(@@( J/-$"A(IH Porting a MIDP/2.-.)R'T.01A($2@A!/5$7B=G1%#/. when the application is build for the Nokia/6600 device for example.4ij!/5$7B=%":1.0 Game to MIDP/1.xml To build the existing game we need to copy the sample-!(. The following example uses the game-engine for Nokia MIDP/2.&.171. Adjusting the build.)98T-section the target-devices are selected.7$/%@AV=X=hA ((#17. The “Series60Midp2” device is a 152 . Since we want to build the application for a MIDP/2.3A ((G1%#/.)*'&O-]C4'1.$!3$/%@Aa(7":!51(!./!8. the version of the game and so on.-.J":1@AF%/0&B(N/23C".5@Aij#1!5/840.5.1*3?-1 file. The !(.ij!/5$7B=b".usePolishGameApi Explanation Defines whether the J2ME Polish game-engine should be used on MIDP/2.W. but it can also be edited with any decent text-editor.#. The above example “]C4'1. We need to copy and adjust the !(.)R'T-section contains general information about the project: ?$%2/ ((5$.1*3?-1 script and is usually empty. Possible values are “true” or “false”.1*T.41L":!51=b".1A (($%2/O.. The name of the application can also contain the name and vendor of the target-device. we enter any MIDP/2.J":1@Aij!/5$7B=G1%#/.:@AM/(8/0(.$&B3(ZKKh(F%/0&B(N/23C".$"+51(%":1@A!/5$7B=071S/5$7B`":1a!$A(G"501@A3._(.$&B3@A6/!8.1%71@A`SDA ((%":1@ARZUF(S/5$7BA ((G1.A( ((b".^.0 devices as well: ?G".41'<+(&1O” is defined above in the sample !(.0 capable device into the requirements.Oexample. e.0 devices as well.$&B37(./%@A#/3=!%&A ((b".8K3W.&. “Nokia/6600” or “Nokia/Series60Midp2”. which resides in the “sample” subdirectory of the J2ME Polish installation.1*3?-1 includes all the necessary information about the project like the MIDlet-classes. In the following U*.5@AB33!'IICCC=bZ:1!/5$7B=/..0-Compatible Game-Engine Variable polish. into the the root directory of the game.J":1.&A (($.^.jar”.#.1"558(C"%3(3/(-$55(:1kA( IH This information can be changed arbitrarily.A ((.G1#=A ((#151316/%2$./b1.g.1=(a55(._(. The above property “]C*.jar” results in the name “Nokia-6600-example.

The MIDP/2.0-Compatible Game-Engine virtual device representing a typical Series 60 phone with MIDP/2.0 support. Such is phone supports additionally the Mobile Media API (mmapi) and the Wireless Messaging API (wmapi). The device selection is very flexible and can select all MIDP/2.0 devices which support the Mobile Media API as well, for example. For keeping this example easy to manage, we use only the selection by the device's identifier:
?#1G$,1]1g0$.1:1%37H ((?.1g0$.1:1%3(%":1@AP#1%3$2$1.A(G"501@AJ/-$"IN1.$17TKU$#!ZA(IH ?I#1G$,1]1g0$.1:1%37H

The <build>-section controls the actual build process. For keeping this example easy, we choose not to use the GUI of J2ME Polish and set the “(8.J'1,8K`(,” attribute to “R"18.”. We also need to adjust the <midlet>-subelement and enter the full name of our game-class:
?+0$5# ((071S/5$7B`0$@A2"571A ((.17M$.@A.17/0.,17A ((C/.-M$.@Aij#$.=C/.-;A H ((?f44(:$#5137(#12$%$3$/%(44H ((?:$#513(,5"77@A#1=1%/0&B=!/5$7B=1L":!51=U1%0U$#513A(%":1@AFL":!51A(IH ?I+0$5#H

The U!(,1*T-section has many subelements and can automate many tasks from the inclusion of the debugging framework to the signing of the application. These settings are outside of the scope or this article, though.
Managing the Resources

J2ME Polish manages the inclusion of resources automatically for you. Just copy all resources which are needed in any case into the “&.8'(&#.8” folder of your project (create it first if necessary). You can then use the subfolders for including resources only for devices which can use these resources. For example you can place MIDI soundfiles into the “&.8'(&#.8Z-,*,” folder and 3gpp video files into the “&.8'(&#.8Za%44” folder. This results in smaller application bundles, since unnecessary resources will not be included at all. More specific resources are included instead of general resources. You could keep low-color images into the general “&.8'(&#.8” folder and use the “&.8'(&#.8Ze,98J.&J,?.13Ydo” folder for using high-color versions of these images for devices which support at least 16 bits per pixel (65.536 colors). The same principle can be used for including specific resources for all devices of a specific vendor (e.g. “&.8'(&#.8ZD')<+I&,#88')” or “&.8'(&#.8Z\'$,"”) or even for specific devices (e.e. “&.8'(&#.8Z\'$,"Zdd[[”). This powerful automatic resource assembling of J2ME Polish is the reason why no subfolders can be used within the application code. All resources are copied into the base-folder of the application. So instead of :-"%.3#&."9.:-"%.2E,-"%.8Z84&,9.34)%E5 you need to use :-"%.3#&."9.:-"%.2E84&,9.34)%E5 within the source code. This has the extra benefit of saving space within the final jar-file as well as heap-size in the game.

153

The MIDP/2.0-Compatible Game-Engine
Building the Game

Now all settings necessary for building the game with J2ME Polish have been made, so now call “ant” on the command-line from within the base folder or we can right-click the !(,1*3?-1 file within the IDE and select “Run Ant”, “make” or similar. J2ME Polish will now preprocess, compile, obfuscate, preverify and package the game automatically. When the above settings will be used, we will find the files “\'$,"+ D.&,.8d[A,*4H+.?"-41.3S"&” and “\'$,"+D.&,.8d[A,*4H+.?"-41.3S"*” in the “*,89” folder of the project after the build. The game should now be tested with an emulator or a real device, to make sure everything works as expected. Porting the Game to MIDP/1.0 After the successful transition to J2ME Polish, porting a game to MIDP/1.0 is very easy.
Necessary Source Code Changes
!

Checklist for Porting
!

All resources needs to be loaded from the base directory, e.g. Image.createImage(“/sprite.png”) Use import-statements instead of full-qualified class-names in the source code Use preprocessing for adjusting the source code to specific devices, e.g. //#if polish.midp2 || polish.api.mmapi Use the automatic resource assembling for using specific resources for the target-devices. Set tight collision rectangles, since pixel-level collision detection cannot be used on MIDP/1.0 devices Sprite-transformations are only supported for devices which support Nokia's UI-API, so transformed PNGs need to be used for other devices. The super-implementation of keyPressed() and keyReleased() should always be called first, when such methods are overridden.

!

Subclasses of GameCanvas need to call the superimplementations of any overridden $.<J&.88.*2,)95 and $.<^.1."8.*2,)95-methods, so that the J2ME Polish gameengine knows about these keys. When there is a compile error stating that a S"W"?3-,#&'.*,9,')31#*(,3%"-.-class cannot be found, please ensure that you use ,-4'&9-statements rather than fully qualified class-names in your source-code: Instead of A<`"-.7")W"80.?9.)*80
S"W"?3-,#&'.*,9,')31#*(,3%"-.3`"-.7")W"80!"#$ ,-4'&9%&!'!#(#)!$*&$)##+#+, ,-4'&90S"W"?3-,#&'.*,9,')31#*(,3%"-.3`"-.7")W"86 A<`"-.7")W"80.?9.)*80`"-.7")W"8

!

!

!

Working Around the Limitations of the Game-Engine
Pixel-Level Collision Detection

!

Pixel-level collision detection cannot be used on MIDP/1.0 platforms, so we need to set tight collision rectangles for the sprites.
Sprite Transformations

Another limitation of J2ME Polish is that sprite-transformations are only supported for Nokia devices so far. This means that for other devices transformed sprite-images are needed. These can be easily included by putting them in the “&.8'(&#.8Z\'D4&,9.>&")8R'&-"9,')8” folder. We can adjust the handling of sprite-transformations by using the preprocessing of J2ME Polish:
ZZn,R0v24'1,8K3-,*4H0jj04'1,8K38(44'&9D4&,9.>&")8R'&-"9,')5

154

The MIDP/2.0-Compatible Game-Engine
4&,W"9.0R,)"1089"9,#0,)90A:^^p^rDIN@I\7I0F0).V0,)9PQCaLbLyLhO6 ZZn.)*,R P333Q ZZn,R04'1,8K3-,*4H0jj04'1,8K38(44'&9D4&,9.>&")8R'&-"9,') 9K,8384&,9.38.9>&")8R'&-20D4&,9.3>^;\DrA:^^p^056 ZZn.18. 9K,8384&,9.38.9g&"-.D._(.)#.20A:^^p^rDIN@I\7I056 ZZn.)*,R

In the above example we use call the transform(int)-method of the sprite only when the device either uses the MIDP/2.0 platform or supports sprite transformation. Otherwise the frame-sequence MIRROR_SEQUENCE will be used instead. A similar adjustment can be needed during the instantiation of the sprite, when the transformed image has different frame-dimensions:
ZZn,R04'1,8K3-,*4H0jj04'1,8K38(44'&9D4&,9.>&")8R'&-"9,') ,)90R&"-.z,*9K0F0Y[6 ,)90R&"-.M.,%K90F0f6 ZZn.18. ZZn0,)90R&"-.z,*9K0F0d6 ZZn0,)90R&"-.M.,%K90F0f6 ZZn.)*,R 9K,8384&,9.0F0).V0D4&,9.2084&,9.:-"%.L0R&"-.z,*9KL0R&"-.M.,%K9056

For an even more flexible approach you can use preprocessing variables. These variables can be defined in the UW"&,"!1.8T-subelement of the !(,1*3?-10file:
?G".$"+517H ((?G".$"+51( %":1@A!5"81.=2.":1M$:1%7$/%7A( G"501@AVK^(_A( $2@A!/5$7B=70!!/.3N!.$31Y."%72/.:"3$/%(yy(!/5$7B=:$#!ZA(( ((IH ((?G".$"+51( %":1@A!5"81.=2.":1M$:1%7$/%7A( G"501@AT^(_A( 0%5177@A!/5$7B=70!!/.3N!.$31Y."%72/.:"3$/%(yy(!/5$7B=:$#!ZA(( ((IH ((?G".$"+51( %":1@A!5"81.=2.":1M$:1%7$/%7A( G"501@AT^(TA( $2@A!/5$7B=$#1%3$2$1.(@@(J/-$"IWZVKA(( ((IH ?IG".$"+517H

In the above example the frame-dimensions are set to 10x8 for devices which support either the MIDP/2.0 or the sprite transformation. The dimension 6x8 are used for all other devices. For the Nokia/7210 phone the special value of 6x6 is used. In the source-code a default-value should always be used for cases in which the variables are not set:
ZZn,R041"<.&3R&"-.B,-.)8,')8/*.R,).* ZZnF09K,8384&,9.0F0).V0D4&,9.2084&,9.:-"%.L0]C41"<.&3R&"-.B,-.)8,')8O056 ZZn.18. 9K,8384&,9.0F0).V0D4&,9.2084&,9.:-"%.L0Y[L0f056 ZZn.)*,R

By using this approach the resources can later be changed without needing to change the source155

*4H0jj04'1.0 features like CustomItems and ItemCommandListener on MIDP/1.R04'1.0 game: ZZn. the fullscreen-mode can be activated by defining the preprocessing-variable “4'1.2!''1.)A'*.R Useful Preprocessing Symbols ! 4'1..8K`(.R ! ! ! Another common issue is the usage of a fullscreen-mode.0 devices. The 8.&0"(*. ZZ0333 J1"<. When you are using J2ME Polish's advanced GUI.3)'$.8K3-.0 A<7(89'-:9.*4H 8.J'1."-L0A"(*. ! 4'1.3--"4.8K3-.-056 ZZn. is defined when the Mobile Media API is supported by the current device. ! You might need to adjust the GUI as well.8K3#1*#Y3Y indicates the current configuration.-256 9K. however.1.R04'1.R04'1. but the 8. you can even use MIDP/2.9g(11D#&. When the J2ME Polish's GUI is not used.8K3`"-.*4H indicates the current MIDP platform.0 phones do support this API however. is enabled when the GUI of J2ME Polish is used.R You can use a multitude of preprocessing symbols and variables.The MIDP/2.*4H0jj04'1.3--"4."+(.q056 ZZ0333 ZZn.7")W"83(8.)*20.>rz. Please compare J2ME Polish's device-database and the preprocessing documentation on page 78 for further information.*.9.V0D'()*20*"9"L 0D'()*3gp^A.8K3"4.0 devices.8K3"4.g(11D#&.8K3#1*#Y3[0Z0 4'1.'J1"<.")5-method of the Canvas-class is only available on MIDP/2.209&(. any MIDP/2.-0.9g(11D#&.J'1. Using Preprocessing for Device Specific Adjustments You can use J2ME Polish's preprocessing capabilities for further adjustments of the game.') indicates that MIDP/1.056 ZZn..8K`(.")5method can still be used for MIDP/2. 4'1.9g(11D#&.)A'*.0 devices.9. For MIDP/1."9.8K3"4.2!''1.3)'$.&3#&. 4'1.&0F0A")"%. A typical situation is that the MMAPI is used for sound playback..A056 ZZ03333 ZZn.)*.0-Compatible Game-Engine code..)*.)4(9D9&.83R'&-3"44. 4'1.8K3-.0 devices: ZZn.0 GUI code needs to be hidden from the MIDP/1.-0F0). Which of these are available depends on the device and the current setup.8K3(8.>&" )8R'&-"9.V0A<7(89'-:9.8K3"4. 4'1. Not all MIDP/1. is defined when the Nokia UI API is supported by the current device. ZZ0333 D'()*08'()*0F0).J1"<.*4Y0Z0 4'1.)*.)” (see below).8K38(44'&9D4&. 156 .8K3(8.& 20.)A'*.8K3-.'Z-.R04'1. In these cases the MMAPI code needs to be hidden from such devices: ZZn."+(.8K3-.9.0 Sprite transformations are supported for the current device.

Extending J2ME Polish

Extending J2ME Polish
J2ME Polish can be extended quite simply and in several ways. Build-Tools:
! ! !

Obfuscator: integrate your own (or a third party) obfuscator Preprocessing: add your own preprocessing directives You can also use the <java>-element to extend J2ME Polish Backgrounds and Borders: custom borders or backgrounds enhance the possibilities Items: extend and use standard CustomItems – and design them using CSS

GUI:
! !

The <java>-element is described on page 59, whereas the other extensions are discussed in this chapter . Integrating a Custom Obfuscator For integrating another obfuscator, you need to first create a class which extends the de.enough.polish.obfuscate.Obfuscator class. Secondly you need to integrate your obfuscator in the “build.xml” file. Preparations Create a new project in your IDE and set the classpath so that it includes the “enough-j2mepolishbuild.jar”, which can be found in the “import” folder of the installation directory. Also include the “ant.jar” file from your Ant-installation into the classpath. Creating the Obfuscator Class Create a new class which extends de.enough.polish.obfuscate.Obfuscator and implement the “obfuscate” method:
Zmm 0m0p!R(8#"9.80"0S"&+R,1.0R'&09K.0%,W.)0*.W,#.3 0m0 0m0s4"&"-0*.W,#.0>K.0GHAI0*.W,#. 0m0s4"&"-08'(&#.g,1.0>K.0S"&+R,1.0#')9",),)%09K.04&'S.#980#1"88.8 0m0s4"&"-09"&%.9g,1.0>K.0R,1.09'0VK,#K09K.0'!R(8#"9.*0#1"88.808K'(1*0!.0#'4,.*09'0 0m0s4"&"-04&.8.&W.0;110)"-.80'R0#1"88.80VK,#K08K'(1*0!.04&.8.&W.*L 0m000000000000000009K"90-.")80)'90&.)"-.*0'&0&.-'W.*3 0m0s4"&"-0!''971"88J"9K0;04"9K09'09K.01,!&"&<0#')9",),)%0.,9K.&09K.0A:BJZY3[ 0m00000000000000000'&0A:BJZH3[0.)W,&')-.)93 0m0s9K&'V80e(,1*I?#.49,')0VK.)09K.0'!R(8#"9,')0R",1.* 0mZ 4(!1,#0"!89&"#90W',*0'!R(8#"9.20 B.W,#.0*.W,#.L0 g,1.08'(&#.g,1.L0 g,1.09"&%.9g,1.L0 D9&,)%PQ04&.8.&W.L0 J"9K0!''971"88J"9K05 9K&'V80e(,1*I?#.49,')6

0

You can make use of following protected variables: 157

Extending J2ME Polish
" " "

de.enough.polish.LibraryManager libraryManager: a manager for device-APIs java.io.File libDir: the path to the “import” folder org.apache.tools.ant.Project project: the Ant project in which the obfuscator is embedded

If you need further configuration settings, you can add them with the <parameter> construct, which is discussed below. To call the obfuscator, you typically need to accomplish these tasks in the “obfuscate”-method: 1. Set the classpath for the given device: You can get the device-specific APIs by calling *.W,#.3%.971"884"9K250which returns a String array containing the locations of the deviceAPI-Jars. The usual behavior is to set the classpath for the obfuscator to the given bootClassPath and the device-specific APIs. 2. Specify which classes should be spared from obfuscation: the classes specified by the preservearray should not be obfuscated at all. These always include the MIDlet classes and maybe some other classes which are loaded with the Class.forName()-mechanism. 3. Start the obfuscator: set the input to the provided sourceFile and the output to the specified targetFile. Both of these files are Jars. When there is an exception, abort the build by throwing a org.apache.tools.ant.BuildException explaining the details why the obfuscation was aborted. Integrating the Obfuscator into the build.xml You can integrate any thirdparty obfuscator with the usual <obfuscator>-element in the build.xml file (compare page 48).
?/+207,"3/.(0%5177@A3173A(1%"+51@A3.01A( ,5"77@A,/:=,/:!"%8=/+207,"31=U8E+207,"3/.A ,5"77S"3B@A==I/+207,"3/.4!./b1,3I+$%I,5"7717A H ?-11!(,5"77@A,/:=,/:!"%8=#8%":$,=N/:1M8%":$,65"77A(IH ?-11!(,5"77@A,/:=,/:!"%8=#8%":$,=a%/3B1.M8%":$,65"77A(IH ?!".":131.(%":1@A7,.$!3Q$51A(G"501@A==I7,.$!37I/+207,"31=7,.$!3A(IH ?I/+207,"3/.H

The “class”-attribute needs to be set to the new class. The classPath-attribute can be used for pointing out the location of the obfuscator. This is only needed when the obfuscator is not on the Ant-classpath. Configuring the Obfuscator with Parameters The obfuscator can be configured using <parameter>-subelements in the build.xml. For each <parameter> a corresponding “set[parameter-name]”-method needs to be implemented, which either needs to have one File parameter, one boolean or one String parameter:
?!".":131.(%":1@A7,.$!3Q$51A(G"501@A==I7,.$!37I/+207,"31=7,.$!3A(IH

For the using the above parameter, the obfuscator needs to implement either the public method 8.9D#&,49g,1.20g,1.0R,1.05 or the public method 8.9D#&,49g,1.20D9&,)%0W"1(.05. When a method with a File-parameter is used, relative file paths are resolved relative to the location of the build.xml file (or to be more precise relative to the project.getBaseDir() location). The file given as 158

Extending J2ME Polish a parameter in the set-method uses an absolute path in that case. Creating and Using Custom Preprocessing Directives You can easily use your own preprocessing directives by extending the de.enough.polish.preprocess.CustomPreprocessor class and by integrating your preprocessor with the <preprocessor>-element in the “build.xml” file. Preparations Create a new project in your IDE and set the classpath so that it includes the “enough-j2mepolishbuild.jar”, which can be found in the “import” folder of the installation directory. Also include the “ant.jar” file from your Ant-installation into the classpath. Creating the Preprocessor Class Create a new class which extends de.enough.polish.preprocess.CustomPreprocessor.
Using the registerDirective()-Method

The easiest way to use custom directive is by registering them with the “registerDirective”-method:
Zmm 0m0;**80"0*,&.#9,W.0VK,#K0,808."&#K.*0R'&0,)09K.04&.4&'#.88.*08'(&#.0#'*.83 0m0zK.).W.&09K.0*,&.#9,W.0,80R'()*L09K.0"44&'4&,"9.0-.9K'*0 0m04&'#.88P*,&.#9,W.+)"-.Q0,80#"11.*3 0m0zK.)0R'&0.?"-41.09K.04&.4&'#.88,)%0*,&.#9,W.0EZZnK.11'E08K'(1*0!.04&'#.88.*L 0m09K.08(!#1"880)..*809'0,-41.-.)909K.0-.9K'*0 0m04&'#.88M.11'20D9&,)%01,).L0D9&,)%=,8901,).8L0D9&,)%0#1"88\"-.053 0m0U4&.T 0m0&.%,89.&B,&.#9,W.2EK.11'E56 0m0ZZ0,809K.08"-.01,$. 0m0&.%,89.&B,&.#9,W.2EZZnK.11'E56 0m0UZ4&.T0 0m00 0m0s4"&"-0*,&.#9,W.09K.04&.4&'#.88,)%0*,&.#9,W.0VK,#K08K'(1*0!.0R'()*3 0m00000000>K.0*,&.#9,W.0)..*809'0#')9",)0"901."890H0#K"&"#9.&802"4"&90R&'0m0 9K.0!.%,)),)%0EZZnE530 0m >K.0EZZnE0!.%,)),)%0,80"**.*0VK.)0)'9084.#,R,.*3 0m0s9K&'V80e(,1*I?#.49,')0VK.)09K.0#'&&.84')*,)%0-.9K'*0#'(1*0)'90!.0R'()*3 0mZ 4&'9.#9.*0W',*0&.%,89.&B,&.#9,W.20D9&,)%0*,&.#9,W.0509K&'V80e(,1*I?#.49,')

When for example the directive “date” is registered, the public method 4&'#.88B"9.20D9&,)%0 1,).L0*.3.)'(%K34'1,8K3(9,13D9&,)%=,8901,).8L0D9&,)%0#1"88\"-.050needs to be implemented. You can make use of following protected variables:
" "

de.enough.polish.preprocess.Preprocessor preprocessor: the main preprocessor de.enough.polish.preprocess.BooleanEvaluator booleanEvaluator : an evaluator for complex terms which can be used in the #if-directive.

If you need further configuration settings, you can add them with the <parameter> construct, which is discussed below. In the processing method the line in which the preprocessing directive was found is usually 159

0#1"88 0mZ 4(!1.01.).-4'&90*.xml file (compare page 58).)%01.ant.#9.xml You can integrate your preprocessor with the usual <preprocessor>-element in the build.09'04&'#.Extending J2ME Polish changed.OE31.41"#.050C 0 ._(.+*.)%20&.)%0#1"88\"-.&.#0W'.)93.3.)92&.-4'&90'&%3"4"#K.83).#9.)9256 ZZ0)'V04&'#.*04&'#.8871"8820D9&.).&.1*I?#. you can override the processClass()-method which allows you to process the whole java-file in one go: Zmm 0m0J&'#.)0#1"883 0m0 0m0s4"&"-01.8L0D9&.88'&0C 04(!1.0. When there is an exception.)90*.38(!89&.3.).0o0E3E056 O D9&.896 .0PE0 o01.)90F01.0'R09K.809K.0#1"88 0m0s4"&"-0#1"88\"-.?pR2E]C*"9.08'(&#.)*807(89'-J&.97(&&.*04&'#.88.apache.).E56 D9&.J'80o0E]C*"9.J'80FF0+Y50C 009K&'V0).D9"&90F01.)%=.4&'#.#9.83%.)%20*.).W.8(1956 0O O Using the processClass()-Method For more complex situations.)01.0o0E0"901.).D9"&90o0EZZn*"9.E31.4&'#.8K3(9.4&'#.8901.).0)"-.&B.)#.)'(%K34'1.2539'D9&.)%25050 o0"&%(-.).#9.)938(!89&./0R'()*0)'0]C*"9.20D9&.&. please make sure that the preprocessing-directive is be removed from the changed line.0%.')6 .')2#1"88\"-.).)*.J'805 o020).).97(&&.3.-4'&90*.88'&250C 8(4.)%2[L0&.88'&0.-256 .13B"9.8901.E56 0O 04(!1.-4'&90S"W"3(9.#0A<J&.tools.).8809K. abort the build by throwing a org.?9.)938(!89&.8L0D9&.#0#1"880A<J&.)90&.4&'#.41"#.O08.%.)'(%K34'1.)*.021.R02&.)%9K25056 1.V0B"9.880n*"9. so that the following preprocessing can continue without errors.13D9&.8(190F0"&%(-.4&'#.)%0"&%(-.1*I?#.).)%=.&256 &.)%=.0#'-3#'-4")<34&.49.88B"9.)%0&.177/.0#'*.8K34&.41"#.8837(89'-J&.?pR20EZZn*"9.W.1!.2E*"9.W.0E0 o021.)9:)*. ?!.#0W'.).886 .0F01.W.BuildException explaining the details why the preprocessing was aborted.)%9K250539&.89.?92550C D9&.88'&6 . When the line is changed.).41"#.0'R09K.( 160 .49.)%0#1"88\"-.).333 O O Integrating the Preprocessor into the build.09K.050C VK.809K.OE56 .6 4(!1.&./.838.J'80F0"&%(-.V0e(.L0D9&.)%01. This example should illustrate the usage of the registerDirective()-method: 4"#$"%.?250o0Y50 o0E/0@)"!1.4&'#.1.W.39''183")93e(.83%.97(&&.

9D#&. relative file paths are resolved relative to the location of the build.1.(H The “class”-attribute needs to be set to the new class.)*. height)-method./:=.(%":1@A7. one boolean or one String parameter: ?!". This is only needed when the preprocessor is not on the Ant-classpath.$!37I!. the preprocessor needs to implement either the public method 8.)%0W"1(... When a method with a File-parameter is used.05 or the public method 8.20D9&. which either needs to have one File parameter.NONE direction.5"77S"3B@A==I!.UP.1.lcdui.xml file (or to be more precise relative to the project."31=7.1!. The classPath-attribute can be used for pointing out the location of the preprocessor.$!3Q$51A(G"501@A==I7.getBaseDir() location). 161 .05. Please note that the Display.":131.177/. Traversal When the custom item gains the focus for the first time.20g. The file given as a parameter in the set-method uses an absolute path in that case..":131.microedition. the custom item will be notified again with the setSize(width.Extending J2ME Polish . Such calls should be surrounded by #ifdef-directives: ZZn.3I+$%I.4!. For each <parameter> a corresponding “set[parameter-name]”-method needs to be implemented.1!. Extending the J2ME Polish GUI Using Custom Items You can integrate custom items to J2ME Polish by extending the javax.R04'1.49g..0 devices. When the width had to be adjusted.8K3-./.9B.9g')920g')93gp\>rD>. Configuring the Preprocessor with Parameters The preprocessor can be configured using <parameter>-subelements in the build..1.(%":1@A7.$!3A(IH ?I!.$!3Q$51A(G"501@A==I7. Subsequent calls will include the direction (either Canvas.xml.1.>:7r>Il>056 ZZn. ZZn0g')90R')90F0g')93%.49g.5"7717A H ?!".1!./.177=U8S.1!.getFont( int ) are only available on MIDP/2../b1.0R.9D#&.1!./. Initialisation J2ME Polish calls the getPrefContentWidth()-method first with an open height (-1)./. TRAVERSE_HORIZONTAL and TRAVERSE_VERTICAL.$!37I/+207.R*. Then the getPrefContentHeight()-method is called with the actual granted width.R Interaction Modes The J2ME Polish implementation supports the interaction modes KEY_PRESS.5"77@A./. the traverse-method will be called with the CustomItem.18.$!3A(IH For the using the above parameter.*4H g')90R')90F0g')93%.A .getColor( int ) and Font.CustomItem class.177/./:!"%8=!.R"(19g')9256 ZZn.177=7.177/.

83R')97'1'&0F089<1.1L0D9<1.1056 O 2.8K3(8.8K3#883-<.jar”.R The second variant is the most flexible one and is encouraged. When the J2ME Polish GUI is used.0-<.R02#'1'&:)90vF0)(1150C 162 .R 3.**.%.&0#'1'&:)90F089<1. A<:9. please make sure that the project-classpath contains the “enough-j2mepolish-client.J'1.R*.089<1.050C 00008(4.#0A<:9. the preprocessing-symbol “polish.)%01"!.8K`(.8K3(8."*084.R04'1.R 9K.8K3(8. therefore.1056 For reading the specific style settings.8K3(.#0"99&.0 based UI: ZZn.8K3(8.2089<1.&9<20E-<."9.R09&(.3.&38.9D9<1. 004(!1. When the item MyItem is now used within the code.-0F0). the method setStyle( Style ) needs to be overridden: ZZn.8K`(.089<1.&201"!. Defining a static style before the super-constructor is called: 4(!1.!(9.20D9<1.3R')97'1'&6 ZZ0)'V0&.)*.-0#''1:9. 004(!1.0#''1D9<1.9.B<)"-.#0A<:9.)*.050C ZZn.R*. Allowing the setting of the style in a second constructor: ZZn.Extending J2ME Polish DOWN.-20D9&.J'1.9.9:)9J&'4.#0W'.)*.R*.8 4&'9.8K`(. the appropriate style can specified with the #style directive: ZZn89<1.)%0#&.-E6 O ZZn. LEFT or RIGHT).-4'&90*.usePolishGui” is defined.3%.R*.0K.J'1.8/ ZZn. ZZ09K.08(4. Specifying the name of the dynamic style: ZZn.1.9.9.R04'1.9(&)0E-<.R04'1.#9'&250C 00&.-+#'1'& :)9.R There are several ways to integrate a CSS-style into the CustomItem: 1.)%01"!.-201"!.#D9<1.#.*0D9&.788D.)'(%K34'1.83R')90F089<1.-+#'1'&E056 . which can be found in the “import” folder of the J2ME Polish installation directory. ..R04'1.R*.R.3m6 ZZn.9D9<1.3R')96 9K.)*.-20D9&.1050C 00ZZn89<1.008(4.&+#"110).R04'1.*809'0!.&201"!.056 00O ZZn.056 ZZn.*08.#9. Using CSS for Designing the CustomItem When the CSS-styles should be used for designing the CustomItem. This can be used when the CustomItem should be used in the J2ME Polish GUI as well in a plain MIDP/2.)/ ZZn08(4.V0A<:9.1L089<1.

)%0)"-.R 00O ZZn.18. e.9:)9J&'4. so that J2ME Polish can process all styles correctly. This file can be used to register CSS attributes which are used in your CustomItems.)%0)"-.)%0)"-.R The setStyle()-method will be called before the preferred content width and height is requested.83#'1'&0F0[?gg[[[[6 O ZZn. “color”. You can use this method only when you have registered the corresponding attribute in the file #(89'-+#88+"99&.&9<20D9&.05 returns either a String representing that value or null when the property is not defined. When the getIntProperty()-method is used. ! 89<1.9J&'4. A description of this attribute. The registration is encouraged nevertheless. This is required.83?-1.&9<20D9&. ! 89<1.9:)9J&'4. Each attribute is represented by an <attribute>-element with following attributes: Attribute name description type Required Yes No No Explanation The name of the attribute.)*.3%.!(9. “integer”. Either “string”. The registration of these attributes is only required when either the 89<1. 9K.)%0)"-.&9<20 D9&. “boolean” or “style”.83?-1. Defaults to “string”.05 returns either an Integer representing that value or null when the property is not defined.&9<20D9&.g.9D9<1.)%0)"-. since future-versions of J2ME Polish might use this information for an embedded CSS editor.83#'1'&0F0[?gg[[[[6 ZZn. when the CustomItem has a style associated with it.)*.0C 9K.20D9<1. Registering Custom CSS Attributes You will find the custom-css-attributes.xml file in the installation directory of J2ME Polish.)9. You can use this method only when you have registered the corresponding attribute in the file #(89'-+#88+"99&.9e''1.&9<20D9&.05+0or the 89<1. The attribute-type needs to be “!''1. “icon-image”.05-method is used in the 8. The attribute-type needs to be either “. Please note that the variable needs to be called “style” or needs to end with “style”. There are 3 different ways to retrieve a property from a style: ! 89<1.9:)9J&'4. since instead of String-based attribute-names numerical short-values will be used in the actual code.256 O0. This approach significantly reduces the runtime-performance and minimizes the heap-usage.)9q"1(.%.05-method of the CustomItem.83#'1'&0F0#'1'&:)93.!(9.")J&'4.3%.")”.05 returns either a Boolean representing that value or null when the property is not defined.3%. The type of the attribute.3%.Extending J2ME Polish 9K.&” or “#'1'&”.3%. the type needs to be either 163 .18.

:^(D$73^(6B/$.$!3$/%@AYB1(%":1(/2(3B1(73851(2/.R)*. the CustomItem merely needs to paint its contents. When the getBooleanProperty()-method is used. As an example we create and integrate an animated background.R Adding a Custom Background For adding a new background.(3B1(.11^. For the constructor we 164 .R04'1.Extending J2ME Polish Attribute Required Explanation “integer” or “color”. ZZ0*&"V0*.J'1.R"(190!"#$%&'()*/ %38.0 onwards.071#A IH Backgrounds and Borders Background and border settings will be enforced by J2ME Polish. therefore. just create a new class which extends the de.enough.83K.0. Each background needs two implementation classes: one class for the client-side which is responsible for the actual painting and another one for the server-side which is responsible for creating the client-background-class and reading the parameters from the CSS definitions. A comma-separated list of allowed values for this attribute.83V.polish. please create a new project called “background-project” and make sure that the files “enough-j2mepolish-build.jar”. The following example defines a simple attribute: ?"33.. It is advisable.%K9056 ZZn.071#473851A 38!1@A73851A "!!5$17Y/@AN. which paints a filled out circle./0!A #17.ui. “enough-j2mepolish-client.*9KL09K. These files can be found in the “import” folder of the J2ME Polish installation directory. that a background is only painted. which paints a “pulsating” circle..$+031 %":1@A2/. Please note that this background is now directly available in J2ME Polish from version 1. the type needs to be “boolean”.83!"#$%&'()*7'1'&056 %3R.jar” are on the classpath of the project. The default-value of this item.jar” and the “midp2.071#($31:=A #12"053@A2/.)*.1`.97'1'&209K.8K`(. when the J2ME Polish-GUI is not used: ZZn..8K3(8. Creating the Client-Side Background-Class For using a new background.1%358(2/. appliesTo default values No No No A comma-separated list of class-names for which this attribute can be applied.Background class.11%^(Q/.#920[L0[L09K.. We are starting with a simple background.

0R.')31#*(.&#1.)90-"?B.&#1.&L0.)"10.&050C 8(4.&6 4&. 4(!1.)B."-. but a bit boring.9.&0F0-.83-"?B.*9K0Z0H6 .83#(&&.96 <0F0#.)90V."-.W"9.&0F0-"?B.)*80e"#$%&'()*0C 4&.)90#.)90#'1'&6 4&.9.&#1.8K3(.83#'1'&0F0#'1'&6 O 4(!1."-.)90K.)90<L0.W"9.8`&'V.-4'&90*.")0."-.0R.)90-"?B.)B. 4"#$"%.3. For doing this we need to override the animate()-method. The #condition-directive at the top ensures that the PulsatingCircleBackground is included only when the GUI of J2ME Polish is actually used.#86 .96 %3R.&0Z0H6 ?0F0#.W"9.*.#0J(18"9.)"10."-.0!''1. a repaint will be triggered resulting in a call of the paint()-method.#0#1"880J(18"9.0R.11.*9KL0.)90#'1'&050C 8(4.')04'1."-.)B."-.9.)"10. so we add an animation to it: the background-diameter should grow and shrink constantly.)9B.)90?L0.)'(%K34'1.83-.)9.0R.9."-.)90#.)B.83#(&&.&L0[L0ad[056 O 4(!1. which is used to implement animations.9.&6 O 4(!1.&|0F0<0o0K.J'1."-.&256 9K.8K3(8.11.#80%50C %38.e"#$%&'()*20.#0J(18"9.W"9.#0W'.&6 9K.%K9L0`&"4K.250C 165 . When this method returns “true”.&l0+0'RR8.9.)%7.)B.&6 4&."-."-.)92.83#'1'&056 %3R.#0!''1."-.)*80e"#$%&'()*0C 4&.)9B.Extending J2ME Polish only need one parameter – the desired color of the circle: ZZn#')*.)%0F09&(.)9B.9.97'1'&209K.-4'&90S"W"?3-. This background is useful.#&'..8K`(.)90-.)%7.%K90Z0H6 .9.9.%K9L0[L0ad[056 O O The paint method is used to render the background and needs to be implemented by all subclasses of Background.)90#'1'&6 4(!1.-"9.)9B.83#'1'&0F0#'1'&6 9K."-.)"10.)9B.3e"#$%&'()*6 4(!1.0#'-3#'-4")<3!"#$%&'()*86 .&#20?L0<L0V.*9KL0K.)90'RR8.9. With returning false the background indicates that no repaint is necessary.9.)%7.83#(&&.&L09K.)90K.9..9.)92.90F09K.83#(&&.e"#$%&'()*0.W"9.&l0F0?0o0V.)9.9.)90V.&#1.97'1'&209K.#80%50C %38.#0#1"880J(18"9.)%7.&#20?L0<L09K.)90<L0.)90#(&&."-.?9.&0F0-.0.e"#$%&'()*20.&6 4&.&256 9K.)90?L0.)90#'1'&L0.e"#$%&'()*0.%K9L0`&"4K.*04".9.3`&"4K.6 4(!1.&6 9K.&|0+0'RR8.9..*04".*9KL0.)9.?9.")0").83#'1'&056 .)90-.#0W'..W"9.)9.

)%0#&.9050 9K&'V80e(.883D9<1.83-"?B.DK."-.&80K"W.)%7."-.49.9.&D9&56 .1*I?#.*809K.8K34&.Extending J2ME Polish .0C 9K."-.&6 .920E-.9.9.9.9.&9.&0F04"&8.8.&0UF0-.9.9.!(9.1*I?#.&256 O 4&'9.')2E:)W"1.)+*.*809K.*07DD/09K.49.)9B.83.8`&'V.R029K.)B.0W"1.8`&'V.0"99&.&Q3E56 O ZZ0)'V0#K.83#(&&.&++6 .9.)'(%K34'1.&9.&0C 4(!1.)%0F0R"18.9(&)09&(."-.)+*.&0FF09K.883e"#$%&'()*7')W.0P-.9."-.4&'#.&D9&56 .9.)%+#.&Q3E56 O D9&.&D9&0F02D9&.6 .089<1.04(18"9.&0.)'(%K34'1.e"#$%&'()*7')W.VD9"9.)B."-.&#1.9.V0e(.&0F04"&8."-."-.6 O O &.e"#$%&'()*7')W.9089<1.96 4(!1.1*I?#.83-. Creating the Server-Side Background-Class For converting CSS-style information into the appropriate background object.)%50C 9K.0 !"#$%&'()*0).04(18"9.*0W"1(.&0FF09K.')0C D9&.preprocess.883D9<1.-4'&90*.8/ .1*I?#."-..DK.0 !"#$%&'()*0).&EL0-"?B.!(9.*07DD/09K.)90-.)%0F09&(.3.R02-.83.)%50!"#$%&'()*3%.-4'&90S"W"3(9."-.L D9<1.&E56 .9.920E-"?+*.83#(&&.9.&250C 8(4.9."-.R09K.9.0#'-3#'-4")<3!"#$%&'()*86 .49.0P-"?+*.9.R029K.-4'&90'&%3"4"#K."-."-."9.&oo6 ..9.49. This class reads the provided CSS information and creates the source-code for creating a new instance: ZZn#')*."-.-.)+*.&50C 9K.enough.-4'&90*.')6 .8K34&.4&'#.&050C 166 ."-.6 O O The implementation uses the field “currentDiameter”.&D9&00F02D9&.#$0.&E56 .R02-"?B.)%7.)90-"?B.)9B.)%50!"#$%&'()*3%.83#(&&.)9B."-.R02-"?B.83."-.3.83#(&&."-.&D9&0FF0)(1150C 9K&'V0).&50C 9K.&9.&#1.polish.R029K.DK.)%0-.)9B.#0#1"880J(18"9.39''183")93e(.9. The constructor now has two additional parameters: the minimum diameter and the maximum diameter for the circle.?9.&9.\..)%+#.#9."-.)*80e"#$%&'()*7')W.0"99&.4&'#.9.0*.9.18.&#1. which is either decreased or increased in each run of the animate()-method.9. 4"#$"%.)B.13M"8KA"46 .)%0-"?B. we need to implement a converter class which extends de.6 O O0.9.:)92E-.9.')0R"18.V0e(.8`&'V.)B.:)92E-"?+*.)92 M"8KA"40!"#$%&'()*L0 D9<1.&EL0-.8K34&.#0J(18"9.9.)'(%K34'1.&#1.&D9&0FF0)(1150C 9K&'V0).-4'&90*.)B.*0D9&."-..3.')2E:)W"1."-."-..BackgroundConverter."-.)B.

#=b". the background color defaults to white.1I7.!(9./&0"..&Q0"99&.!(9.q"1(..3I+$%I..9. we throw a BuildException explaining the details of what went wrong.9.\"-."9.1I7."-.&80"&.)+*.!(9.&Q3E56 O .3I1%/0&B4bZ:1!/5$7B4+0$5#=b".)%+#.5"77!"3B@A$:!/.-&.)%0"99&.xml: ?3"7-#12( %":1@AbZ:1!/5$7BA( .0P-.5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A( .9.)+0")*0-"?+*.'==I+".7'1'&20D9&. “min-diameter” and “max-diameter”. Several directories can be specified by separating them with colons: ?bZ:1!/5$7BH ((((<===> ?+0$5# 78:+/57@AFL":!51N8:+/5^(a%/3B1._("180[3E56 O ZZ0'$"<L09K.*809'0!..)%0(&105..08-"11.)%0 "99&.')2E:)W"1.M$.)B.'( $:!/.3Ib#/:=b"./b1."-.1*I?#.0!"#$%&'()*0).9.L0D9&."-.!(9. To parse these values we can the helper-method 4"&8.0!"#$%&'()*0).050and %.e"#$%&'()*20E o09K.g1'"920D9&."-.q"1(."-.)%0"99&..V0#'-3#'-4")<3!"#$%&'()*83J(18"9.49.*809'0!. we return a String in which a new instance of our background is created.@A7/0.0P-.9.0 'R09K.0 'R09K.*07DD/09K.&#1.)%7.xml.)B.)%0#'1'&q"1(..0%&.3I!. When everything is okay.*07DD/09K.R02-.0'$"</ &. In case no color has been defined.01A 7.1*I?#.!(9."-.)%0"99&./b1.. When a required value is missing or a value is set wrong.)+*.05L04"&8.0-.&0'&0.We do this by specifying the “srcDir”-attribute of the <build>-element in the build.9.83#'1'&”.-&.&Q0"99&.&D9&0o0EL0E0o0-"?B.:)920D9&. In our example we want to use the attribute “color”.L0D9&. we need to ensure that the classes can be found and to use it in the polish."-.04(18"9.9@&120D9&.9.11%@A:1%0A 071S/5$7B`0$@A3. so that this file is never included in the J2ME application.49./0%#A 20557. The easiest way is to do this in the definition of the J2ME Polish task within the build.9.04(18"9. This is useful when the same source folder is used for the client-background-class as well as the serverbackground-class.css file: At first we make sure.0P-"?+*./0%#4!.!(9.05L0 4"&8.&#1. The color value is parsed by the super-class already and can be accessed with “9K.9(&)0E).&#1."31&8@A+".')2E:)W"1. We included the #condition “false”.&09K")09K.83#'1'&0o0EL0E0o0-.\"-. Integrating the Custom Background To use our background./0%#4!.V0e(.5"7717A IH Secondly we need to inform J2ME Polish about the additional source-folder.-&.3I7/0.V0e(.&04"&"-. that the classpath includes our background-project.&D9&0o0E5E6 O O In the method “createNewStatement” we read the provided values from the HashMap.A H ((((<===> 167 .)%+#.'$:!/.'==I+".&0U0[050C 9K&'V0).Extending J2ME Polish 9K&'V0).FL":!51A $:"&1D/"#N3.

you need to implement them with a Background class.)%/0h6 !"#$%&'()*0C 9<4.?4")*0j0#.i.Border class.&86 168 .enough.&6 O Now we can build the application by calling Ant to check the result: Adding a Custom Border Adding a custom border requires the same steps as for creating a custom background.&9. For the server-side the de.&/0y[6 O R')90C 89<1.9.9.9.6 -. These files can be found in the “import” folder of the J2ME Polish installation directory.0#'-3#'-4")<3!'&*. width and strokestyle of the border should be customizable: ZZn#')*.)9.J'1.8K`(. Please note that borders currently do not support the animate()-method. “enough-j2mepolish-client./0#'-3#'-4")<3!"#$%&'()*83J(18"9.preprocess.e"#$%&'()*7')W.jar” and the “midp2. Instead of extending the Background class.')04'1.polish.jar” to the classpath of the project.polish.*0C 4"**.)%7.BorderConverter needs to be extended. we need to extend the de.&6 #'1'&/0VK.ui.css” file of our application.Extending J2ME Polish ?I+0$5#H ?IbZ:1!/5$7BH Thirdly and lastly we need to use the new background in the “resources/polish.8K3(8. so if you want to use animated borders."-. 4"#$"%.&#1. Creating the Client-Side Border-Class We create a border which should draw a round border around items.&/0H[6 -"?+*. The color.enough."-./0!'1*6 #'1'&/0R')97'1'&6 8.0 onwards. As the type we need to define the SERVER-side converting class: R'#(8.jar”.)+*.9. Please note that this border is now directly available in J2ME Polish from version 1./08-"116 O 1"<'(9/0. For this example we create a project called “border-project” and add the files “enough-j2mepolishbuild.

D9<1.-4'&90*.-4'&90*.#07.")08. The class needs to extend the de.9.&z.)"10.6 .*9K0+0Hm!VL0K.)9089&'$.1.9D9&'$.50C %38.R028. When a different strokestyle than Graphics.9D9&'$. we set that style and reset the style in the end of the paint()method.-4'&90S"W"?3-.&#1.6 O 4(!1.83#'1'&0F0#'1'&6 9K.#83Dp=:B056 .D9<1. 4"#$"%.)'(%K34'1.83!'&*.D9<1.*9K6 9K.SOLID is used.0R.97'1'&209K.&z.&20.83!'&*.)'(%K34'1.883D9<1.*.D9<1.#83Dp=:B056 O O O The #condition-directive ensures that this class is only used when the GUI of J2ME Polish is actually used.#0W'.*9KL0K.&6 4(!1.0#'-3#'-4")<3!'&*.49.D9<1.D9<1.')6 .)90!'&*. since the Graphics.DOTTED stroke style is hardly ever used.)90V.02!V0T0[50C %3*&"V.)"10.#&'.8389&'$.8K34&.4&'#.0R.#86 .')31#*(.polish.1*I?#.3.96 169 .&7')W.)90K.')0R"18.*9K6 VK.9D9&'$.-4'&90'&%3"4"#K.83!'&*.3e'&*.&256 9K.)90?L0.050C 8(4..8K3(.8389&'$.)*80e'&*.)'(%K34'1.)90#'1'&6 4&.W"9.883e'&*.%K9L0[L0ad[056 .*9K0F0V.3`&"4K. Creating the Server-Side Border-Class The server side border class reads the CSS-attributes from the polish.39''183")93e(.#80%50C %38.-4'&90*.preprocess.W"9.9.&#1.3.&#20?0o0!VL0<0o0!VL0V.209K.3.&9.&6 .)90!V0F09K.13M"8KA"46 .D9<1.D9<1.D9<1.4&'#.DK.&#20?L0<L0V.&z. In the paint()-method the border is rendered to the screen.css file and creates the code for initializing a new border.9D9&'$.9D9&'$.*9K6 4(!1.R028.)92.)90V.-4'&90*.)90#'1'&L0.enough.6 4&.)'(%K34'1.&0.)"10.)9089&'$.BorderConverter class: ZZn#')*.0F089&'$.056 O %3*&"V.%K90+0Hm!VL0[L0ad[0 56 !V++6 O O .*9K0T0Y50C .#0#1"8807.0F029K.e'&*. This is a J2ME Polish specific convention.W"9.?9.883D9<1.0vF0`&"4K.50C %38..D9<1.)90<L0.*9KL0.0R.*9KL0.D9<1.%K9L0`&"4K.R029K.&0C 4&.Extending J2ME Polish ..8389&'$..83#'1'&056 !''1.&z.20`&"4K.*04".e'&*.8K34&.8K34&.-4'&90S"W"3(9.4&'#.3.&86 .

we assume that the Graphics.7'*.83V.D9<1.0F0ES"W"?3-.\.')31#*(.&L0 D9<1.*.9@&120D9&./b1.SOLID stroke-style should be used.DK.Extending J2ME Polish 4(!1. Integrating the Custom Border To use our background.9089<1.#83Bp>>IBE6 O0.6 .7'*. Unless “dotted” is defined.D9<1.'( $:!/.3.3`&"4K.3I1%/0&B4bZ:1!/5$7B4+0$5#=b".&9.#83Dp=:BE6 O O0.089<1.?9. The easiest way is to do this in the definition of the J2ME Polish task within the build.&256 O 4&'9.D9<1.#9.&#1.*0D9&.&#1.*.5"77%":1@A#1=1%/0&B=!/5$7B="%3=S/5$7BY"7-A( .5"77!"3B@A$:!/.0C 89&'$. we need to ensure that the classes can be found and to use it in the polish.05L04"&8.18.9050 9K&'V80e(.0F0ES"W"?3-.&7')W.+89<1.&20E0 o09K.L D9<1.)%0"99&.D9<1.0vF0)(1150C . The color defaults to black and the width defaults to 1.&0.)%0(&105.:)920D9&.?9.D9<1.V0*.D9<1.#&'.e'&*.83#'1'&0o0EL0E0o09K. so that this file is never included in the J2ME application.)%0 "99&.!(9.3I!.&9.&7')W.')31#*(.#&'.'$:!/.e'&*.\"-.q"1(. This is useful when the same source folder is used for the client-background-class as well as the serverbackground-class.)'(%K34'1.7'1'&20D9&.)%0 "99&.L0D9&.7'*.)%0#'1'&q"1(.R0289&'$.\"-.)%089&'$.)%089&'$..xml: ?3"7-#12( %":1@AbZ:1!/5$7BA( .xml.3`&"4K. So we only need to parse the desired stroke-style. There are some helper methods for parsing the CSS-attributes: 4"&8.550C 89&'$..q"1(.3I+$%I.*. Several directories can be specified by separating them with colons: 170 .)%50!'&*.0F0ES"W"?3-.&7')W. We included the #condition “false”.DK.D9<1.05L04"&8.)92 M"8KA"40!'&*.!(9.&0C 4(!1.VD9"9.92E89&'$.1*I?#.!(9.5"7717A IH Secondly we need to inform J2ME Polish about the additional source-folder.9.')837.#&'.!(9.4!.9(&)0E).#07.#83Dp=:BE6 O &.9._("18289&'$.css file: At first we make sure.0C 89&'$.3Ib#/:=b".'==I+/.)*80e'&*.49.0F02D9&.0o0E5E6 O O The BorderConverter already parses the color and width of the border.#0#1"8807.8K3. that the classpath includes our border-project."9.R02E*'99.L0D9&.E56 D9&.9.18.)%0"99&.')31#*(.7'*.g1'"920D9&.3`&"4K.-.&9.D9<1.&#1.*9K0o0EL0E0o089&'$.We do this by specifying the “srcDir”-attribute of the <build>-element in the build./&0".&3%.7'*.)8.e'&*.&250C 8(4.#=b".*E3.')0 C D9&.050and %.#1.)%0#&.

everyone can participate from the work of others.*0C 4"**.&9. 171 .1I7. Do note.Extending J2ME Polish ?bZ:1!/5$7BH ((((<===> ?+0$5# 78:+/57@AFL":!51N8:+/5^(a%/3B1./08-"116 O 1"<'(9/0.&6 V./0*'99. As the type we need to define the SERVER-side converting class: R'#(8.e"#$%&'()*7')W. We need the code and a complete documentation of your extension..&837. It is recommended to use the JavaDocconventions within the code for the basic documentation.1I7.4!.01A 7.*9K/0H6 #'1'&/0R')97'1'&6 89&'$.#1./0 #'-3#'-4")<3!'&*...de to discuss your contribution.&0C 9<4.FL":!51A $:"&1D/"#N3.M$. The J2ME Polish project adheres to the normal Java style conventions. but German is also accepted..A H ((((<===> ?I+0$5#H ?IbZ:1!/5$7BH Thirdly and lastly we need to use the new background in the “resources/polish.&#1.&6 O Now we can build the application by calling Ant to check the result: Contributing Your Extensions Please consider to contribute your extensions to the J2ME Polish project.60 !'&*.?4")*0j0#.css” file of our application. For distinguishing local from instance variables.3I7/0. This behavior can be enforced in Eclipse by setting the compiler-option “unqualified access to instance variables”.-&."31&8@A+"./0!'1*6 #'1'&/0R')97'1'&6 8.+89<1.)%/0h6 !"#$%&'()*/0)').*6 O R')90C 89<1.11%@A:1%0A 071S/5$7B`0$@A3../0%#A 20557. please use the “this” operator for accessing instance variables.'==I+/. Please get in touch with j2mepolish@enough. however./b1.)9.@A7/0. Preferably the extension is documented in English. In an open source world..i. that J2ME Polish is used commercially as well.

definition”.OZ!. You can load definition-files with the “Open Definition” command or dragging and dropping the file on either the start-script or the editor like shown in following figure. It can also generate the Java/J2ME code for loading that data for you. 7: The ${polish. The structure of the data is kept outside of the data-files themselves and has the extension “. The Binary Data Editor Use the binary-editor for creating and modifying binary data like level data files. Fig.) folder.definition” and the data-file Fig.home}/bin folder on Mac OS X. With the BinaryEditor you can easily adjust any kind of structured binary files like for example level data. “level1.data” from the “bin”-folder for getting a working example setup like shown in the following figure. In each definition you will have several entries which can have arbitrary names like 172 . 8: The binary editor in action.8K3K'-.Standalone Tools Standalone Tools J2ME Polish includes standalone tools for specialized tasks in the ]C4'1. Please load the specification-file “level.

The Font Editor The font editor is used to generate bitmap (*. Standard Java long value (uses 8 bytes). Standard Java String. unless you generate your own code for loading the images. Positive 8 bit value. Explanation -32.bmf) fonts out of any True Type (*. Standard Java int value (uses 4 bytes).216-1 (65. One byte representing true (1) or false (0). Such bitmap fonts can be used by the J2ME Polish GUI with the R')9+!.768.8K3(9.263-1 true.. In the calculation you can use any entry which is listed before the affected entry. The BinaryEditor can also generate the J2ME code for loading data files with the current definition – just select “Code -> Generate Code”.. Such images should usually be the last entry in a definition file.231-1 -263. Type byte unsigned byte short unsigned short int long boolean ASCIIString Values -128. but you can also be a bit more flexible by using a calculation..9A"4g')90utiliy class. which determines how often the entry is repeated.3..+32. You can also define the type of each data-entry.+128 0. “playerY” and so on.535) -231.255 Standard Java byte value.767 Standard Java short value (uses 2 bytes). A PNG image.Standalone Tools “playerX”.. A string consisting of ASCII characters with a max-length of 255 characters..13e. There are predefined types available. So far you can only use simple terms using one operation on a number of entries. UTF-String Text PNG-Image Image Each data entry also has a “count” value. but you can also combine your own types out of the basic types using “Edit -> Add Custom Type”.)'(%K34'1. The ASCII-String uses length + 1 bytes in the data file. You can insert “static” numbers here. In this way you can for example define first a number of columns and a number of rows and then use “columns * rows” for calculating the number of cells of a table structure. 0. false Text Positive 16 bit value.ttf) fonts. Just click into the respective “count” field to start the editor for changing the count-value of the entry. 173 .9-"4 CSS-attribute or directly with the *.

you might want to optimize the images outside of the editor: Just select “File -> Save PNG-Image As.htm#pngout). just reload the PNG-image by selecting “File -> Open PNG-Image”.sourceforge.g.net/pngcrush/) or PNG-Out (http://advsys. e. You might also want to use PNG-image optimizer like PNG-Crush (http://pmt. You can also fine-tune every aspect of the bitmap-font by opening it in the BinaryEditor: select “File -> Open in Binary Editor” to do so.net/ken/utils.Standalone Tools Fig. 174 . The Gimp. When you're done. Since the font-editor does no yet optimize the generated font-images... 9: The font editor in action.” and edit the image in your favorite image editing program.

sigtool.8EZT In case the sigtool.R.')FE&.blackberry.#"9. property. you also need to define the “blackberry.%9''13*.1. otherwise the rapc process will abort the processing.db files are not included in the same location like the certificates. Preparations For transforming and signing the JAR files to the BlackBerry proprietary COD format.8.xml file."&#K0:)0A'9. the BlackBerry Java Development Environment (JDE) needs to be installed. The key for this support is the ${polish.&9.E0 1'#"9.xml script you then need to define the “blackberry. Developing for BlackBerry Devices The BlackBerry platform of Research in Motion is quite popular for business applications.')Ze1"#$e. postcompilers.home}/platforms.8Z8. Signing COD Files J2ME Polish can also automate the requesting of signatures during the build process. finalizers and so on.3*.&&<38.&9. In order to get a certificate.&9<0 )"-. inclusion of platform specific (boot) classpaths. J2ME Polish will automatically invoke the rapc compiler for converting the JAR file into a COD file in the finalize step of the build process.8'(&#.#"9.&E01'#"9.certificate. Remember that resources should be less than 64 kb in size. Normal MIDlets as well as BlackBerry specific applications can be developed with J2ME Polish. You can use the “jar” packager for compressing the resources a bit better than the internal J2ME Polish jar mechanism: U4"#$"%. On Unix systems it can be installed using Wine. you need to register with BlackBerry first. Signatures are required for accessing some Blackberry specific security sensitive APIs and require a certificate.&&<3#.FE!1"#$!. In your build.&E01'#"9.8Z^.FE!1"#$!.Non-MIDP Platforms Non-MIDP Platforms J2ME Polish can be adjusted to support several platforms that support more than the normal MIDP profile.&&<3K'-. and the automatic invocation of preprocessors.%9''1EZT 175 .FES"&E0ZT.8Z#.&9<0)"-.csk and sigtool.&&<3K'-.&0)"-.FE!1"#$!.com/developers.')FE&.&9<0)"-.xml script you then need to define the !1"#$!.&&<0GBI0b3[3HE0 ZT Converting JARs into CODs When you target BlackBerry devices like the BlackBerry/7100t device and have set the !1"#$!.&&<3K'-.')FE7/ZJ&'%&"-0g.dir” property: U4&'4.R.8'(&#.dir” property: U4&'4. The JDE can be downloaded from http://www. In your Ant build. property which points to the installation folder of the JDE: U4&'4. BlackBerry and Palm platforms are supported out of the box.

R. Also you can get verification errors on the BlackBerry devices when you enable the obfuscation.-3.#"9.9EZT Using the J2ME Polish GUI on BlackBerry Devices The J2ME Polish GUI can be used normally on BlackBerry devices as well. classes etc.88FE9. compare the following Troubleshooting section.0)"-.FEJ&'`("&*E0()1.Non-MIDP Platforms When you specify the password as well.4.#. For such cases the password needs to contain only ASCII characters. Developing Native BlackBerry Applications You can also develop native BlackBerry applications by defining the !1"#$!.441. UW"&.0.3"4.jar. otherwise J2ME Polish can't include the password automatically. because currently not all available classes are included in the default library.0. 176 . U4&'4.&&<3-"."!1.38<89. In such cases you can copy the JAR provided by the JDE from ${blackberry.#"9.) variable that contains the name of the class that extends ).)E0W"1(. If you use BlackBerry specific classes in your application you might encounter compiler problems.W.#"9.&&<E0ZT Library J2ME Polish includes the ${polish.home}/import/blackberry4.home}/lib/net_rim_api.441. The successful conversion requires that your MIDlet uses a public constructor.&&<3#. In order to make most of the System. Also native InputFields are used for the text input. Since this file contains unresolved class dependencies you need to use a JDK 1.').8K3!1"#$!.93&.')E0 ZT Please note that the currently provided BlackBerry library does not contain all available classes. This allows J2ME Polish to process trackwheel events and so on correctly.jar library which contains the most important packages that are additionally available on BlackBerry devices.5 JDK. Troubleshooting Deactivate Obfuscation You should deactivate obfuscation for BlackBerry devices.jar to ${polish.&9. J2ME Polish uses this for requesting the signatures without manual intervention. since the rapc compiler already removes any unneeded fields.FE!1"#$!.FE!1"#$!.FE8.FE#'-3#'-4")<34&'*(#93J&'*(#9.home}/import/blackberry-4.34"88V'&*E0W"1(.&9<0)"-.-3*.&&<3-". You can skip the obfuscation for test builds as well as for BlackBerry devices with this definition: U'!R(8#"9'&0)"-. J2ME Polish converts your MIDlet into a native BlackBerry UiApplication.890jj04'1.#&.x and must not use a 1.

FE4"1-3W. so that your application can use the complete available screen.println() message are stored on the memory card.&9<0 )"-. When no ID is defined. Automatically installs the generated PRC file on the connected Palm handheld.3K'-. property that points to the folder into which you have extracted the WEME tools: U4&'4.com/dev/tech/java.xml script you then need to define the 4"1-3V."!1.vendorId palm.0)"-.home}/lib. You can fine tune the conversion process by adding following Ant properties or J2ME Polish variables to the build. URL of the file that contains a splash image.-. the JAR file has to be converted into the proprietary PRC format.largeIcon palm.)*'&:*E0W"1(.Non-MIDP Platforms Developing for Palm Devices Palm handhelds also support J2ME applications when the IBM WebSphere Everyplace Micro Environment (WEME) has been installed.enableInstall false false Default Explanation A 4 character long vendor ID. If you want to install applications directly via the USB connection or if you want to use the complete screen size. URL of the file that contains a small application icon.splash palm.E0 1'#"9.FEI\DzE0ZT 177 .:#')E0W"1(. Enables the debug mode of the Palm.out.palmos.8Z)"9.FE4"1-31"&%.Z841"8K3S4%E0ZT UW"&. Enable the high resolution mode."!1.xml script: Name palm. MIDP applications can be installed normally over the air (OTA) as any other application. an ID will be created automatically.enableHighRes true palm. In this mode all System. Preparations The Palm converter and simulator can be downloaded from http://www.8'(&#.-.0)"-.')FE7/ZJ&'%&"-0g.FE4"1-3V.3K'-.smallIcon palm.1.enableDebug palm. In your build.FE&. The following example adds a splash image to the application and defines a vendor ID: UW"&.W. When you extract the WEME tools you will find additional libraries in the Tools/lib folder. You need to adjust the CLASSPATH environment variable of your system to include those libraries or you need to copy them to ${java. URL of the file that contains a large application icon.8ZJ"1-ZzIAIhyE0 ZT Converting JARs into PRCs J2ME Polish automatically converts JAR files into the Palm PRC format when you target Palm devices.

"441. You need to define the Ant property 4"1-38.home}/samples/doja.)90)"-.9&.441. In Japan DoJa 4.&0)"-.5.dojadeveloper.83>.-.0 is the current standard.5 or C:\iDK.)98T U&. In your IDE you need to include either ${polish.&.1*T section of your build.&9<0 )"-.xml script you might need to specify the doja.#.E0 1'#"9.1*T element: U!(.^.-(1"9'&E0 ZT Developing DoJa Applications with J2ME Polish DoJa is the Japanese J2ME standard created by NTT DoCoMo that also uses CLDC as its foundation._(.1. 178 .8E0ZT U'!R(8#"9'&0)"-.#"9.&.')FE7/ZJ&'%&"-0g.W.T element inside of the U!(.#.-(1"9'&T section. There are currently two versions of DoJa for the international market: 1. J2ME Polish includes a DoJa sample application in ${polish.-(1"9'&3K'-.g._(. that points to the folder that contains the PalmSim..home}/import/doja-2.home Ant property in case you have not installed the DoJa SDK to either C:\jDKDoJa2.5. You then need to adjust your device requirements. e.9&. This standard provides similar capabilities as the MIDP platform.)98T Last but not least you need to specify your :. by calling ")90._(. J2ME Polish includes some virtual devices like the DoJa/os15 or DoJa/os25 ones: U*.1*T You can now build your application and launch the emulator.8ZJ"1-ZD.home}/import/doja-1.5 and 2.') class with the U.FE4"1-38.jar or ${polish.FEJ&'`("&*E0ZT Uv++03330++T UZ!(.&E0W"1(.&. J2ME Polish already includes libraries for both versions. J2ME Polish creates the JAR file without a Manifest and a JAM instead of a JAD descriptor."441. Preparations You can download DoJa emulators from the DoJa Developer Network at http://www.R.1*T U.)9. you can invoke the converter by adding the jar2prc finalizer to the U!(.-.xml script: UR.FES"&H4&#E0ZT Starting the Palm Simulator As with many other vendors you can start the Palm simulator by using the U.i. J2ME Polish Setup In your build.W.-(1"9'& from the command line.)"1.-(1"9'&3K'-.FEB'G"Z'8HhE0ZT UZ*.exe executable: U4&'4.-.0#1"88FE9.5. so that your application is build for DoJa devices.jar to the classpath of your project.^.net.FE:*.Non-MIDP Platforms When you target only a generic device like the Generic/multi one.

"!1. *'S"37')R.&. The size of the i-mode Java Application drawing area. These can be retrieved using #'-3)99*'#'-'3(.9B.Non-MIDP Platforms Optional JAM Attributes Several JAM attributes are optional.xml script. so you can set them by specifying Ant properties or J2ME Polish variables in your build.&&34&. e.3:."!1. Example setting: 9.FEhYH[E0ZT UZW"&.#.g.)"1. To launch the i-mode Java Application automatically at a specified time.-3'(934&. The DoJa Emulator/SDK is only needed for starting the emulator.44J"&"- Explanation Any startup parameters.44>&"#.')q.)91)25 or D<89.&-. When the value is set to ').&%825.%(&"9.& *'S"3J&'R. Example setting: lba[.9V'&$ *'S"3>"&%. e.#"9. Multiple parameters should be separated by a space. The easiest way is to install the DoJa emulator under Windows and then copy the complete folder into your Unix file system.g.i.W.g. Set to K994 for applications which use network functionality.0)"-.9@9) Developing DoJa Applications under Linux and Mac OS X You can build DoJa applications without restrictions under Linux and Mac OS X with J2ME Polish.L|ba[.* This information can be retrieved using the #'-3)99*'#'-'3(9.FE*'S"3DJ8. Name *'S"3. set the time here.9.& *'S"3DJ8.-3.8T UW"&.3%.1. B'G"+Y3h'. 7=B7+Y3[ The i-mode Java Application runtime environment profile version. The J2ME configuration version.&9<25 method.120 bytes (= 5 KB) is reserved: UW"&. *'S"3="()#K.')3%.8T The following table lists the available optional attributes. since the installer won't work together with wine.)91)25 will be displayed after the i-Appli is terminated.*L(8.9 *'S"3.&."!1. *'S"3B&"V. Set to a model name if the application is targeted to a particular model.\. The size of the ScratchPad in bytes.441.9J&'4." *'S"3`.13JK'). *'S"3@8.i. YH[?Ya[ Declares that the i-mode Java Application refers to the handset identification code and IC chip information on its SIM or UIM card. any information output with D<89. In the following example a scratchpad size of 5.E0W"1(. J2ME Polish will use 179 .q. e. Do not set this key for applications targeted to all models.

09K.R Remember that you need to do this for your .#9'&3'4./ 000^.#9.089'&.)09K.8K3*'S" preprocessing symbols for distinguishing between your releases.')0#')0F07')).R directives to branch within an utility class for example: ZZn.9.') preprocessing directive in your Java source file: ZZn#')*. for example.8K3-.Non-MIDP Platforms wine then automatically for executing the emulator under Unix systems.3'4. you can share some code between your DoJa and your MIDP release of your application.0*"9"0.)2E8#&"9#K4"*/ZZZ[604'8F[EL07')).20E)"-.056 000ZZ0333 ZZn.#'&*D9'&. You can use the 4'1.8K3*'S" 000ZZ089'&.#'&*089'&.9.-4'&9 statements as well.1.EL09&(.8K3-. 180 .#'&*D9'&.)0"0&. Ant property in your build.)^.')04'1.#9'&3z^:>I056 000ZZ0333 ZZn. Just use the appropriate n#')*.*4 Of course you can also use these symbols in n.)*.#'&*D9'&.R04'1.0*"9"0. Developing for MIDP and DoJa at the Same Time Since both MIDP and DoJa use the Connected Limited Device Configuration as their foundation.xml script.08#&"9#K04"*/ 0007')). Remember to specify the *'S"3K'-.0F0^. You can exclude a source file for the DoJa release by specifying that it requires an MIDP device.*4 000ZZ089'&.8K3-.R04'1.*4 and 4'1.

11%@A:1%0A 071S/5$7B`0$@A3.. You can now add the third party API by setting the “sourcDir” attribute to “source/src:source/thirdparty”: ?+0$5# $:"&1D/"#N3.17ZA 181 . however.. You have to distinguish between APIs which are available as source code.17/0. How to Integrate a Source Code Third Party API When a third party API is available in source code.1(#$..A(IH ?7/0..17H ?7/0. You can also use the nested <sources>-element for including source-directories based on conditions.. The notation is OS-independent by the way.. out of the scope of this how-to...' and you can separate folders with a slash '/' or a backslash '\'..11%@A:1%0A 071S/5$7B`0$@A3. This is. Just separate the folders with colons or semicolons: ?+0$5# 20557... you can integrate it by modifying the “sourceDir” attribute of the <build>-element in the “build.1I7.11%@A:1%0A 071S/5$7B`0$@A3. Depending on the type of the API different actions are required for integrating the API.17H === How to Integrate Third Party APIs Sometimes a third party API is needed in a project.1I7. and APIs which are available in binary-only form.xml” file.."31&8@A+".@A7/0.01A .. So you can separate different source-paths with either a colon ':' or a semicolon '. Consider the case where your normal application code is placed in the “source/src” directory and the source code of the third party API in the “source/thirdparty” folder.1(#$./0%#A 20557.. Please do not forget to add the library to the classpath of your project within your IDE.17M$.xml” file. In this example the directory “source/test” is only included when the Ant-property “test” is true: ?+0$5# 20557.'==I1L31%7$/%7I7/0..A H In the above example the “source/src” folder of the current project and the “source/src” folder of the “extensions” project are included.-&.1M$. Another case are APIs which are already pre-installed on specific devices.@A7/0.1I7.1I3173A($2@A3173A(IH ?I7/0.Cooking Tips and How-Tos Cooking Tips and How-Tos Building How-Tos How to Use Several Source Folders You can use several source folders by defining the “source”-attribute of the <build>-element in the “build.@A7/0.01A 7/0..@A.01A H ?7/0.

@A.#!". this is noted with the “JavaPackage” capability of that device in the “devices.1I3B$..11%@A:1%0A 071S/5$7B`0$@A3.zip” just needs to be copied into the “import” folder (in the J2ME Polish installation directory or in your project root directory)..-&..17/0. You can modify the “apis.1I7. only the name of the libraries need to be given (instead of specifying the full path)."31&8@A+". zip-files or classfiles). So you can separate different source-paths with either a colon ':' or a semicolon '. In the following example the binary library “tinyline” is integrated..#!". When the libraries are situated in the “import” folder.'. This attribute can point to jar.38A H The notation is OS-independent by the way.11%@A:1%0A 071S/5$7B`0$@A3. which are pre-installed on the devices.17ZA +$%".xml” file.jar” or “phonebook.. It will then be used automatically for the devices which support the “phonebook” API.. So you can separate different source-paths with either a colon ':' or a semicolon '.17M$. they can be integrated with the “binaryLibraries” attribute of the <build>-element in the “build.or zip-files or to a directory containing third party libraries (either jar-files. How to Integrate a Binary Third Party API When a third party API is only available in binary form.01A . A popular example is Nokia's UI-API which provides additional graphic and sound functions. How to Integrate a Device API Many devices provide additional APIs.17ZA +$%".8D$+./0%#A 20557.xml” file (this is again only visible when you have chosen to install the “external device database”) for specifying different library-names.@A. the corresponding library file “phonebook. The corresponding library file “tinylinegzip.$17@A3$%85$%1&9$!=9$!A H In this example all libraries which are situated in the “thirdparty” folder are integrated: ?+0$5# $:"&1D/"#N3."31&8@A+".17/0.01A . paths or aliases.Cooking Tips and How-Tos H 7/0.17M$. When a device supports a specific API.zip” is situated in the “import” folder: ?+0$5# $:"&1D/"#N3./0%#A 20557.8D$+.-&. This is described 182 .1M$.'7/0. Assuming that you want to use API “phonebook”.' and you can separate folders with a slash '/' or a backslash '\'.".$17@A3B$.' and you can separate folders with a slash '/' or a backslash '\'.@A7/0. Several libraries can be separated by colons ':' or semicolons '..".38A The notation is OS-independent by the way..xml” file (this file is visible only when you have chosen to install the “external device database” during the installation of J2ME Polish).

)*.*0.V0:11.0E4'1.&%(-.)*.V0:11. 9K&'V0).Cooking Tips and How-Tos in more detail on page 25.#$E0.)*.&%(-.?0PE0o0.!(%q.)90')1<0VK.R04'1. It is better not to use the “columns” attribute at all in this case.)9I?#.*0*'D'-.R04'1. fonts and borders in the appropriate 183 . Forms and Lists do not use a table layout by default. This is usually fine when the application is stable. too.?0T09K.18. Another optimization is to define often used backgrounds.')256 00ZZn.%"1. More information about special attributes can be found on page 120. no method-arguments will be checked by the J2ME Polish GUI.R. How to Minimize the Memory Footprint There are several possibilities for minimizing the memory-footprint of J2ME Polish: polish.)97K.)*. In that case you should not set the “columns”-attribute to “1”. Please note that combining RetroGuard and ProGuard actually results in bigger classes than when ProGuard is used alone.9K. When this symbol is defined.)97K. You can set and unset the "polish.&%(-.xml” file.&!'8.debugVerbose" symbol by modifying the “verbose” attribute of the <debug>-element.8K38$.4.8K3*.*/ . you should not use default-values in your “resources/polish. Find more information about integrating other obfuscators on page 157.)9I?#. Find more information about the <obfuscator>-element on page 48. compare page 36.83-"?:)*.80)'90*.)09K.)*.#0W'.?050C 00ZZn.?050C 00ZZn.skipArgumentCheck"-symbol in the application code: 4(!1.&%(-.')2E:)W"1. Image Load Strategy When you use the J2ME Polish GUI. for example. The “imageLoadStrategy” attribute of the <build>-element can either be “foreground” or “background”.debugVerbose" symbol for determining if a meaningful exception should be thrown.)%20. This is described in more detail on page 54.)*.debugVerbose Define the preprocessing-symbol "polish.8K38$.css" File When you use the J2ME Polish GUI.R O The above example also uses the "polish. by setting the “symbols” attribute of the <build>-element in the “build. You should also skip the checking of arguments in the application by testing the "polish.)90.R)*.R*.skipArgumentCheck".R02.?0U0[0jj0.4.#$09K.49.0"&%(-. since this is the default behavior anyhow. Optimizing the "polish.%"1. some memory can be saved.xml” file. ZZn09K&'V0).49.skipArgumentCheck and polish.?0EQ3E56 00ZZn.R O 00ZZn.).css” file. How to Use Several Obfuscators Combined You can combine several obfuscators just by adding several <obfuscator>-elements to your “build. By giving verbose information only in cases when it is requested.)*. select the "foreground" image loading strategy for removing the overhead of loading images in a background thread.#$ ZZ0#K.

#0W'. This screen should be derived from Nokia's FullScreenCanvas when this class is available.)%0'9K.)*80A:B1. The assembling of resources is described in more details on page 67. This saves memory and has the additional bonus that you do not need to depend on the dithering of the device.?9. which often results into awkward graphics.44.*0C !"#$%&'()*/0-<e"#$%&'()*6 Zmm08$.80mmZ O R'#(8. So put 4096-colors images into the “resources/BitsPerImage.)6 184 ..16+” folder. Better put them into the “resources/midi” folder.)250C B. When you use the J2ME Polish GUI you can also use device-optimized designs. For example it does not make sense to add MIDI-soundfiles for devices which do not support such files.!(9.*08K'VD41"8KD#&.#96 #'1'&/0%&"<6 "&#/0Yh6 !'&*. Find more information about the J2ME Polish GUI from page 102 onwards.#0#1"880A<A.&+#'1'&/0!1"#$6 !'&*.0841"8KD#&. This requires the usage of the #style-directive in the application code. Use Preprocessing With preprocessing you can make amazing adjustments to specific devices without wasting memory and without losing the portability of an application.841"<"!1. It is also not good to use high-color images for handsets which do not support such images.0C !"#$%&'()*/0-<e"#$%&'()*6 Zmm08$.&0"99&. This is described on page 103. Consider for example this “SplashScreen” solution./0&'()*+&. A third optimization is not to use dynamic styles.css” file.Cooking Tips and How-Tos section of the “resources/polish.&0"99&.*1. Using Optimal Resources Use the resource assembling of J2ME Polish for using only those resources which are actually required by the application. Find more information about static and dynamic styles on page 105.&+V.90C P333Q 4(!1.)%0'9K.90. More information about the #style-directive can be found on page 86. Better create optimized versions of such images.44. which shows a startup logo. In that case you can just refer to the instances: !"#$%&'()*80C -<e"#$%&'()*0C 9<4.12” folder and 65k-colors images into the “resources/BitsPerImage. In a classic solution you would need to test if Nokia's API is available and to load a Nokia-specific version of the SplashScreen class: 4(!1.*9K/0H6 O O 9.80mmZ O This is described in more detail on page 111..91.!(9.

/ 841"8KD#&.)0.3g(117")W"80C 4(!1.8K3"(*..9^."+(.&3#&."D41"8KD#&."0.&0F0A")"%.&3#&.)0F0).*3(.&2071"883%.80"W"."9.18. ZZn0&.J1"<.841"<38.#80%50C P333Q O O 4(!1. 41"<.8'(&#.J:0.3"-&t5L0 u"(*.0#1"88.)*80#'-3)'$.)/ 841"8KD#&.8K3"(*.83*.R04'1.1.256 O0#"9#K02I?#.2uA<\'$.91.)*807")W"8 ZZn.?9..3)'$.'Z"-&t056 41"<..R04'1.)0.91.R04'1.*.)t53).&389"&9256 ZZn.&0F0A")"%.9^.?9.R C 4(!1.#0841"8K08#&.&041"<.L01'"*09K..R09K.%t056 41"<."3-.9^. .9208#&.49.#0W'.*04".&2071"883%.8K3"4."-2u9."9.&6 ZZn.&389"&9256 ZZn.&2071"883%.*04".Cooking Tips and How-Tos 9&<0C ZZ0#K.80.?9.8K3"(*.)0 ZZn..)*.&389"&9256 ZZn.J1"<.3-..#0#1"880A<\'$..#0W'.)056 O O 4(!1.9(&)6 185 ."-2u9.8'(&#.91.'3-.)920`&"4K.#80%50C P333Q O O With the preprocessing capabilities and the integrated device database of J2ME Polish there is an easier and much more memory efficient solution available: 4(!1.t056 41"<."+*."-2u9.V0A<D41"8KD#&.)*80#'-3)'$.#.*041"<A(8.J1"<."D41"8KD#&."9. ZZn0.)256 O 9K.#0#1"880A<D41"8KD#&.8'(&#.#0#1"880A<D41"8KD#&.8K3"(*.?9.)920`&"4K.'ZV"Wt056 41"<.1..18.&0F0A")"%.*.'3V"W 41"<. In a classical environment you would need to check the supported formats at runtime and then decide which one should be used.)0F071"883R'&\"-.t5L0 u"(*.)920`&"4K.8D9&.*.#250C J1"<.&389"&9256 ZZn.91.R04'1.1.#0W'..3-4at5L0 u"(*.8D9&.% 41"<. Using preprocessing and the device database this is much easier and no checks during the runtime are necessary: 4(!1.'Z-.&2071"883%.#80%50C P333Q O O Another example is the playback of sound.W..'3-4.V:)89")#.*3(.'Z-4."3-..'3"-& 41"<.#$0.&3#&.80"0\'$.')0.)*807")W"80C 4(!1.3g(117")W"8 ZZn.8D9&.8'(&#.&0F0A")"%.J1"<.50C ZZ0)'0\'$.#0W'.9^.8D9&."9.*04"."-2u9.3V"Wt5L0 u"(*.&3#&..1"!1.R04'1..

*1. but it has some drawbacks.89Z]C4'1.xml” file.&&'&FE9&(.FE+S"&R.8K3S"*\"-.88"%.)%08.8K3-. OOP is great.<89'&.RFE4'1. Check if you really need methods for accessing variables.89Z]C4'1.8K3.&&'&FE9&(.FE+"1.1'). Try to use preprocessing whenever it makes sense.OZ!. How to Sign MIDlets with J2ME Polish Signing MIDlets can be automated using the <java>-subelement of the <build>-element.%EZT U"&%01.. Sometimes it is better is better to declare them protected or even public and to access them directly. If you have text which is displayed only seldom. Try to minimize the usage of classes and interfaces.88FE9. however.*1. e.*.0-.)4(9S"*0*.&OE T U"&%01.OEZT U"&%01. Remove Debug Code When the application should be shipped any debug code should be removed from the project."80D.0R'&0*.OZ!.<4"880]C4"88V'&*OEZT U"&%01.).89Z]C4'1.89E -. The easiest way is to use the #debug and #mdebug preprocessing directives.FE.0-. notably the runtime and memory implications. consider to move them into a properties file. When an appropriate certificate was purchased and imported into the keystore named “midlets.8K3S"*\"-.OEZT U"&%01.<"1%0^D.g.<9''10+%.R.).)ZG"*>''13S"&E0 R'&$FE9&(.E0 186 .983$8EZT U"&%01. the following two <java>-elements need to be added to the <build>element: US"W"0S"&FE]CV9$3K'-."80D.E0 000000 R".FE+'(94(9S"*0*.90+$.0*.*4HE0 ()1.8K3S"&\"-.983$80+$.).FE+$.ks” with the key “SignMIDlet”.Cooking Tips and How-Tos ZZn.)*.E0 R". This is described in more detail in the introduction to J2ME Polish on page 14. Such MIDlets cannot be installed on real devices. For testing purposes no certificate needs to be purchased and imported.)9. The debugging can then be controlled with the <debug>-element in the “build.).)ZG"*>''13S"&E0 000000 R'&$FE9&(.<0+"1.FE+"**S"&8.1').FE+.#.%)A:B1.FE+$.). General Optimization Tips Some other useful tips for minimizing the memory footprint of an application are also available: Do not use pure Object Orientated Programming.1.%)"9(&.)$. Keys can be generated using the Java-keytool.).**.: T0$.E0 0000 .%)A:B1.W.OEZT UZS"W"T US"W"0S"&FE]CV9$3K'-.R O With the help of preprocessing you can shift the runtime checks to the compile phase.9EZT U"&%01.<89'&.0]C4'1.).

jar” is not available.) =.)(EL0=.R.0-". In that case the path to the JadTool needs to be changed to “${polish.8920EA". Find more information in the chapter “Specific Design Attributes” on page 120.890-".<89'&.ks” keystore is situated in the same directory as the “build.9 In Mac OS X Wireless Toolkit the “JadTool. Please note that the password needs to be specified as a property.)D#&.893:AJ=:7:>056 ZZn89<1.88"%.R.)0A.)3"44.8K3-.).)%0#.8K3S"*\"-.)D#&.FE+'(94(9S"*0*.&9.)0F0).OEZT ?Ib"G"H In the above example the signing is skipped when the test-mode is active or when the current device does not support the MIDP/2.xml” file or alternatively (for the more security conscious folks) on the command-line with the -Dpassword=[value] option: T0")90+B4"88V'&*F8.88FE9. The left column will be 40 pixels wide.FE+"1.#.W.xml” file.OEZT U"&%01. It is assumed that the “midlets.&9EZT U"&%01.).FE+$.)D#&.89E -. How to Apply the J2ME Polish GUI for Existing Applications If an existing application should be “polished up” you should insert #style preprocessing directives within the application to allow a fine grained design.FE+.home}/bin/JadTool.-".)*20ED9"&90`"-..0-.).V0=.**.0]C4'1.)9.FE+"**#.8K3S"*\"-. Form elements will be added from left to right and from top to bottom of the table. whereas the right column will use 100 pixels..*4HE0 ()1. GUI How-Tos How to Use Tables A table can be used for any any Form. It can be installed together with J2ME Polish..FE.*9K/0b[L0Y[[6 O In the above example the dynamic style “form” is used for designing all Form screens.jar” in the above example.).983$8EZT U"&%01.Cooking Tips and How-Tos . List or ChoiceGroup.)D#&.0R'&0*.RFE4'1.EL0)(11056 187 .)4(9S"*0*.89Z]C4'1.#"9.8K3.css” file: R'&-0C 4"**.0-"..). The table is activated by setting the “columns” attribute and optionally the “columns-width” attribute in the “resources/polish.*. This can be done within the “build..):9. ZZn89<1.%)A:B1.11'V6 #'1(-)8/0H6 #'1(-)8+V.9EZT U"&%01.&OE T U"&%01."80D.*1.#&.)%/0h6 !"#$%&'()*+#'1'&/0<.0 standard.89Z]C4'1.

The “dir”-attribute of the <resources>-element in the “build. but you can change this to any other folder.&13H U9"&%.)980T0P333Q U!(.^.8'(&#.&1E 0V'&$B.8K3)"-.90)"-. You can use one application source code for creating several different applications with this technique.)D#&.8 0 *._(.1*Z!'<E 0P333Q 0T 188 .E0T USH-.)*'&O+]C4'1.#.Cooking Tips and How-Tos You then need to use static styles in the “polish..1*Z%. In each target the <j2mepolish>-task is copied and changes are made to the “dir”-attribute of the <resources>-element and to the “workDir”-attributes of the <build>-element: U9"&%.4'1.8'(&#.8KT U. Find more information on designing for specific devices on page 103.*9K/0b[L0Y[[6 O In the last step you should refine your designs by adjusting them for different handsets.)0C 4"**.&1%"-.8'(&#.FE]C4'1. If you want to make adjustments for the Sony-Ericsson P900 for example.8KT <===>(IH ?I3". when no <resources>-element is used.O+%.xml” file.8K3)"-.css”.&FE!(. Best practice is to create one Ant-<target> for each end-application in the “build.&.&FE&.O+!'<3S"&E0 <===>(IH U*.4'1.)R' 0S"&\"-.#.W.&FE&.)%/0h6 !"#$%&'()*+#'1'&/0<.css” file.1*T UZSH-. this makes subsequent changes easier. sound files and design-definitions.xml” file defaults to the “resources” folder.-.90)"-.8Z%.4'1.FE!'<%"-. In this file you can change any settings which you have done in the basic “resources/polish.E0T USH-. Alternatively you can also set the “resDir”-attribute of the <build>-element.)*'&O+]C4'1.W.8KT U.)R' 0S"&\"-.&FE!(.8K3W.&.1* 0V'&$B.11'V6 #'1(-)8/0H6 #'1(-)8+V.FE%._(.&1E 0P333Q 0T U&.&1E ZT P333Q0 UZ!(.css” file.8K3W.8Z%. Static styles can have almost any alphanumerical name and need to start with a dot: 3-".&13S"&E0 U*.8B.-.1* 0&.)980T0P333Q U!(. you need to create the file “resources/Sony-Ericsson/P900/polish.^.FE]C4'1. How to Apply Different Designs to One Application You can alter the appearance of an application easily by using different resources like images. Remember that you only need to specify attributes which are different.

&FE&..9.8'(&#.&+K.R ZZn.2041"<.%K90F0Y[6 ZZn. For more information about preprocessing. .&+K.8'(&#.R. This example changes the “Cancel” command to “Abbruch” (German for cancel): ?G".83?-1” file.R041"<.*9K0F0Y[6 ZZn..FE41"<.* ZZnF0.FEYHE0T UW"&.&+K.R*.0)"-..%K9O6 ZZn.W.0.&+K.FEYHE0T These variables then can be used within the application with the use of preprocessing: ZZn.1*T UZSH-.*9KO6 ZZn.V0D4&.%K9/*.88"%.4'1.*9K0F0]C41"<.).&0F0)..).FE41"<.*9KE0W"1(.&+V.R041"<.1*3?-10file or within the localization--.FE41"<.*9K/*."!1.8 *.8Z!'<E ZT P333Q0 UW"&. When the file is missing.*9KL0K.FE41"<.Cooking Tips and How-Tos 0 U&.839?9 file.L0V.)*.)90V..%K9E0W"1(."%.#.”-attribute of the device in question in the “*.)*.)90V.R*.0)"-."!1. which is located in installation folder of J2ME Polish.. How to Change the Labels of Standard-Commands and Menu-Labels The labels of the standard menu-commands can be changed by setting variables either in the !(.*9KE0W"1(. You could define sprite-dimensions for example each or some of the <j2mepolish>tasks: UW"&. re-run the installation and choose to install the “external device database” as 189 .)90K.BAIH ?IG".. .&13H You can even define or alter <variables> to make further adjustments with the help of preprocessing.R D4&.$"+517H Please refer to the localization information on page 76 for more information.&:-"%.* ZZnF0.%K9E0W"1(."!1.FEYHE0T UW"&.041"<.15A(G"501@Aa++."!1.0)"-.)90K.&+V.8K`(.%K9056 Find more information on the <build> element on page 36.R. please refer to page 78.$"+517H ?G".&+V.18.18. You can override this behavior by setting the “8(44'&98J'1.&+V./::"%#=.FEYHE0T UZ!(.0)"-. How to Enable or Disable the Usage of the GUI for a Specific Device J2ME Polish's GUI is deactivated by default for some older devices like the first version of Nokia Series 40 models.$"+51(%":1@A!/5$7B=.9.8KT ?I3".%K90F0]C41"<.

#.Cooking Tips and How-Tos well.8K`(.”-attribute : It needs to be true.J'1.83?-10and search the device in question. Now set the “8(44'&98J'1.1*3?-1 file to “always”. please try a clean build: remove the “build” folder or call the “ant clean” before building again. 2. Find more information about the assembling of resources on page 67. They are unnecessary and waste space in the application JAR.37S/5$7B`0$@A2"571A(H ?$#1%3$2$1.HJ/-$"IN1.8K`(.1H You can also override the settings in the device-database by setting the “(8.$17hK?I$#1%3$2$1. Compile Error If you have a compile error within the J2ME Polish package or a compile error which seems to be erroneous. when the device should support J2ME Polish's GUI. Preverify Error If you have a preverify error. Open *. regardless of the settings in the device database.W. The automatic resource assembling of J2ME Polish is based on using subfolders.”-attribute of the <build>-element in the !(. In that case the GUI will be used for all devices.H ?f44("%#(7/(/%(44H ?I#1G$. please try a clean build: remove the “build” folder or call the “ant clean” before building again. ?#1G$. 190 . Trouble Shooting Using Subfolders for Resources Subfolders for resources are not supported for two simple reasons: 1.1 70!!/.

In the above example only one target is available.B/(:177"&1@A[155/(d/. it can not be changed anymore.Appendix Appendix Introduction to Ant “Apache Ant is a Java-based build tool.xml” is an XML based document which controls and configures Ant. The file “build.@A#$73A(IH ?I3".@A+0$5#A(IH ?#15131(#$. This can be combined with dependencies of targets to create complex behavior: 191 .3(%":1@A1%/0&B4!/5$7B41L":!51A( (((#12"053@AB155/A H ?3".&13(%":1@A.@A+0$5#A(IH ?#15131(#$. Each <target>element is normally used to accomplish one or several specific tasks: ?!.&13H ?I!. so you can only call “ant clean”.51"%AH ?#15131(#$. The basic syntax consists of the the <project>-root-element and several <target>-elements.&13(%":1@AB155/AH ?1.&13H ?I!.xml” file. In that case it us useful to define a default-target. therefore it is useful to get to know Ant a little bit to make the most out of J2ME Polish. which are like variables with the difference that they can only set once: after a property is set. which is executed whenever no target has been specified: ?!.3H Now the “hello” target will be executed. you can call each of the defined targets by calling “ant [targetname]” on the command line.3H In the above example we have one target called “clean” defined which uses two <delete>-tasks for – who would have thought that – deleting two folders. when just “ant” is called from the command line. In theory.” J2ME Polish uses Ant as its foundation for the build-process./b1./b1.51"%AH ?#15131(#$. Usually there are several targets defined in the “build. it is kind of like Make.@A#$73A(IH ?I3". but without Make's wrinkles.5#fA(IH ?I3".&13H ?3". Assuming that Ant has been set up correctly (compare page 21) and that you are in the directory containing the “build./b1. Another powerful feature of Ant are properties.xml” file./b1.3(%":1@A1%/0&B4!/5$7B41L":!51A(H ?3".&13(%":1@A.

-.)./0Y08.5A(G"501@AB33!'II5/. then the “init”-target (since the “hello”-target depends on the “init”-target) and last but not least the “hello”-target: T0")90*.41'<+(&10.80K994/ZZ1'#"1K'89 e@:=B0D@77IDDg@= >'9"109.A(IH ?I3".-.&13H ?3".51"%AH ?#15131(#$. because the “hello” target depends on the execution of the “init”-target: T0")9 e(.41'<0K./!1./!1.1*3?-1 *.@A+0$5#A(IH ?#15131(#$.9/ K.3(%":1@A1%/0&B4!/5$7B41L":!51A( (((#12"053@AB155/A H ?3"./b1.&13H ?3". When we call “ant hello” or just “ant” the property will be “http://localhost”.0*.41'</ .Appendix ?!."5B/73AIH ?I3".#K'Q0>K.38(%":1@A#1!5/840.1*R.1*3?-1 .9/ K. Such special characters needs to be 192 .0*./0!(./0Y08.#K'Q0>K./b1./:I#/C%5/"#AIH ?I3".38(%":1@A#1!5/840.1.5($7(ij#1!5/840.3H In the above example the property “deploy-url” is defined in two targets – either in “init” or in “deploy”.11' e(.41'<+(&10.&13(%":1@A#1!5/8AH ?!.80K994/ZZVVV3#'-4")<3#'-Z*'V)1'"* e@:=B0D@77IDDg@= >'9"109.&13H ?3".11'/ 00000P.@A#$73A(IH ?I3".&13(%":1@A$%$3AH ?!.B/(:177"&1@AYB1(#1!5/840.5.&13(%":1@A.&13H ?I!.1./:!"%8=.&13(%":1@AB155/A(#1!1%#7@A$%$3AH ?1.company.#')* How to Use Quotation-Marks in Attributes Sometimes quotation-marks are needed within attribute-values.com/download” instead.).11'/ 00000P./0!(.5A( G"501@AB33!'IICCC=.1*R. since the “deploy”-target will be called first.#')* But when we call “ant deploy hello” the property will contain the value “http://www.

193 .Appendix specified xml-encoded. How to Specify Properties on the Command Line You can specify Ant-properties on the command-line with the “-D[name]=[value]” option. We recommend either one of the many good books about Ant or to consult the official Ant manual at K994/ZZ")93"4"#K. a quotation-mark is encoded with “&quot.xml” script. e.3'&%Z-")("1Z0for further information.g.”. T0")90+B4"88V'&*FYHab Such properties can be use like any other properties within the “build. This closes the short introduction to Ant.

org/licenses/gpl-faq. GNU GPL You can use the GPL license for projects.html http://www.Appendix Licenses J2ME Polish is licensed under the GNU General Public License (GPL) as well as several commercial licenses. The drawback is that all applications together can be installed/sold only a 100 hundred times.gnu.html Commercial Licenses If the source code of your mobile applications should not be published under the GNU GPL license. More information about the GPL is available at these sites: " " http://www.8K3'&%Z1.org/licenses/gpl. Enterprise License The enterprise license allows to create and sell any number of applications. Runtime License The runtime license can be used for the creation of any number of mobile applications. ! ! The pricing and license terms can be obtained at K994/ZZVVV3SH-.#. which are licensed under the GNU General Public License without limitations. you can use one of the following commercial licenses: ! Single License The single license can be used for the creation and distribution of one mobile application.83K9-1.gnu.4'1.)8. 194 .

$<="0$ D8E F"#).-! !"#$%&'()%*+.$ IJF8).'/&$)0&"%'123 13145'6%$. O$# >?@'A'B4C?12'A'@3'3@'252 >?@'A'B4C?12'A'@3'3@'251 >?@'A'B4C2G4'A'HH'33'145 K1.809 :$.$0 7$%.Contact Contact !"#$%&'(#)*+.=L$0"+M=N-$' PPPN$0"+M=N-$ 195 .$<". ("%'-$.).